Model Context Protocol (MCP) server for PuppyGraph, enabling graph database queries through Claude
The server defines 6 tools (3 unique + 3 duplicates with mcp__ prefix) with basic descriptions and partial schemas. Tool names follow verb_noun convention (puppygraph_query, puppygraph_schema, puppygraph_status), which is appropriate. However, descriptions are terse (34-68 chars), falling below the 194 char production baseline. Input schemas are present using Zod but lack detailed parameter constraints. The query tool accepts optional 'parameters' as a generic record, which is under-constrained. Error handling returns JSON with error messages but lacks actionable recovery guidance. No output schema is documented. The duplicate mcp__ prefixed tools add confusion without benefit. Overall, the server is functional but falls short of production-grade tool quality.
Execute a graph query (Gremlin or Cypher) against PuppyGraph via mcp__ prefix
Get schema and structure information about the PuppyGraph database via mcp__ prefix
Get connection status and configuration information for PuppyGraph via mcp__ prefix
Execute a graph query (Gremlin or Cypher) against PuppyGraph
Get schema and structure information about the PuppyGraph database
Get connection status and configuration information for PuppyGraph
Duplicate tool definitions with mcp__ prefix confuse tool discovery and waste MCP server resources. The server registers 6 tools when only 3 unique tools exist. LLMs will conflate similarly-named tools.
Tool descriptions are too terse (34-68 chars vs 194 char production baseline). 'Execute a graph query (Gremlin or Cypher) against PuppyGraph' (68 chars) lacks context on WHEN to use this tool vs other query mechanisms, prerequisites (connection required?), or output shape. LLMs cannot reliably distinguish this from similar query tools.
The 'parameters' field in puppygraph_query is under-constrained. It accepts z.record(z.any()), which allows arbitrary keys and values. LLMs cannot predict valid parameter names (query-specific?) or types. This invites hallucinated parameters. No documentation on how to parameterize Gremlin vs Cypher queries differently.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 14 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 34 | - | v1 |
No output schema documented for any tool. puppygraph_query returns JSON.stringify(result) but the LLM has no way to know the structure of 'result' (fields, types, pagination support). This forces the LLM to parse unstructured output or make assumptions.
Error handling returns structured JSON with error messages but provides no recovery guidance. Example: a query execution error returns {'error': 'Connection timeout', 'error_type': 'Error'} with no hint about retrying, checking status, or calling puppygraph_status first. Error responses should guide the LLM's next action.
The 'language' enum in puppygraph_query lacks descriptions. The description says 'The query language to use' but does not explain when to choose Gremlin vs Cypher, syntax differences, or which is preferred. LLMs must guess based on user intent alone.
puppygraph_schema and puppygraph_status tools accept no parameters (empty input schema {}). The description for puppygraph_schema says 'Get schema and structure information about the PuppyGraph database' but does not explain what structure is returned, whether it includes vertex/edge types, or how to filter for specific elements. This is a discovery tool that needs richer documentation.