feat: add MCP server section and docs to the landing page

apps/web/src/components/landing/AgentsSection.astro

@@ -31,7 +31,8 @@ const reads = [
     <h2 class="section__title" id="agents-title">Works with every agent.</h2>
     <p class="section__lede">
       One <code>devmap analyze</code> 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, <a href="#mcp">it can ask for it</a>.
     </p>
     <div class="agents__cta">
       <a class="btn" href="/docs#3-using-devmap-with-ai-agents">Use it with your agent</a>

apps/web/src/components/landing/CommandsSection.astro

@@ -14,7 +14,7 @@ function parse(line: string): { kind: Kind; text: string } {
 
 <section class="commands section page" id="commands" aria-labelledby="commands-title">
   <div class="section__head" data-reveal>
-    <h2 class="section__title" id="commands-title">Eight commands.</h2>
+    <h2 class="section__title" id="commands-title">Nine commands.</h2>
     <p class="section__lede">Pick one and see what it prints. Most of them need no API key.</p>
   </div>
 

apps/web/src/components/landing/HeroSection.astro

@@ -22,7 +22,8 @@ const log: Array<{ text: string; tone?: "ok" | "dim" | "hot" }> = [
 
     <p class="hero__lede" data-hero="2">
       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.
     </p>
 
     <div class="hero__actions" data-hero="3">

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." }
+];
+---
+
+<section class="mcp section page" id="mcp" aria-labelledby="mcp-title">
+  <div class="section__head" data-reveal>
+    <h2 class="section__title" id="mcp-title">Or let the agent ask.</h2>
+    <p class="section__lede">
+      <code>devmap mcp</code> 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.
+    </p>
+  </div>
+
+  <div class="mcp__setup">
+    <ol class="mcp__steps" aria-label="Set up the DevMap MCP server">
+      {steps.map((step, i) => (
+        <li class="card mcp__step" data-reveal style={`--i:${i}`}>
+          <span class="mcp__n" aria-hidden="true">{step.n}</span>
+          <div>
+            <h3>{step.title}</h3>
+            <p>{step.text}</p>
+          </div>
+        </li>
+      ))}
+    </ol>
+
+    <div class="mcp__code" data-reveal style="--i:1">
+      <p class="mcp__label">Claude Code</p>
+      <CopyCommand command={MCP_ADD_COMMAND} />
+      <div class="mcp__file" role="img" aria-label="MCP client configuration for DevMap">
+        <span class="mcp__filename">.mcp.json</span>
+        <pre>{MCP_CONFIG.join("\n")}</pre>
+      </div>
+      <p class="mcp__note">
+        Nothing is sent anywhere. <code>--auto-refresh</code> and <code>--allow-ai</code> are opt-in.
+      </p>
+    </div>
+  </div>
+
+  <ul class="mcp__tools" aria-label="Tools the DevMap MCP server provides">
+    {MCP_TOOLS.map((tool, i) => (
+      <li class="card mcp__tool" data-reveal style={`--i:${i % 4}`}>
+        <code>{tool.name}</code>
+        <p>{tool.text}</p>
+        {tool.needsAi && <span class="mcp__ai">needs --allow-ai</span>}
+      </li>
+    ))}
+  </ul>
+
+  <div class="mcp__cta" data-reveal>
+    <a class="btn" href="/docs#use-it-as-an-mcp-server">MCP setup for your client</a>
+  </div>
+</section>
+
+<style>
+  .section__lede code,
+  .mcp__note code {
+    font-size: 0.875em;
+    color: var(--ink);
+  }
+
+  .mcp__setup {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    gap: 1rem;
+    margin-top: clamp(2.5rem, 5vw, 4rem);
+  }
+
+  @media (min-width: 62rem) {
+    .mcp__setup {
+      grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+      align-items: stretch;
+    }
+  }
+
+  .mcp__steps {
+    display: grid;
+    gap: 1rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .mcp__step {
+    display: flex;
+    gap: 1rem;
+    align-items: flex-start;
+    padding: 1.25rem 1.4rem;
+  }
+
+  .mcp__n {
+    flex: none;
+    display: grid;
+    place-items: center;
+    width: 1.75rem;
+    height: 1.75rem;
+    border: 1px solid var(--rule);
+    border-radius: 999px;
+    font-family: var(--font-mono);
+    font-size: 0.75rem;
+    color: var(--muted);
+  }
+
+  .mcp__step h3 {
+    font-size: 1.125rem;
+    letter-spacing: -0.02em;
+  }
+
+  .mcp__step p {
+    margin-top: 0.25rem;
+    font-size: 0.9375rem;
+    color: var(--muted);
+  }
+
+  .mcp__code {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    align-content: start;
+    gap: 0.9rem;
+    min-width: 0;
+  }
+
+  .mcp__label {
+    font-family: var(--font-mono);
+    font-size: 0.75rem;
+    color: var(--muted);
+  }
+
+  .mcp__file {
+    padding: 1rem 1.1rem 1.2rem;
+    border-radius: var(--radius-lg);
+    background: var(--night);
+    color: var(--night-text);
+    overflow: hidden;
+  }
+
+  .mcp__filename {
+    display: inline-block;
+    padding: 0.2rem 0.6rem;
+    border: 1px solid var(--night-rule);
+    border-radius: 999px;
+    font-family: var(--font-mono);
+    font-size: 0.6875rem;
+    color: var(--night-muted);
+  }
+
+  .mcp__file pre {
+    margin: 0.9rem 0 0;
+    font-size: 0.8125rem;
+    line-height: 1.7;
+    white-space: pre;
+    overflow-x: auto;
+  }
+
+  .mcp__note {
+    font-size: 0.875rem;
+    color: var(--muted);
+  }
+
+  .mcp__tools {
+    display: grid;
+    grid-template-columns: repeat(1, minmax(0, 1fr));
+    gap: 1rem;
+    margin: 1rem 0 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  @media (min-width: 40rem) {
+    .mcp__tools {
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+    }
+  }
+
+  @media (min-width: 62rem) {
+    .mcp__tools {
+      grid-template-columns: repeat(4, minmax(0, 1fr));
+    }
+  }
+
+  .mcp__tool {
+    display: grid;
+    align-content: start;
+    gap: 0.5rem;
+    padding: 1.1rem 1.25rem 1.3rem;
+  }
+
+  .mcp__tool code {
+    font-size: 0.8125rem;
+    color: var(--ink);
+    overflow-wrap: anywhere;
+  }
+
+  .mcp__tool p {
+    font-size: 0.9375rem;
+    color: var(--muted);
+  }
+
+  .mcp__ai {
+    justify-self: start;
+    padding: 0.15rem 0.55rem;
+    border: 1px solid var(--rule);
+    border-radius: 999px;
+    font-family: var(--font-mono);
+    font-size: 0.6875rem;
+    color: var(--muted);
+  }
+
+  .mcp__cta {
+    display: flex;
+    justify-content: center;
+    margin-top: 2rem;
+  }
+</style>

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" }

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 <path>] [--auto-refresh] [--allow-ai]
+```
+
+| Flag | Default | Effect |
+|---|---|---|
+| `--root <path>` | 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 <model-id|auto>`
 
 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 <model-id>`
 - **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`
 
 ---
 

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 <command>` 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";