FIWARE MCP 服务器

这是一个 FIWARE 模型上下文协议（MCP）服务器的首次实现，它提供了一个连接上下文代理和其他服务之间的桥梁。该服务器实现了与 FIWARE 上下文代理交互的基本操作。

目标

• 创建一个基本的 FIWARE MCP 服务器实现
• 提供简单的工具以与上下文代理进行交互
• 展示与上下文代理的基本意图 CRUD 操作
• 作为更复杂 MCP 实现的基础

特性

• 上下文代理版本检查
• 查询上下文代理的能力
• 实体发布和更新

预备条件

• Python 3.7 或更高版本
• pip（Python 包管理器）
• 访问 FIWARE 上下文代理实例

安装

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 响应 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

注意：确保您的认证令牌安全。只要 ngrok 正在运行，公共 URL 就会保持活动状态，并且当您停止隧道时将无法再访问。

可用工具

1. CB_version

   • 检查上下文代理的版本
   • 默认参数：address="localhost", port=1026
   • 返回：包含版本信息的 JSON 字符串

2. query_CB

   • 查询上下文代理
   • 参数：
     • address（默认："localhost"）
     • port（默认：1026）
     • query（默认：""）
   • 返回：包含查询结果的 JSON 字符串

3. publish_to_CB

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

示例用法

# 示例实体数据
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"
}

# 发布到上下文代理
result = publish_to_CB(entity_data=entity_data)

配置

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

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

错误处理

服务器包括全面的错误处理机制，用于：

• 网络连接问题
• 上下文代理返回的无效响应
• 格式不正确的实体数据
• 服务器关闭

贡献

欢迎提交问题和增强请求！

许可证

本项目根据 Apache 许可证 2.0 授权。