# Agentforge Graph > Turn any repo into a Code Knowledge Graph your coding agent can reason over — symbols, API routes, ORM models, architecture decisions & git history as a typed, provenance-tracked graph, served over MCP. Built on AgentForge. - **Type:** MCP server - **Install:** `agentstack add mcp-scaffoldic-agentforge-graph` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Scaffoldic](https://agentstack.voostack.com/s/scaffoldic) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [Scaffoldic](https://github.com/Scaffoldic) - **Source:** https://github.com/Scaffoldic/agentforge-graph - **Website:** https://pypi.org/project/agentforge-graph/ ## Install ```sh agentstack add mcp-scaffoldic-agentforge-graph ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # agentforge-graph [](https://github.com/Scaffoldic/agentforge-graph/actions/workflows/ci.yml) [](https://pypi.org/project/agentforge-graph/) [](https://pypi.org/project/agentforge-graph/) [](https://github.com/Scaffoldic/agentforge-graph/blob/main/LICENSE) > **Turn any repo — or your whole org — into a knowledge graph your coding agent > can actually reason over.** Symbols, calls, imports, **API routes, ORM models, > dependency injection, architecture decisions, git history, LLM summaries** — one > typed, provenance-tracked graph, served over **MCP** in a single command. Scale > it from one repo to a **federated workspace** with **cross-service tracing**, on > a **central** index hosted for the team. Plain code-graph tools answer *"what is connected."* Agents also need *"what is this **for**, what decision governs it, what's the API surface, which tables does this touch, who calls this, what changed."* **agentforge-graph puts parsed structure, framework semantics, architecture decisions, git evolution, and LLM enrichment in one graph an agent can traverse — every fact carrying its provenance.** Built on [AgentForge](https://pypi.org/project/agentforge-py/). ```bash pip install agentforge-graph # ← the engine is in the box; nothing else to run ckg index . # repo → typed graph in seconds (no creds, no server) ckg serve-mcp --repo . # → 10 read-only tools for your agent ``` Index a FastAPI + SQLAlchemy app → its routes, ORM models (with relations), and DI graph — no creds, no server. --- ## What you get out of the box - 🧩 **A typed code graph in one command** — `pip install` → `ckg index .` → files, classes, functions, methods with stable descriptor-based ids and `CONTAINS`/`IMPORTS`/ `CALLS`/`INHERITS` edges. **Embedded Kuzu + LanceDB under `.ckg/` — no server, no cloud, no config.** 10 languages: Python, TypeScript, JavaScript, Go, Ruby, PHP, Java, C#, C++, Rust. - 🌐 **Framework semantics as graph edges** *(the differentiator)* — routes, ORM models, and DI, not just calls. `ckg routes` is your API surface, `ckg models` your data model, `ckg services` your injection map — across **11 packs**: FastAPI, Flask, SQLAlchemy, Django (Python); Express, NestJS (JS/TS); Spring (Java); Gin (Go); ASP.NET (C#); Laravel (PHP); Rails (Ruby). - 🏛️ **Decisions ↔ code** *(the differentiator)* — ingests ADRs/docs and links them to the code they `GOVERN`. A hit on `payments/` surfaces *"ADR-0012 (accepted): idempotency keys must be client-side"* **before** the agent edits. - 🕰️ **Git evolution built in** — `ckg history `, `ckg changed-since `, and `--as-of ` reconstruction. Churn and authorship ride the graph. - 🔎 **Hybrid retrieval** — vector search **entry** → typed **graph expansion**. Ask in natural language, get *connected* context: the symbol, its callers, *and* its governing decision. - ⚡ **Incremental & always-fresh** — re-index only the diff (edit 3 files in a 5k-file repo → seconds, not minutes; embeddings/enrichment recompute only what changed). Keep it fresh automatically: **`ckg watch`** re-indexes your working copy on a trigger you choose (commit / idle / save), and **`ckg ci init`** scaffolds a workflow that keeps the shared central index fresh on every merge. - 🤖 **Agent-native, wired in one command** — served read-only over **MCP (10 tools)** or as a native AgentForge toolset, every response carrying a staleness envelope. **`ckg setup`** writes your agent's MCP config for you. - 🧠 **LLM enrichment, budgeted & opt-in** — design-pattern tags (*"this class is a Repository,"* with confidence + rationale) and bottom-up module summaries, all `llm`-provenance. **CI needs no model calls or cloud creds.** - 🏢 **Scales from one repo to a whole org** — host the index **centrally** (shared dir or SurrealDB/Neo4j), built once and consumed **read-only** by many; serve a multi-repo **workspace** from one federated MCP endpoint; and **trace requests across services** — `ckg services-map` / `ckg trace` draw the cross-service call graph (HTTP client → route, matched by path or OpenAPI contract). **Status: 0.6.4 — org-scale, built in one command, wired in one, kept fresh automatically, and now queryable.** 0.6.4 adds a read-only **structural query** surface (`ckg query --graph` / the `ckg_query` tool) — a guard-railed Cypher subset for the exact questions no typed verb covers, identical across every storage backend. 0.5 added central hosting, a federated multi-repo workspace, and cross-service tracing; 0.6 adds the **build side** — stand up a multi-repo CKG from one `workspace.yaml` + one config + `ckg build --workspace` (members local or by git URL), with fail-fast `ckg doctor` validation and config/CLI-controlled tracing. 0.6.2 adds **`ckg setup`** — one command wires the graph into your agent; 0.6.3 adds **`ckg watch`** (local, keep-fresh-on-a-trigger) and **`ckg ci init`** (a CI workflow that refreshes the central index on every merge). Published on [PyPI](https://pypi.org/project/agentforge-graph/). Each language pack validated on a real OSS repo with a creds-enabled embed/retrieval/enrich run; a real agent answers questions over the tools unattended. See the [`CHANGELOG`](https://github.com/Scaffoldic/agentforge-graph/blob/main/CHANGELOG.md) and [`docs/features/TRACKER.md`](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/features/TRACKER.md). --- ## Run it three ways — one repo, a workspace, or a central store ```bash # 1) a single repo — a typed graph in seconds ckg index . && ckg routes . # 2) a central store — host the index outside the repo, consume read-only # (set store.central_root in ckg.yaml; built once by CI, read by many) ckg status . --read-only # 3) a workspace — build many repos with one command, then the cross-service graph ckg build --workspace workspace.yaml # index (+embed) every member, one command ckg services-map --workspace workspace.yaml # who calls whom (HTTP → route) ckg trace payments --workspace workspace.yaml --direction upstream # blast radius ``` > **Configure once, fail fast.** A `defaults:` block in `workspace.yaml` (store > location, embedder, read-only) is inherited by every member, with per-member > overrides; members can be **local paths or git URLs**. `ckg doctor [--workspace]` > validates the config (drivers installed, credentials present) before you build. Single repo → central store → workspace — the cross-service call graph and blast-radius trace, all creds-free. → pick your path: **[a single repo](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/1-single-repo.md)** · **[a workspace](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/2-workspace.md)** · **[a central store](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/3-central-store.md)**. --- ## Quick start > **Prefer a guided walkthrough?** Pick your setup — **[a single repo](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/1-single-repo.md)** (~10 min), **[a workspace](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/2-workspace.md)** (microservices, one federated endpoint), or **[a central store](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/3-central-store.md)** (org-level shared index) — from the **[Getting started hub](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/01-getting-started.md)**. Or browse all [step-by-step guides](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/README.md). ```bash pip install agentforge-graph # engine included (tree-sitter + kuzu + lancedb) # 1) index a repo into the graph — incremental on every run after the first ckg index . # files/classes/functions/calls (+ ADRs, routes, models…) # explore the graph — no embeddings, no creds, no server ckg map --budget 2000 # centrality-ranked repo orientation ckg routes # API surface: METHOD PATH → handler ckg models # ORM data models: table, fields, relations ckg services # dependency-injection map ckg decisions --status accepted # ADRs and what they govern ckg history # when/who/churn for a symbol ckg status # indexed commit, staleness, node counts ``` Add **semantic search** with any embedding provider (AWS Bedrock, OpenAI, or a local OpenAI-compatible server — see [Models](#models--pick-a-provider-or-bring-your-own)): ```bash pip install "agentforge-graph[bedrock]" # or [openai] ckg embed . # AST chunks → vectors ckg query "how are auth tokens validated" # ranked, *connected* context ckg query --symbol "" --mode impact # reverse deps — "who calls this" # optional: explicit, budgeted LLM enrichment ckg enrich . --all --budget-usd 2 # design-pattern tags + module summaries ckg tagged Repository # symbols tagged with a design pattern ``` ### See it in action ```text $ ckg index . indexed 1c2f3a4 · 412 files · 5,290 nodes / 9,133 edges · 3.1s $ ckg routes POST /payments/{pid}/refund → refund() (app/api.py:42) GET /health → health() (app/api.py:16) $ ckg models users [users] (app/models.py:7) fields: id, name, email relations: posts→posts (relationship) $ ckg query "how are auth tokens validated" auth/tokens.py:88 TokenValidator.validate (cosine 0.71) ← called by api/middleware.py:23 require_auth ⚖ governed by ADR-0007 (accepted): signing keys must rotate every 90 days ``` That last block is the whole point: a natural-language question returns the symbol, **who calls it**, *and* **the decision that governs it** — connected, with provenance. ### Serve it to an agent Read-only over MCP — **10 typed tools**: `ckg_repo_map`, `ckg_search`, `ckg_symbol`, `ckg_impact`, `ckg_neighbors`, `ckg_status`, `ckg_routes`, `ckg_decisions`, `ckg_explain`, `ckg_history` — plus `ckg_query` (a read-only [structural query](docs/guides/13-graph-query.md), added when the backend is query-capable): ```bash ckg setup # wire your agent for you (writes .mcp.json) claude mcp add ckg -- ckg serve-mcp --repo . # or do it manually — stdio (subprocess) ckg serve-mcp --repo . --transport http # or HTTP → http://127.0.0.1:8765/mcp ``` `ckg setup` auto-writes your agent's MCP config (a committable repo `.mcp.json` by default), shows a diff first, and is reversible with `--undo` — see [guide 11](docs/guides/11-agent-auto-configuration.md). Over HTTP, point any MCP client at the URL: `{"mcpServers": {"ckg": {"url": "http://127.0.0.1:8765/mcp"}}}`. ### Keep it fresh ```bash ckg watch # local: re-index on a trigger (commit/idle/save) ckg ci init # central: scaffold a CI workflow that indexes on merge ``` `ckg watch` (opt-in, `pip install 'agentforge-graph[watch]'`) keeps your working copy's graph current — `on-commit` by default, so it won't churn on every save — and refuses a central / read-only store. `ckg ci init` writes a single-writer `.github/workflows/ckg-index.yml` so the shared index refreshes deterministically on merge-to-`main`. See [guide 12](docs/guides/12-watch-and-ci-indexing.md). Or as a native AgentForge toolset: ```python from agentforge import Agent from agentforge_graph.serve import code_graph_tools agent = Agent(model="anthropic:claude-sonnet-4-6", tools=code_graph_tools(".")) ``` → Full guide (tool schemas, client config, guardrails, staleness envelope): [`docs/guides/10-using-over-mcp.md`](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/10-using-over-mcp.md). --- ## What's in the graph | Capability | What you get | |---|---| | **Typed code graph** | Files, classes, functions, methods with stable descriptor-based ids; `CONTAINS`/`IMPORTS`/`CALLS`/`INHERITS` edges. Conservative, no-guess resolution across 10 language packs. | | **Framework awareness** *(differentiator)* | `Route → HANDLED_BY → handler`, `DataModel → HAS_FIELD`/`RELATES_TO`, `Service → INJECTED_INTO` — across 11 packs: FastAPI, Flask, SQLAlchemy, Django, Express, NestJS, Spring, Gin, ASP.NET, Laravel, Rails. `ckg routes`/`models`/`services`. | | **Decisions ↔ code** *(differentiator)* | ADRs/docs ingested and linked to the code they `GOVERN`; doc prose embedded + searchable. | | **Temporal / git evolution** | Per-symbol history, churn, authorship; `changed-since`, `as-of` reconstruction. | | **Hybrid retrieval** | Vector entry → typed graph expansion. Connected context, not a flat list. | | **LLM enrichment** *(differentiator)* | Budgeted design-pattern tags + bottom-up module summaries — `llm`-provenance, opt-out-able. | | **Agent-native** | Read-only MCP (10 tools) or native AgentForge toolset; every response carries a staleness envelope. | | **Embedded-first** | Local Kuzu graph + LanceDB vectors under `.ckg/`. No server. Storage + models pluggable. | --- ## Retrieval quality (measured) Retrieval is the core agent-facing surface, so we measure it — not vibes. On an **objective** natural-language→code benchmark (each documented symbol's docstring is the query, that symbol is the gold answer; labels come straight from the graph's `DESCRIBES` edges, verified leakage-free), over **388 queries across 4 real OSS repos** (click, httpx, flask, fastapi) with Bedrock `cohere.embed-v4`: | | base hybrid retrieval | + Bedrock cross-encoder rerank (w=0.3) | |---|---|---| | **MRR** | 0.952 | 0.971 | | **recall@1** | 0.915 | 0.948 | Base retrieval lands the right code at **rank ≈ 1** out of the box. The optional cross-encoder reranker (Bedrock Rerank — no torch) adds a small but **statistically significant** precision gain (ΔMRR +0.019, 95% CI [+0.008, +0.031], p < 0.001 by paired bootstrap) for ~440 ms/query — so it's **opt-in**, for when top-1 precision is worth the latency. Full method + numbers: [`docs/validation/rerank/benchmark.md`](docs/validation/rerank/benchmark.md). --- ## Storage — what DB, and can I switch it? **By default, nothing to run.** The graph lives in an embedded **Kuzu** database and the vectors in an embedded **LanceDB** index, both under `.ckg/` in your repo (ADR-0006). Zero config, no server. Storage is **pluggable** behind two contracts — `GraphStore` and `VectorStore` ([`core/contracts.py`](https://github.com/Scaffoldic/agentforge-graph/blob/main/src/agentforge_graph/core/contracts.py)) — resolved by a **driver registry** with entry-point groups ([`store/registry.py`](https://github.com/Scaffoldic/agentforge-graph/blob/main/src/agentforge_graph/store/registry.py)): ```yaml # agentforge.yaml (engine config lives under app:) app: store: graph: { driver: kuzu } # built-in vectors: { driver: lancedb } # built-in ``` Three server backends ship first-party as opt-in extras: **Neo4j** (graph), **Postgres/pgvector** (vectors), and **SurrealDB** — multi-model, so one server is *both* graph + vectors. Each passes the *same* `GraphStoreConformance` / `VectorStoreConformance` suite the embedded defaults do (run against live servers in CI). Anything else (SurrealDB aside) is an **out-of-tree adapter**: implement the contract, pass the conformance suite, register an entry point — then it's `pip install + one config line`, no core change. → [`docs/guides/09-storage-backends.md`](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/09-storage-backends.md). ## Models — pick a provider, or bring your own Every model boundary is an **interface** resolved by a provider registry, so switching providers is a on … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Scaffoldic](https://github.com/Scaffoldic) - **Source:** [Scaffoldic/agentforge-graph](https://github.com/Scaffoldic/agentforge-graph) - **License:** Apache-2.0 - **Homepage:** https://pypi.org/project/agentforge-graph/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** yes - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-scaffoldic-agentforge-graph - Seller: https://agentstack.voostack.com/s/scaffoldic - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.