MAS-MCP市
NGSI-LD/SensorThings上可复制LLM试剂与MCP的协调
 
______________________________________________________________________
🌐 概述
MAS-MCP市 提供了FGCS论文中描述的多代理架构的完整、可重复的参考实现：
F. Maciá-Pérez， I. Lorenzo-Fonseca， A.马西亚·菲特尼， *MAS-MCP City-通过NGSI-LD/SensorThings与MCP进行可复制的LLM代理协调，以实现可追溯的SmartCampus室内空气质量和占用率分析*, *未来一代计算机系统*, 2025.
它集成了：
- 人类模型上下文协议（MCP） 使用官方Node SDK的代理和服务器
@modelcontextprotocol/sdk@^1.20.2 - NGSI-LD （上下文）和 OGC传感器 （时间序列）互操作性
- OPA政策 和 基于能力的授权
- 预算/费率限制 和 幂等驱动
- 开放遥测 通过Helm部署的收集器进行端到端跟踪和度量
所有源代码、Helm图表和夹具都是公开的，可以通过此存储库及其Zenodo版本进行复制。
______________________________________________________________________
🧱 存储库结构
MAS-MCP-City/
├── README.md ← this file
├── doc/ ← documentation (code ↔ paper, deployment, artifacts)
│ ├── mcp-to-paper.md
│ ├── deployment.md
│ ├── artifacts.md
│ └── LICENSE.md
├── mcp-servers/ ← three MCP microservices
│ ├── mcp-ngsi/ # NGSI-LD read tools
│ ├── mcp-sta/ # SensorThings read tools
│ └── actuation-mcp/ # Actuation tools (BMS, MQTT)
├── agents/ ← coordinating agents & client library
│ ├── mcp-client/ # generic MCP WebSocket client
│ ├── iaq-orchestrator/ # SmartCampus IAQ workflow
│ └── README.md # detailed agent layer doc + diagram
├── charts/ ← Helm charts for deployment
│ ├── platform/ # MCP servers + OPA + budgets + OTEL
│ ├── observability/ # OTEL collector + ServiceMonitor
│ └── agents/ # smoke test job
├── fixtures/ ← NGSI/STA sample data for reproducibility
└── .github/workflows/ ← CI (image build & Helm lint)______________________________________________________________________
🧩 关键组件
| 图层 | 描述 | 主要技术 |
|---|---|---|
| MCP服务器 | NGSI-LD、SensorThings和执行服务，包括OPA、预算和OTEL跨度(toolWithPolicyOtel) | 节点20，MCP SDK 1.20.2，OPA，Inn |
| 代理 | MCP客户端（IAQ编排器）使用类型化的MCP工具跨服务器进行协调 | 节点20，WS传输 |
| 可观测性 | OTEL收集器、普罗米修斯指标、Grafana/Jaeger仪表板 | OpenTetry、Helm |
| 部署 | Kubernetes/带有强化Pod和策略的Helm | Helm 3，K8s 1.25+ |
| 夹具 | 可再现的NGSI-LD和SensorThings数据 | JSON/JSON-LD |
| CI/CD | GitHub操作：容器构建+Helm lint | GHCR，操作 |
______________________________________________________________________
⚙️ 快速入门（本地）
# 1. Deploy collector
helm upgrade --install masmcp-obs charts/observability -n masmcp --create-namespace
# 2. Deploy servers (OPA + budgets + OTEL)
helm upgrade --install masmcp charts/platform -n masmcp -f charts/platform/values-dev.yaml
# 3. Run agent (IAQ orchestrator)
AUTH_TOKEN=dev-token \
NGSI_WS=ws://localhost:8001 \
STA_WS=ws://localhost:8002 \
ACT_WS=ws://localhost:8003 \
node agents/iaq-orchestrator/dist/cli.js预期输出（干运行驱动）：
{
"ok": true,
"action": "ventilation_boost",
"building": "urn:ngsi-ld:Building:ES-UA:A1",
"co2": 1120,
"ack": { "status": "accepted", "effect": "planned", "idempotency_key": "..." }
}______________________________________________________________________
📊 验证和再现性
- 踪迹： OTEL跨度显示为
mcp.tool.在耶格尔/Tempo。
- 韵律学：
/metrics端点导出
mcp_policy_allow_total, mcp_policy_deny_total, mcp_quota_exceeded_total.
- OPA政策： 可通过ConfigMap配置
masmcp-opa-policies.
- 复制的数字：
- 图5-6→ Helm/K8s拓扑 - 图7→ 数据和控制流（代理↔ 服务器） - 图8→ 跟踪链接的仪表板
详细的复制协议： doc/mcp-to-paper.md.
______________________________________________________________________
📚 文档地图
| 文件 | 目的 |
|---|---|
doc/mcp-to-paper.md | 代码↔ 纸质映射+复制协议 |
doc/deployment.md | Helm/Kubernetes部署指南 |
doc/artifacts.md | 已发布工件、夹具、图表列表 |
agents/README.md | 代理层的设计、使用和图表 |
README-v1.0.md | v1.0发行说明（FGCS提交） |
______________________________________________________________________
🔐 许可证
所有代码和数据均在下发布 知识共享署名-非商业4.0国际（CC BY-NC 4.0）. 经MAS-MCP City作者引用和确认后，允许重复使用。
______________________________________________________________________
🧾 引用
F. Maciá-Pérez， I. Lorenzo-Fonseca， A.马西亚·菲特尼， *MAS-MCP City-通过NGSI-LD/SensorThings与MCP进行可复制的LLM代理协调，以实现可追溯的SmartCampus室内空气质量和占用率分析*, *未来一代计算机系统*, 2025. DOI： 10.5281/芝诺岛175000006
______________________________________________________________________