Reference MCP server with best-practice patterns — starter template for building quality MCP servers (TypeScript)
Server demonstrates solid fundamentals: all 6 tools have clear descriptions (avg 150 chars), proper verb-noun naming, and complete zod-based input schemas with parameter descriptions. Tool composition is clean, each tool has one responsibility. However, output schemas are not documented in code or README, parameter constraints lack formal enums (e.g., 'operator' accepts free-form strings instead of enum), and error handling, while present, does not consistently guide recovery. No tool annotations (readOnlyHint/destructiveHint) despite clear risk profiles. Baseline: 194 chars avg description (this server ~150), 100% of A+ tools have param descriptions (this server: 100%), but output schema documentation is missing.
Perform an arithmetic operation on two numbers. Supports addition, subtraction, multiplication, and division. Returns the result as a formatted string.
Create a new note with a title, content, and optional tags. Notes are stored in memory and can be searched with search_notes. Tags help organize and find notes later.
Echo a message back unchanged. Use this to verify that the MCP connection is working and messages round-trip correctly.
Get current weather data for a city. Returns temperature, conditions, humidity, and wind speed. Data is simulated — this tool demonstrates MCP patterns, not a real weather API.
List files in a directory, optionally filtered by a glob pattern. Returns a newline-separated list of matching filenames. Only lists immediate children (not recursive).
Search stored notes by keyword. Searches note titles, content, and tags. Returns the most recent matches first. If no query is provided, returns the most recent notes.
Output schemas not documented. Tools return structured responses but no schema is visible in code or README. LLMs cannot plan downstream calls or extract fields reliably without knowing response structure.
'operator' parameter in calculate tool accepts free-form string instead of enum. Should constrain to ['add', 'subtract', 'multiply', 'divide'] to prevent hallucinated values.
'units' parameter in get_weather accepts free-form string. Should be enum ['celsius', 'fahrenheit'] to prevent invalid inputs.
No tool annotations (readOnlyHint/destructiveHint/idempotentHint). create_note is marked WRITE but tool definition lacks destructiveHint annotation. Agents cannot infer safety properties.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 63 | 2026-07-28+ | v2 |
Error messages in calculate are actionable but search_notes and list_files lack recovery guidance. When list_files fails on invalid path, no suggestion for valid paths is provided.