Fledge MCP Server

Fledge MCP 服务器

这是一个模型上下文协议 (MCP) 服务器，它将 Fledge 功能连接到 Cursor AI，允许 AI 通过自然语言命令与 Fledge 实例进行交互。

先决条件

• Fledge 本地安装或通过 API 访问（默认值： http://localhost:8081 ）
• 已安装光标 AI
• Python 3.8+

安装

1. 克隆此存储库：

2. 安装依赖项：

运行服务器

1. 确保 Fledge 正在运行：

2. 启动 MCP 服务器：

使用 API 密钥认证进行安全操作：

3. 通过访问健康端点来验证它是否正常工作：

您应该会收到“Fledge MCP 服务器正在运行”作为响应。

连接到光标

1. 在 Cursor 中，前往“设置”>“MCP 服务器”
2. 添加新服务器：
   • 网址： http://localhost:8082/tools
   • 工具文件：上传包含的 tools.json 或指向其本地路径
3. 对于安全服务器，使用安全服务器启动时生成的 api_key.txt 文件中的值配置“X-API-Key”标头。
4. 测试它：打开 Cursor 的 Composer（Ctrl+I），输入“检查 Fledge API 是否可访问”，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. 模拟前端请求：使用不同的方法和有效负载测试 API 请求

文档和架构

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

先进的人工智能辅助功能

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

测试 API

您可以使用附带的测试脚本测试服务器：

安全选项

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

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

API 请求示例

扩展服务器

要添加更多工具：

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

生产注意事项

对于生产部署：

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

在 Smithery.ai 上部署

Fledge MCP 服务器可以部署在 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 协议支持

服务端使用 JSON-RPC 2.0 通过 WebSocket 实现模型上下文协议 (MCP)。支持以下方法：

1. 初始化
   { "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. 工具/列表
   { "jsonrpc": "2.0", "method": "tools/list", "params": {}, "id": "2" }
   响应：返回可用工具及其参数的列表。
3. 工具/调用
   { "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：服务器错误