Educational MCP server implementation demonstrating the Model Context Protocol with tools, resources, and prompts
Four tools with complete schemas and descriptions, but significant gaps in parameter documentation and error guidance. Tool names follow verb_noun convention (list_files, read_file, calculator, text_analyzer). Descriptions are present (avg ~120 chars) but lack actionable context for LLM selection. Schemas are well-formed JSON Schema with types, but most parameters lack descriptions. No output schemas documented. Error handling returns plain strings without recovery guidance. Security validation present in file_tools.py (path traversal prevention) but not consistently applied across all tools.
Evaluate mathematical expressions safely. Supports +, -, *, /, //, %, ** and parentheses. Example: '2 + 3 * 4' returns 14.
List files and directories at a given path. Returns names, types, and sizes.
Read file contents with a line limit for safety. Returns text content.
Analyze text and return statistics: word count, character count, sentence count, reading time, most common words, and more.
Parameter descriptions missing for calculator.expression and text_analyzer.text. LLMs cannot infer parameter meaning from names alone, 'expression' could mean regex, math, or code. Descriptions must state format, constraints, and examples.
No output schemas documented for any tool. LLMs need to know what fields to expect (e.g., does text_analyzer return word_count as int or string? Does list_files return size in bytes or human-readable format?). Document return types for all tools.
Error responses are unstructured strings without recovery guidance. 'File not found: /path' tells LLM nothing about next steps. Should return structured errors with actionable guidance: 'File not found. Try list_files() to see available files in this directory.'
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 53 | <=2025-11-25 | v2 |
read_file max_lines default (100) could silently truncate large files without clear indication. Description says '... (N more lines)' but LLM may not recognize this as truncation. Add explicit 'truncated: true' field to output schema and document truncation behavior prominently.
calculator tool lacks input validation and error classification. What happens if expression contains 'import os' or '__import__'? Description claims 'safely' but no evidence of injection prevention. Add explicit constraint: 'Only +, -, *, /, //, %, ** and parentheses allowed.'