@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