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

Install from PyPI

Once published, you can install directly:

pip install skyforge-mcp

# Run stdio entry (console script)
skyforge-mcp-stdio

# Or run package via module (also stdio)
python -m skyforge_mcp

Environment variables (required by all modes):

export SKYSPARK_URI=http://host.docker.internal:8082/api/demo
export SKYSPARK_USERNAME=su
export SKYSPARK_PASSWORD=su

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)

Clone and configure

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

Start server
```
docker-compose up --build
```
Server runs on http://localhost:8000/mcp

Test with MCP Inspector

npx @modelcontextprotocol/inspector docker exec -it skyspark-mcp-server uv run main.py

Local Setup (Development)

Install and run

# 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 HTTP/SSE mode (for web clients)

uv run main.py

Or stdio mode directly (same as pip/console-script behavior)

uv run python -m skyforge_mcp


## Claude Desktop Integration (stdio)

This server is designed to run as an MCP stdio server when used with Claude Desktop. You can run it through Docker Compose.

Edit your Claude Desktop config:
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

Pick one of the options below.

### Option A — Use cwd (project working directory)
```json
{
"mcpServers": {
 "skyforge-mcp": {
   "type": "stdio",
   "command": "docker",
   "args": ["compose","run","--rm","skyforge-mcp","uv","run","skyforge-mcp-stdio"],
   "cwd": "C:\\\\Users\\\\YOUR_USER\\\\Documents\\\\SkyForge labs\\\\GitHub\\\\skyforge-mcp",
   "env": {
     "SKYSPARK_URI": "http://host.docker.internal:8082/api/demo",
     "SKYSPARK_USERNAME": "su",
     "SKYSPARK_PASSWORD": "su"
   }
 }
}
}

Option B — Pass the compose file path explicitly (works from any cwd)

{
  "mcpServers": {
    "skyforge-mcp": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "compose","-f","C:\\\\Users\\\\YOUR_USER\\\\Documents\\\\SkyForge labs\\\\GitHub\\\\skyforge-mcp\\\\docker-compose.yml",
        "run","--rm","skyforge-mcp","uv","run","skyforge-mcp-stdio"
      ],
      "env": {
        "SKYSPARK_URI": "http://host.docker.internal:8082/api/demo",
        "SKYSPARK_USERNAME": "su",
        "SKYSPARK_PASSWORD": "su"
      }
    }
  }
}

Notes:

Replace YOUR_USER and the path to match your machine.
On Windows JSON, backslashes must be escaped (\\).
Restart Claude Desktop after saving the config.

Cursor MCP (stdio) configuration

Add to Cursor settings (MCP servers). This uses the PyPI package if installed:

{
  "mcpServers": {
    "skyforge-mcp": {
      "command": "python",
      "args": ["-m", "skyforge_mcp"],
      "env": {
        "SKYSPARK_URI": "https://skyspark.skyforge.app/api/skyforgeMcp",
        "SKYSPARK_USERNAME": "skycode",
        "SKYSPARK_PASSWORD": "skycode"
      }
    }
  }
}

Cursor MCP Integration

Add this to your Cursor MCP configuration to run via stdio:

{
  "mcpServers": {
    "skyforge-mcp": {
      "command": "python",
      "args": ["-m", "skyforge_mcp.stdio"],
      "env": {
        "SKYSPARK_URI": "https://skyspark.skyforge.app/api/skyforgeMcp",
        "SKYSPARK_USERNAME": "skycode",
        "SKYSPARK_PASSWORD": "skycode"
      }
    }
  }
}

Alternatively, after pip install skyforge-mcp, you can use the console script:

{
  "mcpServers": {
    "skyforge-mcp": {
      "command": "skyforge-mcp-stdio",
      "env": {
        "SKYSPARK_URI": "https://skyspark.skyforge.app/api/skyforgeMcp",
        "SKYSPARK_USERNAME": "skycode",
        "SKYSPARK_PASSWORD": "skycode"
      }
    }
  }
}

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:

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

# 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

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.github/workflows		.github/workflows
app		app
skyforge_mcp		skyforge_mcp
.DS_Store		.DS_Store
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
main.py		main.py
pyproject.toml		pyproject.toml
setup.zinc		setup.zinc
start_pm2.sh		start_pm2.sh
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Skyforge MCP Server

Features

How It Works

Quick Start

Prerequisites

Install from PyPI

Quick Setup with Example Tools

Docker Setup (Easiest)

Local Setup (Development)

Run HTTP/SSE mode (for web clients)

Or stdio mode directly (same as pip/console-script behavior)

Option B — Pass the compose file path explicitly (works from any cwd)

Cursor MCP (stdio) configuration

Cursor MCP Integration

Creating SkySpark Tools

Configuration

Project Structure

Troubleshooting

Security Notes

Credits & License

Contributing

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Skyforge MCP Server

Features

How It Works

Quick Start

Prerequisites

Install from PyPI

Quick Setup with Example Tools

Docker Setup (Easiest)

Local Setup (Development)

Run HTTP/SSE mode (for web clients)

Or stdio mode directly (same as pip/console-script behavior)

Option B — Pass the compose file path explicitly (works from any cwd)

Cursor MCP (stdio) configuration

Cursor MCP Integration

Creating SkySpark Tools

Configuration

Project Structure

Troubleshooting

Security Notes

Credits & License

Contributing

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages