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

>

> 🔓 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

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

git clone https://github.com/yourusername/skyforge-mcp.git
   cd skyforge-mcp
   
   # Create .env file
   cat > .env  [
  {
    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:

# 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:

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
• 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 - Model Context Protocol implementation
• Phable - Haystack/SkySpark client library by Rick Jennings
• Project Haystack - Building automation data standard

License: MIT - see LICENSE file

Contributing

Issues and PRs welcome! This is an alpha release - feedback appreciated.

Repository: GitHub