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

Project	Description
ModelBound CLI · npm	Terminal + CI for token optimization, skill pipeline, and version management
Cursor Extension · Marketplace	VS Code/Cursor extension for rules sync and MCP bridge
Cursor Plugin	Cursor slash commands for pipeline, safety checks, and versions
Claude Code Plugin	Claude Code plugin for pipeline, hooks, and skill sync
Dev Packs	Open-source curated AI context packs for engineering teams

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

License

MIT © ModelBound