repo-ctx MCP Tools Reference¶

Reference for all 18 MCP tools provided by the repo-ctx server. All tools use the ctx- prefix. Targets are auto-detected as local paths or indexed repositories based on format.

Provider support: GitHub, GitLab, and local Git repositories with auto-detection. Supported languages: Python, JavaScript, TypeScript, Java, Kotlin, Smalltalk, C, C++, Go, Rust, Ruby, PHP, C#, Bash (tree-sitter based).

Quick Reference¶

Tool Details¶

ctx-index¶

Index a repository or organization/group. Provider auto-detection: absolute/relative paths -> local; two-part names (owner/repo) -> GitHub; three+ parts -> GitLab.

await mcp.call("ctx-index", { repository: "fastapi/fastapi" });
await mcp.call("ctx-index", { repository: "microsoft", group: true, provider: "github" });
await mcp.call("ctx-index", { repository: "/home/user/projects/myapp" });

ctx-list¶

List all indexed repositories with metadata. Optional provider filter: github, gitlab, local.

await mcp.call("ctx-list", {});
await mcp.call("ctx-list", { provider: "local" });

ctx-search¶

Unified search for repositories or symbols. Default mode is fuzzy repository search.

await mcp.call("ctx-search", { query: "fastapi" });
await mcp.call("ctx-search", { query: "UserService", mode: "symbols", target: "./src" });

ctx-docs¶

Retrieve documentation for an indexed repository.

await mcp.call("ctx-docs", { repository: "/fastapi/fastapi", max_tokens: 10000, include: ["code", "diagrams"] });

ctx-analyze¶

Analyze code and extract symbols. Auto-detects local path vs indexed repo.

await mcp.call("ctx-analyze", { target: "./src", lang: "python", type: "class" });

ctx-symbol¶

Get detailed information about a specific symbol including signature, documentation, location, and dependencies.

await mcp.call("ctx-symbol", { name: "UserService.createUser", target: "./src" });

ctx-symbols¶

List all symbols defined in a specific file.

await mcp.call("ctx-symbols", { file: "./src/services/user.py" });

ctx-graph¶

Generate dependency graph showing relationships between code elements.

await mcp.call("ctx-graph", { target: "./src", type: "module", format: "dot" });

ctx-dsm¶

Generate a Design Structure Matrix for architecture analysis. A triangular matrix indicates clean layered architecture; cells above the diagonal indicate cycles.

await mcp.call("ctx-dsm", { target: "./src", type: "module" });

ctx-cycles¶

Detect dependency cycles using Tarjan's algorithm. Returns cycle nodes, edges, impact scores, and breakup suggestions.

await mcp.call("ctx-cycles", { target: "./src", type: "module" });

ctx-layers¶

Detect architectural layers from dependency structure using topological analysis.

await mcp.call("ctx-layers", { target: "./src", type: "class" });

ctx-architecture¶

Analyze architecture with layer detection and optional YAML-based rule enforcement. Rules define layer ordering and forbidden dependencies.

await mcp.call("ctx-architecture", { target: "./src" });
await mcp.call("ctx-architecture", { target: "./src", rules_file: "./arch-rules.yaml" });

ctx-metrics¶

Calculate XS (eXcess Structural complexity) metrics. Returns grade (A-F), XS score, component breakdown (cycles, coupling, size, violations), and complexity hotspots.

await mcp.call("ctx-metrics", { target: "./src", type: "module" });

ctx-llmstxt¶

Generate a compact llms.txt summary for a repository (under 2000 tokens). Returns project overview, key files, quickstart guide, and documentation links.

await mcp.call("ctx-llmstxt", { repository: "fastapi/fastapi" });

ctx-dump¶

Export repository analysis to a .repo-ctx directory. Creates a static snapshot including metadata, symbols, and architecture analysis.

await mcp.call("ctx-dump", { path: "./", level: "full", force: true });

ctx-query¶

Run a CPGQL query on source code. Requires Joern installation.

await mcp.call("ctx-query", { path: "./src", query: "cpg.method.name.l" });

ctx-export¶

Export Code Property Graph to a visualization format. Requires Joern installation.

await mcp.call("ctx-export", { path: "./src", output_dir: "./cpg-output", representation: "cfg" });

ctx-status¶

Show system status including Joern availability and supported languages. Optional component parameter: all (default), joern, languages.

await mcp.call("ctx-status", {});

Typical Workflow¶

// 1. Index
await mcp.call("ctx-index", { repository: "fastapi/fastapi" });
// 2. Search
await mcp.call("ctx-search", { query: "fastapi" });
// 3. Read docs
await mcp.call("ctx-docs", { repository: "/fastapi/fastapi", max_tokens: 10000 });
// 4. Analyze code
await mcp.call("ctx-analyze", { target: "/fastapi/fastapi", lang: "python" });
// 5. Check architecture
await mcp.call("ctx-metrics", { target: "./src" });
await mcp.call("ctx-cycles", { target: "./src", type: "module" });

Configuration¶

Minimal setup (local repos + GitHub public):

{
  "mcpServers": {
    "repo-ctx": {
      "command": "uvx",
      "args": ["repo-ctx"]
    }
  }
}

Full setup (all providers):

{
  "mcpServers": {
    "repo-ctx": {
      "command": "uvx",
      "args": ["repo-ctx"],
      "env": {
        "GITLAB_URL": "https://gitlab.company.com",
        "GITLAB_TOKEN": "${GITLAB_TOKEN}",
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Provider requirements: Local repos need no config. GitHub public needs no config (60 req/hr). GitHub private requires GITHUB_TOKEN (5000 req/hr). GitLab requires GITLAB_URL + GITLAB_TOKEN.

Error Messages¶

Tips¶

1. Search before indexing -- use ctx-search to check if a repository is already indexed.
2. Index in batches -- use ctx-index with group: true instead of multiple single-repo calls.
3. Use specific versions -- /owner/repo/v1.0.0 for stable docs vs /owner/repo for latest.
4. Filter by topic -- ctx-docs with topic narrows results to relevant sections.
5. Explicit provider -- set provider when two-part paths could be GitLab or GitHub.
6. Architecture workflow -- run ctx-metrics for a quick health check, then ctx-cycles and ctx-dsm to investigate issues.

Further Reading¶

• User Guide
• API Reference
• Architecture Analysis Guide