io.github.ModelBound/modelbound-mcp

modelbound-mcp

Local-first MCP server for agent skills. Validate, lint, diff, and convert agent skill files across Cursor, Claude, Codex, Kiro, Windsurf, VS Code, and Amazon Q — no account required. Optional cloud sync with ModelBound.

Why ModelBound?

AI tools come and go. You might use Cursor today, switch to Claude Code tomorrow, and try Kiro next week — but your skills, rules, and context shouldn't be locked into any one of them. ModelBound gives you a single place to store and manage your agent skills, so you can move between tools freely without rebuilding your setup each time. Write a skill once, sync it everywhere, and get more value out of every AI subscription you're already paying for.

What it does

modelbound-mcp is a small Model Context Protocol server you run locally over stdio. It exposes tools to your IDE / agent using dot-notation naming for navigable discovery:

Local (no API key, no network):

• ide.detectLayout — find which IDE conventions your repo uses
• skills.listLocal, skills.readLocal, skills.writeLocal
• skills.lint — front-matter, token count, broken links, TODO scan, pass / warn / fail checks (scanner h5)
• skills.flightCheck — Flight Check offline safety scan (injection, exfiltration, secrets, destructive commands, wildcard tools, loop hazards); same rules as npx modelbound check
• skills.checks — deterministic safety/quality checks without full lint (no numeric score)
• skills.scaffold — create a skill with default scope constraints
• skills.reviewStatus, skills.reviewRequest, skills.reviewApprove, skills.reviewReject, skills.reviewGate
• skills.validateFormat — agentskills.io compliance
• skills.convert — translate between IDE formats (e.g. Cursor → Claude)
• skills.diff — compare a local skill with its cloud counterpart

Cloud (with MODELBOUND_API_KEY):

• cloud.pullSkill, cloud.pushSkill, cloud.search
• cloud.listSkills — now accepts ai_type and source_platform filters; every row includes ai_type, source_platform, source_path, and repo
• cloud.resourceTree — returns the team's full hierarchy grouped by platform → top-level dir (.claude/skills, .cursor/rules, .kiro/steering, …) → files. Use this before cloud.listSkills when an orchestrator needs to map context before loading.
• cloud.installMarketplaceSkill
• optimization.health

Resource hierarchy

Orchestrators that juggle multiple AI platforms can call cloud.resourceTree once to get a complete map of available skills, rules, hooks, steering files, and system prompts — grouped exactly how each platform expects them on disk. Pair it with the new ai_type / source_platform filters on cloud.listSkills to load only the slice you need. See examples/resource-tree.ts.

The cloud tools are a thin JSON-RPC proxy to mcp.modelbound.co. All business logic stays server-side; this repo never touches your data or secrets.

Migration from 0.1.x — old snake_case names (detect_ide_layout, pull_skill, …) were removed in 0.2.0. The hosted ModelBound MCP server still accepts both forms forever for backward compatibility.

Anti-slop (0.4.x) — trust scanner bumped to h5 with scope-limit, unbounded-wording, dependency, and refactor findings. skills.readLocal now returns checks, scanner_version, review_state, and review_meta. Override default scope limits via .modelbound/task-budgets.json. Use skills.reviewGate in CI to block unapproved skills.

Install

npx modelbound-mcp

Or install globally:

npm i -g modelbound-mcp

Use as an MCP server

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "modelbound": {
      "command": "npx",
      "args": ["-y", "modelbound-mcp"],
      "env": { "MODELBOUND_API_KEY": "mb_live_..." }
    }
  }
}

MODELBOUND_API_KEY is optional. Without it, local tools still work.

See examples/ for Claude Desktop, Kiro, Windsurf, and VS Code configs.

Use as a CLI

modelbound-mcp detect                                  # which IDE layouts exist here?
modelbound-mcp ls                                      # list every skill file
modelbound-mcp lint .cursor/rules/                     # lint a directory
modelbound-mcp lint .codex/skills/                     # lint Codex skills
modelbound-mcp validate ./SKILL.md                     # agentskills.io compliance
modelbound-mcp convert --from cursor --to claude ./rule.mdc > out.md

Tests

npm test              # unit tests (registry parity, checks, review, harness)
npm run smoke         # local MCP tools + CLI subcommands (+ cloud if MODELBOUND_API_KEY set)
npm run test:e2e      # offline anti-slop / review lifecycle

CLI vs MCP tool mapping: docs/PARITY.md.

Contributing

We want help. Specifically:

• New IDE adapters — Zed, Aider, Continue, JetBrains AI, Cline. See CONTRIBUTING.md for the ~50 line recipe.
• Linter rules — token estimation accuracy, dead-link detection, format-specific gotchas.
• Format converters — fidelity improvements between adapter pairs.

Browse good first issues and the roadmap.

Related projects

Also on Smithery (stdio via npx modelbound-mcp) and the MCP Registry. Install hub: modelbound.co/connect

License

MIT © ModelBound