An MCP server example that demonstrates how to use the Model Context Protocol (MCP) SDK to create a server that can handle requests and responses in a structured way.
Server has 9 tools with basic schemas and descriptions, but significant gaps limit production readiness. All tools have descriptions (10-100 chars, mostly adequate), and input schemas are present with enums and string constraints. However, parameter descriptions are sparse or missing context. Output schemas are undocumented, responses return text blobs without structured field definitions. Error handling is minimal (generic error messages, no recovery guidance). No tool annotations (readOnlyHint, destructiveHint, idempotentHint). Tool naming is verb-first and clear, but composition issues exist: init_repo + get_repo_info + get_repo_structure + read_file form a chain that could be simplified. WRITE tools (create_boilerplate, add_feature, add_new_queue) lack confirmation/dry-run patterns despite irreversible side effects.
Add a new API feature/module to the boilerplate
Add a structured background queue for the selected framework
Generate production-ready boilerplate codebase for selected framework
Shows full boilerplate config for selected framework
Get information about the initialized code repository.
Get the structure of the code repository.
Initialize a code repository for analysis.
Output schemas undocumented. All tools return text content in a generic {type: 'text', text: string} wrapper. LLMs cannot infer structured fields (e.g., what fields does get_repo_info return? What is the structure of get_repo_structure output?). This forces LLMs to parse unstructured text, wasting tokens and increasing hallucination risk.
WRITE tools lack confirmation/dry-run patterns. create_boilerplate, add_feature, and add_new_queue perform irreversible file system mutations without a dry-run or confirmation step. Agents can accidentally scaffold entire projects or add duplicate modules. No recovery guidance in error responses.
Parameter descriptions lack context. 'subPath' in get_repo_structure has description 'Subpath to explore', does it accept relative or absolute paths? Is it optional? What happens if it doesn't exist? 'depth' has no guidance on valid range (1-10? 1-100?). LLMs cannot infer constraints from names alone.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 54 | <=2025-11-25 | v2 |
Lists all available frameworks for boilerplate generation
Read a file from the code repository.
Error messages are generic and non-actionable. 'Error generating boilerplate: {err.message}' or 'Error adding feature: {err.message}' provide no recovery guidance. Per pattern:recovery-guide, errors should tell the LLM what to do next (e.g., 'Framework not found. Call list_supported_frameworks() to see available options.').
No tool annotations. Tools lack readOnlyHint, destructiveHint, or idempotentHint metadata. LLMs cannot determine which tools are safe to retry, which modify state, or which are read-only without parsing descriptions. This is a current MCP spec feature (2026-07-28) that should be present.