Skip to content

MCP.md

Latest commit

 

History

History
142 lines (108 loc) · 4.42 KB

MCP.md

File metadata and controls

142 lines (108 loc) · 4.42 KB
Raw

Codemap MCP Server

Run codemap as an MCP server for Claude Code, Codex, or another MCP client.

Setup

Preferred when codemap is already installed:

codemap setup                 # Configure Claude Code and Codex
codemap setup --agent claude  # Configure only Claude Code
codemap setup --agent codex   # Configure only Codex

Setup writes a managed, versioned absolute executable path. After upgrading or moving Codemap, Codex plugin users should run codemap plugin install first, then rerun setup in each configured project. Claude users skip plugin installation but still rerun setup. Use codemap doctor for strict validation; it reports Codex CLI and Desktop runtimes independently. Agent integrations do not automatically refresh the generated local plugin or per-project setup. For a manual, PATH-dependent Claude definition:

claude mcp add --transport stdio codemap -- codemap mcp

Build

make build-mcp

Claude Code

claude mcp add --transport stdio codemap -- /path/to/codemap-mcp

Or add to your project's .mcp.json:

{
  "mcpServers": {
    "codemap": {
      "command": "codemap",
      "args": ["mcp"]
    }
  }
}

Claude Desktop

Claude Desktop cannot see your local files by default. This MCP server runs on your machine and gives Claude that ability.

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "codemap": {
      "command": "codemap",
      "args": ["mcp"]
    }
  }
}

If you prefer a standalone MCP binary, keep using /path/to/codemap-mcp.

Available Tools (17)

Project Analysis

Tool Description
get_structure Project tree view with file sizes and language detection
get_dependencies Dependency flow with imports, functions, and hub files
get_diff Changed files with line counts and impact analysis
find_file Find files by name pattern
get_importers Find all files that import a specific file
get_hubs List all hub files (3+ importers) with dependent counts
get_file_context Complete dependency context for one file (imports, importers, hub status, connected files)

Watch Daemon

Tool Description
start_watch Begin file watching for a project
stop_watch Stop file watcher
get_activity Recent coding activity (hot files, edits, timeline)
get_working_set Current session's working set: files being edited, ranked by activity, with hub status

Skills

Tool Description
list_skills List available skills with names, descriptions, keywords (metadata only)
get_skill Load full instructions for a specific skill by name

Handoff & Meta

Tool Description
get_handoff Build/read layered handoff artifact (prefix + delta) with lazy file detail loading
status Verify MCP connection and local filesystem access
list_projects Discover projects in a parent directory (with optional filter)

Usage

Once configured, Claude can use these tools automatically. Try asking:

  • "What's the structure of this project?"
  • "Show me the dependency flow"
  • "What files import utils.go?"
  • "Is scanner/types.go a hub file?"
  • "What changed since the last commit?"
  • "What have I been editing this session?"
  • "What skills are available for refactoring?"
  • "Build a handoff summary I can continue in another agent"

Handoff Tool Notes

get_handoff supports:

  • latest=true to read previously saved handoff artifact
  • since="2h" and ref="main" to tune generation
  • json=true for machine-readable output
  • save=true to persist generated artifacts (handoff.latest.json, handoff.prefix.json, handoff.delta.json)
  • prefix=true to return only the stable prefix snapshot
  • delta=true to return only the recent delta snapshot
  • file="path/to/file" to lazy-load full detail for one changed file stub

By default, get_handoff does not write to disk unless save=true is set.

Surface behavior note:

  • MCP: read-only by default (save=false)
  • CLI codemap handoff: save by default (--no-save to disable)

Output and budget notes:

  • text responses are byte-budgeted and line-truncated to protect context
  • handoff payload includes deterministic hashes (prefix_hash, delta_hash, combined_hash)
  • handoff payload includes cache metrics (reuse_ratio, unchanged_bytes, etc.)