MCP server for querying a Neo4j movie database with tools for searching movies by genre, retrieving movie statistics, and accessing movie details as resources
This is a teaching/demo repository with 4 tools spread across multiple solution directories. Tool definitions are minimal and lack the rigor expected of production servers. Schemas are present but descriptions are generic or missing parameter details. No pagination metadata, no output schemas documented, no error handling guidance. The server spans 6 separate implementations (solutions/3c, 6c, 8c, 10c, server, plus client) with inconsistent quality. Average tool score is 48, pulling the overall down significantly. While fastmcp is a solid framework, the tool definitions here read as proof-of-concept rather than production-grade.
Count occurrences of a letter in the text
Get movies by genre from the Neo4j database.
Count the number of nodes and relationships in the graph.
Browse movies in a genre with pagination support.
No output schemas documented for any tool. LLMs cannot plan downstream calls or extract needed data without knowing response structure. This violates pattern:tool and pattern:response-shaper.
Parameter descriptions lack format/constraint details. E.g., 'genre' parameter has no enum (Action, Drama, Comedy, etc.) or note that invalid genres are silently rejected.
count_letters has ambiguous name and incomplete description. Does 'count_letters' count one letter (search param) or all letters? Is search case-sensitive? Can search be multi-char? LLM will guess wrong.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | C | 66 | <=2025-11-25 | v2 |
| 2026-03-09 | D | 51 | - | v1 |
Pagination tools (list_movies_by_genre) do not document total_count or has_next in response. Pattern:paginated-result requires this for context-aware result limiting.
No error handling guidance in tool descriptions. If a genre does not exist, or if the database is down, how should the LLM recover? Pattern:recovery-guide requires actionable error responses.
Tool descriptions are at the lower end of the baseline range (avg 70 chars; baseline p10=34, p90=392). Most are under 70 chars and lack context on WHEN to use the tool or what it returns. E.g., 'Count the number of nodes and relationships' tells WHAT, not WHEN, and omits return type.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) visible. All tools are marked risk:READ_ONLY in metadata, but this is not reflected in per-tool schema. Modern MCP (2026-07-28) expects annotations in tool definition.