@chappibunny/repolens 1.13.1 → 1.14.1

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 1.14.1
+
+### Registry name and publish skip
+
+- MCP Registry server name is `io.github.CHAPIBUNNY/repolens`. `package.json` `mcpName` and `server.json` `name` use that spelling. The registry matches the GitHub username case
+- `server.json` `description` is 100 characters or fewer
+- The release workflow skips `npm publish` when that exact version is already on the registry
+
+## 1.14.0
+
+### MCP server
+
+AI coding tools can call RepoLens over stdio.
+
+- New command: `repolens mcp`. The package also installs `repolens-mcp`
+- Official `@modelcontextprotocol/sdk` server. Tools: `get_system_overview`, `list_modules`, `get_api_surface` (includes routes), `get_dependency_graph`, `get_architecture_diff`, `generate_docs`
+- Read-only except `generate_docs`, which writes Markdown inside the workspace
+- Every path stays inside the workspace root (`REPOLENS_WORKSPACE` or the working directory), using the existing `isInsideRoot` and `resolveOutputDir` helpers
+- Deterministic mode is the default and does not make network calls. Logs go to stderr so they do not corrupt the protocol
+- `get_architecture_diff` uses the existing git diff. `baseRef` compares against the working tree. `headRef` diffs two refs. Unsafe refs are rejected
+- `package.json` `mcpName` is `io.github.CHAPIBUNNY/repolens`. Root `server.json` matches it for the MCP Registry. `smithery.yaml` starts `npx -y @chappibunny/repolens mcp`
+- Client setup, including Cursor and VS Code install badges, is in `docs/MCP.md`
+
+### GitHub Action
+
+- Root `action.yml`: composite action **RepoLens Architecture Docs** (icon `book-open`, color `blue`)
+- Inputs: `command` (`publish`, `demo`, `doctor`), `config`, `node-version`, `pr-comment`, `version`
+- Runs the published package with `npx --yes @chappibunny/repolens@<version>`. Inputs are passed as environment variables and checked before they are placed on the npx argument list
+- `REPOLENS_PR_COMMENT=false` skips the architecture diff comment even when `GITHUB_EVENT_NAME` is `pull_request`
+- Marketplace listing is a checkbox on a GitHub Release. The steps are in `docs/RELEASE.md`. This release does not publish the action, the npm package, or a tag
+
+### Docs badge
+
+- Generated Markdown ends with a shields.io badge linking to https://github.com/CHAPIBUNNY/repolens
+- On by default. Set `branding: false` or `branding.badge: false` to turn it off. Schema v1 stays at `configVersion: 1`
+- README section **Add the badge to your repo** has the snippet
+
 ## 1.13.1
 
 ### Docs

package/README.md

@@ -12,6 +12,8 @@
 [![VS Code Extension](https://img.shields.io/visual-studio-marketplace/v/repolensdox.repolensdox?label=VS%20Code)](https://marketplace.visualstudio.com/items?itemName=repolensdox.repolensdox)
 [![Tests](https://img.shields.io/github/actions/workflow/status/CHAPIBUNNY/repolens/test.yml?label=tests)](https://github.com/CHAPIBUNNY/repolens/actions/workflows/test.yml)
 [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=repolens&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjaGFwcGlidW5ueS9yZXBvbGVucyIsIm1jcCJdfQ%3D%3D)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=repolens&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40chappibunny%2Frepolens%22%2C%22mcp%22%5D%7D)
 
 **Your architecture docs are already outdated.** RepoLens fixes that.
 
@@ -175,19 +177,78 @@ Step-by-step setup for publishers, AI features, Notion, Confluence, GitHub Wiki,
 | `npx @chappibunny/repolens uninstall` | Remove all RepoLens files (config, docs, workflow) |
 | `npx @chappibunny/repolens uninstall --force` | Remove without confirmation prompt |
 | `npx @chappibunny/repolens feedback` | Send feedback to the team |
+| `npx @chappibunny/repolens mcp` | Start the stdio MCP server (`repolens-mcp` is the same server) |
 
 > **Note:** If you installed globally with `npm install -g @chappibunny/repolens`, you can use the shorter `repolens <command>` form.
 > **Warning:** Do not run bare `npx repolens` — there is an unrelated `repolens@0.0.1` placeholder package on npm. Always use the scoped name `@chappibunny/repolens`.
 
 ---
 
+## MCP server
+
+Cursor, Claude Desktop, Claude Code, and VS Code Copilot can call RepoLens over stdio. The server is read-only except for `generate_docs`, which writes Markdown inside the workspace. Deterministic mode does not use the network. Paths cannot leave the workspace root.
+
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=repolens&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjaGFwcGlidW5ueS9yZXBvbGVucyIsIm1jcCJdfQ%3D%3D)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=repolens&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40chappibunny%2Frepolens%22%2C%22mcp%22%5D%7D)
+
+Copy-paste configs for Cursor, Claude Desktop, and VS Code are in [docs/MCP.md](docs/MCP.md).
+
+```json
+{
+  "mcpServers": {
+    "repolens": {
+      "command": "npx",
+      "args": ["-y", "@chappibunny/repolens", "mcp"]
+    }
+  }
+}
+```
+
+## GitHub Action
+
+`action.yml` is a composite action named **RepoLens Architecture Docs**. It runs the published npm package (`npx --yes @chappibunny/repolens@1.14.1`). Inputs are `command` (`publish`, `demo`, or `doctor`), `config`, `node-version`, `pr-comment`, and `version`.
+
+```yaml
+name: Architecture docs
+on:
+  pull_request:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
+      - uses: CHAPIBUNNY/repolens@v1.14.1
+        with:
+          command: publish
+          config: .repolens.yml
+          node-version: "20"
+          pr-comment: ${{ github.event_name == 'pull_request' && 'true' || 'false' }}
+```
+
+The action is listed on the GitHub Marketplace only after a release is published with **Publish this Action to the GitHub Marketplace** checked. Those steps are in [docs/RELEASE.md](docs/RELEASE.md). The tag `v1.14.1` has to exist before `uses: CHAPIBUNNY/repolens@v1.14.1` resolves, and `@chappibunny/repolens@1.14.1` has to be on npm before the action can install it.
+
+## Add the badge to your repo
+
+Generated Markdown includes this line unless `.repolens.yml` sets `branding: false` (or `branding.badge: false`). Add the same badge to a repository README:
+
+```markdown
+[![Docs by RepoLens](https://img.shields.io/badge/Docs%20by-RepoLens-0B5FFF)](https://github.com/CHAPIBUNNY/repolens)
+```
+
+---
+
 ## 📸 Example Output
 
 ### System map
 
 Published system maps are Unicode diagrams drawn from import edges. RepoLens does not emit Mermaid.
 
-The publisher set in 1.13.0 is Notion, Confluence, GitHub Wiki, Obsidian, and Markdown (`src/publishers`, 7 files). Layout and counts are in [ARCHITECTURE.md](docs/ARCHITECTURE.md).
+The publisher set is Notion, Confluence, GitHub Wiki, Obsidian, and Markdown (`src/publishers`, 7 files). 1.14.0 adds the MCP server, the Marketplace action, and the docs badge. 1.14.1 sets the registry name to `io.github.CHAPIBUNNY/repolens`. Layout and counts are in [ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ### System Overview (Technical Profile)
 
@@ -248,6 +309,7 @@ When you open a pull request, RepoLens posts:
 | [Troubleshooting](docs/TROUBLESHOOTING.md) | Common issues and fixes |
 | [Migration](docs/MIGRATION.md) | Upgrading from v0.3.0 or earlier |
 | [Stability](docs/STABILITY.md) | API contract and semver guarantees |
+| [MCP server](docs/MCP.md) | stdio server for Cursor, Claude, and VS Code |
 
 ---
 
@@ -269,6 +331,9 @@ v1.0+ features complete — CLI, config schema, and plugin interface are frozen.
 **Completed:**
 - [x] VS Code extension ([available on Marketplace](https://marketplace.visualstudio.com/items?itemName=repolensdox.repolensdox))
 - [x] Obsidian vault publisher (local notes with wikilinks and frontmatter)
+- [x] MCP server (`repolens mcp`) for Cursor, Claude, and VS Code
+- [x] GitHub Action `RepoLens Architecture Docs` (`action.yml`)
+- [x] Docs by RepoLens badge on generated Markdown
 
 **Next:**
 - [ ] GitHub App for automated setup and status checks

package/bin/repolens-mcp.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+
+const argv = process.argv.slice(2);
+const wantsHelp = argv.includes("--help") || argv.includes("-h");
+const wantsVersion = argv.includes("--version") || argv.includes("-v");
+
+if (wantsVersion && !wantsHelp) {
+  const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  console.log(pkg.version || "0.0.0");
+  process.exit(0);
+}
+
+if (wantsHelp) {
+  const { printHelp } = await import("../src/help.js");
+  printHelp();
+  process.exit(0);
+}
+
+// Stdio MCP owns stdout. Keep RepoLens logs on stderr.
+process.env.REPOLENS_LOG_STDERR = "1";
+const { startMcpServer } = await import("../src/mcp/server.js");
+await startMcpServer();

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@chappibunny/repolens",
-  "version": "1.13.1",
+  "version": "1.14.1",
+  "mcpName": "io.github.CHAPIBUNNY/repolens",
   "description": "AI-assisted documentation intelligence system for technical and non-technical audiences",
   "license": "MIT",
   "type": "module",
@@ -13,7 +14,8 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "repolens": "bin/repolens.js"
+    "repolens": "bin/repolens.js",
+    "repolens-mcp": "bin/repolens-mcp.js"
   },
   "files": [
     "bin",
@@ -37,7 +39,9 @@
     "team-collaboration",
     "discord",
     "obsidian",
-    "ai-documentation"
+    "ai-documentation",
+    "mcp",
+    "model-context-protocol"
   ],
   "repository": {
     "type": "git",
@@ -66,9 +70,11 @@
     "release:major": "npm version major"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "dotenv": "^18.0.8",
     "fast-glob": "^3.3.3",
-    "js-yaml": "^4.3.2"
+    "js-yaml": "^4.3.2",
+    "zod": "3.25.76"
   },
   "optionalDependencies": {
     "@sentry/node": "^10.42.0"

package/src/cli.js

@@ -246,6 +246,15 @@ async function main() {
 
   const command = parsed.command;
 
+  // MCP stdio must start before telemetry and the npm update check.
+  // Those both can open the network, and logs must stay off stdout.
+  if (command === "mcp") {
+    process.env.REPOLENS_LOG_STDERR = "1";
+    const { startMcpServer } = await import("./mcp/server.js");
+    await startMcpServer();
+    return;
+  }
+
   // Initialize telemetry (opt-in via REPOLENS_TELEMETRY_ENABLED=true).
   // @sentry/node is optional; init is a no-op when it is not installed.
   await initTelemetry();
@@ -732,7 +741,7 @@ async function main() {
   }
 
   error(`Unknown command: ${command}`);
-  error("Available commands: init, doctor, migrate, publish, demo, watch, uninstall, feedback, version, help");
+  error("Available commands: init, doctor, migrate, publish, demo, watch, uninstall, feedback, mcp, version, help");
   process.exit(EXIT_ERROR);
 }
 

package/src/core/config-schema.js

@@ -342,6 +342,18 @@ export function validateConfig(config) {
     }
   }
 
+  // Validate branding (optional). Omitted means the docs badge stays on.
+  if (config.branding !== undefined) {
+    const branding = config.branding;
+    const isBoolean = typeof branding === "boolean";
+    const isObject = branding !== null && typeof branding === "object" && !Array.isArray(branding);
+    if (!isBoolean && !isObject) {
+      errors.push("branding must be a boolean or an object");
+    } else if (isObject && branding.badge !== undefined && typeof branding.badge !== "boolean") {
+      errors.push("branding.badge must be a boolean");
+    }
+  }
+
   // Validate documentation configuration (optional)
   if (config.documentation !== undefined) {
     if (typeof config.documentation !== "object" || Array.isArray(config.documentation)) {
@@ -431,6 +443,7 @@ const VALID_CONFIG_KEYS = [
   "documentation",
   "domains",
   "plugins",
+  "branding",
 ];
 
 /**

package/src/core/diff.js

@@ -7,6 +7,14 @@ function emptyDiff() {
   return { added: [], removed: [], modified: [] };
 }
 
+/**
+ * True when `ref` can be passed as one git argument.
+ * Rejects flag-like values and shell metacharacters.
+ */
+export function isSafeGitRef(ref) {
+  return typeof ref === "string" && ref.length > 0 && !ref.startsWith("-") && SAFE_REF.test(ref);
+}
+
 /**
  * Classify one `git diff --name-status` line.
  * Renames and copies (`R100`, `C75`) record the destination path.
@@ -26,17 +34,27 @@ export function classifyDiffLine(line) {
   return { bucket: "modified", file };
 }
 
-export function getGitDiff(baseRef = "origin/main", cwd = process.cwd()) {
-  if (typeof baseRef !== "string" || baseRef.startsWith("-") || !SAFE_REF.test(baseRef)) {
+export function getGitDiff(baseRef = "origin/main", cwd = process.cwd(), headRef) {
+  if (!isSafeGitRef(baseRef)) {
     warn("git diff skipped: base ref contains unsupported characters.");
     return emptyDiff();
   }
 
+  const args = ["diff", "--name-status", baseRef];
+  if (headRef != null && headRef !== "") {
+    if (!isSafeGitRef(headRef)) {
+      warn("git diff skipped: head ref contains unsupported characters.");
+      return emptyDiff();
+    }
+    args.push(headRef);
+  }
+
   let output = "";
 
   try {
     // Pipe stderr so a missing repo or ref does not dump git's usage text.
-    output = execFileSync("git", ["diff", "--name-status", baseRef], {
+    // Arguments stay in an array. Refs are checked by isSafeGitRef first.
+    output = execFileSync("git", args, {
       encoding: "utf8",
       cwd,
       stdio: ["ignore", "pipe", "pipe"],

package/src/delivery/comment.js

@@ -92,6 +92,12 @@ async function findExistingRepoLensComment(owner, repo, issueNumber) {
 }
 
 export async function upsertPrComment(diff) {
+  const flag = process.env.REPOLENS_PR_COMMENT;
+  if (flag === "false" || flag === "0") {
+    log("REPOLENS_PR_COMMENT is disabled, skipping PR comment.");
+    return;
+  }
+
   const eventName = process.env.GITHUB_EVENT_NAME;
   if (eventName !== "pull_request") {
     log("GITHUB_EVENT_NAME is not 'pull_request', skipping PR comment.");

package/src/docs/branding.js

@@ -0,0 +1,29 @@
+/**
+ * Footer badge on generated Markdown.
+ * On unless config sets `branding: false` or `branding.badge: false`.
+ */
+
+export const DOCS_BADGE_MARKER = "<!-- repolens:docs-badge -->";
+
+export const DOCS_BADGE_MARKDOWN =
+  "[![Docs by RepoLens](https://img.shields.io/badge/Docs%20by-RepoLens-0B5FFF)](https://github.com/CHAPIBUNNY/repolens)";
+
+export function brandingEnabled(config) {
+  const branding = config?.branding;
+  if (branding === false) return false;
+  if (branding && typeof branding === "object" && !Array.isArray(branding) && branding.badge === false) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Append the Docs by RepoLens line once. Non-strings are returned unchanged.
+ */
+export function applyBrandingFooter(content, config) {
+  if (typeof content !== "string") return content;
+  if (!brandingEnabled(config)) return content;
+  if (content.includes(DOCS_BADGE_MARKER)) return content;
+  const trimmed = content.trimEnd();
+  return `${trimmed}\n\n${DOCS_BADGE_MARKER}\n${DOCS_BADGE_MARKDOWN}\n`;
+}

package/src/docs/generate-doc-set.js

@@ -34,6 +34,7 @@ import {
 } from "../renderers/renderAnalysis.js";
 import { info, warn } from "../utils/logger.js";
 import path from "node:path";
+import { applyBrandingFooter } from "./branding.js";
 
 export async function generateDocumentSet(scanResult, config, diffData = null, pluginManager = null) {
   info("Building structured context for AI...");
@@ -152,7 +153,7 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
       
       documents.push({
         ...docPlan,
-        content,
+        content: applyBrandingFooter(content, config),
         generated: new Date().toISOString()
       });
       
@@ -163,7 +164,10 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
       // Add placeholder document so publishers know about the failure
       documents.push({
         ...docPlan,
-        content: `# ${docPlan.title}\n\n> **Generation Error:** ${error.message}\n\nPlease check the RepoLens logs for details.\n`,
+        content: applyBrandingFooter(
+          `# ${docPlan.title}\n\n> **Generation Error:** ${error.message}\n\nPlease check the RepoLens logs for details.\n`,
+          config
+        ),
         generated: new Date().toISOString(),
         error: true
       });
@@ -201,7 +205,7 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
           filename: renderer.filename || `${key}.md`,
           category: renderer.category || "custom",
           audience: renderer.audience || ["technical"],
-          content,
+          content: applyBrandingFooter(content, config),
           generated: new Date().toISOString(),
         });
 

package/src/help.js

@@ -14,6 +14,7 @@ Commands:
   watch       Watch for file changes and regenerate docs
   uninstall   Remove RepoLens-generated files from a repository
   feedback    Send feedback to the RepoLens team
+  mcp         Start the stdio MCP server (also available as repolens-mcp)
   version     Print the current RepoLens version
   help        Show this help message
 
@@ -49,6 +50,7 @@ Examples:
   repolens demo
   repolens watch
   repolens uninstall --target /tmp/my-repo
+  repolens mcp
   repolens --version
 `);
 }

package/src/init.js

@@ -738,6 +738,9 @@ function buildRepoLensConfig(projectName, detectedRoots, options = {}) {
     `  - notion      # Auto-detected: publishes if NOTION_TOKEN is set`,
     `  - confluence  # Auto-detected: publishes if CONFLUENCE_URL is set`,
     ``,
+    `# Docs by RepoLens badge on generated Markdown (default: on)`,
+    `# branding: false`,
+    ``,
     `# Optional: Configure Notion publishing behavior`,
     `# notion:`,
     `#   branches:`,
@@ -1390,6 +1393,9 @@ function buildWizardConfig(answers) {
   for (const p of answers.publishers) {
     lines.push(`  - ${p}`);
   }
+  lines.push(``);
+  lines.push(`# Docs by RepoLens badge on generated Markdown (default: on)`);
+  lines.push(`# branding: false`);
 
   if (answers.publishers.includes("notion") && answers.branches.length) {
     lines.push(``);

package/src/mcp/server.js

@@ -0,0 +1,130 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { callTool } from "./tools.js";
+
+const rootField = z.string().optional().describe(
+  "Directory to read. Relative or absolute, and it must stay inside the workspace root. Defaults to the workspace root."
+);
+
+const readOnly = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+};
+
+function packageVersion() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const pkg = JSON.parse(readFileSync(path.join(here, "../../package.json"), "utf8"));
+  return pkg.version || "0.0.0";
+}
+
+/**
+ * Stdio MCP server. Tool handlers live in tools.js so tests can call them
+ * without opening a transport. Logs must stay off stdout.
+ */
+export function createMcpServer() {
+  const server = new McpServer(
+    { name: "repolens", version: packageVersion() },
+    {
+      instructions: [
+        "RepoLens reads the workspace and returns architecture documentation.",
+        "Every path stays inside the workspace root.",
+        "Tools are read-only except generate_docs, which writes Markdown inside that root.",
+        "Deterministic mode (the default) does not make network calls.",
+      ].join(" "),
+    }
+  );
+
+  server.registerTool(
+    "get_system_overview",
+    {
+      title: "System overview",
+      description: "Scan the workspace and return the RepoLens system overview. Read-only. No network calls.",
+      inputSchema: { root: rootField },
+      annotations: readOnly,
+    },
+    async (args) => callTool("get_system_overview", args)
+  );
+
+  server.registerTool(
+    "list_modules",
+    {
+      title: "List modules",
+      description: "Scan the workspace and list detected modules. Read-only. No network calls.",
+      inputSchema: { root: rootField },
+      annotations: readOnly,
+    },
+    async (args) => callTool("list_modules", args)
+  );
+
+  server.registerTool(
+    "get_api_surface",
+    {
+      title: "API surface and routes",
+      description: "Scan the workspace and return the API surface and the route map. Read-only. No network calls.",
+      inputSchema: { root: rootField },
+      annotations: readOnly,
+    },
+    async (args) => callTool("get_api_surface", args)
+  );
+
+  server.registerTool(
+    "get_dependency_graph",
+    {
+      title: "Dependency graph",
+      description: "Scan the workspace and return the import dependency graph. Read-only. No network calls.",
+      inputSchema: { root: rootField },
+      annotations: readOnly,
+    },
+    async (args) => callTool("get_dependency_graph", args)
+  );
+
+  server.registerTool(
+    "get_architecture_diff",
+    {
+      title: "Architecture diff",
+      description: "Return the architecture diff. With only baseRef, compare that ref to the working tree. With baseRef and headRef, run git diff between those two refs. Read-only. No network calls.",
+      inputSchema: {
+        root: rootField,
+        baseRef: z.string().optional().describe("Base git ref. Defaults to HEAD. Compared with the working tree when headRef is omitted."),
+        headRef: z.string().optional().describe("Optional second git ref. When set, the diff is baseRef...headRef as git diff baseRef headRef."),
+      },
+      annotations: readOnly,
+    },
+    async (args) => callTool("get_architecture_diff", args)
+  );
+
+  server.registerTool(
+    "generate_docs",
+    {
+      title: "Generate docs",
+      description: "Generate RepoLens Markdown into a directory inside the workspace. Deterministic by default, which disables AI and does not make network calls. This is the only tool that writes files.",
+      inputSchema: {
+        root: rootField,
+        outputDir: z.string().optional().describe("Output directory relative to the repository. Must stay inside the repository. Defaults to .repolens or documentation.output_dir."),
+        deterministic: z.boolean().optional().describe("Defaults to true. When true, AI stays off and this call does not use the network."),
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (args) => callTool("generate_docs", args)
+  );
+
+  return server;
+}
+
+export async function startMcpServer() {
+  process.env.REPOLENS_LOG_STDERR = "1";
+  const server = createMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/mcp/tools.js

@@ -0,0 +1,202 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { loadConfig } from "../core/config.js";
+import { scanRepo } from "../core/scan.js";
+import { getGitDiff, isSafeGitRef } from "../core/diff.js";
+import { analyzeDependencyGraph } from "../analyzers/dependency-graph.js";
+import {
+  renderSystemOverview,
+  renderModuleCatalog,
+  renderApiSurface,
+  renderRouteMap,
+} from "../renderers/render.js";
+import { renderDependencyGraph } from "../renderers/renderAnalysis.js";
+import { renderArchitectureDiff } from "../renderers/renderDiff.js";
+import { generateDocumentSet } from "../docs/generate-doc-set.js";
+import { writeDocumentSet } from "../docs/write-doc-set.js";
+import { resolveDocsOutputDir, resolveInsideWorkspace, resolveWorkspaceRoot } from "./workspace.js";
+
+const MAX_TEXT = 80_000;
+
+export function asToolText(text) {
+  const body = String(text ?? "");
+  if (body.length <= MAX_TEXT) return body;
+  return `${body.slice(0, MAX_TEXT)}\n\n[truncated ${body.length - MAX_TEXT} characters]`;
+}
+
+export function ok(text) {
+  return { content: [{ type: "text", text: asToolText(text) }] };
+}
+
+export function fail(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return { isError: true, content: [{ type: "text", text: message }] };
+}
+
+function projectRootFromArgs(args) {
+  const workspace = resolveWorkspaceRoot();
+  return resolveInsideWorkspace(workspace, args?.root, "root");
+}
+
+function defaultConfig(root) {
+  return {
+    configVersion: 1,
+    project: { name: path.basename(root) || "repository" },
+    publishers: ["markdown"],
+    scan: {
+      include: ["**/*.{js,ts,jsx,tsx,mjs,cjs,py,go,rs,java,rb,php,cs,swift,kt}"],
+      ignore: [
+        "**/node_modules/**",
+        "**/dist/**",
+        "**/build/**",
+        "**/.git/**",
+        "**/vendor/**",
+        "**/target/**",
+        "**/__pycache__/**",
+      ],
+    },
+    module_roots: ["src", "lib", "app", "packages"],
+    outputs: {
+      pages: [
+        { key: "system_overview", title: "System Overview" },
+        { key: "module_catalog", title: "Module Catalog" },
+        { key: "api_surface", title: "API Surface" },
+        { key: "route_map", title: "Route Map" },
+      ],
+    },
+    documentation: { output_dir: ".repolens", include_artifacts: false },
+    ai: { enabled: false, mode: "off" },
+    branding: true,
+    __repoRoot: root,
+    __configPath: path.join(root, ".repolens.yml"),
+  };
+}
+
+async function prepareConfig(root, { deterministic = true, outputDir } = {}) {
+  const configPath = path.join(root, ".repolens.yml");
+  let cfg;
+  try {
+    await fs.access(configPath);
+    cfg = await loadConfig(configPath);
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      cfg = defaultConfig(root);
+    } else {
+      throw error;
+    }
+  }
+
+  cfg.__repoRoot = root;
+  if (deterministic) {
+    cfg.ai = { ...(cfg.ai || {}), enabled: false, mode: "off" };
+  }
+  if (outputDir != null && outputDir !== "") {
+    cfg.documentation = {
+      ...(cfg.documentation || {}),
+      output_dir: resolveDocsOutputDir(root, outputDir),
+    };
+  }
+  return cfg;
+}
+
+/**
+ * Drop REPOLENS_AI_ENABLED for one call so deterministic mode cannot
+ * reach an AI provider. The previous value is restored afterwards.
+ */
+export async function runDeterministic(fn) {
+  const previous = process.env.REPOLENS_AI_ENABLED;
+  delete process.env.REPOLENS_AI_ENABLED;
+  try {
+    return await fn();
+  } finally {
+    if (previous === undefined) delete process.env.REPOLENS_AI_ENABLED;
+    else process.env.REPOLENS_AI_ENABLED = previous;
+  }
+}
+
+async function scanned(args) {
+  const root = projectRootFromArgs(args);
+  const cfg = await prepareConfig(root, { deterministic: true });
+  const scan = await runDeterministic(() => scanRepo(cfg));
+  return { root, cfg, scan };
+}
+
+export async function getSystemOverview(args = {}) {
+  const { cfg, scan } = await scanned(args);
+  return renderSystemOverview(cfg, scan);
+}
+
+export async function listModules(args = {}) {
+  const { cfg, scan } = await scanned(args);
+  return renderModuleCatalog(cfg, scan);
+}
+
+export async function getApiSurface(args = {}) {
+  const { cfg, scan } = await scanned(args);
+  return `${renderApiSurface(cfg, scan)}\n\n${renderRouteMap(cfg, scan)}`;
+}
+
+export async function getDependencyGraph(args = {}) {
+  const { root, scan } = await scanned(args);
+  const graph = await runDeterministic(() => analyzeDependencyGraph(scan._files || [], root));
+  return renderDependencyGraph(graph);
+}
+
+export async function getArchitectureDiff(args = {}) {
+  const root = projectRootFromArgs(args);
+  const baseRef = args.baseRef == null || args.baseRef === "" ? "HEAD" : args.baseRef;
+  const headRef = args.headRef == null || args.headRef === "" ? undefined : args.headRef;
+  if (!isSafeGitRef(baseRef)) {
+    throw new Error("baseRef contains unsupported characters");
+  }
+  if (headRef !== undefined && !isSafeGitRef(headRef)) {
+    throw new Error("headRef contains unsupported characters");
+  }
+  const raw = getGitDiff(baseRef, root, headRef);
+  return renderArchitectureDiff(raw);
+}
+
+export async function generateDocs(args = {}) {
+  const root = projectRootFromArgs(args);
+  const deterministic = args.deterministic !== false;
+  const outputDir = args.outputDir;
+
+  const run = async () => {
+    const cfg = await prepareConfig(root, { deterministic, outputDir });
+    const scan = await scanRepo(cfg);
+    const raw = getGitDiff("HEAD", root);
+    const docSet = await generateDocumentSet(scan, cfg, raw);
+    const written = await writeDocumentSet(docSet, root);
+    const rel = path.relative(root, written.outputDir) || ".";
+    const lines = [
+      `Wrote ${written.documentCount} documents to ${rel}`,
+      ...written.files.map((file) => `- ${file}`),
+    ];
+    return lines.join("\n");
+  };
+
+  if (deterministic) return runDeterministic(run);
+  return run();
+}
+
+const HANDLERS = {
+  get_system_overview: getSystemOverview,
+  list_modules: listModules,
+  get_api_surface: getApiSurface,
+  get_dependency_graph: getDependencyGraph,
+  get_architecture_diff: getArchitectureDiff,
+  generate_docs: generateDocs,
+};
+
+export const TOOL_NAMES = Object.keys(HANDLERS);
+
+export async function callTool(name, args) {
+  const handler = HANDLERS[name];
+  if (!handler) return fail(new Error(`Unknown tool: ${name}`));
+  try {
+    const text = await handler(args || {});
+    return ok(text);
+  } catch (error) {
+    return fail(error);
+  }
+}

package/src/mcp/workspace.js

@@ -0,0 +1,52 @@
+import path from "node:path";
+import { isInsideRoot, resolveOutputDir } from "../utils/safe-path.js";
+
+/**
+ * Workspace root for the MCP server.
+ * REPOLENS_WORKSPACE wins over the process working directory.
+ */
+export function resolveWorkspaceRoot(explicit) {
+  const candidate = explicit || process.env.REPOLENS_WORKSPACE || process.cwd();
+  if (typeof candidate !== "string" || candidate.length === 0) {
+    throw new Error("Workspace root must be a path string");
+  }
+  if (candidate.includes("\0")) {
+    throw new Error("Workspace root contains a null byte");
+  }
+  return path.resolve(candidate);
+}
+
+/**
+ * Resolve `requested` and require it to stay inside `workspaceRoot`.
+ * An empty value is the workspace root itself.
+ */
+export function resolveInsideWorkspace(workspaceRoot, requested, label = "path") {
+  const root = path.resolve(workspaceRoot);
+  if (!isInsideRoot(root, root)) {
+    throw new Error("Workspace root is not a directory path");
+  }
+  if (requested == null || requested === "" || requested === ".") {
+    return root;
+  }
+  if (typeof requested !== "string") {
+    throw new Error(`${label} must be a string`);
+  }
+  if (requested.includes("\0")) {
+    throw new Error(`${label} contains a null byte`);
+  }
+  const resolved = path.resolve(root, requested);
+  if (!isInsideRoot(root, resolved)) {
+    throw new Error(`${label} escapes the workspace: ${requested}`);
+  }
+  return resolved;
+}
+
+/**
+ * Validate a documentation output directory and return the relative
+ * path `resolveOutputDir` will accept later.
+ */
+export function resolveDocsOutputDir(projectRoot, outputDir) {
+  const relative = outputDir == null || outputDir === "" ? ".repolens" : outputDir;
+  resolveOutputDir(projectRoot, relative);
+  return relative;
+}

package/src/utils/logger.js

@@ -69,9 +69,14 @@ function sanitizeArgs(args) {
   });
 }
 
+function logSink() {
+  // The MCP stdio transport owns stdout. Logs go to stderr in that mode.
+  return process.env.REPOLENS_LOG_STDERR === "1" ? console.error : console.log;
+}
+
 export function log(...args) {
   if (!isTest && isVerbose) {
-    console.log("[RepoLens]", ...sanitizeArgs(args));
+    logSink()("[RepoLens]", ...sanitizeArgs(args));
   }
 }
 
@@ -81,13 +86,13 @@ export function log(...args) {
  */
 export function verbose(...args) {
   if (!isTest && isVerbose) {
-    console.log("[RepoLens]", ...sanitizeArgs(args));
+    logSink()("[RepoLens]", ...sanitizeArgs(args));
   }
 }
 
 export function info(...args) {
   if (!isTest) {
-    console.log("[RepoLens]", ...sanitizeArgs(args));
+    logSink()("[RepoLens]", ...sanitizeArgs(args));
   }
 }