A minimal NestJS Streamable HTTP MCP server for learning and experimentation.
Three tools with clear verb-noun naming (list_posts, get_post, get_user) and complete input/output schemas. Descriptions are concise (40-60 chars) and actionable. All parameters have types and descriptions. Tool annotations (readOnlyHint, idempotentHint) are present.
Get one JSONPlaceholder post by its ID.
Get one JSONPlaceholder user by its ID.
List up to 10 JSONPlaceholder posts, optionally filtered by user ID.
Descriptions lack actionable context. 'List up to 10 JSONPlaceholder posts' does not explain WHEN to use this vs get_post, or what fields are returned.
Error handling is generic. runTool() catches all errors and returns 'JSONPlaceholder data could not be retrieved.' No guidance on retry, user action, or root cause. Per pattern:recovery-guide, errors should tell the LLM what to do next.
Parameter constraints (userId 1-10, limit 1-10, id 1-100) are documented in descriptions but not enforced in Zod schemas shown. Zod min/max are present in code but LLM cannot see them, only description text. Per pattern:constrained-input, constraints must be machine-parseable.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 68 | 2026-07-28+ | v2 |
Output schemas (PostSchema, UserSchema) are defined in Zod but not explicitly documented in tool registration. LLMs cannot see Zod definitions, only what's in the tool metadata. Per pattern:tool, output schema must be documented.
No pagination guidance for list_posts. Limit defaults to 3 and caps at 10, but no mention of offset/cursor or total count. Per pattern:paginated-result, list tools should support pagination and return count.