Groundwork MCP

Groundwork is a local-first MCP server that gives Claude (or any MCP-compatible AI) cited evidence from a codebase by indexing source files with tree-sitter and building a queryable knowledge base of symbols, imports, file content, and structure.

Groundwork returns evidence pinned to the indexed commit so an assistant can verify what it uses:

• "What is this project about?" → reads the actual README.md
• "Where is DQNPricingAgent defined?" → returns file + line number + signature
• "What does rag_agent.py import?" → returns the real import graph
• "Search for all uses of pgvector" → full-text search across all files
• "List all Python files in the agents/ directory" → directory-grouped file tree
• "Delete the ECHO repo index" → removes it cleanly from the database

Groundwork provides source evidence with commit-pinned citations. The assistant remains responsible for interpreting that evidence correctly.

The hosted public architecture page is available at the web service root when deployed with Docker Compose. It shares index snapshots by repository and commit SHA.

How It Works

GitHub Repo URL
      │
      ▼
  GitHub tarball API           ← commit-pinned source, no local Git required
      │
      ▼
  The Sieve                   ← strips binaries, lock files, node_modules,
      │                          hidden dirs, oversized files, etc.
      ▼
  tree-sitter language pack    ← real AST extraction for 40+ mapped languages
      │                        ← raw text retained for indexed files
      ▼
  SQLite (local, WAL mode)     ← jobs · parsed_files · FTS5 · symbols · edges
      │                          32MB cache · auto-migration · cascade deletes
      ▼
  14 MCP Tools                 ← structured, commit-pinned evidence
      │
      ▼
  Auto-cleanup                 ← clone directory removed after parse (disk efficient)

Tools

Supported Languages

The tree-sitter language pack provides the grammars; Groundwork maps 40+ common source/config languages and stores raw UTF-8 content up to the configured file-size limit (512KB by default). Grammars load lazily, so only languages present in a repo are needed. The first use of a grammar may download its parser library; repo source itself stays local. File reads accept 1-based start_line and inclusive end_line (0 requests EOF), return at most 200 lines per call, and include next_start_line when more content is available. Search, symbol, and call-graph results include repo, commit SHA, path, line span, and a permalink where source locations exist. Repository text is marked as untrusted evidence.

Installation

Fastest setup (PyPI)

Install Python 3.11+ and uv, then use:

uvx --from groundwork-mcp groundwork-mcp

Claude Code:

claude mcp add --scope user groundwork -- uvx --from groundwork-mcp groundwork-mcp

Cursor mcp.json:

{
  "mcpServers": {
    "groundwork": {
      "command": "uvx",
      "args": ["--from", "groundwork-mcp", "groundwork-mcp"]
    }
  }
}

VS Code and Cursor workspace extension

The lightweight workspace extension is in extensions/vscode. It starts Groundwork over local MCP stdio and indexes each open workspace through ingest_local_path:

cd extensions/vscode
npm install
npm run compile
npx @vscode/vsce package
code --install-extension groundwork-mcp-0.1.0.vsix

The extension defaults to the PyPI uvx command. Until PyPI publishing is enabled, set groundwork.command to uv and groundwork.args to run --project <path-to-groundwork-mcp> groundwork-mcp. Automatic workspace indexing can be disabled with groundwork.autoIndex.

Claude Desktop uses the same command and args in its mcpServers.groundwork entry. The PyPI command becomes live after PyPI trusted publishing is configured and a GitHub release successfully publishes the package. For the first release, add a pending trusted publisher in PyPI account settings with GitHub owner ARYANRAJ1121, repository groundwork-mcp, workflow publish-pypi.yml, and environment pypi, then publish GitHub Release v0.6.0. Until that succeeds, use the source setup below or the existing v0.5.0 Docker image.

Prerequisites

• Python 3.11+
• uv — install
• Internet access to GitHub for remote repositories (ingest_local_path works offline)

Setup

# 1. Clone
git clone https://github.com/ARYANRAJ1121/groundwork-mcp.git
cd groundwork-mcp

# 2. Install dependencies (include router for Laya)
uv sync --extra router

# 3. Verify
uv run python -c "from groundwork_mcp.server import mcp; print('OK')"

Claude Desktop Configuration

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "groundwork": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "C:\\path\\to\\groundwork-mcp",
        "groundwork-mcp"
      ]
    }
  }
}

Restart Claude Desktop. Groundwork appears under Integrations.

Usage Example

You:    Ingest https://github.com/ARYANRAJ1121/ECHO

Claude: [ingest_repo]        Job started: abc-123. Polling...
        [get_ingest_status]  Parsing 28/34 files (82%)...
        [get_ingest_status]  Complete — 34 files, ~74K tokens. Commit df87f2d7.

You:    What is this project about?

Claude: [get_file_content → README.md]
        ECHO is a multi-agent pricing simulation where AI agents compete
        in a simulated market. The project studies whether agents develop
        collusive pricing behavior...

You:    List all files in the agents directory.

Claude: [list_repo_files → path_filter=agents]
        agents/
          dqn_agent.py      python   187 lines   8KB
          heuristic_agent.py python  142 lines   5KB
          llm_agent.py      python   201 lines   9KB
          rag_agent.py      python   218 lines  10KB
          rl_agent.py       python   163 lines   7KB

You:    Where is DQNPricingAgent defined?

Claude: [query_symbols → name=DQNPricingAgent]
        [class] DQNPricingAgent
                agents/dqn_agent.py:12–187
                → class DQNPricingAgent(BasePricingAgent):

You:    Search for pgvector across all files.

Claude: [search_code → query=pgvector]
        6 result(s) for 'pgvector':
          docker-compose.yml
            L14:   POSTGRES_EXTENSIONS: pgvector
          agents/rag_agent.py
            L8:    from pgvector.psycopg2 import register_vector
            L47:   self.cursor.execute("CREATE EXTENSION IF NOT EXISTS pgvector")

Configuration

Control behaviour via environment variables:

Local and private repositories

Call ingest_local_path(path) to index a directory on the machine running Groundwork. Source stays on that machine and the SQLite index remains in GROUNDWORK_DATA_DIR. For private GitHub repositories, set GROUNDWORK_GITHUB_TOKEN to a fine-grained token with read-only Contents access before starting local mode. Tokens are sent to GitHub over HTTPS and never written to the database. Shared remote mode rejects server-wide private tokens.

Streamable HTTP and OAuth

For a self-hosted remote MCP endpoint, register a GitHub OAuth App and set the OAuth variables above, then start with GROUNDWORK_TRANSPORT=http. FastMCP serves Streamable HTTP at /mcp. Put HTTPS/TLS in front of public deployments. The unauthenticated HTTP override is for local development only.

Docker

Local stdio mode keeps the index in a named volume:

docker run --rm -i -v groundwork-data:/data ghcr.io/aryanraj1121/groundwork-mcp:v0.6.0

To build the image from source instead, run docker build -t groundwork-mcp . and replace the image name above with groundwork-mcp.

Compose runs the OAuth-protected MCP endpoint and public architecture page together. Set the OAuth variables in .env, set the base URL to the public HTTPS MCP URL, and route TLS traffic to ports 8000 and 8080:

docker compose up -d --build

The public page only indexes GitHub public repos. Its shared cache is keyed by (repository, commit SHA).

Data Storage

~/.groundwork/
  groundwork.db      # SQLite — all jobs, files, symbols, edges
  repos/             # Temporary clone dirs (auto-deleted after parse)

Schema

Optional semantic retrieval

Keyword search works out of the box through SQLite FTS5. For conceptual queries, install Ollama, pull an embedding model, and build a per-snapshot semantic index:

ollama pull nomic-embed-text
# Call index_semantic(job_id) once for each repository snapshot.
# Then call search_code(job_id, query, mode="hybrid") or mode="semantic".

Embeddings are generated by the local Ollama service and stored in the local SQLite database. They are opt-in; normal ingestion and keyword search do not download a model or send repository content to an embedding service. Re-index semantic chunks after indexing a new commit.

Benchmark

benchmarks/tasks.json and its fixture repo define a repeatable paired repo-QA benchmark. The same model answers once with the complete repository (the no-Groundwork baseline) and once with Groundwork FTS-retrieved evidence. It reports answer accuracy, citation precision for both arms, and provider-reported token counts with per-task responses. The benchmark runs locally through Ollama and does not require a paid API key. Start Ollama and install a model, then run:

uv sync --locked
ollama pull llama3
uv run python benchmarks/run.py --model llama3:latest

Set OLLAMA_HOST if Ollama is listening somewhere other than http://localhost:11434. Raw output is written to the ignored benchmark-results.json.

Initial local run (2026-10-30, Ollama llama3:latest, 13 synthetic fixture questions): baseline and Groundwork each scored 13/13 answers and 13/13 exact citations. The baseline used 3,330 model-reported tokens; Groundwork used 1,638, a 50.81% reduction. This is one small fixture run, not evidence of lower hallucination rates or production performance. The per-task report is in benchmarks/results/ollama-llama3-2026-10-30.json.

Production Features

• Commit-pinned ingestion — GitHub tarball download avoids local Git, deep paths, and branches moving during the fetch
• Staleness checks — re-ingesting checks the remote tip and creates a fresh snapshot when it changed
• Hybrid retrieval — ranked FTS5 keyword search by default, with optional local Ollama embeddings and reciprocal-rank fusion
• Isolated worker state — one SQLite connection and parser instance per thread, with WAL mode
• Concurrency limit — max 2 ingestion jobs run simultaneously via asyncio semaphore
• Auto-cleanup — clone directory deleted after parse; all data lives in SQLite
• Auto-migration — new columns added to existing databases on startup, no manual steps
• WAL mode — SQLite Write-Ahead Logging for concurrent reads during writes
• Untrusted source framing — repository contents are labeled as evidence, never as model instructions
• No credentials stored — optional token is read from environment and never stored in SQLite
• Binary detection — skips images, executables, and non-text files automatically

Security

• HTTPS GitHub URLs only — SSH and non-GitHub URLs are rejected at validation
• Commit-pinned archive — GitHub tarballs are downloaded at a resolved immutable commit
• File size limits — configurable caps on total repo size and individual files
• No shelling out to Git — remote ingestion uses HTTPS API/tarballs
• Public shared index — hosted page accepts public repos only; local mode supports private sources

Stack

License

MIT — LICENSE