MCP Server

@modularityjs/mcp is a Model Context Protocol server that exposes the framework's catalogue, documentation, and wiring recipes to LLM coding agents. Instead of injecting the full AGENTS.md into every prompt, agents query specifics on demand — which drivers exist for @modularityjs/cache?, read the websocket-wiring recipe, find the package exporting AuthIdentity.

The server is tooling (not a framework runtime contract). It speaks stdio JSON-RPC and is consumed by any MCP client: Claude Code, Cursor, Aider, Codex CLI, Zed, etc.

Install and register

The package ships a single bin, modularityjs-mcp. Register it in your agent's MCP config — no global install required, the agent spawns it via npx.

Claude Code (.mcp.json in your project root)

{
  "mcpServers": {
    "modularityjs": {
      "command": "npx",
      "args": ["@modularityjs/mcp"]
    }
  }
}

Then in any session: "Use the modularityjs tools to list drivers for the cache contract."

Cursor (.cursor/mcp.json)

Same shape:

{
  "mcpServers": {
    "modularityjs": {
      "command": "npx",
      "args": ["@modularityjs/mcp"]
    }
  }
}

Codex / Aider / Zed

Any host that accepts an MCP server command works the same way. Point it at npx @modularityjs/mcp.

In a fresh local checkout (running the server from source rather than npx), run pnpm install first — node packages/mcp/bin/mcp.mjs needs node_modules linked and the package's dist/ built (pnpm --filter @modularityjs/mcp build).

Private registry note

Agents spawn npx outside your project root, so they read only ~/.npmrc — not the project-level file. Both the scope mapping and the _auth line must live in your home .npmrc:

@modularityjs:registry=https://npm.modularityjs.com/
//npm.modularityjs.com/:_auth=<base64(username:password)>

(Or npm login --scope=@modularityjs --registry=https://npm.modularityjs.com/.) See Registry Access for the full setup, including the project-level mapping and CI auth.

What the server exposes

Resources

URI	Content
manifest://catalog	The full manifest.json — every package's kind, extends targets, module class, imports, exports, dependencies.
manifest://agents-md	Pre-rendered AGENTS.md — full conventions blob for one-shot priming.
docs://index	The docs landing page.
docs://guide/<slug>	A guide page (e.g. docs://guide/architecture).
docs://packages/<slug>	A package reference page (e.g. docs://packages/http).
recipe://<name>	A wiring recipe — one of minimal-app, anti-patterns, auth-wiring, cache-wiring, database-wiring, events-wiring, file-uploads-wiring, outbox-wiring, session-wiring, storage-wiring, validation-wiring, websocket-wiring, picker-example.

Templated resources (docs://{area}/{slug} and recipe://{name}) are enumerated via resources/list, so a host can offer them as completions.

Tools

Tool	Returns
search_docs	Top-N matches across all bundled docs, with title, score, and an excerpt around the first hit.
list_contracts	Every contract package and its drivers + extensions catalog.
list_drivers	Canonical drivers (kind=driver) implementing a given contract (e.g. @modularityjs/cache). Excludes extensions — use list_extensions for those, or packages_targeting for the union.
list_extensions	Extensions (kind=extension) that decorate, adapt, or integrate a given package. Each entry includes its structural shape: decorator (single contract target), driver-feature (single driver target), or cross-contract (≥2 targets).
packages_targeting	Union of list_drivers and list_extensions — every package whose extends list includes the given name. Use when kind doesn't matter.
find_extensions_between	Extensions whose extends list spans every package in the given set. Answer "is there an extension that bridges http and auth?" (http-auth) or "an extension spanning cache + telemetry?" (cache-telemetry).
find_symbol	The package that exports a public symbol (e.g. CacheService, AuthIdentity).
find_package	The full manifest entry for a single package by name.
list_packages_by_kind	Packages with a given kind (contract, driver, extension, primitive, tooling).
transitive_dependencies	Resolve every workspace package implied by picking a set of root modules.
get_recipe	Return one of the 13 wiring recipes by name (minimal-app, anti-patterns, auth-wiring, cache-wiring, database-wiring, events-wiring, file-uploads-wiring, outbox-wiring, session-wiring, storage-wiring, validation-wiring, websocket-wiring, picker-example).

Example interaction

A typical session, paraphrased:

You: "Add a Redis-backed cache to this app."

Agent: calls list_drivers({ contract: '@modularityjs/cache' }) → sees cache-memory and cache-redis. Reads docs://packages/cache for configuration. Reads recipe://minimal-app to confirm the module-array pattern. Edits package.json + the app's modules array. Done.

The win is token economy: agents fetch the ~2 KB they need instead of the ~50 KB AGENTS.md.

How it stays current

The docs and manifest are snapshotted into the package at build time. The build, test, typecheck, lint, and lint:fix scripts all chain pnpm run copy-docs (scripts/copy-docs.mjs) before running, so the bundled snapshot stays in step with whatever the working tree looks like. Because all @modularityjs/* packages share a version (Changesets fixed mode), @modularityjs/mcp@X always ships the exact docs and catalogue from tag X. Bumping the framework bumps the MCP server — no drift, no out-of-band refresh.

If you want bleeding-edge docs while iterating, run the server from a checkout:

cd /path/to/modularityjs
pnpm --filter @modularityjs/mcp build

Then point the agent at the local path:

{
  "mcpServers": {
    "modularityjs": {
      "command": "node",
      "args": ["/path/to/modularityjs/packages/mcp/bin/mcp.mjs"]
    }
  }
}