Documentation Assistant MCP Server

An MCP server that generates and maintains grounded, enterprise-grade documentation for any codebase — by analyzing real project artifacts (source tree, git history, package manifests, env files, existing docs), never fabricating facts. Every claim in a generated document either traces back to something the server's own analyzers actually found, or is explicitly labeled an assumption — never silently blended into the narrative as if it were fact.

Contents

• Setup Guide

• Usage Guide

• Integrating with AI Agents / MCP Clients

  • Claude Code

  • Claude Desktop

  • Cursor

  • Windsurf

  • Antigravity

  • VS Code (Copilot Chat / MCP)

  • Cline

  • Continue.dev

  • Zed

  • Gemini CLI

  • JetBrains AI Assistant

  • Any other MCP client

• Tools

• Documentation

• Status

• Contributing

• Security

• License

Related MCP server: Documentation MCP Server

Setup Guide

Prerequisites

• Node.js >= 20

• An Anthropic API key — required for analyze_project and generate_readme's narrated sections; generate_env_docs, generate_changelog, and review_documentation are fully deterministic and work without a real key (see docs/Testing.md), but this server only ever talks to Anthropic — it validates ANTHROPIC_API_KEY against Anthropic's own key shape (sk-ant-...) at startup and refuses to boot with a key from another provider, a typo, or an empty value, even if you only intend to use the deterministic tools (see docs/Configuration.md)

There are two ways to run this server: install the published npm package (recommended for everyone using it as a tool), or build from source (for contributors).

Option A — Install from npm (recommended)

Nothing to clone or build — every client config in this README uses npx, which downloads and caches the package on first run:

npx -y docs-assistant-mcp

The server speaks MCP over stdio — running it directly in a terminal will look like it hangs; that's expected, it's waiting for a client to connect over stdin/stdout. It's meant to be launched by an MCP client (see below), not run standalone. Set ANTHROPIC_API_KEY as an environment variable — everything else has a sensible default, see docs/Configuration.md.

Prefer a global install instead of npx re-resolving on every launch:

npm install -g docs-assistant-mcp
docs-assistant-mcp

Option B — Build from source (for contributors)

git clone <this-repo-url>
cd docs-assistant-mcp
pnpm install   # pnpm >= 9; `corepack enable` provides it on most systems
cp .env.example .env

Open .env and set at minimum:

ANTHROPIC_API_KEY=sk-ant-...

pnpm build     # produces dist/index.js, a self-contained ESM bundle with a shebang
node dist/index.js

During development, pnpm dev runs the server straight from TypeScript source with hot reload. See CONTRIBUTING.md and docs/Development.md for the full local workflow.

Verify it's working

Point any MCP client at the server (npx -y docs-assistant-mcp, or dist/index.js if built from source) and list its tools — Milestone 1 ships five (analyze_project, generate_env_docs, generate_changelog, generate_readme, review_documentation), and Milestone 2 has begun with generate_architecture (12 more tools are specified in docs/Tool-Reference.md and land in later milestones). See docs/Troubleshooting.md if the server exits immediately (almost always a missing/invalid ANTHROPIC_API_KEY).

Usage Guide

Step 1 — Understand a project

Ask your AI agent something like:

"Analyze the project at /path/to/my-project"

which drives a call like:

{ "tool": "analyze_project", "arguments": { "projectPath": "/absolute/path/to/my-project" } }

The server scans the project's filesystem, git history, package manifests, and env files, runs every deterministic analyzer (technology detection, complexity, documentation coverage, risk findings), and asks Claude to narrate a grounded summary and architecture description. Every claim in the response traces back to a fact the analyzers actually computed — anything the model infers beyond that is returned separately in assumptions[], never blended into the narrative.

Step 2 — Generate documentation

{ "tool": "generate_readme", "arguments": { "projectPath": "/absolute/path/to/my-project" } }

Returns a ready-to-use README.md. Overview/Features/Usage/Troubleshooting are narrated and grounded; Installation/Configuration/Contributing/License are generated deterministically straight from facts (the actual install command for the detected package ecosystem, an actual table of env vars, whether a LICENSE/CONTRIBUTING file really exists) — nothing here is guessed.

{ "tool": "generate_env_docs", "arguments": { "projectPath": "/absolute/path/to/my-project" } }
{ "tool": "generate_changelog", "arguments": { "projectPath": "/absolute/path/to/my-project" } }

Both fully deterministic. generate_env_docs documents every environment variable a project declares or reads, without ever reading a real .env file's actual values. generate_changelog groups real commits into Breaking Changes/Features/Fixes/Other via conventional-commit types — optionally scoped with fromRef/toRef (e.g. two tags).

Step 3 — Review what already exists

{ "tool": "review_documentation", "arguments": { "projectPath": "/absolute/path/to/my-project" } }

Returns coverageScore/qualityScore/consistencyScore (0–100 each) plus missingSections[]/recommendations[] — works against hand-written docs alone, no other generator needs to have run first.

Step 4 — Document the architecture

{ "tool": "generate_architecture", "arguments": { "projectPath": "/absolute/path/to/my-project" } }

Returns content (Architecture.md), plus its parts separately: layers[]/modules[] (from the real src/ directory structure), dependencyGraph (Mermaid, built from real relative-import statements), dataFlow (Mermaid), designPatterns[] (evidence-grounded, from real class names — e.g. a FooRepository class is Repository-pattern evidence, two classes implementing the same interface is Strategy-pattern evidence), techStack[], and decisions[] (titles pulled from docs/adr/*.md, if any exist). Only the overview paragraph is narrated; everything else is rendered deterministically from what the scan actually found.

What's next (Milestone 2+)

generate_database_docs, generate_api_docs, and diagram generators round out Milestone 2; deployment/security/testing docs and release notes land in Milestone 3; PRD/TRD/contribution guide in Milestone 4; synchronize_docs (incremental regeneration) in Milestone 5. See docs/Tool-Reference.md for the full contract of every planned tool, and PLANNING.md for the full roadmap rationale.

Tips

• Pass an absolute projectPath, not relative — this server reads the filesystem directly on the machine it runs on; it has no notion of your AI agent's current working directory.

• If a generated document's assumptions[] array is non-empty, that's the server telling you exactly what it couldn't ground in a fact — not a bug.

• generate_changelog needs a real git repository at projectPath; it returns a VALIDATION_ERROR otherwise rather than fabricating history.

Integrating with AI Agents / MCP Clients

The server is a standard MCP server over stdio — command: npx, args: ["-y", "docs-assistant-mcp"], plus whatever env vars you need from docs/Configuration.md. Every client below just wants that triple in a slightly different place; npx -y downloads and caches the published npm package on first run, so there's nothing to clone or build first.

Built from source instead? Swap "command": "npx", "args": ["-y", "docs-assistant-mcp"] for "command": "node", "args": ["/absolute/path/to/docs-assistant-mcp/dist/index.js"] in any of the configs below — an absolute path, since relative paths resolve against the client's working directory, not this repo.

Claude Code

claude mcp add docs-assistant \
  --scope project \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -- npx -y docs-assistant-mcp

(--scope project writes to .mcp.json, committable so your team gets it too; use --scope user for a personal, machine-wide registration instead.) Or edit .mcp.json directly:

{
  "mcpServers": {
    "docs-assistant": {
      "command": "npx",
      "args": ["-y", "docs-assistant-mcp"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

Run claude mcp list to confirm it's registered, then ask Claude Code to analyze or document a project — it will discover and call the tools directly.

Claude Desktop

Edit the config file (create it if it doesn't exist):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "docs-assistant": {
      "command": "npx",
      "args": ["-y", "docs-assistant-mcp"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

Restart Claude Desktop afterward — new servers are only picked up on launch.

Cursor

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for a global registration):

{
  "mcpServers": {
    "docs-assistant": {
      "command": "npx",
      "args": ["-y", "docs-assistant-mcp"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

Cursor picks up project-scoped MCP servers automatically; you can also manage them under Settings → MCP.

Windsurf

Windsurf → Settings → Cascade → MCP Servers → "View raw config" opens ~/.codeium/windsurf/mcp_config.json for direct editing:

{
  "mcpServers": {
    "docs-assistant": {
      "command": "npx",
      "args": ["-y", "docs-assistant-mcp"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

Antigravity

Antigravity supports MCP servers via the same command/args/env shape used above, managed through its MCP/tools settings panel (look for "MCP Servers" or "Manage MCP" in Settings):

{
  "mcpServers": {
    "docs-assistant": {
      "command": "npx",
      "args": ["-y", "docs-assistant-mcp"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

VS Code (Copilot Chat / MCP)

VS Code's built-in MCP support uses a servers key (not mcpServers) and an explicit type. Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "docs-assistant": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "docs-assistant-mcp"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

VS Code will prompt to start the server the first time you open the workspace; use the "MCP: List Servers" command afterward to confirm it connected.

Cline

Cline (VS Code extension) stores MCP config in cline_mcp_settings.json:

• macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

• Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

• Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

{
  "mcpServers": {
    "docs-assistant": {
      "command": "npx",
      "args": ["-y", "docs-assistant-mcp"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

Continue.dev

Continue uses YAML, not JSON — add an entry under the top-level mcpServers key in config.yaml (or drop a standalone file under .continue/mcpServers/):

mcpServers:
  - name: docs-assistant
    command: npx
    args:
      - -y
      - docs-assistant-mcp
    env:
      ANTHROPIC_API_KEY: sk-ant-...

Zed

Zed uses a context_servers key (not mcpServers) with a source: "custom" field, in settings.json:

{
  "context_servers": {
    "docs-assistant": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "docs-assistant-mcp"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

Gemini CLI

Add to mcpServers in ~/.gemini/settings.json (user-scope) or .gemini/settings.json (project-scope):

{
  "mcpServers": {
    "docs-assistant": {
      "command": "npx",
      "args": ["-y", "docs-assistant-mcp"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

JetBrains AI Assistant

Settings → Tools → AI Assistant → Model Context Protocol (MCP) → "Command" (top-left of the dialog) → "As JSON":

{
  "mcpServers": {
    "docs-assistant": {
      "command": "npx",
      "args": ["-y", "docs-assistant-mcp"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

Works the same way across IntelliJ IDEA, WebStorm, PyCharm, and other JetBrains IDEs with the AI Assistant plugin installed.

Any other MCP client

Any client that speaks MCP over stdio works the same way: launch npx -y docs-assistant-mcp, pass ANTHROPIC_API_KEY (and any other vars from docs/Configuration.md) as environment variables, and let the client's tool-discovery handshake do the rest. See docs/API.md for the wire-level details.

Tools

Full contracts (including planned tools): docs/Tool-Reference.md.

Documentation

Planning & Architecture Proposal · Architecture · Tool Reference · Configuration · API · Security Guide · Development · Deployment · Testing · Troubleshooting · ADRs

Status

Milestone 1 (5 tools) is complete. Milestone 2 has begun: generate_architecture is implemented and tested; generate_database_docs, generate_api_docs, and the diagram generators remain. See PLANNING.md §13 for the full 5-milestone roadmap through diagrams, deployment/security/testing docs, PRD/TRD, and incremental synchronization.

Contributing

Bug reports, feature requests, and pull requests are welcome — see CONTRIBUTING.md for the local dev setup and PR checklist. Participation is governed by the Code of Conduct.

Security

This server reads real project artifacts (source, git history, .env.example-style files) and calls the Anthropic API for narrated sections — see SECURITY.md for the vulnerability-reporting process and docs/Security-Guide.md for what's actually implemented (secret redaction, filesystem sandboxing, prompt-injection framing, fact-grounding).

License

Apache License 2.0