UFO MCP Server

UFO MCP 服务

通过 Claude Desktop 等兼容 MCP 的客户端控制你的 Dynatrace UFO 设备。

版本 1.0.1 - MCP 规范 2024-11-05

🚀 快速开始

前提条件

• 网络中有一台 Dynatrace UFO 设备
• 找到 UFO 的 IP 地址（查看路由器，或在支持 mDNS 时使用 ufo.local）

📦 安装

选项 1：直接下载（推荐）

# macOS (Apple Silicon)
curl -L https://github.com/starspace46/ufo/releases/download/v1.0.1/ufo-mcp-darwin-arm64 -o /usr/local/bin/ufo-mcp
chmod +x /usr/local/bin/ufo-mcp

# macOS (Intel)
curl -L https://github.com/starspace46/ufo/releases/download/v1.0.1/ufo-mcp-darwin-amd64 -o /usr/local/bin/ufo-mcp
chmod +x /usr/local/bin/ufo-mcp

# Linux
curl -L https://github.com/starspace46/ufo/releases/download/v1.0.1/ufo-mcp-linux-amd64 -o /usr/local/bin/ufo-mcp
chmod +x /usr/local/bin/ufo-mcp

选项 2：Docker

docker pull starspace46/ufo-mcp:latest

# Run with Docker
docker run -d \
  --name ufo-mcp \
  -e UFO_IP=YOUR_UFO_IP_HERE \
  -v ~/.ufo-effects:/data \
  starspace46/ufo-mcp:latest

选项 3：从源代码构建

git clone https://github.com/starspace46/ufo-mcp-server.git
cd ufo-mcp-server
go build -o ufo-mcp ./cmd/server
sudo mv ufo-mcp /usr/local/bin/

🔧 客户端设置

选项 A：桌面扩展（推荐用于多 Agent 场景）

如果要进行多 Agent 协调，让多个 Claude Desktop 实例共享同一 UFO 状态，请使用桌面扩展：

1. 构建扩展

make dxt

2. 启动 HTTP 服务

docker run -d --name ufo-mcp-shared -p 8080:8080 -v "$(pwd)/data:/data" ufo-mcp:local --transport http --port 8080

3. 安装扩展

1. 打开 Claude Desktop
2. 前往设置 > 扩展
3. 将 build/ufo-mcp.dxt 拖到扩展区域

优势：

• ✅ 多个 Claude Desktop 实例共享 UFO 状态
• ✅ Agent 之间实时协调
• ✅ 集中管理效果栈
• ✅ 无需编辑配置文件

详细文档请参阅 extension/README.md。

选项 B：直接配置 MCP

适用于单 Agent场景，或偏好传统 MCP 服务配置的情况：

Claude Desktop

将以下内容添加到 Claude Desktop 配置中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

直接安装

{
  "mcpServers": {
    "ufo": {
      "command": "/usr/local/bin/ufo-mcp",
      "args": [
        "--transport", "stdio",
        "--ufo-ip", "YOUR_UFO_IP_HERE"
      ]
    }
  }
}

Docker 安装

{
  "mcpServers": {
    "ufo": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "UFO_IP=YOUR_UFO_IP_HERE",
        "-v", "~/.ufo-effects:/data",
        "starspace46/ufo-mcp:latest",
        "--transport", "stdio"
      ]
    }
  }
}

Cline（VS Code 扩展）

将以下内容添加到 VS Code 的 settings.json：

直接安装

{
  "mcp.servers": {
    "ufo": {
      "command": "/usr/local/bin/ufo-mcp",
      "args": ["--transport", "stdio", "--ufo-ip", "YOUR_UFO_IP_HERE"]
    }
  }
}

Docker 安装

{
  "mcp.servers": {
    "ufo": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "UFO_IP=YOUR_UFO_IP_HERE",
        "-v", "~/.ufo-effects:/data",
        "starspace46/ufo-mcp:latest",
        "--transport", "stdio"
      ]
    }
  }
}

MuleSoft Anypoint Code Builder

UFO MCP 服务包含对 MuleSoft MCP Connector（0.1.0-BETA）的旧版 SSE 支持。

1. 以 HTTP 模式启动服务：

# Direct
ufo-mcp --transport http --port 8080 --ufo-ip YOUR_UFO_IP_HERE --effects-file ./data/effects.json

# Docker
docker run -d \
  --name ufo-mcp-http \
  -p 8080:8080 \
  -e UFO_IP=YOUR_UFO_IP_HERE \
  -v ~/.ufo-effects:/data \
  starspace46/ufo-mcp:latest \
  --transport http

2. 在 Anypoint Code Builder 中配置 MCP 连接：
   • 服务 URL：http://localhost:8080
   • SSE 端点路径：/sse
   • 服务会自动处理重新连接时的会话持久化

其他 MCP 客户端

对于标准 HTTP/2 MCP 客户端，请连接到 http://localhost:8080/mcp

服务支持同时使用多种传输模式：

• stdio：适用于桌面客户端（Claude、Cline）的标准输入/输出
• http：适用于 Web 客户端的 HTTP/2 + SSE
• 旧版 SSE：与 MuleSoft 兼容的双向 SSE

💡 使用示例

配置完成后，可以让 Claude：

• “把 UFO 变成红色” - 将所有 LED 设为红色
• “播放彩虹效果” - 启动彩色动画
• “把顶部环设为蓝色，底部环设为绿色” - 独立控制各环
• “将亮度设为 50%” - 调整整体亮度
• “让顶部环旋转” - 为环形图案添加动画
• “显示当前 UFO 状态” - 查看当前显示内容

🎨 内置效果

服务包含预配置效果：

• rainbow - 循环变换的彩虹色（持续播放）
• breathingGreen - 平缓的绿色脉冲（持续播放）
• policeLights - 紧急灯光模式（30 秒）
• oceanWave - 舒缓的蓝色波浪（持续播放）
• fireGlow - 闪烁的火焰效果（持续播放）
• alertPulse - 红色警报闪烁（20 秒）

🛠️ 可用工具

• configureLighting - 通过一条命令设置整个 UFO 的灯光（顶部环、底部环、徽标）
• sendRawApi - 直接向 UFO 发送原始 API 命令
• playEffect - 播放效果库中的指定灯光效果
• stopEffect - 停止当前效果，并从效果栈中恢复上一个效果
• getLedState - 查询当前 LED 状态
• listEffects - 显示所有可用效果（内置和自定义）

📝 配置选项

命令行参数

• --transport 或 -t：传输类型（stdio 或 http，默认值：stdio）
• --port：使用 http 传输时的 HTTP 端口（默认值：8080）
• --ufo-ip：UFO 设备 IP 地址（覆盖 UFO_IP 环境变量）
• --effects-file：效果 JSON 文件的路径（默认值：/data/effects.json）

环境变量

• UFO_IP：UFO 设备的 IP 地址或主机名（例如，192.168.1.100 或 ufo.local）

🐛 故障排除

1. 找不到 UFO：在路由器的管理面板中检查 UFO 的 IP 地址
2. 连接被拒绝：确保 UFO 已开机并连接到网络
3. 效果无法保存：检查效果文件位置的写入权限
4. Docker 权限问题：确保效果目录可写

📄 许可证

MIT 许可证 - 详情请参阅 LICENSE 文件