Fledge MCP Server

Fledge MCP Server

这是一个 Model Context Protocol（MCP）服务，可将 Fledge 功能连接到 Cursor AI，让 AI 通过自然语言命令与 Fledge 实例交互。

前提条件

• 本地已安装 Fledge，或可通过 API 访问（默认地址：http://localhost:8081）
• 已安装 Cursor AI
• Python 3.8+

安装

1. 克隆此仓库：

git clone https://github.com/Krupalp525/fledge-mcp.git
cd fledge-mcp

2. 安装依赖：

pip install -r requirements.txt

运行服务

1. 确保 Fledge 正在运行：

fledge start

2. 启动 MCP 服务：

python mcp_server.py

如需通过 API 密钥认证来安全运行：

python secure_mcp_server.py

3. 访问健康检查端点以确认服务正常运行：

curl http://localhost:8082/health

你应收到“Fledge MCP Server is running”作为响应。

连接到 Cursor

1. 在 Cursor 中，前往 Settings > MCP Servers

2. 添加新服务：

   • URL： http://localhost:8082/tools
   • Tools 文件：上传随附的 tools.json，或指定其本地路径

3. 对于安全服务，请将“X-API-Key”请求头配置为启动安全服务时生成的 api_key.txt 文件中的值。

4. 测试：打开 Cursor 的 Composer（Ctrl+I），输入“Check if Fledge API is reachable”，AI 应调用 validate_api_connection 工具。

可用工具

数据访问与管理

1. get_sensor_data：从 Fledge 获取传感器数据，可选择按时间范围和数量限制进行筛选
2. list_sensors：列出 Fledge 中的所有可用传感器
3. ingest_test_data：将测试数据导入 Fledge，可选择批次数量

服务控制

4. get_service_status：获取所有 Fledge 服务的状态
5. start_stop_service：按类型启动或停止 Fledge 服务
6. update_config：更新 Fledge 配置参数

前端代码生成

7. generate_ui_component：生成用于可视化 Fledge 数据的 React 组件
8. fetch_sample_frontend：获取适用于不同框架的前端示例模板
9. suggest_ui_improvements：获取由 AI 提供的 UI 代码改进建议

实时数据流

10. subscribe_to_sensor：订阅传感器数据更新
11. get_latest_reading：获取指定传感器的最新读数

调试与验证

12. validate_api_connection：检查是否可以访问 Fledge API
13. simulate_frontend_request：使用不同的方法和负载测试 API 请求

文档与架构

14. get_api_schema：获取可用 Fledge API 端点的信息
15. list_plugins：列出可用的 Fledge 插件

AI 辅助高级功能

16. generate_mock_data：生成逼真的模拟传感器数据用于测试

测试 API

你可以使用随附的测试脚本测试服务：

# For standard server
python test_mcp.py

# For secure server with API key
python test_secure_mcp.py

安全选项

安全服务（secure_mcp_server.py）增加了 API 密钥认证：

1. 首次运行时，会生成一个 API 密钥并存储在 api_key.txt 中
2. 所有请求都必须在 X-API-Key 请求头中包含此密钥
3. 健康检查端点仍可在未经身份验证的情况下访问

API 请求示例

# Validate API connection
curl -X POST -H "Content-Type: application/json" -d '{"name": "validate_api_connection"}' http://localhost:8082/tools

# Generate mock data
curl -X POST -H "Content-Type: application/json" -d '{"name": "generate_mock_data", "parameters": {"sensor_id": "temp1", "count": 5}}' http://localhost:8082/tools

# Generate React chart component
curl -X POST -H "Content-Type: application/json" -d '{"name": "generate_ui_component", "parameters": {"component_type": "chart", "sensor_id": "temp1"}}' http://localhost:8082/tools

# For secure server, add API key header
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: YOUR_API_KEY" -d '{"name": "list_sensors"}' http://localhost:8082/tools

扩展服务

如需添加更多工具：

1. 将工具定义添加到 tools.json
2. 在 mcp_server.py 和 secure_mcp_server.py 中实现工具处理程序

生产环境注意事项

生产环境部署时：

• 使用 HTTPS
• 部署在 Nginx 等反向代理之后
• 实施更可靠的身份验证（JWT、OAuth）
• 添加速率限制
• 为订阅设置持久化数据存储

在 Smithery.ai 上部署

Fledge MCP Server 可以部署在 Smithery.ai 上，以提升可扩展性和可用性。按照以下步骤进行部署：

1. 前提条件

   • 在本地计算机上安装 Docker
   • 拥有 Smithery.ai 账号
   • 安装 Smithery CLI 工具

2. 构建和部署

   # Build the Docker image
   docker build -t fledge-mcp .
   
   # Deploy to Smithery.ai
   smithery deploy
   

3. 配置 smithery.json 文件包含部署配置：

   • 在端口 8082 上使用 WebSocket 传输
   • 可配置的 Fledge API URL
   • 工具定义和参数
   • 超时设置

4. 环境变量 在 Smithery.ai 控制面板中设置以下环境变量：

   • FLEDGE_API_URL：你的 Fledge API 端点
   • API_KEY：你的安全 API 密钥（如果使用安全模式）

5. 验证 部署后，验证服务是否正在运行：

   smithery status fledge-mcp
   

6. 监控 通过 Smithery.ai 控制面板监控部署：

   • 实时日志
   • 性能指标
   • 错误跟踪
   • 资源使用情况

7. 更新 若要更新部署：

   # Build new image
   docker build -t fledge-mcp .
   
   # Deploy updates
   smithery deploy --update
   

JSON-RPC 协议支持

该服务通过 WebSocket 使用 JSON-RPC 2.0 实现 Model Context Protocol（MCP）。支持以下方法：

1. initialize

   {
       "jsonrpc": "2.0",
       "method": "initialize",
       "params": {},
       "id": "1"
   }
   

   响应：

   {
       "jsonrpc": "2.0",
       "result": {
           "serverInfo": {
               "name": "fledge-mcp",
               "version": "1.0.0",
               "description": "Fledge Model Context Protocol (MCP) Server",
               "vendor": "Fledge",
               "capabilities": {
                   "tools": true,
                   "streaming": true,
                   "authentication": "api_key"
               }
           },
           "configSchema": {
               "type": "object",
               "properties": {
                   "fledge_api_url": {
                       "type": "string",
                       "description": "Fledge API URL",
                       "default": "http://localhost:8081/fledge"
                   }
               }
           }
       },
       "id": "1"
   }
   

2. tools/list

   {
       "jsonrpc": "2.0",
       "method": "tools/list",
       "params": {},
       "id": "2"
   }
   

   响应：返回可用工具及其参数列表。

3. tools/call

   {
       "jsonrpc": "2.0",
       "method": "tools/call",
       "params": {
           "name": "get_sensor_data",
           "parameters": {
               "sensor_id": "temp1",
               "limit": 10
           }
       },
       "id": "3"
   }
   

错误代码

该服务遵循标准的 JSON-RPC 2.0 错误代码：

• -32700：解析错误
• -32600：无效请求
• -32601：未找到方法
• -32602：参数无效
• -32000：服务端错误