ai-intake-documentation-mcp

An MCP server that onboards a codebase for AI-agent-assisted development: it scans the project, asks the questions only a human can answer (purpose, target users, constraints), and maintains living documentation under .ai/ — one set for humans, one distilled for AI coding agents — built from an append-only evidence archive so nothing is lost and every fact is traceable.

Works with Claude Code, Gemini CLI, or any other MCP-capable client, and alongside (but independently of) ai-intake-mcp, a separate Jira ticket-execution harness.

Status

Phase 1 + Phase 2 done, plus a plans lifecycle: scan a repo, detect/initialize .ai/, record evidence, ingest pre-existing/legacy .ai/ content, fold evidence into polished docs, detect drift, and track plans through draft/active/completed. See .ai/docs/project-context.md for the full picture and .ai/evidence/onboarding/ for the design record this was built from.

All Jira ticket work and all planning work must have a plan file under .ai/plans/ — see the Tools table below.

Related MCP server: codebase-doc-generator

Why documentation lives in two places

• .ai/docs/ — narrative, for a human building a mental model: rationale, history, "why we chose X over Y."

• .ai/context/ — distilled, for an AI agent: terse factual statements and business rules, chunked so a harness can load only what's relevant to a given task instead of everything.

Both are regenerated from .ai/evidence/, an append-only archive of raw human answers, agent discoveries, and corrections — the evidence is the actual source of truth; the docs are a view onto it. See .ai/docs/architecture.md for the full schema.

Repo structure

packages/
  context-schema/       @dmahal/context-schema — shared .ai/ types, validators, fs helpers
  documentation-mcp/     @dmahal/documentation-mcp — the MCP server
.ai/                      this project's own onboarding output (dogfooded)
  plans/                    draft/ active/ completed/ — required for all ticket + planning work

A monorepo purely for development convenience (one commit can touch the schema and its consumer together) — each package still publishes to npm independently.

Getting started

npm install
npm run build          # builds both packages

Build context-schema before documentation-mcp if building manually with tsc instead of the root script — the server imports the schema package's compiled output.

Add it to an MCP client

Claude Code (.mcp.json at a repo root, or claude mcp add):

{
  "mcpServers": {
    "documentation-mcp": {
      "command": "node",
      "args": ["path/to/ai-intake-documentation-mcp/packages/documentation-mcp/dist/index.js"]
    }
  }
}

Gemini CLI (~/.gemini/settings.json or .gemini/settings.json) uses the same mcpServers/command/args shape.

This repo's own .mcp.json already points at the local build, so it's usable directly from a Claude Code session opened here. Once published to npm, command/args becomes npx -y @dmahal/documentation-mcp instead of a local path — identical config in both clients.

Tools

Typical call order: detect_ai_dir → (init_ai_scaffold or, if non-conformant, propose_ai_dir_migration → apply_ai_dir_migration) → scan_project → record_evidence (as needed) → list_evidence → write_doc / write_context_chunk → get_setup_status / check_drift. Independently, for any ticket or planning work: write_plan → transition_plan (draft → active on approval → completed when done).

Relationship to ai-intake-mcp

ai-intake-mcp is a separate, already-existing repo — a Jira ticket-execution harness (tracker_get_issue, implement_ticket, approve_plan, worktree_create, etc.) that auto-writes .ai/intake-mcp.json on first tracker use. This project never touches that file. The two stay separate servers (different lifecycle, different blast radius) but share the .ai/ schema via @dmahal/context-schema, so their file layout can't drift even though they're released independently. The planned integration — the harness reading .ai/context/ during planning and calling record_evidence during implementation — is tracked as future work, not yet built here.

Development

• npm run build — builds both packages (tsc).

• npm run clean — removes dist/ in both packages.

• npm test — runs the Vitest suite (packages/*/test/**/*.test.ts), covering everything the manual smoke-test scripts used to: detect_ai_dir/init_ai_scaffold states, scan_project's depth search and existing_agent_docs detection, evidence recording + synthesis, the legacy-.ai/ migration flow, the plans lifecycle (including the collision-suffix case), and upgrade_ai_dir (missing-directory backfill, an unmigratable schema_version failing cleanly, non-conformant repos left untouched).

• CI (.github/workflows/ci.yml) runs npm run build + npm test on push/PR to main.

License

MIT