Transforms cultural sky descriptions into modern astronomical coordinates and Stellarium scripts. Supports multiple cultural calendar systems (Mayan, Julian, Egyptian, Gregorian) and provides star coordinate lookups using the Hipparcos catalog.
Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
This MCP server has critical definition quality gaps. Of the 8 declared tools, only 2 are verifiable in the provided source code (list_cultures in server.py and convert_culture_to_coordinates in server.py). The remaining 6 tools (list_cultures duplicate, get_culture_details, search_cultural_object, convert_date, get_star_coordinates, generate_stellarium_script) appear only in src/mcp_server.py with incomplete implementation stubs. Tool descriptions are present but generic and lack actionable context for LLM selection. Input parameter schemas show type information but descriptions are minimal and lack format/constraint details. Most critically: parameter descriptions are under 20 characters in many cases (e.g., 'Hipparcos catalog ID as a string' for get_star_coordinates), descriptions lack WHEN/WHY context for tool selection, and output schemas are entirely undocumented. Error handling is minimal, tools return plain strings instead of structured errors with recovery guidance. The server exhibits duplicated tool names (list_cultures appears twice with different descriptions) which creates ambiguity for LLMs.
Parameter descriptions are minimal (many under 30 characters) and lack format constraints, ranges, enums, or WHEN/WHY guidance, violates pattern:constrained-input
Eliminate the duplicate list_cultures tool. Choose one definition (e.g., 'list all culture IDs' vs 'list cultures with objects') and keep only that; make the other a separate tool if both use cases are needed (e.g., list_culture_ids vs describe_cultures).
Document the output schema for every tool. Use JSON Schema format in the tool registration. Example: convert_culture_to_coordinates should return {"culture_id": string, "object_name": string, "ra_degrees": number, "dec_degrees": number, "jd_value": number, "utc_date": string}. This enables LLM multi-step planning.
Expand parameter descriptions to 50 - 150 characters each, including: (1) WHAT the parameter controls, (2) valid format/range/enum, (3) WHEN/WHY it's needed. Example: culture_id: 'The unique identifier for a sky culture system (e.g., 'maya', 'egyptian', 'polynesian'). Retrieve available IDs by calling list_cultures().'
Move example values from descriptions into schema constraints. Replace 'Hipparcos ID (e.g., '12345')' with a description 'Hipparcos catalog ID (integer 1 - 120,000)' and add a minLength/maxLength or pattern in the schema. Use enums for fixed sets (e.g., calendar systems: gregorian, julian, mayan, egyptian).
Add structured error responses. Instead of 'Error: Culture not found', return: 'Culture 'unknown_id' not found. Available cultures: [list]. Call list_cultures() to discover options.' This guides the LLM to recovery steps.
Implement proper date format validation. Define date_str parameter with an enum of supported formats or a regex pattern constraint: e.g., pattern: '^(M:\d+,\d+,\d+,\d+,\d+|J:\d+,\d+,\d+|\d{4}-\d{2}-\d{2}T.*Z?)$'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Tool descriptions lack WHEN/WHY context, they state WHAT but not when LLMs should select them over similar tools (e.g., list_cultures vs get_culture_details)
Example values embedded in descriptions (e.g., '12345' for Hipparcos ID, 'M:13,0,0,0,0' for Mayan dates) encourage LLMs to reuse them literally instead of understanding the format
No structured error handling, tools return plain strings ('Error:', '❌ Error:') instead of actionable error messages with recovery steps (e.g., 'Culture not found. Call list_cultures() to see available options.')
6 of 8 tools only partially visible in source code (src/mcp_server.py contains incomplete stubs without full logic), cannot verify actual behavior against documented schemas
Tools return unstructured strings or JSON-as-string instead of structured, typed response objects, wastes tokens and forces LLMs to parse and reason about format
Tool names lack specificity or clarity in some cases: search_cultural_object (searches what?), convert_date (convert to what?), generate_stellarium_script (does it run?)
Date format specification embedded in description text instead of declared as enum or regex pattern in schema, LLMs cannot reliably parse or validate complex formats
convert_culture_to_coordinatesconvert_date
Complete the implementation of tools in src/mcp_server.py. The stubs are incomplete and cannot be verified. Either merge them into server.py with full logic or provide complete source with input validation and documented behavior.
Change tool response format from string to structured JSON. Example: convert_culture_to_coordinates should return a dict with fields (culture_id, object_name, ra_deg, dec_deg, julian_day, utc_date, observer_lat, observer_lon) instead of a formatted string. This is cheaper to process and enables downstream tool chaining.
Add a WHEN/WHY clause to each tool description to help LLMs disambiguate. Example: 'list_cultures: Call this FIRST to discover available sky culture systems and the objects they define. Use get_culture_details() to get full info on one culture, or search_cultural_object() to find a specific star across all cultures.'
Specify min/max/enum constraints for numeric parameters (e.g., latitude -90 to 90, longitude -180 to 180, limit 1 - 100). Add these to parameter descriptions and schema.
Validate all inputs early and return clear, actionable errors. Example: if culture_id is not found, respond with 'Culture 'xyz' not found. Available: [list]. Tip: Use list_cultures() to see all options.' rather than a bare 404.
Add rate-limit and timeout guidance for tools that call external services (Skyfield ephemeris downloads, Stellarium script generation). Example: 'Note: First call may take 10 - 30s to download ephemeris data (de421.bsp). Subsequent calls are instant. Set timeout >= 60s.' This prevents agent timeouts.