A template MCP server with FastAPI and Scalar UI
The server defines 5 tools with reasonable naming (verb-first pattern) and basic descriptions in Korean and English. However, critical gaps exist: (1) Parameters lack detailed descriptions for format/constraints; (2) Output schemas are not documented, tools return JSON strings with no declared structure; (3) Error handling is generic (wraps exceptions in JSON but provides no recovery guidance); (4) No input validation or constraint documentation visible in code. Tool descriptions are present but short (averaging ~80 chars), meeting minimum bar but not optimized for LLM selection. The fastmcp framework infers schemas from Python type hints, which is a positive automation, but the resulting schemas are minimal, no enums, no min/max bounds, no format specifications. The code shows basic safety (CRUD operations with error wrapping) but lacks the sophistication needed for production agent orchestration.
새로운 데이터를 생성합니다. 데이터 입력 및 추가작업에 활용할 수 있습니다.
데이터를 삭제합니다. 데이터 정리 및 관리에 활용할 수 있습니다.
데이터 ID로 특정 데이터를 조회합니다. 상세 정보 확인에 활용할 수 있습니다.
키워드로 데이터를 검색합니다. 검색 및 필터링에 활용할 수 있습니다.
기존 데이터를 업데이트합니다. 데이터 수정 및 갱신에 활용할 수 있습니다.
Output schemas undocumented. Tools return raw JSON strings with no declared structure (fields, types, nesting). LLMs cannot plan downstream tool calls or extract fields reliably.
Parameter descriptions lack constraint details. 'query' parameter in search_data_by_query has no guidance on format, min/max length, or special characters. 'limit' has no bounds (1 - 100? 1 - 1000?). This invites invalid input.
Error handling is generic wrapper (wraps exceptions in JSON) with no recovery guidance. An LLM receiving {'error': 'Connection timeout'} has no guidance on whether to retry, call a different tool, or ask the user. Errors should be categorized (retryable, user-fixable, fatal) with suggested next steps.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 53 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 47 | - | v1 |
Destructive tool (delete_data_by_id) has no confirmation/dry-run pattern. Agents can permanently delete data with a single call. Should require explicit confirmation or support a dry-run mode to prevent catastrophic errors.
Parameter types are inferred from Python hints but not validated in code. update_existing_data accepts optional strings with defaults='', but empty strings may be treated as 'update to empty' rather than 'skip this field'. This ambiguity can cause data loss.
search_data_by_query returns potentially large result sets with no pagination documentation. Response structure is undocumented, unclear if it returns a list, count, total, or next_cursor. Large unstructured responses waste context and risk hallucination.