# CLAUDE.md — grafeo-mcp

> Instructions for Claude Code when working in this repository.

## Project

grafeo-mcp is an MCP (Model Context Protocol) server that wraps GrafeoDB, exposing graph queries, traversals, vector search, and graph algorithms as callable tools for any MCP-compatible AI agent (Claude Desktop, Copilot Studio, VS Code, Azure AI Foundry, etc.).

## Tech Stack

- **Language:** Python 3.12+
- **Package manager:** uv (lockfile, venv, scripts)
- **Build backend:** hatchling
- **MCP SDK:** mcp >=1.25,<2 (Python SDK by Anthropic)
- **Database:** grafeo >=0.4 (GrafeoDB — embedded graph database)
- **Linting/Formatting:** ruff (line-length 120, target py312)
- **Type checking:** ty (Astral's Rust-based type checker)
- **Testing:** pytest + pytest-asyncio (asyncio_mode = "auto")
- **Hooks:** prek (Rust-based pre-commit replacement; ruff + ty)

## Key Commands

```bash
uv sync                    # Install all deps (including dev)
uv run grafeo-mcp          # Run the MCP server (stdio transport)
uv run grafeo-mcp streamable-http  # Run with HTTP transport
uv run pytest              # Run tests
uv run ruff check .        # Lint
uv run ruff format .       # Format
uv run ty check            # Type check
```

## Source Layout

```text
src/grafeo_mcp/
  server.py              # FastMCP + lifespan (opens/closes GrafeoDB)
  tools/                 # @mcp.tool() handlers
    query.py             # execute_gql (auto-normalizes Cypher syntax)
    graph.py             # create_node, create_edge, get_node, get_neighbors,
                         #   search_nodes_by_label, graph_info
    vector.py            # vector_search, mmr_search, create_vector_index,
                         #   vector_graph_search
    algorithms.py        # pagerank, dijkstra, louvain, betweenness_centrality,
                         #   connected_components
  resources/             # @mcp.resource() handlers
    schema.py            # graph://schema, graph://stats
    nodes.py             # graph://nodes/{node_id}
  prompts/               # @mcp.prompt() workflow orchestrators
    templates.py         # explore_graph, knowledge_extraction, graph_analysis,
                         #   similarity_search
```

## Conventions

- All tool functions receive a `ctx: Context[ServerSession, AppContext]` parameter to access the GrafeoDB instance via `ctx.request_context.lifespan_context.db`.
- Tool docstrings ARE the agent-facing documentation — write them as clear instructions with examples.
- Keep tools flat (no nested dict args), with sensible defaults and `limit` params on list operations.
- Return error strings from tools instead of raising exceptions.
- Ruff rules: E, F, W, I, UP, B, SIM, RUF.
- No type: ignore comments — fix the actual types.

## Design Principles

- **Schema-first:** `graph_info` is the entry point — agents check schema before querying.
- **Token-aware:** all list-returning tools have `limit` params and truncate large results.
- **Disambiguation:** tool docstrings include "Use this when..." / "Do NOT use for..." lines.
- **Error recovery:** error messages suggest which tool to try next.

## Environment Variables

- `GRAFEO_DB_PATH` — path to the database file. If unset or missing, uses in-memory mode.

## GrafeoDB Source Reference

The full GrafeoDB project lives at `H:\GrafeoDB\grafeo\`. Key locations:

- `crates/bindings/python/src/database.rs` — Python API surface (PyGrafeoDB methods)
- `crates/bindings/python/src/graph.rs` — Node/Edge Python types
- `crates/bindings/python/src/query.rs` — QueryResult Python type
- `crates/bindings/python/src/bridges/algorithms.rs` — Algorithms Python API

This is the authoritative source for the `grafeo` package API. May contain unreleased features.

When testing reveals issues with the grafeo Python bindings, write todo/issue files to:
`H:\GrafeoDB\grafeo\.claude\todo\4_language_bindings\`

## Internal Docs

See `.claude/` for additional context:

- `ARCHITECTURE.md` — system design, module responsibilities, data flow
- `CODE_STYLE.md` — formatting, naming, and patterns
- `ROADMAP.md` — planned features and milestones
- `.archive/grafeo-mcp-original-spec.md` — original design spec
