# Codesteward

> Structural code graph server for AI agents — parses repositories into a Neo4j graph via tree-sitter and exposes it as an MCP tool interface with lexical, referential, semantic, and dependency queries.

- **Type:** MCP server
- **Install:** `agentstack add mcp-codesteward-codesteward`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Codesteward](https://agentstack.voostack.com/s/codesteward)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [Codesteward](https://github.com/Codesteward)
- **Source:** https://github.com/Codesteward/codesteward
- **Website:** https://codesteward.ai/product/graph-server

## Install

```sh
agentstack add mcp-codesteward-codesteward
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Structural code graph server for AI agents.
  Parse any repository into a queryable graph via tree-sitter AST — and expose it as an MCP tool interface your AI agent can call directly. Supports Neo4j, JanusGraph, or GraphQLite (embedded SQLite — zero setup for local dev).

---

## What it does

Codesteward parses your codebase into a persistent structural graph and exposes four [Model Context Protocol](https://modelcontextprotocol.io) tools that AI agents (Claude Code, Cursor, Windsurf, Copilot, …) can call to answer questions like:

- *"Which functions are protected by JWT auth?"*
- *"What does `process_payment` call, transitively?"*
- *"Which files depend on this external package?"*
- *"Is this route guarded by an auth middleware?"*

Rather than scanning files repeatedly, the agent queries a pre-built graph — cross-file relationships, call chains, auth guards, and dependency edges all resolved in a single query.

**Supported languages:** TypeScript · JavaScript · Python · Java · Go · Rust · PHP · C# · Kotlin · Scala · C · C++ · SQL *(context tagging)* · COBOL *(regex)*

## MCP Tools

| Tool | Description |
| ---- | ----------- |
| `graph_rebuild` | Parse a repository and write the structural graph to the configured backend (Neo4j, JanusGraph, or GraphQLite) or run in stub mode |
| `codebase_graph_query` | Query via named templates (`lexical`, `referential`, `semantic`, `dependency`) or raw passthrough (`cypher` / `gremlin`) |
| `graph_augment` | Add agent-inferred relationships (confidence  **Note:** Claude Code requires `"type": "stdio"` in the server config. Other tools
> (Cursor, Cline) don't need it.

| Tool | Config file |
| ---- | ----------- |
| Claude Code | `~/.claude.json` (under `mcpServers`) |
| Cursor | `~/.cursor/mcp.json` |
| Cline | `cline_mcp_settings.json` in VS Code globalStorage |
| Codex CLI | `~/.codex/config.yaml` (under `mcp_servers`) |
| Gemini CLI | `~/.gemini/settings.json` (under `mcpServers`) |

Requires [uv](https://docs.astral.sh/uv/). `uvx` downloads and caches the package on first run. The graph persists to `~/.codesteward/graph.db` across sessions.

### Docker + Neo4j — persistent graph

```bash
# 1. Point the server at your repository
export REPO_PATH=/path/to/your/repository

# 2. Start Neo4j + MCP server
docker compose -f docker-compose.neo4j.yml up -d

# 3. Copy config templates into the repo you want to analyse
cp templates/.mcp.json /path/to/your/repository/
cp templates/CLAUDE.md /path/to/your/repository/
```

The server runs at **`http://localhost:3000/sse`**. Call `graph_rebuild()` with no arguments — the server already knows the repo path from the volume mount.

### Docker + JanusGraph — persistent graph (Apache 2.0)

```bash
# 1. Point the server at your repository
export REPO_PATH=/path/to/your/repository

# 2. Start JanusGraph + MCP server
docker compose -f docker-compose.janusgraph.yml up -d

# 3. Copy config templates into the repo you want to analyse
cp templates/.mcp.json /path/to/your/repository/
cp templates/CLAUDE.md /path/to/your/repository/
```

Same workflow as the Neo4j stack — all named query templates work identically. Raw query passthrough uses Gremlin instead of Cypher.

### Manual Docker run

```bash
docker run -p 3000:3000 \
  -v /path/to/your/repo:/repos/project:ro \
  -e NEO4J_PASSWORD=secret \
  ghcr.io/bitkaio/codesteward-mcp:latest
```

For full setup instructions covering all AI tools, see the **[setup guides](docs/setup/)**.

## Installation

```bash
# All 14 languages + GraphQLite (recommended for local dev)
uv pip install "codesteward-mcp[graph-all,graphqlite]"

# Core languages only (TypeScript, JavaScript, Python, Java) + GraphQLite
uv pip install "codesteward-mcp[graph,graphqlite]"

# Individual language extras
uv pip install "codesteward-mcp[graph-go,graphqlite]"       # Go
uv pip install "codesteward-mcp[graph-rust,graphqlite]"     # Rust
uv pip install "codesteward-mcp[graph-csharp,graphqlite]"   # C#
uv pip install "codesteward-mcp[graph-kotlin,graphqlite]"   # Kotlin
uv pip install "codesteward-mcp[graph-scala,graphqlite]"    # Scala
uv pip install "codesteward-mcp[graph-c,graphqlite]"        # C
uv pip install "codesteward-mcp[graph-cpp,graphqlite]"      # C++
uv pip install "codesteward-mcp[graph-php,graphqlite]"      # PHP

# Neo4j backend (alternative — requires a running Neo4j 5+ server)
uv pip install "codesteward-mcp[graph-all]"

# JanusGraph backend (alternative — requires a running JanusGraph 1.0+ server)
uv pip install "codesteward-mcp[graph-all,janusgraph]"
```

Requires Python 3.12+. GraphQLite is the default backend for local development — an embedded SQLite graph database that requires no external services. The graph persists to `~/.codesteward/graph.db` across sessions.

## Configuration

All settings can be provided via environment variables, a YAML config file, or CLI flags.
Priority: **CLI flags > env vars > YAML file > defaults**.

| Setting | Env var | Default | Description |
| ------- | ------- | ------- | ----------- |
| Transport | `TRANSPORT` | `sse` | `sse`, `http`, or `stdio` |
| Host | `HOST` | `0.0.0.0` | HTTP bind host |
| Port | `PORT` | `3000` | HTTP bind port |
| Graph backend | `GRAPH_BACKEND` | `auto` | `auto`, `neo4j`, `janusgraph`, or `graphqlite`. Auto-detects: Neo4j if password set, JanusGraph if URL changed, otherwise GraphQLite |
| Neo4j URI | `NEO4J_URI` | `bolt://localhost:7687` | Neo4j connection URI |
| Neo4j user | `NEO4J_USER` | `neo4j` | Neo4j username |
| Neo4j password | `NEO4J_PASSWORD` | *(empty)* | Set to enable Neo4j backend |
| JanusGraph URL | `JANUSGRAPH_URL` | `ws://localhost:8182/gremlin` | Gremlin Server WebSocket URL |
| GraphQLite DB path | `GRAPHQLITE_DB_PATH` | `~/.codesteward/graph.db` | SQLite database file path |
| Default tenant | `DEFAULT_TENANT_ID` | `local` | Tenant namespace |
| Default repo | `DEFAULT_REPO_ID` | *(empty)* | Repo ID |
| Default repo path | `DEFAULT_REPO_PATH` | `/repos/project` | Server-side path for `graph_rebuild` |
| Workspace | `WORKSPACE_BASE` | `workspace` | Directory for build metadata |
| Log level | `LOG_LEVEL` | `INFO` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |

## Taint Analysis (optional)

The `taint_analysis` tool is registered automatically when the `codesteward-taint` binary is on
`PATH`. Without it the server starts normally and the other four tools are unaffected.

### Docker

Pass `--build-arg TAINT_VERSION=` to download and bundle the binary:

```bash
docker build --build-arg TAINT_VERSION=0.1.0 -t codesteward-mcp:taint .
```

### Standalone

Download a pre-built binary from the
[codesteward-taint releases](https://github.com/bitkaio/codesteward-taint/releases) and place it
on `PATH`:

```bash
# macOS (Apple Silicon)
curl -L https://github.com/bitkaio/codesteward-taint/releases/latest/download/codesteward-taint-darwin-arm64 \
     -o /usr/local/bin/codesteward-taint
chmod +x /usr/local/bin/codesteward-taint
```

### Workflow

```text
graph_rebuild          # build the structural graph first
taint_analysis         # trace taint paths; writes TAINT_FLOW edges to Neo4j
codebase_graph_query   # query_type="semantic" to read findings
```

## Graph Model

### Nodes — `LexicalNode`

Every parsed symbol becomes a `LexicalNode`:

| Property | Description |
| -------- | ----------- |
| `node_id` | Stable unique ID: `{node_type}:{tenant_id}:{repo_id}:{file}:{name}` |
| `node_type` | `function`, `class`, `method`, `file`, `module`, `external` |
| `name` | Symbol name |
| `file` | Repo-relative file path |
| `line_start` / `line_end` | Source location |
| `language` | Detected language |
| `tenant_id` / `repo_id` | Multi-tenancy namespace |
| `confidence` | `1.0` for parser-emitted; `< 1.0` for agent-inferred |

### Edges

| Edge type | Meaning |
| --------- | ------- |
| `CALLS` | Function A calls function B (cross-file resolved) |
| `IMPORTS` | File/module imports another |
| `EXTENDS` | Class inherits from another |
| `GUARDED_BY` | Function protected by a decorator/annotation (`@login_required`, `@UseGuards`, FastAPI `Depends`, `@PreAuthorize`, …) |
| `PROTECTED_BY` | Function protected by router-scope middleware (`APIRouter`, Express `router.use()`, Gin group, Actix scope, Laravel route group, ASP.NET `MapGroup().RequireAuthorization()`) |
| `DEPENDS_ON` | File depends on an external package |
| `TAINT_FLOW` | Untrusted input reaches a dangerous sink (written by `codesteward-taint`; queryable via `semantic`) |
| `calls` / `guarded_by` / `taint_flow` / … | Agent-inferred edges with `confidence < 1.0` via `graph_augment` |

## Development

```bash
# Setup
uv venv && source .venv/bin/activate
uv sync --all-packages --extra graph-all

# Run tests
pytest tests/ -v

# Run the server locally
codesteward-mcp --transport sse --port 3000

# Lint + type-check
ruff check src/ tests/
mypy src/
```

## Releases

See [CHANGELOG.md](CHANGELOG.md) for the full history or browse [GitHub Releases](https://github.com/bitkaio/codesteward/releases).

## License

Apache License 2.0 — Copyright (c) 2026, bitkaio LLC

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Codesteward](https://github.com/Codesteward)
- **Source:** [Codesteward/codesteward](https://github.com/Codesteward/codesteward)
- **License:** Apache-2.0
- **Homepage:** https://codesteward.ai/product/graph-server

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:** no
- **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-codesteward-codesteward
- Seller: https://agentstack.voostack.com/s/codesteward
- 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%.