# skyspark-mcp

MCP server for [SkySpark](https://skyfoundry.com/product) — connect AI assistants to your building automation data.

Evaluate Axon expressions, read/write records, manage functions, and explore your SkySpark projects through the [Model Context Protocol](https://modelcontextprotocol.io/).

## Features

- **21 tools** for comprehensive SkySpark interaction
- **SCRAM, token, or no-auth** — works with any network setup (including Tailscale)
- **Multi-project** — target different projects from the same server
- **Base64-safe commits** — avoids Axon `${}` string interpolation issues
- **Production-tested** — used daily for building analytics dashboards

## Quick Start

```bash
pip install skyspark-mcp
```

Create a `.env` file (see `.env.example`):

```env
SKYSPARK_HOST=192.168.1.100
SKYSPARK_PORT=8080
SKYSPARK_PROJECT=demo
SKYSPARK_AUTH=scram
SKYSPARK_USERNAME=su
SKYSPARK_PASSWORD=your-password
```

Run the server:

```bash
# SSE transport (default, port 8765)
skyspark-mcp

# stdio transport (for direct MCP client integration)
skyspark-mcp --stdio
```

## Tools

### Core
| Tool | Description |
|------|-------------|
| `ss_eval` | Evaluate any Axon expression |
| `ss_about` | Server info (version, project, user) |
| `ss_read` | Read records by Haystack filter |
| `ss_read_by_id` | Read a single record by ID |
| `ss_search` | Full-text search across records |

### CRUD
| Tool | Description |
|------|-------------|
| `ss_create` | Create a new record |
| `ss_update` | Update record tags |
| `ss_delete` | Delete matching records |

### Functions
| Tool | Description |
|------|-------------|
| `ss_func_list` | List project functions |
| `ss_func_read` | Read function source code |
| `ss_func_commit` | Update function source (base64-safe) |
| `ss_func_commit_batch` | Batch commit multiple functions |
| `ss_func_diff` | Compare current vs proposed source |
| `ss_funcs_all` | List ALL functions including built-ins |

### Content (base64-safe)
| Tool | Description |
|------|-------------|
| `ss_view_update` | Update view source |
| `ss_page_update` | Update Docunomicon page content |
| `ss_rec_create` | Create record with complex tag values |

### Discovery
| Tool | Description |
|------|-------------|
| `ss_views` | List views |
| `ss_templates` | List Docunomicon templates |
| `ss_libs` | List installed extensions |
| `ss_projects` | List available projects |

## Authentication

### SCRAM (default)
Standard SkySpark authentication. Set `SKYSPARK_USERNAME` and `SKYSPARK_PASSWORD`.

### No Auth
For trusted networks (Tailscale, VPN, localhost). Set `SKYSPARK_AUTH=none`. The server strips auth headers automatically.

### Token
Pre-shared auth token. Set `SKYSPARK_AUTH=token` and `SKYSPARK_PASSWORD=your-token`.

## Multi-Project

Every tool accepts an optional `project` and `server` parameter:

```
ss_eval(expr="readAll(site)", project="other_project")
ss_read(filter_expr="site", server="http://other-server:8080", project="demo")
```

Clients are pooled per server+project combination.

## Usage with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "skyspark": {
      "command": "skyspark-mcp",
      "args": ["--stdio"],
      "env": {
        "SKYSPARK_HOST": "192.168.1.100",
        "SKYSPARK_PORT": "8080",
        "SKYSPARK_PROJECT": "demo",
        "SKYSPARK_AUTH": "scram",
        "SKYSPARK_USERNAME": "su",
        "SKYSPARK_PASSWORD": "your-password"
      }
    }
  }
}
```

## Usage with mcporter

```bash
# SSE
npx mcporter call --allow-http 'http://localhost:8765/mcp.ss_eval(expr: "readAll(site)")'

# stdio
npx mcporter call --stdio "skyspark-mcp --stdio" 'ss_eval(expr: "1 + 1")'
```

## Dependencies

- [phable](https://github.com/rick-jennings/phable) — Python Haystack client
- [FastMCP](https://github.com/jlowin/fastmcp) — MCP server framework

## License

MIT — built by [Pip](https://github.com/pipseedai) 🌱