NextFlows Academy starter — build an MCP server in TypeScript (Weeks 1–6)
Server has 6 tools with basic schemas and descriptions, but significant gaps limit production readiness. Tool names follow verb_noun convention (greet, search_notes, list_notes, add_note, update_note, delete_note), which is good. However, descriptions are inconsistent: greet, list_notes, add_note, and delete_note have descriptions (10-50 chars), while search_notes and update_note lack descriptions entirely. Input schemas are present for all tools with proper type definitions and constraints (minLength, maxLength, minimum, maximum), but output schemas are not documented. Error handling is minimal, no recovery guidance, no categorization of error types. Parameter descriptions are present but generic (e.g., 'Keyword or phrase to search for' lacks format/constraint details). No tool annotations (readOnlyHint, destructiveHint) despite clear risk levels (READ_ONLY, WRITE, DESTRUCTIVE). Security: file path traversal is mitigated in src/lib/file.ts, but notes.json write operations use hardcoded Windows path separator ('\\'), causing cross-platform failures. No pagination on search_notes despite accepting a limit parameter, unclear if results are capped. Overall, this is a functional but incomplete implementation suitable for learning, not production.
Add a new note to the local notes collection.
Delete an existing note from the local notes collection.
Return a short greeting for a person. Use this to verify the MCP server is running.
List available local note and FAQ files the model can search or open.
search_notes and update_note lack descriptions entirely. LLMs cannot determine when to select these tools without docstrings.
No output schemas documented for any tool. LLMs cannot plan downstream calls or extract required fields (e.g., note IDs for chaining).
No tool annotations (readOnlyHint, destructiveHint) despite explicit risk levels. Agents cannot distinguish safe reads from destructive writes.
Cross-platform path bug: src/lib/notes.ts uses hardcoded Windows separator ('\\notes.json'). Will fail on Unix/Linux/macOS.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 54 | 2026-07-28+ | v2 |
Error handling lacks recovery guidance. Errors like 'Note with ID X not found' do not suggest next steps (e.g., 'Call list_notes to see available IDs').