jschroeder-mips/gyrfalcon_mcp_server

Gyrfalcon MCP Server for ATLAS Explorer

A Model Context Protocol (MCP) server that provides seamless integration between Claude Desktop and ATLAS Explorer, enabling AI-powered analysis of processor simulation experiments.

🚀 Overview

This MCP server allows you to:

• Run ATLAS Explorer experiments directly from Claude Desktop conversations
• Analyze performance data with AI-powered insights
• Compare multiple experiments to identify optimization opportunities
• Get expert recommendations based on processor simulation results

The server wraps the AtlasExplorer Python library and provides structured access to experiment management and performance analysis capabilities.

📋 Prerequisites

Before getting started, ensure you have:

1. Python 3.12+ installed
2. UV package manager (recommended) or pip
3. ATLAS Explorer API access with valid credentials
4. Claude Desktop installed
5. ELF files for your workloads (typically in resources/ directory)

🛠️ Installation

Step 1: Clone the Repository

git clone <repository-url>
cd gyrfalcon_mcp_server

Step 2: Set Up Python Environment

Using UV (recommended):

# Install UV if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

Using pip:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Step 3: Configure ATLAS Explorer Credentials

You have two options for configuration:

Option A: Environment Variable (Recommended)

1. Copy the example environment file:

   cp env-example .env
   

2. Edit .env and add your ATLAS Explorer credentials:

   # Required: Your ATLAS Explorer configuration
   MIPS_ATLAS_CONFIG=your_api_key:your_channel:your_region
   
   # Optional: API version override
   API_EXT_VERSION=0.0.97
   

   Format: MIPS_ATLAS_CONFIG=apikey:channel:region

   • apikey: Your ATLAS Explorer API key
   • channel: Usually "development" or "production"
   • region: AWS region (e.g., "us-west-2")

Option B: ATLAS Explorer Configuration File

Run the interactive configuration:

uv run atlasexplorer/atlasexplorer.py configure

This will create a configuration file at ~/.config/mips/atlaspy/config.json.

🔧 Claude Desktop Configuration

Step 1: Locate Claude Desktop Configuration

Find your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

Step 2: Add MCP Server Configuration

Add the Gyrfalcon MCP server to your Claude Desktop configuration:

Option 1: Python Direct (Recommended - Most Reliable)

{
  "mcpServers": {
    "gyrfalcon": {
      "command": "/Users/yourusername/path/to/gyrfalcon_mcp_server/run_mcp_server_python.sh",
      "env": {
        "MIPS_ATLAS_CONFIG": "your_api_key:your_channel:your_region"
      }
    }
  }
}

Option 2: UV with Path Detection

{
  "mcpServers": {
    "gyrfalcon": {
      "command": "/Users/yourusername/path/to/gyrfalcon_mcp_server/run_mcp_server.sh",
      "env": {
        "MIPS_ATLAS_CONFIG": "your_api_key:your_channel:your_region"
      }
    }
  }
}

Option 3: Direct UV execution (if UV is in system PATH)

{
  "mcpServers": {
    "gyrfalcon": {
      "command": "uv",
      "args": ["run", "server.py"],
      "cwd": "/Users/yourusername/path/to/gyrfalcon_mcp_server",
      "env": {
        "MIPS_ATLAS_CONFIG": "your_api_key:your_channel:your_region"
      }
    }
  }
}

Option 4: Direct Python path (ultimate fallback)

{
  "mcpServers": {
    "gyrfalcon": {
      "command": "/Users/yourusername/path/to/gyrfalcon_mcp_server/.venv/bin/python",
      "args": ["server.py"],
      "cwd": "/Users/yourusername/path/to/gyrfalcon_mcp_server",
      "env": {
        "MIPS_ATLAS_CONFIG": "your_api_key:your_channel:your_region"
      }
    }
  }
}

Important:

• Replace /Users/yourusername/path/to/gyrfalcon_mcp_server/ with the actual path to your installation
• Replace your_api_key:your_channel:your_region with your actual ATLAS Explorer credentials
• Use Option 1 (run_mcp_server_python.sh) for the most reliable setup - it bypasses UV path issues entirely

💡 Why Python script is recommended: Claude Desktop runs in a restricted environment where UV may not be found in PATH. The Python script uses the virtual environment directly, ensuring reliable startup.

Step 4: Restart Claude Desktop

After saving the configuration, restart Claude Desktop completely for the changes to take effect.

📁 Directory Structure

Organize your project files as follows:

gyrfalcon_mcp_server/
├── server.py                 # Main MCP server
├── run_mcp_server.sh         # Server startup script
├── pyproject.toml            # UV project configuration
├── requirements.txt          # Python dependencies
├── .env                      # Environment variables (create from env-example)
├── README.md                 # This file
├── resources/                # ELF workload files
│   ├── mandelbrot_rv64_O0.elf
│   ├── mandelbrot_rv64_O3.elf
│   └── memcpy_rv64.elf
├── myexperiments/           # Experiment results (auto-created)
└── examples/                # Example scripts
    ├── ae_singlecore.py
    └── ae_multicore.py

🎯 Usage with Claude Desktop

Once configured, you can use the following capabilities in your Claude Desktop conversations:

Running Experiments

Single-core experiment:

Please run a single-core experiment with the mandelbrot_rv64_O0.elf workload using the I8500_(1_thread) core type.

⏱️ Timing Note: ATLAS Explorer experiments run on remote simulation hardware and typically take 2-5 minutes to complete. Claude will wait for the experiment to finish before responding with results.

Multi-core experiment:

Run a multi-core experiment with mandelbrot_rv64_O0.elf and memcpy_rv64.elf using the I8500_(2_threads) core.

Analyzing Results

Performance analysis:

Analyze the performance results from my latest experiment and provide insights on the IPC, cache performance, and potential optimizations.

Comparing experiments:

Compare the performance between experiment ABC123 and experiment XYZ789. Which one performed better and why?

Getting Information

List available resources:

What ELF files do I have available for experiments?

List experiments:

Show me all my previous experiments and their status.

🔧 Available MCP Tools

The server provides these tools to Claude:

Experiment Execution

• run_single_core_experiment() - Execute single-core experiments
• run_multi_core_experiment() - Execute multi-core experiments

Analysis & Insights

• analyze_experiment_performance() - Detailed performance analysis
• compare_experiments() - Compare multiple experiments
• get_available_resources() - List available ELF files and experiments

Data Access

• atlas-experiments/list - List all experiments
• atlas-experiments/{id}/summary - Get specific experiment summary

🐛 Troubleshooting

Common Issues

1. "Atlas Explorer configuration not found"

Solution: Ensure MIPS_ATLAS_CONFIG is set in your environment or .env file
Format: export MIPS_ATLAS_CONFIG=apikey:channel:region

2. "ELF file not found"

Solution: 
- Check that ELF files are in the resources/ directory
- Use absolute paths or relative paths from the server directory
- Verify file permissions

3. "Command not found: uv"

Solution:
- Install UV: curl -LsSf https://astral.sh/uv/install.sh | sh
- Or use pip installation method instead
- Ensure UV is in your PATH

4. Claude Desktop can't connect to server

Solution:
- Verify the path in claude_desktop_config.json is correct and absolute
- Ensure run_mcp_server.sh is executable (chmod +x run_mcp_server.sh)
- Check that all dependencies are installed (uv sync)
- Restart Claude Desktop after configuration changes
- Check Claude Desktop logs for specific error messages

5. "exec: uv: not found" error

Solution:
- Use Option 1 (Python direct script) to bypass UV path issues entirely
- Or ensure UV is in system PATH: curl -LsSf https://astral.sh/uv/install.sh | sh
- Verify UV installation and path: which uv
- Check UV works: uv --version

6. Permission errors

Solution:
- Ensure write permissions in myexperiments/ directory
- Check file permissions on ELF files
- Run with appropriate user permissions

Debug Mode

Enable verbose logging by setting verbose: true when calling experiment functions, or by adding debug environment variables:

export ATLAS_DEBUG=1
export MCP_DEBUG=1

Testing the Server

Test the server independently:

# Test server startup
uv run server.py

# Test with example workloads
uv run examples/ae_singlecore.py --elf resources/mandelbrot_rv64_O0.elf

📊 Example Workflow

Here's a complete example workflow:

1. Start a conversation with Claude Desktop

2. Check available resources:

   What ELF files do I have available for experiments?
   

3. Run an experiment:

   Please run a single-core experiment with mandelbrot_rv64_O0.elf using the I8500_(1_thread) core type.
   

4. Analyze the results:

   Analyze the performance of my latest experiment. Focus on IPC, cache hit rates, and any performance bottlenecks you can identify.
   

5. Compare with optimized version:

   Now run the same experiment with mandelbrot_rv64_O3.elf and compare the results. Which optimization level performed better?
   

6. Get recommendations:

   Based on these results, what optimizations would you recommend for improving performance on this workload?
   

🔒 Security Considerations

• API Keys: Never commit API keys to version control. Use environment variables or configuration files.
• File Access: The server only accesses files in the project directory and subdirectories.
• Network: All communication with ATLAS Explorer uses HTTPS/secure channels.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📝 License

This project is licensed under the terms specified in the LICENSE file.

🆘 Support

For issues and questions:

1. Check the troubleshooting section above
2. Review ATLAS Explorer documentation
3. Open an issue on the repository
4. Contact the development team

🔄 Updates

To update the server:

git pull origin main
uv sync  # Update dependencies
# Restart Claude Desktop

Happy experimenting with ATLAS Explorer and Claude! 🚀

MCP Server for AtlasExplorer