智能数据模型MCP服务器

模型上下文协议（MCP）服务器，为AI代理提供对FIWARE智能数据模型的访问，实现与符合NGSI-LD标准的物联网平台的无缝集成。

______________________________________________________________________

概述

此MCP服务器允许AI代理：

发现 15个以上领域（智慧城市、能源、农业等）的现有智能数据模型
搜索按名称、属性或关键字列出的模型
生成从任意JSON数据中提取符合NGSI-LD标准的实体
验证数据与智能数据模型模式
访问模型模式、示例和JSON-LD上下文
探索集成规划的领域和模型

______________________________________________________________________

了解智能数据模型组织：

上图说明了智能数据模型的层次结构：

领域：智慧城市、能源或农业等高端行业。
科目：某一领域内的特定类别（例如，水、流动性）。
模型：定义特定实体的单个数据模型。
属性：构成每个模型的属性和关系。

每个级别都托管在自己的GitHub存储库中，确保了模块化和可扩展的架构。

特性

🔍 发现和搜索

浏览所有可用域（智慧城市、能源、物流等）
列出特定域中的模型
跨域按名称、属性或关键字搜索模型
获取详细的模型信息，包括模式和示例

⚡ NGSI-LD一代

将任意JSON数据转换为符合NGSI-LD标准的实体
从数据结构自动推断实体类型
智能财产类型检测（财产、地理财产、关系）
地理数据识别和GeoJSON生成

✅ 验证

根据智能数据模型模式验证数据
使用用户友好的消息进行全面的错误报告
NGSI-LD实体结构验证
数据模型兼容性分析

📊 资源

服务器说明: sdm://instructions -获取MCP服务器说明和功能
直接访问JSON模式： sdm://domain/model/schema.json
模型示例： sdm://domain/model/examples.json
域上下文： sdm://domain/context.jsonld

______________________________________________________________________

安装

先决条件

Python 3.9或更高版本
UV包管理器（从安装https://github.com/astral-sh/uv) 或 pip（Python包管理器）

从源头安装（UV-推荐）

git clone https://github.com/agaldemas/smartdatamodels-mcp
cd smart-data-models-mcp
uv sync

从源代码安装（pip替代）

git clone https://github.com/agaldemas/smartdatamodels-mcp
cd smart-data-models-mcp
pip install -e .

______________________________________________________________________

安装2

从TestPyPI安装（当前版本：0.1.1）

pip install --index-url https://test.pypi.org/simple/ smart-data-models-mcp

uv tool install --index-url https://test.pypi.org/simple/ smart-data-models-mcp

Testpypi URL： https://test.pypi.org/project/smart-data-models-mcp/0.1.1/

从PyPI安装（发布时）

从pypi安装

pip install smart-data-models-mcp

uv tool install smart-data-models-mcp

注：对于使用pip安装PyPI，请使用 `pip install smart-data-models-mcp` （发布时）。

Github配置

为了获得最佳性能并避免速率限制，您可以配置GitHub个人访问令牌：

创建GitHub令牌：

- 转到GitHub设置→ 开发者设置→ 个人访问令牌→ 代币（经典） - 点击“生成新令牌（经典）” - 选择最小作用域（访问公共存储库不需要作用域） - 复制生成的令牌

配置环境变量：

- 创建一个 .env 项目目录中的文件 - 添加以下行：

   GITHUB_READ_TOKEN=ghp_your_token_here

备选方案：设置系统环境变量：

   export GITHUB_READ_TOKEN=ghp_your_token_here

服务器自动从以下位置加载令牌 `.env` 文件或环境变量，并将其用于GitHub API请求。如果没有提供令牌，请求将正常工作，但可能会受到速率限制。

日志记录配置

服务器会写入详细的日志以帮助进行故障排除和监控。日志文件会在项目的 logs/ 目录：

logs/
└── smart-data-models.log

日志配置：

地点： logs/smart-data-models.log （相对于项目根）
格式：时间戳-记录器名称-级别-消息
轮换：10MB文件大小，5个备份
级别：调试（文件）、信息（控制台）

您可以查看日志以获取以下详细信息：

API对GitHub的请求
Pysmartdatamodels操作
缓存行为
错误情况和故障排除详细信息

______________________________________________________________________

服务器启动命令

在特定端口上启动服务器（SSE模式）

要在特定端口上以SSE模式运行服务器，请使用以下命令：

# Using UV (recommended)
uv run python src/smart_data_models_mcp/server.py --transport sse --port 3200

# Using pip
python src/smart_data_models_mcp/server.py --transport sse --port 3200

在特定端口上启动服务器（HTTP流模式）

要在特定端口上以HTTP流模式运行服务器，请使用以下命令：

# Using UV (recommended)
uv run python src/smart_data_models_mcp/server.py --transport http --port 3210

# Using pip
python src/smart_data_models_mcp/server.py --transport http --port 3210

可用的命令行选项：

--transport：运输方式(stdio, sse，或 http，默认值： stdio)
--port：HTTP/SSE模式的端口号（默认值：SSE为3200，HTTP为3210）
--host：主机地址（默认值： 127.0.0.1)
--help：显示帮助消息

示例：

cd ~/Documents/mcp/smartdatamodels-mcp
# Run in stdio mode (default)
uv run python src/smart_data_models_mcp/server.py

# Run in SSE mode on port 3200
uv run python src/smart_data_models_mcp/server.py --transport sse --port 3200

# Run in HTTP streamable mode on port 3210
uv run python src/smart_data_models_mcp/server.py --transport http --port 3210

# Run in SSE mode on different host and port
uv run python src/smart_data_models_mcp/server.py --transport sse --host 0.0.0.0 --port 8080

# Show help
uv run python src/smart_data_models_mcp/server.py --help

______________________________________________________________________

MCP服务器配置

Smart Data Models MCP服务器支持两种传输模式：

标准：标准输入/输出模式（默认）-建议用于大多数用例
SSE：服务器发送事件模式-用于基于web的集成和自定义设置

STDIO模式（默认）

stdio模式是运行MCP服务器的标准方式，建议用于大多数AI助手集成。

临床MCP服务器配置

要配置与Cline一起使用的智能数据模型mcp服务器，请将以下内容添加到Cline mcp设置文件中：

地点： ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

{
  "mcpServers": {
    "smart-data-models": {
      "autoApprove": [
      ],
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "python3",
      "args": [
        "src/smart_data_models_mcp/server.py"
      ],
      "cwd": "/Users/alaingaldemas/Documents/mcp/smartdatamodels-mcp/src"
    }
  }
}

______________________________________________________________________

HTTP流模式

{
  "mcpServers": {
    "smart-data-models-http": {
      "autoApprove": [],
      "disabled": false,
      "type": "streamableHttp",
      "timeout": 180,
      "url": "http://127.0.0.1:3210/mcp"
    }
  }
}

______________________________________________________________________

Claude桌面配置

如果您更喜欢将服务器与Claude Desktop一起使用，请将以下内容添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "smart-data-models": {
      "command": "python",
      "args": ["src/smart_data_models_mcp/server.py"],
      "cwd": "
//smartdatamodels-mcp",
      "env": {}
    }
  }
}

注意：此配置仍有待验证

SSE模式配置

对于基于web的集成或需要将服务器作为web服务运行时，可以使用SSE（服务器发送事件）传输模式。将以下配置添加到MCP设置中：

{
  "mcpServers": {
    "smart-data-models": {
      "disabled": false,
      "timeout": 180,
      "type": "sse",
      "url": "http://127.0.0.1:3200/sse"
    }
  }
}

注：增加的超时时间（180秒）是专门为 search_data_models 该工具可能需要时间来检查智能数据模型存储库以找到匹配的模型。

本地n8n使用配置

此mcp服务器还可以通过mcp客户端节点与n8n一起使用端点应该是：

http://localhost:3200/sse

http://host.docker.internal:3200/sse 如果n8n在docker下

选择 sse作为服务器传输

______________________________________________________________________

安装步骤

   cd 
/p/smart-data-models-mcp

在开发模式下安装：

   uv sync

配置MCP服务器：

- 打开Cline MCP设置文件： ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json - 添加智能数据模型服务器配置 - 重新启动Cline以加载新服务器

测试配置：

- 问Cline：“智能数据模型中有哪些领域？” - 如果它显示域信息，则服务器工作正常

______________________________________________________________________

用法

基本命令

配置后，重新启动Claude Desktop以加载MCP服务器。然后，您可以要求克劳德：

发现模型

"Show me all available domains in Smart Data Models"
"What models are available in the Smart Cities domain?"
"Find data models related to weather or climate"

获取模型详细信息

"Get detailed information about the WeatherObserved model"
"Show me the schema for a Building model"
"What are some examples of a Device model?"

生成NGSI-LD实体

"Convert this JSON data to NGSI-LD format: {...}"
"Create an NGSI-LD entity for a weather sensor"
"Generate a Building entity from this data: {...}"

验证数据

"Validate this data against the WeatherObserved model"
"Is this JSON valid for a Device entity?"
"Check if my data matches the Building schema"

______________________________________________________________________

交互示例

1.领域探索

用户： “智能数据模型中有哪些可用域？”

克劳德： 显示可用域，并提供交互式选项来探索每个域中的模型。

2.模型发现

用户： “查找与天气相关的数据模型”

克劳德： 跨域搜索并返回WeatherObserved、WeatherForecast和其他带有描述的天气模型。

3.数据生成

用户： “将此传感器数据转换为NGSI-LD：”

{
  "temperature": 25.5,
  "humidity": 60,
  "location": [-122.4194, 37.7749],
  "timestamp": "2025-01-15T10:30:00Z"
}

克劳德： 生成具有适当属性类型的格式正确的NGSI-LD实体。

4.验证

用户： “根据智能数据模型验证此建筑数据”

克劳德： 检查数据结构，并提供详细的验证结果和修复建议。

支持的域名

智慧城市
农业食品
水
能量
物流
机器人学
传感器
跨部门
健康
目的地
环境
航空学
制造
孵化
协调

MCP工具

list_domains

列出所有可用的智能数据模型域。

退货： 包含可用域和计数的JSON字符串

list_subjects

列出所有可用的智能数据模型主题。

退货： 包含可用主题和计数的JSON字符串

list_domain_subjects

列出属于特定领域的所有主题。

参数：

domain：获取主题的域名

退货： 包含域中主题和计数的JSON字符串

list_models_in_subject

列出特定主题中的所有数据模型。

参数：

subject：主题的名称（例如，“dataModel.SmartCities”、“dataModel.Energy”）

退货： 主题和计数中包含模型的JSON字符串

search_data_models

按名称、属性或关键字跨主题搜索数据模型。

参数：

query：搜索查询（型号名称、属性或关键字）
domain：可选域筛选器（例如“智慧城市”）
subject：可选主题过滤器（例如“dataModel.User”）
include_attributes：是否在结果中包含属性详细信息

退货： 包含搜索结果、计数和查询信息的JSON字符串

get_model_details

获取特定数据模型的详细信息。

参数：

model：模型的名称
subject：可选主题名称（例如，“dataModel.User”）

退货： JSON字符串，包含模型详细信息，包括模式、示例和元数据

validate_against_model

根据智能数据模型架构验证数据。

参数：

model：模型的名称
data：要验证的数据（可以是JSON字符串或字典）
subject：可选主题名称（例如，“dataModel.User”）

退货： 带有验证结果的JSON字符串（目前总是返回成功）

generate_ngsi-ld_from_json

从任意JSON数据生成符合NGSI-LD的实体。

参数：

data：输入数据（可以是JSON字符串或字典）
entity_type：可选NGSI-LD实体类型
entity_id：可选NGSI-LD实体ID
context：NGSI-LD实体的可选上下文URL

退货： 带有生成的NGSI-LD实体的JSON字符串

建议_匹配_模型

建议与提供的数据结构匹配的智能数据模型。

参数：

data：要分析的数据（可以是JSON字符串或字典）

退货： 带有建议模型和相似性分数的JSON字符串

MCP资源

sdm://instructions

获取此MCP服务器说明和功能。

退货： MCP服务器说明为纯文本，包含有关使用FIWARE智能数据模型的所有可用工具和资源的详细信息。

sdm://{subject}/{model}/schema.json

获取特定智能数据模型的JSON模式。

参数：

subject：主题（必须以“dataModel”开头。）
model：型号名称

退货： JSON模式为字符串

sdm://{subject}/{model}/example.json

获取特定智能数据模型的示例实例。

参数：

subject：主题（必须以“dataModel”开头。）
model：型号名称

退货： JSON字符串示例

sdm://{subject}/context.jsonld

获取主题的JSON-LD上下文。

参数：

subject：主题（必须以“dataModel”开头。）

退货： JSON-LD上下文为字符串

技术细节

数据源

pysmartdata模型：智能数据模型的官方Python包
GitHub API：直接访问模型存储库
回退机制：可靠性的多个数据源

缓存

域名/型号列表的30分钟TTL
内存模式和示例缓存
自动缓存失效

错误处理

服务不可用时性能下降
为开发人员和AI代理提供清晰的错误消息
验证错误格式化，以获得更好的用户体验

演出

并发操作的异步/等待模式
高效缓存减少了API调用
大型数据集的流式响应

发展

设置开发环境

# Clone and install in development mode (UV)
git clone https://github.com/agaldemas/smartdatamodels-mcp
cd smart-data-models-mcp
uv sync --dev

# OR: Clone and install in development mode (pip alternative)
git clone https://github.com/agaldemas/smartdatamodels-mcp
cd smart-data-models-mcp
pip install -e .[test]

# Alternative: Install with all development tools (pip)
pip install -e .[test,dev]  # Assuming equivalent optional dependencies are configured

开发命令（UV）：

# Run tests
uv run pytest

# Run with debugging (stdio mode)
uv run python src/smart_data_models_mcp/server.py --transport stdio

# Run with debugging (SSE mode)
uv run python src/smart_data_models_mcp/server.py --transport sse --port 3200

开发命令（pip替代）：

# Activate virtual environment (if using venv)
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Run tests
pytest

# Run with debugging (stdio mode)
python src/smart_data_models_mcp/server.py --transport stdio

# Run with debugging (SSE mode)
python src/smart_data_models_mcp/server.py --transport sse --port 3200

建筑

smart_data_models_mcp/
├── server.py           # FastMCP server and tool definitions
├── data_access.py      # Smart Data Models API integration
├── model_generator.py  # NGSI-LD generation logic
├── model_validator.py  # Schema validation logic
└── __init__.py

测试

该项目包括一个全面的测试套件，以确保所有功能正常工作。测试位于 tests/ 目录，并包括集成测试和API验证。

运行测试

紫外线测试（推荐）：

# Install test dependencies
uv sync --dev

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=smart_data_models_mcp --cov-report=html

# Run specific test files
uv run pytest tests/test_mcp.py          # MCP server tools and resources tests
uv run pytest tests/test_data_access.py  # Integration tests for data access layer

# Run tests with verbose output
uv run pytest -v tests/

使用pip进行测试（替代方案）：

# Install test dependencies
pip install -e .[test]

# Run all tests
pytest

# Run with coverage (requires pytest-cov)
pytest --cov=smart_data_models_mcp --cov-report=html

# Run specific test files
pytest tests/test_mcp.py          # MCP server tools and resources tests
pytest tests/test_data_access.py  # Integration tests for data access layer

# Run tests with verbose output
pytest -v tests/

测试文件

tests/test_mcp.py：MCP服务器工具和资源的全面测试

- 测试所有9个MCP工具（list_domains、list_subjects、search_data_models等） - 测试所有4个MCP资源（指令、模式、示例、上下文） - 测试错误处理和边缘情况 - 验证JSON响应格式和API集成 - 测试成功操作和失败场景

tests/test_data_access.py：数据访问层的集成测试

- 测试SmartDataModelsAPI类功能 - 使用GitHub API集成测试域和主题列表 - 测试模型发现、细节检索和缓存 - 测试模式、示例和上下文获取 - 使用多种策略测试搜索功能 - 验证API响应、错误处理和性能

tests/test_suggest_matching_models.py：模型建议功能的专门测试

- 测试相似性评分和属性匹配 - 测试MCP服务器集成以获得模型建议 - 验证建议排名和响应结构 - 测试边缘情况和错误处理

手动测试

您可以运行其他集成测试来验证您的设置。所有测试都旨在通过pytest运行时正确导入项目模块。

测试套件的预期输出应显示所有通过覆盖率报告和API验证的测试。

贡献

分叉存储库
创建要素分支
通过测试实现您的更改
确保所有测试通过
提交拉取请求

开发指南

遵循PEP 8风格指南
为新函数添加类型提示
包含全面的文档字符串
编写新功能的单元测试
更新API变更文档

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

链接

故障排除

常见问题

服务器未启动

检查Python版本（需要3.9+）
验证是否安装了依赖项
检查克劳德桌面日志

未找到模型

验证域名和型号名称是否正确
检查GitHub API的互联网连接
尝试重新启动Claude Desktop

验证错误

确保数据是有效的JSON
检查架构兼容性
查看特定问题的错误消息

获取帮助

检查问题页
查看文档
联系FIWARE社区

______________________________________________________________________

*建于❤️ FIWARE生态系统和AI代理集成。*

🤖 AI贡献者

特别感谢我们的AI合作伙伴：

克莱恩：用于代码开发、项目结构和自动化测试的AI助手（AlaingClineBot）

______________________________________________________________________

Smartdatamodels MCP

快速接入

详细介绍

智能数据模型MCP服务器

模型上下文协议（MCP）服务器，为AI代理提供对FIWARE智能数据模型的访问，实现与符合NGSI-LD标准的物联网平台的无缝集成。

概述

了解智能数据模型组织：

每个级别都托管在自己的GitHub存储库中，确保了模块化和可扩展的架构。

特性

🔍 发现和搜索

⚡ NGSI-LD一代

✅ 验证

📊 资源

安装

先决条件

从源头安装（UV-推荐）

从源代码安装（pip替代）

安装2

从TestPyPI安装（当前版本：0.1.1）

从PyPI安装（发布时）

从pypi安装

注： 对于使用pip安装PyPI，请使用 pip install smart-data-models-mcp （发布时）。

Github配置

服务器自动从以下位置加载令牌 .env 文件或环境变量，并将其用于GitHub API请求。如果没有提供令牌，请求将正常工作，但可能会受到速率限制。

日志记录配置

服务器启动命令

在特定端口上启动服务器（SSE模式）

在特定端口上启动服务器（HTTP流模式）

MCP服务器配置

STDIO模式（默认）

临床MCP服务器配置

HTTP流模式

Claude桌面配置

注意：此配置仍有待验证

SSE模式配置

本地n8n使用配置

安装步骤

用法

基本命令

发现模型

获取模型详细信息

生成NGSI-LD实体

验证数据

交互示例

1.领域探索

2.模型发现

3.数据生成

4.验证

支持的域名

MCP工具

list_domains

list_subjects

list_domain_subjects

list_models_in_subject

search_data_models

get_model_details

validate_against_model

generate_ngsi-ld_from_json

建议_匹配_模型

MCP资源

sdm://instructions

sdm://{subject}/{model}/schema.json

sdm://{subject}/{model}/example.json

sdm://{subject}/context.jsonld

技术细节

数据源

缓存

错误处理

演出

发展

设置开发环境

建筑

测试

运行测试

测试文件

手动测试

贡献

开发指南

许可证

链接

注：对于使用pip安装PyPI，请使用 `pip install smart-data-models-mcp` （发布时）。

服务器自动从以下位置加载令牌 `.env` 文件或环境变量，并将其用于GitHub API请求。如果没有提供令牌，请求将正常工作，但可能会受到速率限制。