# 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](#setup-guide)
- [Usage Guide](#usage-guide)
- [Integrating with AI Agents / MCP Clients](#integrating-with-ai-agents--mcp-clients)
  - [Claude Code](#claude-code)
  - [Claude Desktop](#claude-desktop)
  - [Cursor](#cursor)
  - [Windsurf](#windsurf)
  - [Antigravity](#antigravity)
  - [VS Code (Copilot Chat / MCP)](#vs-code-copilot-chat--mcp)
  - [Cline](#cline)
  - [Continue.dev](#continuedev)
  - [Zed](#zed)
  - [Gemini CLI](#gemini-cli)
  - [JetBrains AI Assistant](#jetbrains-ai-assistant)
  - [Any other MCP client](#any-other-mcp-client)
- [Tools](#tools)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [Security](#security)
- [License](#license)

---

## Setup Guide

### Prerequisites

- Node.js >= 20
- An [Anthropic API key](https://console.anthropic.com/) — 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](./docs/Testing.md#testing-without-a-real-anthropic-key)), 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](./docs/Configuration.md#anthropic_api_key-validation))

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:

```bash
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](#integrating-with-ai-agents--mcp-clients)), not run
standalone. Set `ANTHROPIC_API_KEY` as an environment variable — everything else has a sensible
default, see [docs/Configuration.md](./docs/Configuration.md).

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

```bash
npm install -g docs-assistant-mcp
docs-assistant-mcp
```

### Option B — Build from source (for contributors)

```bash
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:

```bash
ANTHROPIC_API_KEY=sk-ant-...
```

```bash
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](./CONTRIBUTING.md) and [docs/Development.md](./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](#tools) table below, or
[docs/Tool-Reference.md](./docs/Tool-Reference.md) for full contracts). See
[docs/Troubleshooting.md](./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:

```json
{ "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

```json
{ "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.

```json
{ "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

```json
{ "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

```json
{ "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

```json
{ "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.

```json
{ "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

```json
{ "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](./docs/Configuration.md) — 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

```json
{ "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

```json
{
  "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](./docs/Tool-Reference.md#synchronize_docs)).

### 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](./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

```bash
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:

```json
{
  "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`

```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):

```json
{
  "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:

```json
{
  "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):

```json
{
  "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:

```json
{
  "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`

```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/`):

```yaml
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`:

```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):

```json
{
  "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":

```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](./docs/Configuration.md)) as environment variables, and let the client's
tool-discovery handshake do the rest. See [docs/API.md](./docs/API.md#connecting) 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](./docs/Tool-Reference.md).

## Documentation

[Architecture](./docs/Architecture.md) ·
[Tool Reference](./docs/Tool-Reference.md) · [Configuration](./docs/Configuration.md) ·
[API](./docs/API.md) · [Security Guide](./docs/Security-Guide.md) ·
[Development](./docs/Development.md) · [Deployment](./docs/Deployment.md) ·
[Testing](./docs/Testing.md) · [Troubleshooting](./docs/Troubleshooting.md) ·
[ADRs](./docs/adr/)

## Contributing

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

## 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](./SECURITY.md) for the
vulnerability-reporting process and [docs/Security-Guide.md](./docs/Security-Guide.md) for what's
actually implemented (secret redaction, filesystem sandboxing, prompt-injection framing,
fact-grounding).

## License

[Apache License 2.0](./LICENSE)