Astro MCP

# Astro MCP - Agentic Astronomical Data Access A modular Model Context Protocol (MCP) server that provides unified access to multiple astronomical datasets through a clean, extensible architecture. ## Vision This MCP server aims to transform big-data astronomy from a software engineering problem into a natural language conversation. Instead of spending months learning astroquery APIs, researchers simply ask for what they need and get clean, processed analysis-ready data products. One expert solves the complexity once; thousands of scientists benefit forever. A student with little programming experience can now perform the same multi-survey analysis as an expert astronomer using nothing but natural language and an AI assistant. This isn't just about astronomy—it's a template for democratizing all of science. Every field has brilliant researchers spending 80% of their time on data wrangling instead of discovery. By removing that bottleneck, we accelerate the pace of scientific progress itself. The result: AI scientists that can seamlessly access and cross-match data from dozens of astronomical surveys, enabling discoveries that would have taken months of setup to attempt just a few years ago. ## Quick Setup for Cursor & Claude Desktop ### 1. Clone and Setup Environment ```bash # Clone the repository git clone https://github.com/SandyYuan/astro_mcp.git cd astro_mcp # Create a dedicated conda environment with Python 3.11+ conda create -n mcp python=3.11 conda activate mcp # Install dependencies pip install -r requirements.txt # Install astronomical libraries for full functionality pip install sparclclient datalab astropy astroquery ``` ### 2. Test the Server ```bash # Test basic functionality python test_server.py # Test with a simple query (optional) python -c " import asyncio from server import astro_server async def test(): result = astro_server.get_global_statistics() print('✅ Server working:', result['total_files'], 'files in registry') services = astro_server.list_astroquery_services() print(f'✅ Astroquery: {len(services)} services discovered') asyncio.run(test()) " ``` ### 3. Configure for Cursor Add this configuration to your Cursor MCP settings: ```json { "mcpServers": { "astro-mcp": { "command": "/path/to/conda/envs/mcp/bin/python", "args": ["/path/to/astro_mcp/server.py"], "cwd": "/path/to/astro_mcp", "env": {} } } } ``` **To find your conda Python path:** ```bash conda activate mcp which python # Copy this path for the "command" field above ``` ### 4. Configure for Claude Desktop Edit your Claude Desktop MCP configuration file: **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "astro-mcp": { "command": "/path/to/conda/envs/mcp/bin/python", "args": ["/path/to/astro_mcp/server.py"], "cwd": "/path/to/astro_mcp", "env": {} } } } ``` ### 5. Restart and Test 1. **Restart Cursor/Claude Desktop** to load the new MCP server 2. **Test with a query** like: - "Search for galaxies near RA=10.68, Dec=41.27" - "Get Betelgeuse's coordinates from SIMBAD" - "Find 10 BOSS galaxies around z=0.5 and save as FITS" - "List available astroquery services" ### 6. Troubleshooting **Server won't start:** ```bash # Check Python environment conda activate mcp python --version # Should be 3.11+ # Test server manually python server.py # Should start without errors ``` **MCP connection issues:** - Verify the Python path in your config points to the conda environment - Ensure the working directory (`cwd`) points to the astro_mcp folder - Check that all dependencies are installed in the correct environment **Missing astronomical data:** ```bash # Install optional dependencies for full functionality conda activate mcp pip install sparclclient datalab astropy astroquery h5py ``` ## Usage Examples with Cursor/Claude Desktop Once configured, you can ask natural language questions about astronomical data: ### Basic Searches - *"Find galaxies near RA=150.5, Dec=2.2 within 0.1 degrees"* - *"Search for quasars with redshift between 2 and 3"* - *"Get Betelgeuse's exact coordinates from SIMBAD"* - *"Find 10 BOSS galaxies around redshift 0.5"* ### Multi-Survey Access - *"Query VizieR for stellar catalogs in the Orion region"* - *"Search SDSS for galaxies and save as FITS format"* - *"Get object information from multiple astronomical databases"* - *"List all available astroquery services for galaxy studies"* ### Spectral Data Analysis - *"Get the spectrum for DESI object with ID 1270d3c4-9d36-11ee-94ad-525400ad1336"* - *"Show me detailed spectral information for the brightest quasar you can find"* - *"Find a galaxy spectrum and analyze its redshift"* ### File Management & Conversion - *"List all saved astronomical data files"* - *"Convert my galaxy catalog to FITS format"* - *"Preview the structure of the latest search results"* - *"Show me storage statistics for downloaded data"* ### Advanced Queries - *"Find high-redshift galaxies (z > 1.5) and save their spectra"* - *"Search for objects in the COSMOS field and analyze their types"* - *"Cross-match DESI and SDSS data for the same sky region"* The server will automatically: - Execute appropriate database queries across multiple surveys - Save results with descriptive filenames and metadata - Handle coordinate conversions and astronomical calculations - Convert data to standard formats (CSV, FITS) as needed ## Architecture ``` astro_mcp/ ├── server.py # Main MCP server entry point ├── data_sources/ # Modular data source implementations │ ├── __init__.py │ ├── base.py # Base class for all data sources │ ├── desi.py # DESI survey data access │ ├── astroquery_universal.py # Universal astroquery wrapper │ └── astroquery_metadata.py # Service metadata and capabilities ├── data_io/ # File handling and conversion │ ├── __init__.py │ ├── preview.py # Data preview and structure analysis │ └── fits_converter.py # FITS format conversion ├── tests/ # Test suite ├── examples/ # Usage examples └── requirements.txt # Project dependencies ``` ## Features ### 🔭 **Universal Astronomical Data Access** - **DESI**: Dark Energy Spectroscopic Instrument via SPARCL and Data Lab - **Astroquery**: Automatic access to 40+ astronomical services (SIMBAD, VizieR, SDSS, Gaia, etc.) - **Auto-discovery**: Automatically detects and configures available astroquery services - **Unified interface**: Same API for all data sources ### 📁 **Intelligent File Management** - Automatic data saving with descriptive filenames - Cross-source file registry and organization - Comprehensive metadata tracking with provenance - Smart file preview with loading examples - FITS format conversion for astronomical compatibility ### 🔍 **Powerful Search Capabilities** - Coordinate-based searches (point, cone, box) across all surveys - Object type and redshift filtering - SQL queries with spatial indexing (Q3C) - Natural language query interpretation - Cross-survey data correlation ### 📊 **Data Analysis & Conversion Tools** - Spectral data retrieval and analysis - Automatic FITS conversion for catalogs, spectra, and images - File structure inspection and preview - Statistics and storage management - Extensible tool architecture for custom analysis ### 🤖 **AI-Optimized Interface** - Parameter preprocessing and validation - Intelligent error handling with helpful suggestions - Automatic format detection and conversion - Consistent metadata across all data sources ## Installation > **Quick Start:** For Cursor & Claude Desktop integration, see the [Quick Setup](#quick-setup-for-cursor--claude-desktop) section above. ### Manual Installation ```bash # Clone the repository git clone https://github.com/SandyYuan/astro_mcp.git cd astro_mcp # Create and activate environment conda create -n mcp python=3.11 conda activate mcp # Install core dependencies pip install -r requirements.txt # Install astronomical libraries pip install sparclclient datalab astropy astroquery # Optional: Install development dependencies pip install pytest coverage ``` ### Verify Installation ```bash # Test the server components python test_server.py # Check available astroquery services python -c " import asyncio from server import astro_server async def show_services(): services = astro_server.list_astroquery_services() print(f'✅ Discovered {len(services)} astroquery services') for service in services[:5]: # Show first 5 print(f' - {service["full_name"]} ({service["service"]})') asyncio.run(show_services()) " ``` ## Quick Start ### 1. Start the MCP Server ```bash python server.py ``` ### 2. Available Tools The server provides these main tools: **Data Access:** - `search_objects` - Find astronomical objects (DESI) - `astroquery_query` - Universal queries across 40+ astronomical services - `get_spectrum_by_id` - Retrieve detailed spectral data (DESI) **Service Discovery:** - `list_astroquery_services` - Show all available astronomical databases - `get_astroquery_service_details` - Detailed service information - `search_astroquery_services` - Find services by criteria **File Management:** - `preview_data` - Inspect saved files with structure analysis - `list_files` - Manage saved data across all sources - `file_statistics` - Storage usage and organization info - `convert_to_fits` - Convert data to FITS format ### 3. Example Usage ```python # Get object coordinates from SIMBAD astroquery_query( service_name="simbad", object_name="Betelgeuse" ) # Search SDSS for galaxies with SQL astroquery_query( service_name="sdss", query_type="query_sql", sql="SELECT TOP 10 ra, dec, z FROM SpecObj WHERE class='GALAXY' AND z BETWEEN 0.1 AND 0.3" ) # Search VizieR catalogs astroquery_query( service_name="vizier", ra=10.68, dec=41.27, radius=0.1 ) # Convert results to FITS convert_to_fits( identifier="search_results.csv", data_type="catalog" ) ``` ## Data Sources ### DESI (Dark Energy Spectroscopic Instrument) **Status**: ✅ Fully Implemented - **SPARCL Access**: Full spectral data retrieval - **Data Lab SQL**: Fast catalog queries (sparcl.main table) - **Coverage**: DESI EDR (~1.8M) and DR1 (~18M+ spectra) - **Wavelength**: 360-980 nm, Resolution: R ~ 2000-5500 ### Astroquery Universal Access **Status**: ✅ Fully Implemented **Major Services Available:** - **SIMBAD**: Object identification and basic data - **VizieR**: Astronomical catalogs and surveys - **SDSS**: Sloan Digital Sky Survey data and spectra - **Gaia**: Astrometric and photometric data - **MAST**: Hubble, JWST, and other space telescope archives - **IRSA**: Infrared and submillimeter archives - **ESASky**: Multi-mission astronomical data - **And 30+ more services...** **Capabilities:** - Automatic service discovery and configuration - Intelligent query type detection - Parameter preprocessing and validation - Unified error handling and help generation **Required Dependencies**: ```bash pip install astroquery astropy ``` ## Extending the Architecture ### Adding a New Data Source 1. **Create the data source class**: ```python # data_sources/my_survey.py from .base import BaseDataSource class MySurveyDataSource(BaseDataSource): def __init__(self, base_dir=None): super().__init__(base_dir=base_dir, source_name="my_survey") # Initialize survey-specific clients def search_objects(self, **kwargs): # Implement survey-specific search pass ``` 2. **Update the main server**: ```python # server.py from data_sources import MySurveyDataSource class AstroMCPServer: def __init__(self, base_dir=None): # ... existing code ... self.my_survey = MySurveyDataSource(base_dir=base_dir) ``` ### Adding New Astroquery Services The astroquery integration automatically discovers new services. To add custom metadata: ```python # data_sources/astroquery_metadata.py ASTROQUERY_SERVICE_INFO = { "my_service": { "full_name": "My Custom Service", "description": "Custom astronomical database", "data_types": ["catalogs", "images"], "wavelength_coverage": "optical", "object_types": ["stars", "galaxies"], "requires_auth": False, "example_queries": [ { "description": "Search by object name", "query": "astroquery_query(service_name='my_service', object_name='M31')" } ] } } ``` ## File Organization Files are automatically organized by data source with comprehensive metadata: ``` ~/astro_mcp_data/ ├── file_registry.json # Global file registry with metadata ├── desi/ # DESI-specific files │ ├── desi_search_*.json # Search results │ ├── spectrum_*.json # Spectral data │ └── *.fits # FITS conversions └── astroquery/ # Astroquery results ├── astroquery_simbad_*.csv # SIMBAD queries ├── astroquery_sdss_*.csv # SDSS results ├── astroquery_vizier_*.csv # VizieR catalogs └── *.fits # FITS conversions ``` ## Development ### Project Structure Benefits - **Modularity**: Easy to add new surveys and analysis tools - **Universal Access**: Single interface to 40+ astronomical databases - **Separation of Concerns**: Data access, I/O, and analysis are separate - **Testability**: Each module can be tested independently - **Scalability**: Clean architecture supports unlimited growth ### Testing ```bash # Run all tests pytest # Test specific modules pytest tests/test_desi.py pytest tests/test_astroquery.py # Test with coverage pytest --cov=data_sources tests/ ``` ### Contributing 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/new-capability`) 3. Add your data source or tool following the existing patterns 4. Write tests for new functionality 5. Update documentation and examples 6. Submit a pull request ## Dependencies ### Core Requirements - `mcp>=1.0.0` - Model Context Protocol framework - `pandas>=2.0.0` - Data manipulation - `numpy>=1.24.0` - Numerical computing ### Astronomical Libraries - `astroquery>=0.4.6` - Universal astronomical database access - `astropy>=5.0.0` - FITS files and astronomical calculations - `sparclclient>=1.0.0` - DESI SPARCL access - `datalab>=2.20.0` - NOAO Data Lab queries ### Optional Features - `h5py>=3.8.0` - HDF5 file support - `pytest>=7.0.0` - Testing framework ## License [Specify your license here] ## Citation If you use this software in your research, please cite: ```bibtex @software{astro_mcp, title={Astro MCP: Universal Astronomical Data Access for AI Agents}, author={[Your Name]}, year={2024}, url={[Repository URL]} } ``` ## Support - **Issues**: [GitHub Issues](link-to-issues) - **Documentation**: [Full Documentation](link-to-docs) - **Discussions**: [GitHub Discussions](link-to-discussions) ## Roadmap ### Current (v0.1.0) - ✅ DESI data access via SPARCL and Data Lab - ✅ Universal astroquery integration (40+ services) - ✅ Automatic FITS conversion for all data types - ✅ Intelligent file management with comprehensive metadata - ✅ Natural language query interface ### Planned (v0.2.0) - 🚧 Cross-survey object matching and correlation - 🚧 Advanced astronomical calculations (distances, magnitudes) - 🚧 Time-series analysis for variable objects - 🚧 Visualization tools integration ### Future (v0.3.0+) - 🔮 Machine learning integration for object classification - 🔮 Real-time data streaming from surveys - 🔮 Custom analysis pipeline creation - 🔮 Multi-wavelength data correlation tools