FIWARE MCP Server

FIWARE MCP Server

这是 FIWARE Model Context Protocol（MCP）Server 的首个实现，可在 Context Broker 与其他服务之间提供桥接。该服务实现了与 FIWARE Context Broker 交互的基本操作。

目标

• 为 FIWARE 创建基本的 MCP 服务实现
• 提供与 Context Broker 交互的简单工具
• 演示与 Context Broker 进行基本的意图 CRUD 操作
• 为更复杂的 MCP 实现奠定基础

功能

• 检查 Context Broker 版本
• 查询 Context Broker 的能力
• 发布和更新实体

前提条件

• Python 3.7 或更高版本
• pip（Python 包安装程序）
• 可访问 FIWARE Context Broker 实例

安装

1. 克隆此仓库：

git clone <repository-url>
cd FIWARE_MCP_01

2. 安装所需的依赖项：

pip install -r requirements.txt

Claude Desktop 集成

Claude Desktop 应通过 STDIO 启动该服务。请勿将“mcp install”或“mcp run”与此服务搭配使用。

配置示例（请根据你的环境调整路径）：

{
  "mcpServers": {
    "CB-assistant": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "requests>=2.31.0",
        "--with",
        "fastmcp>=0.3.0",
        "python",
        "PATH\\TO\\FIWARE-MCP-Server\\server.py"
      ]
    }
  }
}

如果使用 pip 安装依赖项，也可以采用以下配置：

{
  "mcpServers": {
    "CB-assistant": {
      "command": "python",
      "args": [
        "PATH\\TO\\FIWARE-MCP-Server\\server.py"
      ]
    }
  }
}

使用方法

默认情况下，运行脚本会以 STDIO 模式启动服务。使用 --http 可启动 HTTP 服务。

• STDIO（默认）：

python server.py

• HTTP 模式：

python server.py --http

• HTTP 主机/端口（可选）：

python server.py --http --host 127.0.0.1 --port 5001

使用 --http 运行时，服务会绑定到指定的主机/端口，并使用无状态 HTTP 会话，以兼容可流式 HTTP 客户端。

使用 ngrok 转发（HTTP 模式）

要通过外部 API（例如 OpenAI Responses API）使用大模型，你可能需要将本地 MCP 服务公开到互联网。在 HTTP 模式下运行时，可使用 ngrok 创建到该服务的公共 HTTPS 隧道。

1. 在 https://ngrok.com 注册，并为你的操作系统安装 ngrok 客户端。
2. 将 ngrok 身份验证令牌添加到客户端（按照适用于你操作系统的 ngrok 设置说明操作）。例如：
   • ngrok（v3）配置命令：ngrok config add-authtoken <YOUR_AUTH_TOKEN>
3. 以 HTTP 模式启动 MCP 服务（如果尚未运行）。示例：
   • python server.py --http --host 127.0.0.1 --port 5001
4. 启动 ngrok 隧道，将流量转发到你的 HTTP 服务：
   • ngrok http http://127.0.0.1:5001 （如果配置了不同的主机/端口，请替换为相应值）
5. ngrok 启动后会显示一个或多个公共转发 URL。MCP 端点可通过以下地址访问：
   • {PUBLIC_URL}/mcp

注意：请妥善保管你的身份验证令牌。公共 URL 在 ngrok 运行期间保持有效，停止隧道后将无法访问。

可用工具

1. CB_version

   • 检查 Context Broker 的版本
   • 默认参数：address="localhost"，port=1026
   • 返回：包含版本信息的 JSON 字符串

2. query_CB

   • 查询 Context Broker
   • 参数：
     • address（默认值："localhost"）
     • port（默认值：1026）
     • query（默认值：""）
   • 返回：包含查询结果的 JSON 字符串

3. publish_to_CB

   • 在 Context Broker 中发布或更新实体
   • 参数：
     • address（默认值："localhost"）
     • port（默认值：1026）
     • entity_data（必需：包含实体信息的字典）
   • 返回：包含操作状态的 JSON 字符串

使用示例

# Example entity data
entity_data = {
    "id": "urn:ngsi-ld:TemperatureSensor:001",
    "type": "TemperatureSensor",
    "temperature": {
        "type": "Property",
        "value": 25.5
    },
    "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld"
}

# Publish to Context Broker
result = publish_to_CB(entity_data=entity_data)

配置

可以通过修改 server.py 中的以下参数来配置服务：

• 主机地址（仅 HTTP 模式）
• 端口号（仅 HTTP 模式）
• 超时设置

错误处理

服务包含完善的错误处理机制，可处理以下情况：

• 网络连接问题
• Context Broker 返回无效响应
• 实体数据格式错误
• 服务关闭

贡献

欢迎提交问题和功能改进请求！

许可证

本项目采用 Apache License 2.0 许可。