Graph Server

The Graph Server is an MCP server that builds a structural graph of your code and makes it queryable by any MCP client. No LLM inside — pure deterministic AST analysis.

Getting Started

No Docker and no database server. The default backend is GraphQLite — an embedded SQLite graph that persists to ~/.codesteward/graph.db between sessions. Requires uv (Python 3.12+).

1. Set up once, machine-wide

Auto-detects your installed AI tools (Claude Code, Cursor, Cline, Codex CLI, Gemini CLI), registers the MCP server globally, and merges workflow instructions into your existing config files — nothing is overwritten.

uvx --from "codesteward-mcp[graph-all,graphqlite]" codesteward-mcp setup

To remove everything again, run the same command with --uninstall.

2. Open any repo and ask

No .mcp.json, no per-project config, no repeated setup. The agent builds the graph on first use and queries it from then on.

# Any repository on your machine
cd /path/to/your/project
claude   # or: cursor, cline, codex, gemini

# The agent calls these for you:
graph_status(repo_id="my-project")
graph_rebuild(repo_path="/path/to/your/project", repo_id="my-project")
codebase_graph_query(query_type="referential", query="authenticate", repo_id="my-project")

Manual setup

If you would rather configure it yourself, add the server to your MCP client config directly. uvx downloads and caches the package on first run.

{
  "mcpServers": {
    "codesteward-graph": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "codesteward-mcp[graph-all,graphqlite]",
        "codesteward-mcp", "--transport", "stdio"
      ]
    }
  }
}

Note: Claude Code requires "type": "stdio" in the server config. Cursor and Cline do not need it.

MCP Tools

await graph_rebuild({
  repo_path: "/workspace",
  changed_files: null   // null = full rebuild
})

await codebase_graph_query({
  cypher: `
    MATCH (caller)-[:CALLS*1..5]->(fn:Function)
    WHERE fn.name = "processPayment"
    RETURN caller.name, caller.file
    ORDER BY caller.file
  `,
  repo_id: "payments-service"
})

await graph_augment({
  edges: [{
    source_id: "fn::validatePayment",
    edge_type: "calls",
    target_name: "stripe.charges.create",
    confidence: 0.85,
    rationale: "Dynamic dispatch via SDK client"
  }],
  repo_id: "payments-service"
})

await taint_analysis({
  repo_id:    "payments-service",
  frameworks: ["fastapi"],  // or null to auto-detect
  level:      3
})

Edge Types

Supported Languages

Every supported language contributes the same structural edges to the same graph. Polyglot monorepos get a single queryable model.

Cypher Query Examples

MATCH (caller)-[:CALLS*1..5]->(fn:Function {name: "processPayment"})
RETURN caller.name, caller.file, caller.line_start
ORDER BY caller.file

MATCH (fn:Function)
WHERE fn.name =~ "(?i).*(route|handler|controller).*"
  AND NOT (fn)-[:CALLS|GUARDED_BY]->()
RETURN fn.name, fn.file, fn.line_start

MATCH (child)-[:EXTENDS*1..]->(base:Class {name: "BaseController"})
RETURN child.name, child.file, child.language
ORDER BY child.language, child.file

Backends

GRAPH_BACKEND defaults to auto: Neo4j if a password is set, JanusGraph if its URL is changed, otherwise GraphQLite. For a laptop, the default needs no configuration at all.

NEO4J_URI=bolt://your-host:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your-password

JANUSGRAPH_URL=ws://localhost:8182/gremlin

Supported MCP Clients

The setup command auto-detects and configures these. The table shows where each tool keeps its config if you are wiring it up by hand.

Any other MCP client works too — point it at the same stdio command, or run the server over sse / http on port 3000 via TRANSPORT.

Setup

Prerequisites: Go 1.22+ and a running ClickHouse instance.

1. Apply the schema

clickhouse-client --multiquery < migrations/001_initial.sql

2. Start the proxy

CLICKHOUSE_DSN=clickhouse://localhost:9000/audit \
  go run ./cmd/proxy

3. Point your agent at the proxy

ANTHROPIC_BASE_URL=http://localhost:8080

OPENAI_BASE_URL=http://localhost:8080/v1

GEMINI_API_BASE_URL=http://localhost:8080

AUDIT_PROJECT=myorg/myrepo \
AUDIT_BRANCH=feature/refactor \
CLICKHOUSE_DSN=clickhouse://localhost:9000/audit \
  go run ./cmd/proxy

Configuration

All configuration via environment variables. No config files required.

Proxy Chaining

Audit Proxy slots into existing proxy chains. Set UPSTREAM_PROXY and it forwards through your existing proxy while capturing the full audit trail.

Agent -> [codesteward-audit-proxy :8080] -> [Your Existing Proxy] -> LLM API

UPSTREAM_PROXY=http://proxy.corp.internal:3128 \
  go run ./cmd/proxy

UPSTREAM_PROXY=https://api.portkey.ai \
  go run ./cmd/proxy

If UPSTREAM_PROXY is not set, the proxy checks standard HTTPS_PROXY / HTTP_PROXY environment variables — companies with a system-wide proxy get chaining automatically.

ClickHouse Query Examples

SELECT session_id, ts, tool_name, tool_input
FROM audit_events
WHERE ts > now() - INTERVAL 7 DAY
  AND JSONExtractString(tool_input, 'file_path') LIKE '%/.env%'
ORDER BY ts DESC;

SELECT project, branch, agent, tool_name, count() AS calls
FROM audit_events
WHERE toDate(ts) = today()
GROUP BY project, branch, agent, tool_name
ORDER BY calls DESC;

IDE Plugins

The Codesteward IDE plugins are the recommended way to set up the audit proxy. Install the plugin from the official marketplace and it handles everything — no manual environment variables needed.

Installation

Search "Codesteward Audit Proxy" in the Extensions Marketplace
# or
ext install bitkaio.codesteward-audit-proxy

Search "Codesteward Audit Proxy" in the JetBrains Marketplace
# Settings → Plugins → Marketplace

What the plugin does

• Sets the proxy URL for each detected agent (ANTHROPIC_BASE_URL, OPENAI_BASE_URL, GEMINI_API_BASE_URL)
• Injects identity headers automatically: user (from git), project, branch, session ID, and team
• Tracks branch changes in real time — headers update when you switch branches
• Status bar indicator shows proxy state and health
• Header inspector panel lets you see exactly what metadata is being sent

Supported agents

Team configuration

Commit a .codesteward.json to your repository root for shared team settings. The plugin reads it automatically — no per-developer setup needed.

{
  "proxy": {
    "url": "https://audit.corp.internal:8443",
    "enabled": true
  },
  "identity": {
    "team": "platform-engineering",
    "project": "payment-service"
  }
}

Setup

Prerequisites: ClickHouse with audit proxy events, and Docker.

1. Apply the migrations

clickhouse-client --host <host> --query "$(cat migrations/001_session_summaries.sql)"
clickhouse-client --host <host> --query "$(cat migrations/002_session_chunk_extractions.sql)"

2. Start the summarizer

# Docker Compose (includes Ollama sidecar)
docker compose up -d

# The model is auto-pulled on first startup
# Summaries appear in audit.session_summaries

Running without Docker

ollama pull phi3:mini
uv sync
CLICKHOUSE_URL=http://localhost:8123 \
  uv run python -m summarizer.main

uv sync --extra openai
LLM_PROVIDER=openai \
SUMMARIZER_MODEL=gpt-4o-mini \
OPENAI_API_KEY=sk-... \
CLICKHOUSE_URL=http://localhost:8123 \
  uv run python -m summarizer.main

uv sync --extra anthropic
LLM_PROVIDER=anthropic \
SUMMARIZER_MODEL=claude-haiku-4-5-20251001 \
ANTHROPIC_API_KEY=sk-ant-... \
CLICKHOUSE_URL=http://localhost:8123 \
  uv run python -m summarizer.main

Configuration

All configuration via environment variables. No config files required.

Run modes

• poll (default) — continuous loop. Processes pending sessions, sleeps, repeats. Use for Docker / systemd.
• once — single cycle, then exits. Use for cron jobs or Kubernetes CronJobs.

Version-gated re-summarization

Changing SUMMARIZER_VERSION (e.g., from v1 to v2) causes all sessions within the lookback window to be re-summarized. Useful after changing prompts, switching models, or adding new fact categories. Old summaries are preserved as revisions.

LLM Providers

Ollama (default)

Local inference. The model is auto-pulled on startup if not available. Recommended CPU-friendly models:

• phi3:mini (3.8B params, ~2.3 GB) — good quality-to-size ratio
• mistral (7B params, ~4.1 GB) — better quality, needs more RAM
• llama3:8b (8B params, ~4.7 GB) — strong general performance

OpenAI

Set LLM_PROVIDER=openai and OPENAI_API_KEY. Install the SDK: uv sync --extra openai. Supports custom base URLs via OPENAI_BASE_URL for Azure OpenAI or local vLLM. Recommended: gpt-4o-mini, gpt-4o.

Anthropic

Set LLM_PROVIDER=anthropic and ANTHROPIC_API_KEY. Install the SDK: uv sync --extra anthropic. Recommended: claude-haiku-4-5-20251001, claude-sonnet-4-20250514.

Processing Pipeline

Every poll cycle, the summarizer discovers sessions with events in the lookback window that have been inactive for the cooldown period and haven't been summarized with the current version.

Single-pass (short sessions)

When events fit within the token budget, the summarizer compresses them into a timeline and sends them to the LLM in one call. The response is parsed as YAML containing the summary, key decisions, and tags.

Chunked extract-merge-synthesize (long sessions)

For sessions that exceed the budget, events are split into chunks at natural boundaries (time gaps > 5 minutes). Each chunk is sent to the LLM to extract 11 categories of structured facts. Facts are then merged deterministically (no LLM, no information loss) before a final synthesis pass produces the summary.

Token budget

The character budget is derived from the model's token limit with language-aware ratios (English ~4.0 chars/token, German ~3.0, Chinese ~1.5). 28 languages are supported. Set CONTEXT_MAX_CHARS to override the calculation entirely.

Security

• Secrets are stripped via regex before any text reaches the LLM
• Tool inputs (which may contain file contents) are never sent — only extracted file paths
• API response bodies are excluded from context

Evaluation

The prompt evaluator is a separate batch service that uses a strong LLM (Claude or GPT-4o) to score summarizer outputs. It runs periodically (daily or weekly) on a configurable sample size.

Evaluation levels

• Chunk-level — for each chunk extraction: did it capture all visible facts? Are they accurate? Did the model hallucinate? Each of the 11 fact categories is scored independently.
• Summary-level — does the final summary accurately cover key activities? Are decisions complete and well-stated? Are tags meaningful?

Prompt provenance

Every summary and extraction is tagged with the exact prompt version (prompt_id), a hash of the prompt text (prompt_hash), and a hash of the input context (input_context_hash). This creates full traceability from output to instructions.

Evaluation data collection

When enabled, the summarizer stores the exact input context sent to the LLM alongside the output. The evaluator needs this to see the same context the original model saw — not a re-rendered version that might differ due to code changes or configuration drift.

Auto-Optimization

When enabled, the evaluator goes beyond scoring. It analyzes patterns across all scored outputs, generates a revised prompt, validates it, and promotes it if it outperforms the current one.

Optimization pipeline

1. Analyze — identify which fact categories consistently underperform and what high-scoring outputs have in common
2. Generate — feed the analysis to the strong model with the current prompt, low-scoring examples with feedback, and high-scoring examples as references
3. Validate — re-process a sample of real sessions with the candidate prompt. Score the new outputs with the same evaluator
4. Promote or reject — promote only if the candidate wins by a meaningful margin. Marginal gains are flagged for human review. Worse results are rejected outright

Safety guardrails

• Validation gate — no prompt goes live without proving it's better than what it replaces
• Auto-rollback — after promotion, outputs are continuously scored. If quality drops below historical baselines, the previous prompt is restored automatically
• Lineage limits — configurable depth limit on automatic iterations. The system pauses for human review after N generations, preventing unbounded prompt drift
• Full audit trail — every prompt links to its parent. Every optimization decision is logged with scores and reasoning

Operation Modes

Automatic (hands-off)

The system manages the full loop: evaluate, generate, validate, promote, monitor, rollback. Best for teams that want continuous improvement without dedicating engineering time to prompt maintenance.

Manual (human-in-the-loop)

The evaluator runs in evaluation-only mode, providing quality scores and detailed feedback. Engineers write improved prompts informed by the data. The system handles validation and promotion. Best for teams that prefer direct control over prompt changes.

Cost considerations

• Summarization — unchanged, still uses the same small/local model
• Evaluation — strong model on configurable samples (default 20 outputs), periodic schedule. Cost is bounded
• Optimization — one candidate prompt per run (single LLM call)
• Validation — re-processes the same sample with the candidate, bounded by sample size

Setup

Taint analysis builds on the structural graph. Build the graph first, then run the analyzer.

# 1. Build the graph
codesteward-mcp graph_rebuild --repo-path /path/to/repo

# 2. Run taint analysis
codesteward-taint \
  --repo-id  my-repo \
  --repo-path /path/to/repo \
  --frameworks fastapi \
  --level 3

Output edges in the graph

(source:Function)-[:TAINT_FLOW {
  cwe:       "CWE-89",
  hops:      3,
  level:     3,
  sanitized: false
}]->(sink:Function)

CLI Flags

Custom Catalogs

Add custom source/sink definitions by creating YAML files in a catalog directory and passing --catalog-dir.

# Example custom catalog: my-catalogs/internal-api.yaml
sources:
  - name: get_user_input
    type: parameter
    language: python
    cwe: CWE-89

sinks:
  - name: execute_raw_query
    type: function_call
    language: python
    cwe: CWE-89

codesteward-taint \
  --repo-id my-repo \
  --repo-path /path/to/repo \
  --catalog-dir ./my-catalogs

Supported Frameworks