# Roadmap — grafeo-mcp

## Phases

Detailed plans with tasks and design decisions live in `.claude/todo/`.

| Phase | Name                                                     | Status      | Description                                |
| ----- | -------------------------------------------------------- | ----------- | ------------------------------------------ |
| 1     | [Foundation](todo/phase-1-foundation.md)                 | Complete    | Project scaffold, tooling, server skeleton |
| 2     | [Core Tools](todo/phase-2-core-tools.md)                 | Complete    | Query + graph CRUD + traversal tools       |
| 3     | [Vector & Algorithms](todo/phase-3-vector-algorithms.md) | Complete    | Vector search, hybrid search, analytics    |
| 4     | [Resources & Prompts](todo/phase-4-resources-prompts.md) | Complete    | Rich schema resources, workflow prompts    |
| 5     | [Distribution](todo/phase-5-distribution.md)             | In Progress | README, CI, PyPI publishing                |
| 6     | [Future](todo/phase-6-future.md)                         | Not Started | Post-v0.1.0 enhancements                   |

## Key Design Decisions

- **GQL only** — single query tool (`execute_gql`) with auto-normalization of Cypher syntax. No separate Cypher/Gremlin tools.
- **14 tools** — enough to be useful, focused enough for agent context windows.
- **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** — every tool docstring says when to use it and when not to.
- **Error recovery** — error messages suggest which tool to try next.
- **`get_neighbors`** — dedicated traversal tool (most impactful addition from research).
- **`vector_graph_search`** — hybrid vector + graph expansion in a single call.
- **Workflow prompts** — prompts guide agents through multi-step tool sequences, not just templates.
- **MCP SDK v1.x** — uses `FastMCP` (stable). Will upgrade to v2 `MCPServer` when it ships.
- **prek** — Rust-based pre-commit replacement for git hooks.

## Archive

The original design spec is preserved in [.archive/grafeo-mcp-original-spec.md](.archive/grafeo-mcp-original-spec.md).
