Skip to main content
Glama
Nis7538

repo-compass

by Nis7538
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

repo-compass

An MCP server that gives coding agents structural understanding of a codebase — symbols, references, module dependencies, diff impact, hotspots — plus an eval harness that measures whether it actually helps.

Under construction. See PLAN.md for the roadmap. Done so far: M0 (scaffold), M1 (indexer).

Install

uv sync

Related MCP server: codebase-rag

Usage

uv run compass index path/to/repo              # index Java + Python (incremental on re-run)
uv run compass symbol Order.add --repo path/to/repo --refs

compass symbol accepts a simple name (add), a qualified suffix (Order.add) or search words (getUser also finds get_user_by_id). --refs lists call sites, each labeled with a confidence tier:

method com.example.shop.model.Order.add  public Order add(Item item)  .../model/Order.java:25
    exact    .../model/Order.java:36:13  add(...)
    likely   .../service/OrderService.java:17:19  order.add(...)

The index is stored in your user cache directory (never inside the repository); --db overrides the location.

Limitations

  • Reference resolution is approximate. It uses names, imports, packages and scopes, not types. exact means the binding is certain from syntax; likely means the target's class is visible but the receiver's type is unknown; possible means only the name matches. There is no type inference or override/dispatch analysis. Details and known failure cases: ADR-003.

  • Only call sites are references. Type usages (parameters, extends, casts) are not.

  • Outside a git work tree, .gitignore is not applied (ADR-004).

  • Java and Python only.

Indexing speed: about 2.4s for a 50k-line repo, and 7.3s for apache/commons-lang (207k lines). See docs/benchmarks.md, including the slower first run after a fresh clone.

Development

uv run pytest -q                 # tests (includes a ~5s benchmark marked slow)
uv run pytest -q -m "not slow"   # skip the benchmark
uv run ruff check .              # lint
uv run ruff format --check .     # format check
uv run python scripts/bench_index.py --synthetic 50000

Design decisions are recorded in docs/adr/.

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Axon

    harshkedia177
    A
    license
    Not graded
    quality
    C
    maintenance
    A graph-powered code intelligence engine that indexes codebases into a structural knowledge graph to provide AI agents with deep context on function calls, types, and execution flows. It offers local, zero-dependency tools for hybrid search, impact analysis, and dead code detection across Python, JavaScript, and TypeScript projects.
    956 PyPI
    814
    MIT

  • codebase-rag

    Ar-maan05
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables LLM agents to efficiently understand and navigate a codebase by providing semantic search over symbols and a reference graph, replacing expensive grep/glob calls with structured tools like definition lookup, caller/callee queries, and change-impact analysis.
    3
    MIT

  • code-graph-mcp

    attaxr
    A
    license
    Not graded
    quality
    B
    maintenance
    Turns a codebase into a queryable graph with semantic search, call graphs, and control/data flow analysis, served to AI coding agents via the Model Context Protocol.
    401 npm
    MIT