@goalgrid/ai-dev-mcp

An AI Developer Assistant MCP server. It scans any software project, writes a hidden .ai/ knowledge folder, and exposes coding-assistant tools to Cursor, Claude Desktop, and Claude Code so the assistant understands the whole codebase before it changes anything.

Status — Milestone 4 (the full assistant). Ships 11 static knowledge artifacts (no key needed) plus 11 tools. The mutating tools are diff-first: they return a per-file unified diff and write nothing unless apply: true. LLM tools need ANTHROPIC_API_KEY. See docs/ai-dev-assistant/00-BLUEPRINT.md.

Tools

| Tool | LLM? | Writes? | What it does | |------|------|---------|--------------| | scan_project | no | .ai/ | Walk + static-analyze; (re)write the 11 .ai/ artifacts. Incremental. | | search_code | no | no | Text/regex search with an optional path glob → file:line + snippets. | | find_related_files | no | no | Import-graph neighbours (imports / imported-by / siblings / tests). | | analyze_codebase | yes | PROJECT_FLOW.md | The A-to-Z walkthrough + AI change-playbook. Cached. | | explain_code | yes | no | Explain one file, grounded in its source + related files. | | plan_feature | yes | audit | Plan before coding: impacted files, steps, risks, test plan, open questions. | | modify_code | yes | opt-in | Change existing code → per-file diff. Writes only with apply: true. | | generate_code | yes | opt-in | Create new code for a feature → diff. Writes only with apply: true. | | generate_tests | yes | opt-in | Write a test file for a target (auto-detects framework). Diff-first. | | fix_errors | yes | opt-in | Detect (tsc) or accept errors → smallest fixes; reports before/after counts. | | review_code | yes | no | Review the git diff (or a file) → scored, actionable findings. |

Every mutating apply is recorded in .ai/decisions.json (audit trail). LLM tools read ANTHROPIC_API_KEY from the environment or a .env.local at the project root; their outputs are cached under .ai/.cache/llm/ (an unchanged prompt never pays twice).

What it generates

Running a scan writes <project>/.ai/:

| File | Contents | |------|----------| | manifest.json | Index + rootHash (Merkle of file hashes) for incremental re-scans. Read first. | | project.json | Name, type, languages (%), frameworks + versions, package manager, build tools, scripts, entry points. | | files-index.json | Every source file: type, role, size, content hash, imports, exports. | | architecture.json | Layers, module dependency graph (+ Mermaid), entry points, static summary. | | component-map.json | UI components: client/server, props, hooks, rendered children. | | api-map.json | Server routes (methods/kind) ↔ client fetch/axios calls, external APIs. | | database-map.json | DB type, models, fields, relations, enums, query-usage sites (Prisma parser). | | dependency-map.json | Declared deps + usage counts, unused, missing (imported-not-declared), risky. | | security-report.json | Secrets (redacted), XSS/eval/command-injection patterns, with severities. | | performance-report.json | Large files, heavy components, sync I/O, bundle/render risks + suggestions. | | code-quality.json | Metrics, TODOs, complex files, rolling-hash duplication, smells. |

Heuristic static reports are high-recall by design; precision re-ranking is the job of the later LLM pass (Milestone 3).

Install

# from the repo root
npm install            # installs workspace deps incl. @modelcontextprotocol/sdk
npm run build -w @goalgrid/ai-dev-mcp   # compiles to packages/mcp/dist/

Try it without a client (CLI)

# scan a project and write its .ai/ folder
npx tsx packages/mcp/src/cli.ts /path/to/project --validate

# or, after building:
node packages/mcp/dist/cli.js /path/to/project

Flags: --force (re-scan even if unchanged), --max <n> (cap files), --validate (check every artifact against the schema).

Add to Cursor

.cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "ai-dev-mcp": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/packages/mcp/dist/index.js"],
      "env": { "AI_DEV_MCP_ROOT": "/ABSOLUTE/PATH/TO/your-project" }
    }
  }
}

Add to Claude Desktop

claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "ai-dev-mcp": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/packages/mcp/dist/index.js"],
      "env": { "AI_DEV_MCP_ROOT": "/ABSOLUTE/PATH/TO/your-project" }
    }
  }
}

Add to Claude Code

claude mcp add ai-dev-mcp -- node /ABSOLUTE/PATH/TO/packages/mcp/dist/index.js

Then ask the assistant to "scan the project" — it calls scan_project, which writes .ai/. Every later tool reads that folder first, so the assistant always works from an accurate map of your codebase.

Remote connector (HTTP) — for Claude Desktop / claude.ai

Claude Desktop sandboxes local (stdio) MCP servers, so a stdio server that lives on a remote box (e.g. reached over SSH) won't stay connected there. For a remote MCP, run the HTTP transport and add it as a custom connector URL.

Run it on the server (token is REQUIRED — the endpoint is network-exposed):

AI_DEV_MCP_TRANSPORT=http \
AI_DEV_MCP_PORT=8787 \
AI_DEV_MCP_TOKEN="$(openssl rand -hex 24)" \
AI_DEV_MCP_ROOT=/abs/path/to/project \
node packages/mcp/dist/index.js
# → listens on :8787/mcp ; GET / is an unauthenticated health check

Put it behind HTTPS (Claude requires a valid TLS URL) — e.g. Nginx on your domain proxying https://your-domain/mcp → http://127.0.0.1:8787/mcp. Then in Claude Desktop/▸ Settings → Connectors → Add custom connector, enter the URL https://your-domain/mcp and the bearer token. All requests must send Authorization: Bearer <AI_DEV_MCP_TOKEN>.

Notes

• AI_DEV_MCP_ROOT sets the default project root; a tool's root argument overrides it.
• The server speaks JSON-RPC on stdout — all logs go to stderr. Never add console.log to server code.
• Re-runs are incremental: if rootHash is unchanged, nothing is rewritten.