Graphenium
OfficialServer Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Graphenium relational index server with 12 consolidated tools. Use get_graph_info for the handshake, health checks, and diagnostics, get_architecture_summary for repo-level structure, communities, and hotspots, query_graph for keyword exploration, inspect_symbol for node details, neighbors, references, analysis, file summaries, and change explanations, and trace_path for shortest, safest, transitive, and cross-module paths. Use run_datalog for logic queries, create_planning_workspace and add_planned_symbol to declare designs, validate_plan for policy and delta gates, and verify_changes for scope-creep audits, blast radius, and verification plans. Use mutate_graph for add_node, add_edge, remove_edge, and recluster mutations, and reload_graph to hot-swap the underlying graph. All writes persist to disk immediately.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| create_planning_workspaceA | Create a new virtual planning workspace. Use this tool first when starting any multi-file feature or refactoring task, before calling add_planned_symbol or validate_plan. Do not use this tool if a plan already exists for your current task. This is a mutating operation that initializes an empty Virtual AST associated with the provided plan_id. The workspace is stored in the server's graph state and persisted to disk immediately, so it remains available for the duration of the server session. If the plan_id already exists, this operation is idempotent and returns the existing workspace. Returns the initialized workspace ID on success. |
| get_architecture_summaryA | Return a repository-level architecture summary with communities, cross-community connectors, and architectural hotspots. Set community_id to focus on one community instead of the overview, include_community_members to append its full member list, and include_god_nodes to append the most highly connected hub nodes. |
| inspect_symbolA | Inspect a symbol and retrieve its structural neighborhood and metrics. Use this read-only tool as your primary orientation step before modifying a specific class, function, or module. Use this instead of query_graph when you already know the exact target ID and need its direct callers, neighbors, or a verification plan. The baseline response returns canonical node details. Use the boolean flags to append optional data blocks (for example, include_callers=true appends all incoming dependencies). Setting multiple flags to true (such as include_analysis and include_file_summary) can produce large responses; use only the flags needed for your immediate task to conserve context budget. |
| trace_pathA | Trace connectivity and multi-hop paths across the codebase architecture. Use this read-only tool to map blast radius, find shortest paths, or verify transitive layering. Use this instead of query_graph or inspect_symbol when you need to prove deep, multi-hop relationships between specific components. The tool operates in five distinct modes: shortest (finds semantic or strict AST paths between source and target), safest (finds the path with highest aggregate confidence), transitive_forward (downstream reachability), transitive_reverse (upstream callers), and module_dependencies (cross-module edges). Returns a structured Markdown report detailing the traced paths, confidence scores, and edge relations. Traversal halts when depth is reached, and output is truncated to fit the budget. |
| verify_changesA | Verify a change in one unified report. Returns the scope creep audit, blast radius, verification checklist, and must-read files for the supplied target symbols. When plan_id is set it also returns the plan details and post-edit compliance audit. Optional snapshot or graph path inputs add what-changed and graph-diff sections. |
| mutate_graphA | Apply a manual mutation to the relational index in one call. Use action='add_node' to register a concept or rationale node, action='add_edge' to record a verified relationship, action='remove_edge' to delete a stale or false-positive edge, or action='recluster' to re-run community detection. Successful mutations persist to disk immediately. |
| run_datalogA | Run a logic query over the codebase graph. Standard library predicates are pre-loaded (do not redefine them):
|
| validate_planA | Validate a planning workspace before writing code. Always runs the Louvain modularity delta gate and surprise analysis. Unless skip_policy_rules is true, it also applies explicit .graphenium/policy.json rules when present. |
| reload_graphA | Reload the relational index from a graph.json file without restarting the MCP server. If no path is given, reloads from the path the server was launched with. Use this to point a running server at a different repository's graph, or to pick up changes after re-running |
| query_graphA | Query the relational index with keywords to find relevant nodes and explore their topology. Use this read-only tool for initial discovery when you do not yet know the exact node IDs. If you already know the target ID, use inspect_symbol instead. To trace deep multi-hop paths, use trace_path instead. The query mechanism scores nodes by keyword match and traverses their neighborhood (BFS by default, or DFS if dfs=true). Results are rendered as a structured Markdown report. To prevent context bloat, the output is strictly truncated to fit within the provided budget (default 2000). |
| add_planned_symbolA | Register an intended new or modified symbol and its dependency edges in a virtual planning workspace. Use this tool to declare your architectural design before writing code. Do NOT use mutate_graph (which modifies the physical index) for planned changes. Prerequisites: You must first call create_planning_workspace to obtain a valid plan_id. Side effects: This is an in-memory mutation that adds a virtual node to the specified workspace. It automatically runs pre-flight policy checks; if the proposed symbol or its dependencies violate .graphenium/policy.json rules (for example, forbidden dependencies), the tool returns a PRE_FLIGHT_VIOLATION error and blocks the registration. If the target_symbol does not exist, the tool returns an error and records nothing. Duplicate calls for the same symbol are idempotent. Returns a success confirmation or a structural violation error. |
| get_graph_infoA | Return graph metadata, health, and diagnostics in one call. Always returns project root, schema version, build time, extraction modes, languages, node/edge/hyperedge/community counts, active policy gates, and the graph trust mode. Set include_stats to append scoped statistics, include_unresolved to list unresolved imports, include_resolution to append the resolution-quality report, and include_ambiguous to list ambiguous edges and label collisions. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 12 tools
The read-side triad is explicitly disambiguated: query_graph for keyword discovery, inspect_symbol for a known ID's neighborhood, and trace_path for multi-hop proofs, with cross-references in each description. The boundary between mutate_graph (physical index) and add_planned_symbol (virtual workspace) is also clearly stated. Minor overlap remains between the composite reporting tools (verify_changes, get_architecture_summary, get_graph_info) whose optional flags can produce partially redundant sections.
Every name is snake_case verb_noun (verify_changes, trace_path, mutate_graph, validate_plan, reload_graph, query_graph, inspect_symbol, run_datalog). The get_ prefix is used consistently for the three read-oriented summary tools. No mixed conventions or vague bare verbs.
Twelve tools map cleanly onto distinct phases: discovery, inspection, traversal, architecture/diagnostics, custom queries, physical mutation, and a three-step planning lifecycle. Nothing appears padded, and no single tool tries to do everything.
Lifecycle coverage is strong: read/discover, query, mutate, plan-create, plan-extend, plan-validate, plus reload and diagnostics. Gaps are modest but real: mutate_graph supports add_node/add_edge/remove_edge but not node removal or node property updates, and there is no tool to list or discard planning workspaces, leaving abandoned plans as a dead end.