diff --git a/apps/web/src/components/landing/AgentsSection.astro b/apps/web/src/components/landing/AgentsSection.astro index c8b4dc9..61317c3 100644 --- a/apps/web/src/components/landing/AgentsSection.astro +++ b/apps/web/src/components/landing/AgentsSection.astro @@ -31,7 +31,8 @@ const reads = [

Works with every agent.

One devmap analyze for Claude Code, Codex, Cursor, Gemini CLI, - OpenCode and more. If a tool can read files, it can read the map. + OpenCode and more. If a tool can read files, it can read the map. If it + speaks MCP, it can ask for it.

Use it with your agent diff --git a/apps/web/src/components/landing/CommandsSection.astro b/apps/web/src/components/landing/CommandsSection.astro index cecc50d..41a1e2c 100644 --- a/apps/web/src/components/landing/CommandsSection.astro +++ b/apps/web/src/components/landing/CommandsSection.astro @@ -14,7 +14,7 @@ function parse(line: string): { kind: Kind; text: string } {
-

Eight commands.

+

Nine commands.

Pick one and see what it prints. Most of them need no API key.

diff --git a/apps/web/src/components/landing/HeroSection.astro b/apps/web/src/components/landing/HeroSection.astro index c450cea..a406a3e 100644 --- a/apps/web/src/components/landing/HeroSection.astro +++ b/apps/web/src/components/landing/HeroSection.astro @@ -22,7 +22,8 @@ const log: Array<{ text: string; tone?: "ok" | "dim" | "hot" }> = [

DevMap reads your codebase and writes a map that developers and AI agents - start from: entry points, critical files, features and routes. + start from: entry points, critical files, features and routes. Read it as + files, or let your agent ask over MCP.

diff --git a/apps/web/src/components/landing/McpSection.astro b/apps/web/src/components/landing/McpSection.astro new file mode 100644 index 0000000..0cca3ec --- /dev/null +++ b/apps/web/src/components/landing/McpSection.astro @@ -0,0 +1,222 @@ +--- +import CopyCommand from "./CopyCommand.astro"; +import { MCP_ADD_COMMAND, MCP_CONFIG, MCP_TOOLS } from "../../data/mcp"; + +const steps = [ + { n: "1", title: "Analyze once", text: "Run devmap analyze in the project. It writes .devmap/snapshot.json." }, + { n: "2", title: "Register the server", text: "Add the command below to Claude Code, or the config to Cursor, Codex and opencode." }, + { n: "3", title: "Ask the agent", text: "It calls the tools it needs instead of reading the whole map up front." } +]; +--- + +
+
+

Or let the agent ask.

+

+ devmap mcp runs DevMap as an MCP server. The agent calls a tool + and gets structured JSON back, so it reads only the part of the map it + needs. Read-only by default, and every answer says if the snapshot is stale. +

+
+ +
+
    + {steps.map((step, i) => ( +
  1. + +
    +

    {step.title}

    +

    {step.text}

    +
    +
    2. + ))} +
+ +
+

Claude Code

+ + +

+ Nothing is sent anywhere. --auto-refresh and --allow-ai are opt-in. +

+
+
+ +
    + {MCP_TOOLS.map((tool, i) => ( +
  • + {tool.name} +

    {tool.text}

    + {tool.needsAi && needs --allow-ai} +
    • + ))} +
+ +
+ MCP setup for your client +
+
+ + diff --git a/apps/web/src/components/landing/SiteHeader.astro b/apps/web/src/components/landing/SiteHeader.astro index 84140b8..a3b47ab 100644 --- a/apps/web/src/components/landing/SiteHeader.astro +++ b/apps/web/src/components/landing/SiteHeader.astro @@ -1,6 +1,7 @@ --- const links = [ { href: "/#agents", label: "Agents" }, + { href: "/#mcp", label: "MCP" }, { href: "/#commands", label: "Commands" }, { href: "/#frameworks", label: "Frameworks" }, { href: "/docs", label: "Docs" } diff --git a/apps/web/src/content/docs/overview.md b/apps/web/src/content/docs/overview.md index 599d368..6b93881 100644 --- a/apps/web/src/content/docs/overview.md +++ b/apps/web/src/content/docs/overview.md @@ -1,6 +1,6 @@ --- title: "DevMap Docs: install, commands and supported frameworks" -description: "Install DevMap, run devmap init and analyze, read the generated .devmap files and use them with AI agents. Commands, supported JS/TS frameworks and privacy." +description: "Install DevMap, run devmap init and analyze, read the generated .devmap files and use them with AI agents or as an MCP server. Commands, supported JS/TS frameworks and privacy." --- # DevMap Docs @@ -147,6 +147,43 @@ Recommended reading order for agents (also written into `DEVMAP.md` / `AGENTS.md Works with Claude Code, OpenAI Codex, Gemini CLI, Cursor, GitHub Copilot, and any agent that can read files or consume `--json` output. +### Use it as an MCP server + +`devmap mcp` runs DevMap as a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio. Instead of reading a context file at the start, the agent calls a tool and gets structured JSON for just the part it needs. Analyze once, then register the server: + +```bash +devmap analyze +claude mcp add devmap -- npx -y @flaid/devmap mcp +``` + +Other clients launch the same command (`npx -y @flaid/devmap mcp`). For Cursor, Codex, opencode and any stdio client: + +```json +{ + "mcpServers": { + "devmap": { + "command": "npx", + "args": ["-y", "@flaid/devmap", "mcp"] + } + } +} +``` + +Most clients start the server in the folder you opened. If yours does not, add `--root /absolute/path/to/project`. The first `npx` download can exceed a client's startup timeout, so after `npm install -g @flaid/devmap` use `devmap` as the command with `mcp` as the argument. + +| Tool | What it does | +|---|---| +| `devmap_overview` | Framework, entry points, critical files, features and flows. Start here | +| `devmap_map` | Dependency map of the project, one feature or one file | +| `devmap_flow` | Trace a feature or API request end to end | +| `devmap_routes` | List page and API routes | +| `devmap_impact` | What is affected if a file changes | +| `devmap_find` | Find features, files and routes by keyword | +| `devmap_analyze` | Re-analyze and refresh the snapshot, writing only inside `.devmap/` | +| `devmap_explain` | AI explanation of a file, feature or function. Only with `--allow-ai` | + +The server is read-only by default and runs static analysis only. Every answer includes `snapshot: { generatedAt, stale }` so the agent knows when to refresh. Full client setup and tool inputs: [docs/mcp.md](https://github.com/itsflaid/devmap/blob/main/docs/mcp.md). + --- ## Why not just point my AI agent at the repo? @@ -232,6 +269,22 @@ Diagnostics for a broken setup. Checks DevMap version, Node version, provider/AP devmap doctor ``` +### `devmap mcp` + +Runs DevMap as an MCP server over stdio. Started by your agent's client, not by hand. See [Use it as an MCP server](#use-it-as-an-mcp-server). + +```bash +devmap mcp [--root ] [--auto-refresh] [--allow-ai] +``` + +| Flag | Default | Effect | +|---|---|---| +| `--root ` | current folder | Project root that contains `.devmap/snapshot.json` | +| `--auto-refresh` | off | Re-analyze when the snapshot is stale or missing, before answering | +| `--allow-ai` | off | Let analysis use your AI provider and expose `devmap_explain` | + +stdout carries the JSON-RPC stream only. Logs go to stderr. + ### `devmap config model ` Override the model used for AI-powered commands, or restore automatic routing. @@ -255,6 +308,7 @@ devmap config model llama-3.1-8b-instant --local | `.devmap/index.json` | AI agent entry point | | `.devmap/features/*.json` | Feature-level navigation | | `.devmap/snapshot.json` | Full project intelligence, source of truth | +| `.devmap/analyze.lock` | Temporary lock while the MCP server re-analyzes, removed when done | | `.devmap/maps/*` | `devmap map` output (`.md` + `.mermaid`) | | `.devmap/flows/*` | `devmap flow` output (`.md` + `.mermaid`) | | `.devmap/config.local.json` | Optional per-project model override, not committed (`.devmap/` is gitignored) | @@ -276,6 +330,8 @@ Straight from `devmap doctor`'s real checks: - **Snapshot missing or corrupt** → `devmap analyze --fresh` - **Model unavailable** → `devmap init` or `devmap config model ` - **Node version unsupported** → upgrade to Node.js 22.12+ +- **MCP client times out on start** → install globally (`npm install -g @flaid/devmap`) and use `devmap` with the argument `mcp` instead of `npx` +- **MCP answers say `stale: true`** → ask the agent to call `devmap_analyze`, or start the server with `--auto-refresh` --- diff --git a/apps/web/src/data/commands.ts b/apps/web/src/data/commands.ts index 0d7adc1..779f71c 100644 --- a/apps/web/src/data/commands.ts +++ b/apps/web/src/data/commands.ts @@ -1,5 +1,5 @@ /** - * The eight commands shown in the command explorer. + * The nine commands shown in the command explorer. * * `out` lines use a one-character prefix for styling: * "§ " section heading "· " dim / secondary "+ " highlighted @@ -14,7 +14,7 @@ * To refresh the real ones: build packages/cli, copy the repo somewhere outside git, run * `node packages/cli/dist/index.js ` there, and trim the output. Do not edit lines by hand. */ -export type CommandGroup = "Set up" | "Map" | "Read"; +export type CommandGroup = "Set up" | "Map" | "Read" | "Serve"; export interface CommandEntry { id: string; @@ -204,13 +204,24 @@ export const COMMANDS: CommandEntry[] = [ "", "§ Answer", "The CLI entry point. It builds the commander program and hands", - "init, analyze, onboarding, map, flow, explain, config and doctor", + "init, analyze, onboarding, map, flow, explain, config, doctor and mcp", "to their command handlers." ] + }, + { + id: "mcp", + cmd: "devmap mcp", + name: "devmap mcp", + group: "Serve", + summary: "Run DevMap as an MCP server. Your agent starts it and calls tools; you rarely run it by hand.", + source: "illustrative", + out: [ + "· DevMap MCP server ready (root: ~/your-project)" + ] } ]; -export const COMMAND_GROUPS: CommandGroup[] = ["Set up", "Map", "Read"]; +export const COMMAND_GROUPS: CommandGroup[] = ["Set up", "Map", "Read", "Serve"]; /** Which command is open when the page loads. */ export const DEFAULT_COMMAND = "analyze"; diff --git a/apps/web/src/data/mcp.ts b/apps/web/src/data/mcp.ts new file mode 100644 index 0000000..a93c5fa --- /dev/null +++ b/apps/web/src/data/mcp.ts @@ -0,0 +1,35 @@ +/** + * Tools the DevMap MCP server exposes, shown in the "Works as an MCP server" section. + * Keep in step with packages/cli/src/mcp/server.ts and docs/mcp.md. + */ +export interface McpTool { + name: string; + text: string; + /** Only registered when the server starts with --allow-ai. */ + needsAi?: boolean; +} + +export const MCP_TOOLS: McpTool[] = [ + { name: "devmap_overview", text: "Framework, entry points, critical files, features and flows. Where an agent starts." }, + { name: "devmap_map", text: "Dependency map of the project, one feature or one file." }, + { name: "devmap_flow", text: "Trace a feature or an API request from entry to database." }, + { name: "devmap_routes", text: "List page and API routes." }, + { name: "devmap_impact", text: "What breaks if this file changes, followed through the import graph." }, + { name: "devmap_find", text: "Find features, files and routes by keyword." }, + { name: "devmap_analyze", text: "Re-analyze and refresh the snapshot. Writes only inside .devmap/." }, + { name: "devmap_explain", text: "Explain a file, feature or function with your own AI key.", needsAi: true } +]; + +/** The Claude Code one-liner and the .mcp.json every client can use. */ +export const MCP_ADD_COMMAND = "claude mcp add devmap -- npx -y @flaid/devmap mcp"; + +export const MCP_CONFIG = [ + "{", + ' "mcpServers": {', + ' "devmap": {', + ' "command": "npx",', + ' "args": ["-y", "@flaid/devmap", "mcp"]', + " }", + " }", + "}" +]; diff --git a/apps/web/src/lib/site.ts b/apps/web/src/lib/site.ts index c4a9a4e..ad95559 100644 --- a/apps/web/src/lib/site.ts +++ b/apps/web/src/lib/site.ts @@ -6,7 +6,7 @@ export const SITE = { url: SITE_URL, title: "DevMap: analyze once, reuse context everywhere", description: - "DevMap is a CLI that maps your codebase once: entry points, critical files, features and routes for developers and AI agents to start from.", + "DevMap is a CLI and MCP server that maps your codebase once: entry points, critical files, features and routes for developers and AI agents to start from.", ogImage: "/og.png", ogImageAlt: "DevMap: analyze once, reuse context everywhere", github: "https://github.com/itsflaid/devmap", diff --git a/apps/web/src/pages/index.astro b/apps/web/src/pages/index.astro index 075d830..e09af0d 100644 --- a/apps/web/src/pages/index.astro +++ b/apps/web/src/pages/index.astro @@ -4,6 +4,7 @@ import CommandsSection from "../components/landing/CommandsSection.astro"; import FrameworksSection from "../components/landing/FrameworksSection.astro"; import GetStartedSection from "../components/landing/GetStartedSection.astro"; import HeroSection from "../components/landing/HeroSection.astro"; +import McpSection from "../components/landing/McpSection.astro"; import MethodSection from "../components/landing/MethodSection.astro"; import OutputSection from "../components/landing/OutputSection.astro"; import ProblemSection from "../components/landing/ProblemSection.astro"; @@ -45,6 +46,7 @@ const jsonLd = [
+