A FastAPI-based MCP server that integrates OpenAI models with MCP tools through pydantic-ai. It manages MCP server connections, tool discovery, and agent-based query processing with Supabase conversation history storage.
This server defines 2 weather tools with reasonable clarity. Tool names follow verb_noun convention (get-alerts, get-forecast). Both tools have descriptions and input schemas with proper JSON Schema structure. However, there are notable gaps: output schemas are NOT documented (only TextContent responses are returned with no schema definition), parameter descriptions are minimal (latitude/longitude lack range constraints, state parameter lacks guidance on validation), and error handling is present but not well-integrated into the tool interface. The server returns plain text responses rather than structured objects, making it harder for LLMs to chain calls. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are declared. The code shows decent input validation (latitude -90 to 90, longitude -180 to 180, state length check) but these constraints are not formally declared in the schema, they appear only in the implementation.
Get weather alerts for a state
Get weather forecast for a location
Output schemas not documented. Both tools return TextContent with no formal schema definition of the returned text structure. LLMs cannot infer what fields or format the response will contain, limiting ability to chain calls or extract structured data.
Parameter constraints not formally declared in schema. The state parameter requires validation (2-letter code) but this is only enforced in code, not expressed in the JSON Schema via pattern or enum. Latitude/longitude have range constraints (-90 to 90 and -180 to 180) that appear only in error handling, not in the schema minValue/maxValue.
Parameter descriptions lack detail. 'Two-letter state code (e.g. CA, NY)' provides an example but not formal constraints. Latitude/longitude descriptions are purely functional with no guidance on valid ranges or what happens outside them. By the rubric baseline of 72-character average param annotation, these are too terse.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 54 | <=2025-11-25 | v2 |
| 2026-03-09 | D | 55 | - | v1 |
No tool annotations. Tools are marked READ_ONLY in the metadata but do not declare readOnlyHint in the tool definition. This is a current spec pattern (2026-07-28) that should be used to make tool safety explicit.
Error messages in code are unstructured. Errors like 'Invalid coordinates. Latitude must be between -90 and 90, longitude between -180 and 180.' are returned as TextContent but do not follow a consistent error response schema. This makes it hard for LLMs to distinguish success from failure programmatically.
No pagination support. The get-alerts tool could return many active alerts but offers no limit or offset parameters. Response could grow arbitrarily, wasting context. The rubric baseline expects pagination (limit + offset/cursor) for list-returning tools.