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
• Contributing
• Security
• License

---

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 — all 18 should appear (see the Tools table below, or docs/Tool-Reference.md for full contracts). 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.

Step 5 — Document the database, API, and system flows

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

Both fully deterministic. generate_database_docs reads a real schema.prisma (or a .sql file with a CREATE TABLE statement) — tables, columns, relations, indexes, a Mermaid ER diagram, and business rules inferred from real naming conventions (soft-delete columns, audit timestamps, required vs. optional foreign keys). generate_api_docs prefers a real OpenAPI/Swagger spec when one exists in the project; otherwise it falls back to regex-extracted Express/Fastify/NestJS routes from source, and the source field in the response always says which.

{ "tool": "generate_sequence_diagram", "arguments": { "projectPath": "/absolute/path/to/my-project", "flowSteps": [{ "from": "Client", "to": "API", "message": "POST /orders" }] } }
{ "tool": "generate_flow_diagram", "arguments": { "projectPath": "/absolute/path/to/my-project", "flowType": "auth" } }

Both render Mermaid + PlantUML. generate_sequence_diagram either renders flowSteps you supply verbatim (zero inference), or — given traceHint instead — does a static regex reference scan for that symbol across JS/TS source, labeled "code-reference" since it's not a true runtime trace. generate_flow_diagram builds user/application/request/auth/deployment/data flows strictly from real evidence (layer directories, detected auth/infra dependencies) — a flow type with no supporting evidence returns a notes[] explanation instead of an invented diagram.

Step 6 — Document releases, deployment, security, and testing

{ "tool": "generate_release_notes", "arguments": { "projectPath": "/absolute/path/to/my-project", "fromTag": "v1.0.0", "toTag": "v1.1.0" } }
{ "tool": "generate_deployment_docs", "arguments": { "projectPath": "/absolute/path/to/my-project" } }
{ "tool": "generate_security_docs", "arguments": { "projectPath": "/absolute/path/to/my-project" } }
{ "tool": "generate_testing_docs", "arguments": { "projectPath": "/absolute/path/to/my-project" } }

All four fully deterministic. generate_release_notes groups real commits between two refs/tags by conventional-commit type; set includePrs: true to also include real merged GitHub PRs (requires GITHUB_TOKEN, see Configuration — returns an empty list otherwise, never fabricated PR data). generate_deployment_docs reads real Dockerfile/docker-compose/Kubernetes manifest/Terraform files for scaling and rollback guidance. generate_security_docs reports real auth/RBAC/encryption dependency evidence and a real .gitignore/env-var check, plus an OWASP Top 10 checklist that honestly marks categories "not-detected" when nothing in the project can confirm them either way. generate_testing_docs reports the real detected test framework, real unit/integration/e2e file counts by directory convention, and real coverage-config presence.

Step 7 — Product/technical requirements and contribution docs

{ "tool": "generate_trd", "arguments": { "projectPath": "/absolute/path/to/my-project" } }
{ "tool": "generate_contribution_guide", "arguments": { "projectPath": "/absolute/path/to/my-project" } }
{ "tool": "generate_prd", "arguments": { "projectPath": "/absolute/path/to/my-project", "requirementsHint": "Focus on the billing module." } }

generate_trd and generate_contribution_guide are fully deterministic: the TRD composes the real content every other structural tool above already produced for the same project (a roll-up, not a new source of facts); the contribution guide renders real install/test/lint/build commands from your package manifest. generate_prd is the one tool in this server that calls the LLM — grounded in the same facts analyze_project uses, plus your optional requirementsHint. It's the highest-inference tool here, so expect a longer assumptions[] array than the structural tools above; that's the grounding mechanism working as intended, not a bug.

Step 8 — Keep docs in sync

{
  "tool": "synchronize_docs",
  "arguments": {
    "projectPath": "/absolute/path/to/my-project",
    "manifest": [
      {
        "path": "docs/Security.md",
        "tool": "generate_security_docs",
        "lastGeneratedHash": "<hash you recorded last time>"
      }
    ]
  }
}

Fully deterministic. For each manifest entry, reads the doc directly off disk: if its current hash doesn't match lastGeneratedHash, it was hand-edited since it was last generated and comes back as a conflicts[] entry — never overwritten. Otherwise it's regenerated and reported as skipped (unchanged) or updated (with fresh content for you to write and the new hash to record). Only supports the fully deterministic content tools above (generate_readme/ generate_architecture/generate_prd call the LLM, so hash-comparing their output isn't meaningful — see docs/Tool-Reference.md).

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

All 18 tools are implemented.

Tool	Purpose
analyze_project	Grounded project summary, architecture, complexity, coverage, risks, recommendations
generate_env_docs	Document every environment variable, never exposing secret values
generate_changelog	Markdown changelog from real git history, grouped by conventional-commit type
generate_readme	Grounded README with deterministic Installation/Configuration/Contributing/License
review_documentation	Score existing docs on coverage/quality/consistency, list gaps
generate_architecture	Architecture.md: layers, modules, patterns, dependency graph
generate_database_docs	Tables, relations, indexes, ER diagram, business rules from a real Prisma/SQL schema
generate_api_docs	Endpoint docs from a real OpenAPI/Swagger spec, or code-derived routes as a fallback
generate_sequence_diagram	Mermaid + PlantUML sequence diagram from caller-supplied steps or a static symbol trace
generate_flow_diagram	User/application/request/auth/deployment/data flow diagrams grounded in real evidence
generate_release_notes	Release notes from real commits, optionally + real merged GitHub PRs
generate_deployment_docs	Deployment/scaling/rollback guide from real Dockerfile/docker-compose/K8s/Terraform
generate_security_docs	Auth/RBAC/encryption/secrets evidence + an OWASP Top 10 checklist
generate_testing_docs	Testing strategy from the real test suite structure
generate_prd	Product Requirements Document, grounded + heavily assumption-flagged
generate_trd	Technical Requirements Document, composed from the other tools' real output
generate_contribution_guide	CONTRIBUTING.md from real install/test/lint/build commands
synchronize_docs	Regenerate only docs whose real content actually changed, via content hashing

Full contracts: docs/Tool-Reference.md.

Documentation

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

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