cartogopher 5.0.0

package/README.md

@@ -0,0 +1,48 @@
+# cartogopher
+
+AI-native code intelligence: parses codebases into a searchable graph of functions, types, endpoints, and call relationships. Includes both a CLI and an MCP server.
+
+## Install
+
+```bash
+npm install -g cartogopher
+```
+
+npm only downloads the binary for your platform (darwin-arm64, darwin-x64, linux-x64, or linux-arm64).
+
+Try it without installing globally:
+
+```bash
+npx cartogopher bake
+```
+
+## Quick start (Claude Code)
+
+```bash
+export CARTOGOPHER_API_KEY=cg_live_your_key
+cd your-project
+cartogopher bake                  # parse the codebase (~10–30s)
+cartogopher install-skill         # drop the skill into .claude/skills/cartogopher/
+```
+
+Now any Claude Code agent in this project knows how to use cartogopher. It uses the regular `Bash` tool to call `cartogopher search`, `cartogopher impact`, etc.
+
+For a system-wide install (works in every project):
+```bash
+cartogopher install-skill --global   # → ~/.claude/skills/cartogopher/SKILL.md
+```
+
+## MCP server (alternative to the skill)
+
+If you'd rather plug in as an MCP server instead of a skill:
+
+```bash
+cartogopher mcp
+```
+
+Configure your MCP client to invoke that command. **The skill is generally cheaper to run** — see bench results in the repo's `tests/bench/engrambench/results/`.
+
+## Docs
+
+- API key: https://cartogopher.com/download
+- Docs: https://cartogopher.com/docs

package/bin/cartogopher.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const PLATFORM_PACKAGES = {
+  "darwin-arm64": "@cartogopher/darwin-arm64",
+  "darwin-x64": "@cartogopher/darwin-x64",
+  "linux-x64": "@cartogopher/linux-x64",
+  "linux-arm64": "@cartogopher/linux-arm64",
+};
+
+function resolveBinary() {
+  const key = `${process.platform}-${process.arch}`;
+  const pkg = PLATFORM_PACKAGES[key];
+  if (!pkg) {
+    console.error(
+      `cartogopher: unsupported platform ${key}. Supported: ${Object.keys(PLATFORM_PACKAGES).join(", ")}`
+    );
+    process.exit(1);
+  }
+
+  let pkgJsonPath;
+  try {
+    pkgJsonPath = require.resolve(`${pkg}/package.json`);
+  } catch (err) {
+    console.error(
+      `cartogopher: platform package '${pkg}' is not installed.\n` +
+        `This usually means npm skipped optional dependencies, or the platform package failed to download.\n` +
+        `Try: npm install -g ${pkg}`
+    );
+    process.exit(1);
+  }
+
+  const exeName = process.platform === "win32" ? "cartogopher.exe" : "cartogopher";
+  const binary = path.join(path.dirname(pkgJsonPath), "bin", exeName);
+  if (!fs.existsSync(binary)) {
+    console.error(`cartogopher: binary missing at ${binary}`);
+    process.exit(1);
+  }
+  return binary;
+}
+
+function mcpScriptPath() {
+  return path.join(__dirname, "..", "lib", "mcp-server.js");
+}
+
+function bundledSkillPath() {
+  return path.join(__dirname, "..", "share", "cartogopher", "SKILL.md");
+}
+
+function installSkill(argv) {
+  // Usage: cartogopher install-skill [--global] [--dest <dir>]
+  const flagGlobal = argv.includes("--global");
+  const destIdx = argv.indexOf("--dest");
+  const targetRoot = destIdx >= 0 && argv[destIdx + 1]
+    ? path.resolve(argv[destIdx + 1])
+    : flagGlobal
+      ? path.join(process.env.HOME || "", ".claude", "skills", "cartogopher")
+      : path.join(process.cwd(), ".claude", "skills", "cartogopher");
+
+  const src = bundledSkillPath();
+  if (!fs.existsSync(src)) {
+    console.error(`cartogopher install-skill: bundled SKILL.md not found at ${src}`);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(targetRoot, { recursive: true });
+  const dest = path.join(targetRoot, "SKILL.md");
+  fs.copyFileSync(src, dest);
+  console.log(`Installed cartogopher skill → ${dest}`);
+  console.log("Claude Code agents in this project can now load it via /cartogopher.");
+  process.exit(0);
+}
+
+const args = process.argv.slice(2);
+if (args[0] === "install-skill") {
+  installSkill(args.slice(1));
+}
+
+const binary = resolveBinary();
+const env = { ...process.env, CARTOGOPHER_MCP_SCRIPT: mcpScriptPath() };
+
+const result = spawnSync(binary, args, {
+  stdio: "inherit",
+  env,
+});
+
+if (result.error) {
+  console.error(`cartogopher: failed to exec binary: ${result.error.message}`);
+  process.exit(1);
+}
+process.exit(result.status === null ? 1 : result.status);

package/lib/mcp-server.js

@@ -0,0 +1,868 @@
+#!/usr/bin/env node
+
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} = require('@modelcontextprotocol/sdk/types.js');
+const fs = require('fs');
+const path = require('path');
+const { execSync, execFileSync } = require('child_process');
+
+class CartoGopherMCP {
+  constructor() {
+    this.rootDir = this.findProjectRoot();
+    this.bakesDir = path.join(this.rootDir, 'bakes');
+    this.docMode = false;
+    this.binary = this.findBinary();
+
+    if (process.env.DEBUG) {
+      console.error(`MCP v4 Server initialized:`);
+      console.error(`  Root dir: ${this.rootDir}`);
+      console.error(`  Bakes dir: ${this.bakesDir}`);
+      console.error(`  Binary: ${this.binary || 'NOT FOUND'}`);
+    }
+
+    this.server = new Server(
+      { name: 'cartogopher-mcp-v4', version: '4.3.0' },
+      { capabilities: { tools: {} } }
+    );
+
+    this.setupHandlers();
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Project & Binary Discovery (reused from v1)
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  findProjectRoot() {
+    if (process.env.CARTOGOPHER_ROOT) return process.env.CARTOGOPHER_ROOT;
+    if (process.env.CURSOR_WORKSPACE) {
+      const ws = process.env.CURSOR_WORKSPACE;
+      if (this.isValidProject(ws)) return ws;
+    }
+    const cwd = process.cwd();
+    if (this.isValidProject(cwd)) return cwd;
+    const gitRoot = this.getGitRoot();
+    if (gitRoot && this.isValidProject(gitRoot)) return gitRoot;
+    return cwd;
+  }
+
+  getGitRoot() {
+    try {
+      return execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+    } catch { return null; }
+  }
+
+  isValidProject(dir) {
+    try {
+      const indicators = [
+        'go.mod', 'go.sum', 'main.go', 'requirements.txt', 'setup.py',
+        'pyproject.toml', 'Pipfile', 'Cargo.toml', 'Cargo.lock',
+        'package.json', 'tsconfig.json', 'fast.yaml', '.git', 'Makefile', 'Dockerfile',
+      ];
+      if (indicators.some(f => fs.existsSync(path.join(dir, f)))) return true;
+      const exts = ['.go', '.py', '.rs', '.js', '.ts', '.html', '.css', '.vue', '.jsx', '.tsx'];
+      try {
+        if (fs.readdirSync(dir).some(f => exts.some(e => f.endsWith(e)))) return true;
+      } catch {}
+      if (fs.existsSync(path.join(dir, 'bakes'))) return true;
+      return false;
+    } catch { return false; }
+  }
+
+  findBinary() {
+    const candidates = [
+      process.env.CARTOGOPHER_INSTALL_ROOT ? path.join(process.env.CARTOGOPHER_INSTALL_ROOT, 'cartogopher') : null,
+      path.join(this.rootDir, 'cartogopher'),
+      path.join(path.dirname(path.dirname(process.argv[1])), 'cartogopher'),
+      'cartogopher',
+    ].filter(Boolean);
+
+    for (const p of candidates) {
+      if (p === 'cartogopher') {
+        try { execSync('which cartogopher', { stdio: 'pipe' }); return p; } catch { continue; }
+      } else if (fs.existsSync(p)) {
+        return p;
+      }
+    }
+    return null;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // CLI Execution Helper
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  execCLI(args) {
+    if (!this.binary) {
+      throw new Error('cartogopher binary not found. Install with: go install github.com/jakenesler/CartoGopher/cmd/cartogopher@latest');
+    }
+
+    const env = { ...process.env };
+    if (process.env.CARTOGOPHER_API_KEY) {
+      env.CARTOGOPHER_API_KEY = process.env.CARTOGOPHER_API_KEY;
+    }
+
+    if (process.env.DEBUG) {
+      console.error(`execCLI: ${this.binary} ${args.join(' ')}`);
+    }
+
+    try {
+      const stdout = execFileSync(this.binary, args, {
+        timeout: 30000,
+        maxBuffer: 10 * 1024 * 1024,
+        encoding: 'utf8',
+        cwd: this.rootDir,
+        env,
+      });
+      return stdout.trim();
+    } catch (err) {
+      const msg = err.stderr ? err.stderr.toString().trim() : err.message;
+      throw new Error(msg || 'CLI command failed');
+    }
+  }
+
+  /** Resolve bakeDir from MCP args → --out value. Strips /latest suffix since CLI expects parent. */
+  resolveBakeDir(args) {
+    let dir = args?.bakeDir || args?.path || null;
+    if (!dir) return null;
+    // Strip trailing /latest — CLI expects the parent bakes dir
+    return dir.replace(/\/latest\/?$/, '');
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Tool Schemas (identical to v1 for backward compatibility)
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  getToolDefinitions() {
+    // bakeDir is accepted by most tools as an optional override; documented once
+    // here rather than on every field to keep system-prompt cost down.
+    const bakeDir = { type: 'string' };
+
+    return [
+      // ── Setup / modes ─────────────────────────────────────────────
+      {
+        name: 'llm_instructions',
+        description: 'Setup notes for this project.',
+        inputSchema: { type: 'object', properties: { path: { type: 'string' } } },
+      },
+      {
+        name: 'doc_mode_enable',
+        description: 'Verbose mode for doc generation; pair with doc_mode_disable.',
+        inputSchema: { type: 'object', properties: {} },
+      },
+      {
+        name: 'doc_mode_disable',
+        description: 'Exit verbose doc mode.',
+        inputSchema: { type: 'object', properties: {} },
+      },
+
+      // ── Core code intel ───────────────────────────────────────────
+      {
+        name: 'shake',
+        description: 'Repo overview: structure, packages, entry points.',
+        inputSchema: { type: 'object', properties: { path: { type: 'string' } } },
+      },
+      {
+        name: 'bake',
+        description: 'Full bake.json (large; prefer narrower tools).',
+        inputSchema: { type: 'object', properties: { bakeDir } },
+      },
+      {
+        name: 'symbol',
+        description: 'Function/type details: signature, calls, complexity, file:line.',
+        inputSchema: {
+          type: 'object',
+          properties: { name: { type: 'string' }, bakeDir },
+          required: ['name'],
+        },
+      },
+      {
+        name: 'full_symbol',
+        description: 'Verbose symbol details (needs doc_mode_enable).',
+        inputSchema: {
+          type: 'object',
+          properties: { name: { type: 'string' }, bakeDir },
+          required: ['name'],
+        },
+      },
+      {
+        name: 'search',
+        description: 'AST search for functions, types, packages.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            q: { type: 'string' },
+            limit: { type: 'integer' },
+            package: { type: 'string' },
+            bakeDir,
+          },
+          required: ['q'],
+        },
+      },
+      {
+        name: 'supersearch',
+        description: 'AST search with context/pattern filters (identifiers, calls, assigns, strings, etc.).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            query: { type: 'string' },
+            context: { type: 'string', description: 'all|strings|comments|identifiers|map-keys|imports|assignments' },
+            pattern: { type: 'string', description: 'call|assign|return|map-access' },
+            limit: { type: 'integer' },
+            show_context: { type: 'integer' },
+            exclude_tests: { type: 'boolean' },
+            package: { type: 'string' },
+            languages: { type: 'string' },
+          },
+          required: ['query'],
+        },
+      },
+      {
+        name: 'file_functions',
+        description: 'Functions in a file (no full read).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            file: { type: 'string' },
+            include_summaries: { type: 'boolean' },
+            bakeDir,
+          },
+          required: ['file'],
+        },
+      },
+      {
+        name: 'related_to',
+        description: 'Call graph: callers + callees of a symbol.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            symbol: { type: 'string' },
+            depth: { type: 'integer' },
+            bakeDir,
+          },
+          required: ['symbol'],
+        },
+      },
+      {
+        name: 'impact',
+        description: 'Refactor blast radius: callers, endpoints, CRUD, risk score.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            symbol: { type: 'string' },
+            depth: { type: 'integer' },
+            bakeDir,
+          },
+          required: ['symbol'],
+        },
+      },
+      {
+        name: 'api_surface',
+        description: 'Exported functions and types.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            package: { type: 'string' },
+            limit: { type: 'integer' },
+            bakeDir,
+          },
+        },
+      },
+      {
+        name: 'package_summary',
+        description: 'Package stats + top-complexity functions.',
+        inputSchema: {
+          type: 'object',
+          properties: { package: { type: 'string' }, bakeDir },
+          required: ['package'],
+        },
+      },
+      {
+        name: 'crud_operations',
+        description: 'CRUD by entity.',
+        inputSchema: {
+          type: 'object',
+          properties: { entity: { type: 'string' }, bakeDir },
+        },
+      },
+      {
+        name: 'architecture_map',
+        description: 'Directory map; with `intent`, suggests placement.',
+        inputSchema: {
+          type: 'object',
+          properties: { intent: { type: 'string' }, bakeDir },
+        },
+      },
+      {
+        name: 'suggest_placement',
+        description: 'Where to place a new function.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            function_name: { type: 'string' },
+            function_type: { type: 'string', description: 'handler|service|repository|model|util|test' },
+            related_to: { type: 'string' },
+            bakeDir,
+          },
+          required: ['function_name', 'function_type'],
+        },
+      },
+      {
+        name: 'find_docs',
+        description: 'Find README/.env/config files.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            type: { type: 'string', description: 'readme|env|config|all' },
+            root: { type: 'string' },
+          },
+        },
+      },
+
+      // ── API endpoints ─────────────────────────────────────────────
+      {
+        name: 'api_trace',
+        description: 'Trace endpoint: frontend → handler → CRUD.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            endpoint: { type: 'string' },
+            method: { type: 'string' },
+            bakeDir,
+          },
+          required: ['endpoint'],
+        },
+      },
+      {
+        name: 'all_endpoints',
+        description: 'All HTTP endpoints (backend + frontend-called).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            include_frontend: { type: 'boolean' },
+            include_backend: { type: 'boolean' },
+            bakeDir,
+          },
+        },
+      },
+
+      // ── File ops ──────────────────────────────────────────────────
+      {
+        name: 'slice',
+        description: 'Read lines [start, end] of a file.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            file: { type: 'string' },
+            start: { type: 'integer' },
+            end: { type: 'integer' },
+            root: { type: 'string' },
+          },
+          required: ['file', 'start', 'end'],
+        },
+      },
+      {
+        name: 'patch',
+        description: 'Replace lines [start, end], or create new file (omit start/end).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            file: { type: 'string' },
+            function_name: { type: 'string' },
+            start: { type: 'integer' },
+            end: { type: 'integer' },
+            new_content: { type: 'string' },
+            root: { type: 'string' },
+          },
+          required: ['file', 'new_content'],
+        },
+      },
+
+      // ── Frontend (single tool, many ops) ──────────────────────────
+      {
+        name: 'frontend',
+        description: 'Frontend (Vue/React/Svelte/Angular/Proto/GraphQL). See `op`.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            op: {
+              type: 'string',
+              enum: ['summary', 'search', 'template', 'script', 'renderers', 'component', 'props', 'store', 'composables', 'deps', 'react', 'react_component', 'react_hooks', 'svelte', 'svelte_component', 'svelte_stores', 'angular', 'angular_component', 'angular_services', 'angular_routes', 'proto', 'proto_service', 'proto_messages', 'graphql', 'graphql_type', 'graphql_operations'],
+            },
+            name: { type: 'string' },
+            type: { type: 'string', description: 'For search: template|script|all' },
+            depth: { type: 'integer' },
+            limit: { type: 'integer' },
+            bakeDir,
+          },
+          required: ['op'],
+        },
+      },
+
+      // ── External specs (OpenAPI / GraphQL) and academic papers ───
+      {
+        name: 'navigator',
+        description: 'Fetched OpenAPI specs. ops: list, search, endpoint.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            op: { type: 'string', enum: ['list', 'search', 'endpoint'] },
+            query: { type: 'string' },
+            spec: { type: 'string' },
+            path: { type: 'string' },
+            method: { type: 'string' },
+            limit: { type: 'integer' },
+            bakeDir,
+          },
+          required: ['op'],
+        },
+      },
+      {
+        name: 'gqlnav',
+        description: 'Fetched GraphQL schemas. ops: list, search, type, summary.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            op: { type: 'string', enum: ['list', 'search', 'type', 'summary'] },
+            query: { type: 'string' },
+            spec: { type: 'string' },
+            name: { type: 'string' },
+            kind: { type: 'string', description: 'type|input|enum|query|mutation|subscription|all' },
+            limit: { type: 'integer' },
+            bakeDir,
+          },
+          required: ['op'],
+        },
+      },
+      {
+        name: 'scholar',
+        description: 'Academic papers via Semantic Scholar / OpenAlex. ops: search, paper, citations, list.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            op: { type: 'string', enum: ['search', 'paper', 'citations', 'list'] },
+            query: { type: 'string' },
+            id: { type: 'string', description: 'S2 ID, DOI, ArXiv, or OpenAlex ID' },
+            direction: { type: 'string', description: 'citations|references' },
+            source: { type: 'string', description: 's2|openalex' },
+            year: { type: 'string' },
+            fields: { type: 'string' },
+            open_access: { type: 'boolean' },
+            limit: { type: 'integer' },
+            refresh: { type: 'boolean' },
+            bakeDir,
+          },
+          required: ['op'],
+        },
+      },
+
+      // ── Architecture analysis ─────────────────────────────────────
+      {
+        name: 'decompose',
+        description: 'Suggest microservice boundaries from call graph + CRUD ownership.',
+        inputSchema: { type: 'object', properties: { bakeDir } },
+      },
+      {
+        name: 'architecture_smells',
+        description: 'Anti-patterns: god functions, cyclic deps, mega-modules, N+1, layer violations.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            max_complexity: { type: 'integer' },
+            max_fan_out: { type: 'integer' },
+            max_fan_in: { type: 'integer' },
+            max_pkg_funcs: { type: 'integer' },
+            bakeDir,
+          },
+        },
+      },
+    ];
+  }
+
+  setupHandlers() {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: this.getToolDefinitions(),
+    }));
+
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args = {} } = request.params;
+
+      try {
+        const result = this.handleToolCall(name, args);
+        return { content: [{ type: 'text', text: result }] };
+      } catch (error) {
+        return {
+          content: [{ type: 'text', text: `Error: ${error.message}` }],
+          isError: true,
+        };
+      }
+    });
+  }
+
+  handleToolCall(name, args = {}) {
+    if (name === 'doc_mode_enable') {
+      this.docMode = true;
+      return 'Documentation mode ENABLED. Full responses active. Remember to disable when done.';
+    }
+    if (name === 'doc_mode_disable') {
+      this.docMode = false;
+      return 'Documentation mode DISABLED. Back to ultra-compact mode.';
+    }
+    // Collapsed-family tools dispatch by args.op; legacy <family>_<op> names
+    // still route to the same handlers so existing callers don't break.
+    if (name === 'navigator' || name.startsWith('navigator_')) {
+      const op = name === 'navigator' ? (args.op || 'list') : name.substring('navigator_'.length);
+      return this.handleNavigatorTool(`navigator_${op}`, args);
+    }
+    if (name === 'gqlnav' || name.startsWith('gqlnav_')) {
+      const op = name === 'gqlnav' ? (args.op || 'list') : name.substring('gqlnav_'.length);
+      return this.handleGQLNavTool(`gqlnav_${op}`, args);
+    }
+    if (name === 'scholar' || name.startsWith('scholar_')) {
+      const op = name === 'scholar' ? (args.op || 'search') : name.substring('scholar_'.length);
+      return this.handleScholarTool(`scholar_${op}`, args);
+    }
+    return this.handleCoreTool(name, args);
+  }
+
+  handleCoreTool(name, args = {}) {
+    let result;
+    switch (name) {
+      case 'llm_instructions': {
+        const a = ['llm-instructions'];
+        a.push('--root', args?.path || this.rootDir);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'shake': {
+        const a = ['shake-summary'];
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'bake': {
+        const a = ['bake-summary'];
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'full_symbol':
+      case 'symbol': {
+        const a = ['symbol', args.name];
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'search': {
+        const a = ['search', args.q];
+        if (args.package) a.push('--pkg', args.package);
+        if (args.limit) a.push('-l', String(args.limit));
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'supersearch': {
+        const a = ['search', args.query];
+        if (args.context) a.push('--in', args.context);
+        if (args.pattern) a.push('--pattern', args.pattern);
+        if (args.package) a.push('--pkg', args.package);
+        if (args.limit) a.push('-l', String(args.limit));
+        if (args.show_context) a.push('-C', String(args.show_context));
+        if (args.exclude_tests) a.push('--exclude-test');
+        if (args.languages) a.push('--lang', args.languages);
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'slice': {
+        const a = ['slice', args.file, '--start', String(args.start), '--end', String(args.end)];
+        a.push('--root', args.root || this.rootDir);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'patch': {
+        const a = ['patch', args.file, '--content', args.new_content];
+        if (args.start) a.push('--start', String(args.start));
+        if (args.end) a.push('--end', String(args.end));
+        if (args.function_name) a.push('--function', args.function_name);
+        a.push('--root', args.root || this.rootDir);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'api_surface': {
+        const a = ['api-surface'];
+        if (args.package) a.push('--package', args.package);
+        if (args.limit) a.push('--limit', String(args.limit));
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'related_to': {
+        const a = ['related-to', args.symbol];
+        if (args.depth) a.push('--depth', String(args.depth));
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'package_summary': {
+        const a = ['package-summary', args.package];
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'crud_operations': {
+        const a = ['crud'];
+        if (args.entity) a.push('--entity', args.entity);
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'architecture_map': {
+        const a = ['architecture-map'];
+        if (args.intent) a.push('--intent', args.intent);
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'file_functions': {
+        const a = ['file-functions', args.file];
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'suggest_placement': {
+        const a = ['suggest-placement', '--name', args.function_name, '--type', args.function_type];
+        if (args.related_to) a.push('--related-to', args.related_to);
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'find_docs': {
+        const a = ['find-docs'];
+        if (args.type) a.push('--type', args.type);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'frontend': {
+        const a = ['frontend', args.op];
+        if (args.name) a.push('--name', args.name);
+        if (args.type) a.push('--search-type', args.type);
+        if (args.depth) a.push('--depth', String(args.depth));
+        if (args.limit) a.push('--limit', String(args.limit));
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'api_trace': {
+        const a = ['api-trace', args.endpoint];
+        if (args.method) a.push('--method', args.method);
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'all_endpoints': {
+        const a = ['all-endpoints'];
+        if (args.include_frontend === false) a.push('--frontend=false');
+        if (args.include_backend === false) a.push('--backend=false');
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'impact': {
+        if (!args.symbol) throw new Error('Missing required parameter: symbol');
+        const a = ['impact', args.symbol];
+        if (args.depth) a.push('--depth', String(args.depth));
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'decompose': {
+        const a = ['decompose'];
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'architecture_smells': {
+        const a = ['architecture-smells'];
+        if (args.max_complexity) a.push('--max-complexity', String(args.max_complexity));
+        if (args.max_fan_out) a.push('--max-fan-out', String(args.max_fan_out));
+        if (args.max_fan_in) a.push('--max-fan-in', String(args.max_fan_in));
+        if (args.max_pkg_funcs) a.push('--max-pkg-funcs', String(args.max_pkg_funcs));
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+    return result;
+  }
+
+  handleNavigatorTool(name, args = {}) {
+    let result;
+    switch (name) {
+      case 'navigator_list': {
+        const a = ['navigator', 'list'];
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'navigator_search': {
+        const a = ['navigator', 'search', args.query];
+        if (args.spec) a.push('--spec', args.spec);
+        if (args.method) a.push('--method', args.method);
+        if (args.limit) a.push('--limit', String(args.limit));
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'navigator_endpoint': {
+        const a = ['navigator', 'endpoint', args.spec, args.path];
+        if (args.method) a.push('--method', args.method);
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      default:
+        throw new Error(`Unknown navigator tool: ${name}`);
+    }
+    return result;
+  }
+
+  handleGQLNavTool(name, args = {}) {
+    let result;
+    switch (name) {
+      case 'gqlnav_summary': {
+        if (!args.spec) throw new Error('Missing required parameter: spec (schema name from gqlnav_list)');
+        const a = ['gql-nav', 'summary', args.spec];
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'gqlnav_list': {
+        const a = ['gql-nav', 'list'];
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'gqlnav_search': {
+        if (!args.query) throw new Error('Missing required parameter: query');
+        const a = ['gql-nav', 'search', args.query];
+        if (args.spec) a.push('--spec', args.spec);
+        if (args.kind) a.push('--kind', args.kind);
+        if (args.limit) a.push('--limit', String(args.limit));
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'gqlnav_type': {
+        if (!args.spec) throw new Error('Missing required parameter: spec (schema name from gqlnav_list)');
+        if (!args.name) throw new Error('Missing required parameter: name (type/query/mutation name)');
+        const a = ['gql-nav', 'type', args.spec, args.name];
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      default:
+        throw new Error(`Unknown gqlnav tool: ${name}`);
+    }
+    return result;
+  }
+
+  handleScholarTool(name, args = {}) {
+    let result;
+    switch (name) {
+      case 'scholar_search': {
+        if (!args.query) throw new Error('Missing required parameter: query');
+        const a = ['scholar', 'search', args.query];
+        if (args.source) a.push('--source', args.source);
+        if (args.year) a.push('--year', args.year);
+        if (args.fields) a.push('--fields', args.fields);
+        if (args.open_access) a.push('--oa');
+        if (args.limit) a.push('--limit', String(args.limit));
+        if (args.refresh) a.push('--refresh');
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'scholar_paper': {
+        if (!args.id) throw new Error('Missing required parameter: id (paper ID, DOI, ArXiv ID, or OpenAlex ID)');
+        const a = ['scholar', 'paper', args.id];
+        if (args.source) a.push('--source', args.source);
+        if (args.refresh) a.push('--refresh');
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'scholar_citations': {
+        if (!args.id) throw new Error('Missing required parameter: id (paper ID)');
+        const direction = args.direction || 'citations';
+        const a = ['scholar', direction, args.id];
+        if (args.source) a.push('--source', args.source);
+        if (args.limit) a.push('--limit', String(args.limit));
+        if (args.refresh) a.push('--refresh');
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      case 'scholar_list': {
+        const a = ['scholar', 'list'];
+        const out = this.resolveBakeDir(args);
+        if (out) a.push('--out', out);
+        result = this.execCLI(a);
+        break;
+      }
+      default:
+        throw new Error(`Unknown scholar tool: ${name}`);
+    }
+    return result;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Server Lifecycle
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  async run() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+
+    if (process.env.DEBUG) {
+      console.error('cartogopher MCP v4 server started');
+      console.error(`  Root: ${this.rootDir}`);
+      console.error(`  Binary: ${this.binary || 'NOT FOUND'}`);
+    }
+  }
+}
+
+const server = new CartoGopherMCP();
+server.run().catch(console.error);

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "cartogopher",
+  "version": "5.0.0",
+  "description": "AI-native code intelligence: parses codebases into a searchable graph of functions, types, endpoints, and call relationships. CLI + MCP server.",
+  "bin": {
+    "cartogopher": "bin/cartogopher.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "share",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://cartogopher.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JakeNesler/CartoGopher.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JakeNesler/CartoGopher/issues"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Jake Nesler",
+  "keywords": [
+    "code-intelligence",
+    "ast",
+    "mcp",
+    "llm",
+    "code-search",
+    "static-analysis"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.2"
+  },
+  "optionalDependencies": {
+    "@cartogopher/darwin-arm64": "5.0.0",
+    "@cartogopher/darwin-x64": "5.0.0",
+    "@cartogopher/linux-x64": "5.0.0",
+    "@cartogopher/linux-arm64": "5.0.0"
+  }
+}

package/share/cartogopher/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: cartogopher
+description: Code intelligence CLI for analyzing codebases. Use when exploring code architecture, searching for functions, tracing API endpoints, understanding call graphs, or analyzing dependencies. Supports 20+ languages.
+argument-hint: [command] [args]
+allowed-tools: Bash(cartogopher:*) Read
+---
+
+# CartoGopher CLI
+
+Parses codebases into a searchable graph of functions, types, endpoints, and call relationships. Local-only — runs on a SQLite store on disk; no servers to set up.
+
+## Setup
+
+```bash
+cartogopher bake     # parse the current project (~10-30s for typical repos)
+```
+
+That's it. Re-run `cartogopher bake` (or use `cartogopher watch`) when files change; it's incremental.
+
+## Commands
+
+### Search
+```bash
+cartogopher search "CreateUser"                   # name search
+cartogopher search "webhook" --in=strings         # search string literals only
+cartogopher search "TODO" --in=comments           # search comments only
+cartogopher search "Delete" --pattern=call        # find function call sites
+cartogopher search "handles payment" --mode=semantic   # semantic vector search
+```
+
+### Symbol lookup
+```bash
+cartogopher symbol CreateUser              # function details: signature, calls, file, complexity
+cartogopher symbol UserService             # type details: fields, methods
+```
+
+### Call graph
+```bash
+cartogopher related-to HandleRequest             # callers + callees
+cartogopher related-to HandleRequest --depth=3
+```
+
+### Impact analysis (refactor blast radius)
+```bash
+cartogopher impact DeleteUser              # transitive callers, affected endpoints, files, risk score
+cartogopher impact DeleteUser --depth=5
+```
+
+### Architecture
+```bash
+cartogopher architecture-map               # directory map with purpose inference
+cartogopher architecture-smells            # detect anti-patterns (god functions, N+1, mega-modules)
+cartogopher decompose                      # suggest microservice boundaries
+cartogopher suggest-placement NewHandler service   # where to put new code
+```
+
+### API endpoints
+```bash
+cartogopher all-endpoints                  # every HTTP endpoint in the codebase
+cartogopher api-trace /api/users           # trace endpoint: frontend -> handler -> CRUD
+cartogopher api-surface --package=controllers
+```
+
+### CRUD analysis
+```bash
+cartogopher crud                           # entity CRUD breakdown
+cartogopher crud --entity=User
+```
+
+### File operations
+```bash
+cartogopher file-functions controllers/auth.go    # list functions in a file (no full read)
+cartogopher slice auth.go --start=10 --end=50     # read specific lines
+cartogopher patch auth.go --start=10 --end=20 --content="new code"
+```
+
+### Frontend (Vue / React / Svelte / Angular / Proto / GraphQL)
+```bash
+cartogopher frontend summary
+cartogopher frontend component UserCard
+cartogopher frontend search "payment"
+cartogopher frontend deps UserCard
+```
+
+### Overview
+```bash
+cartogopher shake                          # full repo overview (Shake.readme)
+cartogopher package-summary controllers    # package stats + top-complexity functions
+cartogopher find-docs                      # discover README/.env/config files
+```
+
+## Common flags
+
+| Flag | Description |
+|---|---|
+| `--root=PATH` | Project root (default: `.`) |
+| `--limit=N` | Max results (default: 20) |
+| `--depth=N` | Call graph / impact depth (default: 2) |
+| `--package=PKG` | Filter by package |
+| `--lang=LANG` | Filter by language |
+| `--in=CONTEXT` | Search context: `all`, `strings`, `comments`, `identifiers`, `map-keys`, `imports` |
+| `--pattern=TYPE` | Search pattern: `call`, `assign`, `return`, `map-access` |
+| `--mode=semantic` | Vector search (requires `bake` to have populated embeddings) |
+
+## When to use what
+
+- **"Where does X get used?"** → `related-to X` or `search X --pattern=call`
+- **"What would break if I rename X?"** → `impact X`
+- **"What does this codebase look like?"** → `shake` or `architecture-map`
+- **"Are there any code smells?"** → `architecture-smells`
+- **"What's in this file?"** → `file-functions path/to/file` (don't `Read` the whole file)
+- **"What endpoints exist?"** → `all-endpoints`, then `api-trace` on a specific one
+- **"What does this function call?"** → `symbol FunctionName`