# npx
claude mcp add codemap -- npx mcp-codemap

# docker
claude mcp add codemap -- docker run --rm -i -v .:/project:z ghcr.io/breca/mcp-codemap

npx mcp-codemap serve -p /path/to/your/project

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

{
  "mcpServers": {
    "codemap": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", ".:/project:z", "ghcr.io/breca/mcp-codemap"]
    }
  }
}

{
  "mcp": {
    "codemap": {
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-codemap"]
    }
  }
}

{
  "mcp": {
    "codemap": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", ".:/project:z", "ghcr.io/breca/mcp-codemap"]
    }
  }
}

{
  "mcp": {
    "codemap": {
      "type": "local",
      "command": ["npx", "mcp-codemap"]
    }
  }
}

{
  "mcp": {
    "codemap": {
      "type": "local",
      "command": ["docker", "run", "--rm", "-i", "-v", ".:/project:z", "ghcr.io/breca/mcp-codemap"]
    }
  }
}

mcpServers:
  - name: codemap
    command: npx
    args:
      - mcp-codemap

mcpServers:
  - name: codemap
    command: docker
    args:
      - run
      - --rm
      - -i
      - -v
      - .:/project:z
      - ghcr.io/breca/mcp-codemap

map(scope?, detail?, max_depth?)

map(detail="names")                          # orient on the whole project
map(scope="src/api", detail="signatures")    # drill into a module
map(detail="full")                           # inspect dependency graph

PROJECT: 53 files | 642 entities | csharp/go/java/javascript/kotlin/php/python/ruby/rust/typescript
INDEXED: just now
C=class F=function M=method I=interface P=property E=enum V=variable T=type N=namespace

=== src/tools/ [5 files, 13 entities] ===

  src/tools/describe-entity.ts
    I DescribeEntityParams :6-9
      "Parameters for the describe-entity tool."
    F describeEntity :12-27
      "Generate or retrieve a natural-language description for a named entity."
    F formatDescribeResult :29-37

  src/tools/get-context.ts
    I GetContextParams :5-9
      "Parameters for the map tool: optional scope, depth limit, and detail level."
    F getContext :12-18
      "Build and return the compact text map of the codebase."

  src/tools/query.ts
    I QueryParams :6-8
      "Parameters for the query tool: entity name or qualified name."
    F queryEntity :11-104
      "Deep-dive on a single entity: signature, source, callers, callees, and members."

  src/tools/reindex.ts
    I ReindexParams :6-9
      "Parameters for the reindex tool: optional file paths and force flag."
    F reindex :12-52
      "Re-index changed files; auto-detects via git diff when no paths given."

  src/tools/update-context.ts
    I UpdateContextParams :6-10
      "Parameters for the update-context tool."
    F updateContext :13-55
      "Incrementally update the index; falls back to full rescan if requested."

PROJECT: 53 files | 642 entities | csharp/go/java/javascript/kotlin/php/python/ruby/rust/typescript
INDEXED: just now
C=class F=function M=method I=interface P=property E=enum V=variable T=type N=namespace

=== src/parser/languages/ [11 files, 162 entities] ===

  src/parser/languages/base.ts (10 entities)
  src/parser/languages/python.ts (12 entities)
  src/parser/languages/typescript.ts (10 entities)

  src/parser/languages/base.ts
    I ExtractedEntity :4-17
      "A code entity (class, function, variable, etc.) extracted from a parse tree."
    I FileParseResult :29-33
      "Complete extraction output for a single source file."
    I LanguageExtractor :45-50
      "Contract for language-specific extractors that turn parse trees into entities."
    F getDocComment :53-68
      "Extract a JSDoc-style comment immediately preceding a node."
    F getSignature :82-140
      "Build a human-readable signature string from a class, function, or interface node."

  src/parser/languages/python.ts
    C class PythonExtractor implements LanguageExtractor :11-343  exp
      "Extracts classes, functions, and imports from Python source files."
      P language :12-12
      P extensions :13-13
      M extract(tree: Parser.Tree, sourceCode: string, filePath: string): FileParseResult :15-23
      M walkNode(
    node: Parser.SyntaxNode,
    sourceCode: string,
    filePath: string,
    entities: ExtractedEntity[],
    ...
  ): void :25-97
      M extractEntity(...): ExtractedEntity | null :99-171
    > imports: src/parser/languages/base.ts

  src/parser/languages/typescript.ts
    C class TypeScriptExtractor implements LanguageExtractor :15-352  exp
      "Extracts classes, functions, interfaces, and relationships from TypeScript/TSX files."
      ...
    > imports: src/parser/languages/base.ts
    > used-by: src/parser/languages/javascript.ts

=== RELATIONSHIPS ===
src/parser/languages/javascript.ts -> src/parser/languages/typescript.ts [extends: TypeScriptExtractor]
src/parser/languages/python.ts -> src/parser/languages/base.ts [implements: LanguageExtractor]
src/parser/languages/typescript.ts -> src/parser/languages/base.ts [implements: LanguageExtractor]

query(entity)

query(entity="UserService")             # find by name
query(entity="UserService.createUser")  # find by qualified name

class PythonExtractor [exported]
src/parser/languages/python.ts:10-342

SIGNATURE: class PythonExtractor implements LanguageExtractor

MEMBERS:
  property language :11-11
  property extensions :12-12
  method extract(tree, sourceCode, filePath): FileParseResult :14-22
  method walkNode(...): void :24-96
  method extractEntity(...): ExtractedEntity | null :98-170
  method extractDocstring(...): string | null :172-187

DEPENDS ON:
  imports ExtractedEntity (src/parser/languages/base.ts:3)
  imports FileParseResult (src/parser/languages/base.ts:26)
  implements LanguageExtractor (src/parser/languages/base.ts:40)

USED BY:
  imports ScanResult (src/parser/pipeline.ts:15)

SOURCE:
  10 | export class PythonExtractor implements LanguageExtractor {
  11 |   language = 'python';
  12 |   extensions = ['.py'];
  ...

reindex(paths?, force?)

reindex()                               # auto-detect via git diff
reindex(paths=["src/foo.ts"])           # specific files
reindex(force=true)                     # full rescan, ignore cache

Git diff update (30 changed files)
  Processed: 18
  Skipped (unchanged): 11
  Errors: 1
    src/broken.js: TypeError: Cannot read properties of undefined

{
  "excludePatterns": [
    "**/node_modules/**",
    "**/dist/**",
    "**/build/**",
    "**/.git/**",
    "**/vendor/**",
    "**/__pycache__/**",
    "**/target/**",
    "**/*.min.js",
    "**/*.bundle.js",
    "**/*.generated.*",
    "**/.codemap/**"
  ],
  "maxFileSize": 1000000
}

# npx
npx mcp-codemap map [-s scope] [--detail level]     # print the map
npx mcp-codemap query <entity>                      # inspect an entity
npx mcp-codemap reindex [paths...]                  # re-index
npx mcp-codemap stats                               # show project stats
npx mcp-codemap web [--port 3333]                   # interactive web UI
npx mcp-codemap install-hooks                       # git hooks for auto re-indexing
npx mcp-codemap uninstall-hooks                     # remove installed git hooks

# docker (mount your project at /project)
docker run --rm -v .:/project:z ghcr.io/breca/mcp-codemap map -p /project
docker run --rm -v .:/project:z ghcr.io/breca/mcp-codemap stats -p /project
docker run --rm -v .:/project:z ghcr.io/breca/mcp-codemap query <entity> -p /project
docker run --rm -v .:/project:z -p 3333:3333 ghcr.io/breca/mcp-codemap web -p /project

codemap web [--port 3333]