AI导哈

模型上下文协议服务器

连接AI助手与SkySpark和Haxall建筑自动化系统的模型上下文协议服务器，动态将SkySpark Axon功能暴露为MCP工具。

  • by skyforge-labs
  • Python
  • 本地部署
  • 5 星标
  • 更新于
在 GitHub 查看 skyforge-labs/skyforge-mcp

使用说明

Skyforge MCP 服务器

⚠️ Alpha版发布 - 这是早期的alpha版本。请预期可能会存在bug和破坏性变更。

🚫 禁止/不允许 非生产用途 - 这是一个开发/实验版本。如需用于生产环境，请联系 james@skyforge-labs.com（可译为：“詹姆斯@天空锻造实验室邮箱”或根据具体语境简化为“詹姆斯的天空锻造实验室邮箱”）

解锁 未进行身份验证 - 这台服务器没有内置认证。CORS（跨域资源共享）设置完全开放（allow_origins=["*"]）。 自行使用，风险自担，并确保妥善部署。

一个模型上下文协议（MCP）服务器，用于将人工智能助手连接到SkySpark和Haxall楼宇自动化系统。它能动态地将您的SkySpark Axon功能作为MCP工具暴露出来。

特点/功能

  • 动态轴突工具 - 在运行时从SkySpark获取工具定义
  • 即时支持 - 从SkySpark中暴露模板化提示
  • 双运输（或“双重运输”） - 支持stdio（Claude桌面版）和HTTP/SSE（网页客户端）
  • 类型安全 - 完整的Haystack类型系统，支持自动JSON Schema转换
  • Docker 准备就绪 - 包含简单的Docker部署

它是如何工作的

服务器每次从SkySpark获取工具 list_tools 请求。这意味着：

  • 在SkySpark中创建Axon函数以添加新工具
  • 模式更改无需重启服务器
  • SkySpark是您获取真相的唯一来源

快速入门

先决条件

  • 带有API访问权限的SkySpark或Haxall服务器
  • Docker（推荐）或 Python 3.12+ 及其以上版本 紫外线

使用示例工具快速设置

为了立即进行测试，请导入随附的 setup.zinc 将文件添加到您的SkySpark项目中。这提供了示例MCP工具和所需的 fetchMcpTools() 功能。

Docker 设置（最简单的方法）

  1. 克隆并配置

    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. 启动服务器

    docker-compose up --build

    服务器运行于 http://localhost:8000/mcp

  3. 使用MCP Inspector进行测试

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

本地设置（开发）

  1. 安装并运行
    # 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桌面集成

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

Docker：

{
  "mcpServers": {
    "skyforge": {
      "command": "docker",
      "args": ["exec", "-i", "skyspark-mcp-server", "uv", "run", "main.py"]
    }
  }
}

本地：

{
  "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"
      }
    }
  }
}

保存后重启 Claude 桌面版。

创建SkySpark工具

在SkySpark中，实施 fetchMcpTools() 以表格形式返回工具定义。每一行应包含：

  • name - 工具标识符（字符串）
  • dis - 显示名称（字符串）
  • help - 描述（字符串）
  • params - 参数模式（字典或列表）

在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)

导入随附的（内容/文件） setup.zinc 将文件放入您的SkySpark项目中，作为示例工具和所需的（内容） fetchMcpTools() 功能。

当客户端调用时，服务器会自动获取工具 list_tools。

配置

创造 .env 文件：

# 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

这三个变量都是必需的。

项目结构

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

故障排除

连接错误：

  • **Docker（注：Docker是一个开源的应用容器引擎，用于开发、交付和运行应用程序。）**使用 host.docker.internal 而不是 localhost 在 SKYSPARK_URI 中
  • 验证SkySpark URI是否可访问： curl http://your-server:8080/api/demo
  • 检查 .env 凭证；资历；资格
  • 确保启用SkySpark API

未显示工具：

  • 验证 fetchMcpTools() 在SkySpark中存在该函数
  • 检查服务器日志： docker-compose logs 或者 uv run main.py
  • 使用MCP Inspector进行测试

Docker问题：

docker-compose logs              # View logs
docker-compose restart           # Restart
docker-compose up --build        # Rebuild

安全注意事项

⚠️（表示警告或提醒的符号，无具体文字含义，可译为“警告”或根据上下文译为相应提示） 重要提示：

版权声明与许可

构建于：

许可证： MIT - 请参阅LICENSE文件

做出贡献

欢迎提出问题和提交拉取请求（PR）！这是一个alpha版本，欢迎提供反馈。

仓库： GitHub

相关 MCP