Skyforge MCP Server

# Skyforge MCP Server > ⚠️ **ALPHA RELEASE** - This is an early alpha version. Expect bugs and breaking changes. > > 🚫 **NOT FOR PRODUCTION** - This is a development/experimental version. For a production implementation, please contact [james@skyforge-labs.com](mailto:james@skyforge-labs.com) > > 🔓 **NO AUTHENTICATION** - This server has no built-in authentication. CORS is wide open (`allow_origins=["*"]`). Use at your own risk and secure your deployment appropriately. A Model Context Protocol (MCP) server that connects AI assistants to SkySpark and Haxall building automation systems. Dynamically exposes your SkySpark Axon functions as MCP tools. ## Features - **Dynamic Axon Tools** - Fetches tool definitions from SkySpark at runtime - **Prompt Support** - Expose templated prompts from SkySpark - **Dual Transport** - Supports stdio (Claude Desktop) and HTTP/SSE (web clients) - **Type Safety** - Full Haystack type system with automatic JSON Schema conversion - **Docker Ready** - Simple Docker deployment included ## How It Works The server fetches tools from SkySpark on each `list_tools` request. This means: - Add new tools by creating Axon functions in SkySpark - No server restart needed for schema changes - SkySpark is your single source of truth ## Quick Start ### Prerequisites - SkySpark or Haxall server with API access - Docker (recommended) OR Python 3.12+ with [uv](https://docs.astral.sh/uv/) ### Quick Setup with Example Tools For immediate testing, import the included `setup.zinc` file into your SkySpark project. This provides example MCP tools and the required `fetchMcpTools()` function. ### Docker Setup (Easiest) 1. **Clone and configure** ```bash git clone https://github.com/yourusername/skyforge-mcp.git cd skyforge-mcp # Create .env file cat > .env << EOF SKYSPARK_URI=http://host.docker.internal:8080/api/demo SKYSPARK_USERNAME=your_username SKYSPARK_PASSWORD=your_password EOF ``` 2. **Start server** ```bash docker-compose up --build ``` Server runs on `http://localhost:8000/mcp` 3. **Test with MCP Inspector** ```bash npx @modelcontextprotocol/inspector docker exec -it skyspark-mcp-server uv run main.py ``` ### Local Setup (Development) 1. **Install and run** ```bash # Install uv package manager curl -LsSf https://astral.sh/uv/install.sh | sh # Clone and setup git clone https://github.com/yourusername/skyforge-mcp.git cd skyforge-mcp uv sync # Create .env (same as above) # Run stdio mode (for Claude Desktop) uv run main.py # OR run HTTP/SSE mode (for web clients) uv run uvicorn main:app --host 0.0.0.0 --port 8000 ``` ## Claude Desktop Integration Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS): **Docker:** ```json { "mcpServers": { "skyforge": { "command": "docker", "args": ["exec", "-i", "skyspark-mcp-server", "uv", "run", "main.py"] } } } ``` **Local:** ```json { "mcpServers": { "skyforge": { "command": "uv", "args": ["run", "main.py"], "cwd": "/path/to/skyforge-mcp", "env": { "SKYSPARK_URI": "http://localhost:8080/api/demo", "SKYSPARK_USERNAME": "your_username", "SKYSPARK_PASSWORD": "your_password" } } } } ``` Restart Claude Desktop after saving. ## Creating SkySpark Tools In SkySpark, implement `fetchMcpTools()` to return tool definitions as a grid. Each row should have: - `name` - Tool identifier (Str) - `dis` - Display name (Str) - `help` - Description (Str) - `params` - Parameter schema (Dict or List) **Example in SkySpark:** ```axon // Return MCP tools grid fetchMcpTools: () => [ { name: "getSiteEquips", dis: "Get Site Equipment", help: "Returns all equipment for a site", params: { kind: "Dict", params: { siteId: { kind: "Ref", help: "Site reference ID", required: marker() } } } } ].toGrid // Tool implementation (called via `call()`) getSiteEquips: (dict) => readAll(equip and siteRef == dict->siteId) ``` Import the included `setup.zinc` file into your SkySpark project for example tools and the required `fetchMcpTools()` function. The server fetches tools automatically when clients call `list_tools`. ## Configuration Create `.env` file: ```bash # For Docker: use host.docker.internal to access host machine SKYSPARK_URI=http://host.docker.internal:8080/api/demo # For local development: use localhost # SKYSPARK_URI=http://localhost:8080/api/demo SKYSPARK_USERNAME=your_username SKYSPARK_PASSWORD=your_password ``` All three variables are required. ## Project Structure ``` skyforge-mcp/ ├── app/ │ ├── skyspark/ # SkySpark integration │ │ ├── client.py # Phable-based API client │ │ ├── converters.py # Haystack ↔ JSON Schema conversion │ │ ├── grid.py # HGrid wrapper for dual format output │ │ └── types.py # Extended Haystack types │ └── tools/ │ └── axon_tools.py # Hardcoded tool examples ├── main.py # MCP server entry point ├── docker-compose.yml # Docker setup └── Dockerfile # Container definition ``` ## Troubleshooting **Connection errors:** - **Docker**: Use `host.docker.internal` instead of `localhost` in SKYSPARK_URI - Verify SkySpark URI is accessible: `curl http://your-server:8080/api/demo` - Check `.env` credentials - Ensure SkySpark API is enabled **No tools appearing:** - Verify `fetchMcpTools()` function exists in SkySpark - Check server logs: `docker-compose logs` or `uv run main.py` - Test with MCP Inspector **Docker issues:** ```bash docker-compose logs # View logs docker-compose restart # Restart docker-compose up --build # Rebuild ``` ## Security Notes ⚠️ **Important:** - **This is NOT for production use** - if you are interested in a production implementation, contact [james@skyforge-labs.com](mailto:james@skyforge-labs.com) - No built-in authentication - secure your network/deployment - CORS allows all origins - intended for local development - Store credentials securely (`.env` files, environment variables) - For production, add authentication middleware or use VPN/firewall ## Credits & License **Built with:** - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - Model Context Protocol implementation - [Phable](https://github.com/rick-jennings/phable) - Haystack/SkySpark client library by Rick Jennings - [Project Haystack](https://project-haystack.org/) - Building automation data standard **License:** MIT - see LICENSE file ## Contributing Issues and PRs welcome! This is an alpha release - feedback appreciated. **Repository:** [GitHub](https://github.com/skyforge-labs/skyforge-mcp)