@particle-academy/docs-mcp

Dev tool — not for production. A local Model Context Protocol server that hands your coding agent the docs shipped inside every installed @particle-academy/* package. Runs on your machine, talks stdio, exits when your editor closes. Zero runtime dependencies, no network 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 versions you 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 import from it in application code. It's a CLI; the bin is docs-mcp.

❌ Not: a hosted service. Everything runs locally against your own node_modules and your own packages/ workspace folder. Nothing leaves your 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 spawn it 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 somewhere else. The server scans <cwd>/node_modules/@particle-academy/* and (if present) <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 the editor at it.

Tools exposed to the agent

| Tool | Description | | --------------------- | -------------------------------------------------------------------------------------------- | | docs_list_packages | Every scanned package with name, version, file count, source. | | docs_list | All doc paths. Optional package filter. | | docs_read | Read one doc by (package, path). | | docs_search | Substring search; returns hits with line numbers + section headings. | | docs_refresh | Re-scan the filesystem (call after npm install of a fancy-* package mid-session). |

All tools return both human-readable text and a structuredContent JSON payload so agents can either read the formatted lines or destructure rows programmatically.

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. The fastest 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 an editor 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 the path 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 counterparts for 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, call docs_refresh (or just restart the editor). Avoids surprising file events and keeps the process simple.

Privacy

Everything stays on your machine. The process reads markdown files from disk 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 the same cwd your editor uses. If nothing shows up there, the issue is scope/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.json wins over node_modules/@particle-academy/*/package.json. That's usually what you want. Pass --no-workspace to force node_modules.

License

MIT