@particle-academy/docs-mcp

@particle-academy/docs-mcp

Dev tool — not for production. A local Model Context Protocolserver that hands your coding agent the docs shipped inside everyinstalled @particle-academy/* package. Runs on your machine, talksstdio, exits when your editor closes. Zero runtime dependencies, nonetwork calls, no telemetry.

If you're working on a project that uses react-fancy, fancy-sheets,fancy-flow, agent-integrations, etc., this lets Claude Code / Cursor/ Claude Desktop pull from the docs that actually match the versionsyou installed — instead of guessing from training data.

What it is (and isn't)

✅ Is: a dev-time MCP server you wire into your editor's MCP config.Spawned as a subprocess when your editor starts, killed when it stops.

❌ Not: a runtime library you ship in your app bundle. Don't importfrom it in application code. It's a CLI; the bin is docs-mcp.

❌ Not: a hosted service. Everything runs locally against your ownnode_modules and your own packages/ workspace folder. Nothing leavesyour machine.

❌ Not: a docs publisher. It only exposes README.md and docs/**files that already ship inside @particle-academy/* packages.

❌ Not: a search index — substring grep, no rankings, no embeddings.Good enough for "find me the docs page that mentions X."

Install + configure

You don't install this into your project. Configure your editor to spawnit on demand via npx:

Claude Code / Cursor (.mcp.json in project root)

{
  "mcpServers": {
    "particle-docs": {
      "command": "npx",
      "args": ["-y", "@particle-academy/docs-mcp"]
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "particle-docs": {
      "command": "npx",
      "args": ["-y", "@particle-academy/docs-mcp"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

cwd defaults to the editor's working dir, which is usually correct —specify explicitly only if the editor launches the server from somewhereelse. The server scans <cwd>/node_modules/@particle-academy/* and (ifpresent) <cwd>/packages/*.

Restart your editor. The first invocation downloads + caches the package;subsequent launches are instant.

Locally-built / pre-publish

While developing this package itself (or before it's published to npm),point the editor at the local build:

{
  "mcpServers": {
    "particle-docs": {
      "command": "node",
      "args": ["/absolute/path/to/packages/docs-mcp/dist/cli.js"]
    }
  }
}

Run npm run build once in packages/docs-mcp/ before pointing theeditor at it.

Tools exposed to the agent

All tools return both human-readable text and a structuredContent JSONpayload so agents can either read the formatted lines or destructure rowsprogrammatically.

Typical agent flow

agent: docs_list_packages
   → 11 packages found
agent: docs_search { query: "controlled component" }
   → 3 hits across react-fancy/docs/Forms.md, fancy-sheets/docs/Spreadsheet.md, ...
agent: docs_read { package: "@particle-academy/react-fancy", path: "docs/Forms.md" }
   → full markdown

CLI flags (for debugging)

docs-mcp [options]

  --cwd <dir>           Project root to scan from (default: process.cwd())
  --scope <name>        Restrict to scope(s). Repeatable. Default: @particle-academy
  --scope-any           Scan every npm scope
  --package <name>      Scan only these packages. Repeatable.
  --include-unscoped    Include unscoped packages
  --no-workspace        Don't scan <cwd>/packages/*/docs even if present
  --list                Print discovered packages and exit
  -h, --help            Show this help

Smoke-test the scan without spinning up MCP

npx @particle-academy/docs-mcp --list

Lists every package + doc path the scanner found, then exits. Thefastest way to verify it's seeing what you expect.

Smoke-test the MCP loop without an editor

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"docs_search","arguments":{"query":"slash command","limit":3}}}' \
  | npx @particle-academy/docs-mcp

Three JSON-RPC frames go in, three come back. Useful when debugging aneditor config that isn't reaching the server.

How the scan works

For each candidate package, the server includes:

1. <package>/README.md (if present, exposed at path README.md)
2. Every .md / .mdx file under <package>/docs/**

Paths are stable docs-relative strings (README.md, docs/guides/sheets.md,docs/api/components.md) — that's what docs_read accepts as thepath argument.

Scan sources, in order:

1. <cwd>/node_modules/@particle-academy/*/ — installed packages.
2. <cwd>/packages/*/ — monorepo workspace packages (when packages/exists). In-tree packages win over their installed counterpartsfor the same package name, so docs match the code you're editing.

Subdirectory node_modules are not recursed. Symlinks are followed.

No watchers. If you npm install or pull new docs mid-session, calldocs_refresh (or just restart the editor). Avoids surprising fileevents and keeps the process simple.

Privacy

Everything stays on your machine. The process reads markdown files fromdisk and writes JSON to stdout. It never opens a socket, makes a fetch,or phones home.

Troubleshooting

• docs_list_packages returns nothing: run with --list from thesame cwd your editor uses. If nothing shows up there, the issue isscope/scan — try --scope-any or --cwd <path> to widen.
• Editor says the MCP server crashed: run the CLI directly (npx @particle-academy/docs-mcp) and paste in a single {"jsonrpc":"2.0",…}line. Errors are written to stderr; the editor usually hides those.
• Versions look wrong: in a monorepo, the in-tree packages/*/package.jsonwins over node_modules/@particle-academy/*/package.json. That'susually what you want. Pass --no-workspace to force node_modules.

License

MIT