A collection of MCP server examples demonstrating basic to advanced implementations including filesystem operations, text analysis, calculations, and external API integration
The server defines 10 tools across three domains (filesystem, text/math utilities, weather). Tool schemas are present and mostly valid JSON Schema, with type definitions and descriptions for parameters. However, the server exhibits significant gaps: (1) descriptions are inconsistent in quality and length, some exceed 200 chars, violating token efficiency; (2) output schemas are not formally documented for any tool, forcing LLMs to infer result structure; (3) no error recovery guidance is provided; (4) parameter descriptions lack actionable constraints (e.g., weather tools mention 'metric|imperial|standard' in the description rather than as enums); (5) filesystem tools lack explicit mention of security implications in descriptions, despite implementing permission checks in code. The code shows good defensive programming (ValidationError, PermissionError classes, isPathAllowed checks), but this is not surfaced in the tool definitions themselves. Most tools are single-responsibility (good), but compositions are weak, no guidance on which tools to call in sequence or how output fields chain. Median tool score is 52, placing this in the 'Fair' range (C).
List all directories the server is allowed to access
List contents of a directory
Read content from a file
Search for files matching a pattern
Write content to a file
Perform mathematical calculations
Format code with proper indentation
Analyze text and provide statistics like word count, character count, etc.
Output schemas not documented. None of the 10 tools include a documented return type or result structure. LLMs cannot plan downstream tool calls or extract specific fields without inferring structure from execution.
Enum values stated in descriptions rather than as JSON Schema enums. Weather tools ('metric|imperial|standard') declare allowed values in free-text descriptions. This allows LLMs to hallucinate invalid values. Use JSON Schema enum constraints.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 44 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 35 | - | v1 |
Get 5-day weather forecast for a location
Get current weather information for a location
No error recovery guidance. Tools throw generic errors ('Failed to read file', 'Failed to write file'). LLMs receive no actionable next steps, should guide to isPathAllowed, retry logic, or alternative approaches.
Security implications not surfaced in tool descriptions. Filesystem tools implement permission checks (isPathAllowed) and custom error classes (PermissionError, ValidationError) in code, but descriptions do not mention these restrictions or warn about access boundaries.
Tool composition guidance missing. No documentation on which tools to call in sequence or what fields chain between tools. E.g., search_files returns 'matches' array, but no guidance on feeding results to read_file.
Parameter 'expression' in calculate tool lacks constraints. No documentation of allowed syntax, operator support, or boundaries (e.g., max result size, timeout). LLMs may pass expressions that fail or hang.