Servidor MCP para Smart Cities

智慧城市 MCP 服务

此 MCP（Model Context Protocol）服务允许 AI 与智慧城市的 IoT 设备数据交互，包括公共照明、水表和燃气表。

注意：

• 此 MCP 服务目前仅支持通过 Stdio（标准输入/输出）连接。
• 已使用 Cursor 和 VSCode 中的 GitHub Copilot 作为 MCP 客户端进行测试和验证。

应用日志

MCP 服务的日志保存在项目的 logs 文件夹中的文件里（默认是 logs/server.log 和轮转文件）。

原因：

• 由于 MCP 客户端与 MCP 服务之间通过 Stdio（标准输入/输出）进行通信，任何在控制台输出的日志都可能干扰客户端与服务之间的消息交换。
• 因此，所有日志都会写入文件，以确保 MCP 通信正常运行。

若要查看日志，只需使用任何文本编辑器打开 logs 文件夹中的文件，或使用以下命令：

cat logs/server.log

文件会自动轮转，以避免文件过度增长。

📚 项目文档

本项目提供了结构化文档，满足不同需求和受众的需要。每个文件都有特定用途，旨在提高工作效率并便于理解项目。

🎯 文档概览

文件	目标受众	用途	阅读方式
.cursorrules	Cursor AI	自动上下文	自动
.github/copilot-instructions.md	GitHub Copilot	VSCode 指南	自动
.vscode/mcp.json	VSCode/Copilot	MCP 配置	手动/自动
QUICKSTART.md	所有人	快速设置	首次访问
docs/DEVELOPMENT.md	开发者	规范和架构	开发期间
docs/AI_CONTEXT.md	AI/Cursor	优化交互	自动查询
README.md	所有人	完整文档	参考

---

🤖 .cursorrules - AI 自动上下文

用途： Cursor 会自动读取此文件，以了解项目上下文，无需手动说明。

使用时机：

• ✅ 始终 - 打开项目时，Cursor 会自动读取
• ✅ 首次询问有关项目的问题时
• ✅ Cursor 需要了解特定规范时

使用方式：

• Cursor： 自动读取，并在整个会话期间保留上下文
• 开发者： 需要了解规范时手动查阅
• 新的 AI： 获取上下文时首先查阅的文件

内容：

• 项目结构和技术
• 代码规范（ID、时间戳、日志）
• 重要命令
• MCP 特定注意事项

使用示例：

Você: "Crie uma nova ferramenta MCP para monitorar tráfego"
Cursor: (lê .cursorrules) "Entendo que preciso seguir o padrão Zod, usar logs em arquivo, e registrar no server.ts..."

---

🆕 .github/copilot-instructions.md - GitHub Copilot 指南

用途： 面向 VSCode 中 GitHub Copilot 的专用指南文件，提供详细的项目上下文。

使用时机：

• 🎯 使用带 Copilot 的 VSCode - GitHub Copilot 会自动读取
• 🔧 在 VSCode 中开发 - 获取结合上下文的建议
• 📋 代码规范 - 自动遵循项目规范

使用方式：

• GitHub Copilot： 为智能建议提供自动上下文
• VSCode： 与开发环境原生集成
• 开发者： 查阅以了解特定规范

内容：

• Smart Cities 项目的完整上下文
• 特定开发规范
• 已实现的 MCP 工具结构
• 实现新功能的规范
• 验证和错误处理指南

使用示例：

Você: Começa a digitar uma nova função MCP no VSCode
Copilot: (lê .github/copilot-instructions.md) Sugere automaticamente padrão Zod, timestamps UNIX, logs em arquivo

---

🔧 .vscode/mcp.json - VSCode 的 MCP 配置

用途： VSCode 专用配置，用于连接 MCP 服务，并针对 GitHub Copilot 进行优化。

何时使用：

• 🖥️ VSCode - 自动配置 MCP
• 🤝 GitHub Copilot - 直接集成工具
• ⚙️ 开发 - 自动设置环境

使用方式：

• VSCode： 自动加载 MCP 配置
• GitHub Copilot： 直接访问服务端工具
• 开发者： 无需手动配置，简化设置流程

内容：

• MCP 服务的 stdio 配置
• 安全的环境变量（使用 inputs）
• 编译后服务的路径
• MongoDB 专用配置

使用示例：

1. Abrir projeto no VSCode
2. VSCode detecta .vscode/mcp.json automaticamente
3. Solicita credenciais do MongoDB (primeira vez)
4. Copilot tem acesso às 13 ferramentas MCP

---

⚡ QUICKSTART.md - 快速入门指南

用途： 无需阅读冗长文档，在不到 5 分钟内让项目运行起来。

何时使用：

• 🚀 首次访问项目时
• 🔧 遇到问题时——当某些功能无法正常运行
• 👥 演示时——快速设置并展示运行效果
• 🧪 测试时——更改后的快速验证
• 📅 日后——忘记如何运行时（6 个月后）

使用方式：

• 新开发者： 首个阅读的文件
• 你自己： 命令的快速参考
• 演示： 为客户或同事设置环境
• CI/CD： 自动化脚本的基础

内容：

• 完整设置的 3 个步骤
• 测试和验证命令
• 基本故障排除
• 可直接使用的提示词示例
• 参考 ID 和时间戳
• 新增： VSCode/Copilot 配置

使用示例：

Cenário: Novo membro da equipe
1. Lê QUICKSTART.md (3 min)
2. Executa 3 comandos
3. Configura VSCode/Copilot
4. Testa com prompts prontos
5. Projeto funcionando ✅

---

🏗️ docs/DEVELOPMENT.md - 开发指南

用途： 开发和维护所需的代码规范、架构和最佳实践。

何时使用：

• 🔨 积极开发时——编写或修改代码时
• 🏗️ 了解架构时——理解结构和设计模式
• ➕ 新增功能时——添加 MCP 工具
• 🐛 调试时——了解流程和日志
• 📖 代码审查时——检查是否符合规范

使用方式：

• 开发者： 编码过程中查阅
• 代码审查： 检查规范
• 重构： 维护一致性的指南
• 入职培训： 深入了解技术细节

内容：

• 项目架构详解
• 使用 Zod 的验证规范
• MCP 响应结构
• 分页约定
• 如何添加新工具
• 代码示例
• 新增： VSCode 和 Copilot 配置

使用示例：

Tarefa: Adicionar ferramenta de monitoramento de temperatura
1. Consulta DEVELOPMENT.md para padrões
2. Segue estrutura de validação Zod
3. Implementa paginação conforme exemplo
4. Registra no server.ts seguindo convenção
5. Testa com VSCode/Copilot

---

🧠 docs/AI_CONTEXT.md - AI 交互上下文

用途： 通过具体示例和已知限制，优化人类、AI 与 IoT 数据之间的交互。

何时使用：

• 💬 复杂提示词——高级数据查询
• 📊 分析——需要从数据中获取洞察时
• 🗺️ 地理查询——按地区查询数据
• ⏰ 时间数据——历史分析
• 🤔 了解功能——了解可以执行哪些操作

使用方式：

• Cursor： 自动查阅，以生成更有效的提示词
• GitHub Copilot： 为代码建议提供上下文
• 用户： 了解如何提问的示例
• 其他 AI： 了解数据结构的上下文
• 开发： 了解常见用例

内容：

• 有效的自然语言提示词示例
• 详细的数据结构
• 限制和性能注意事项
• 常见使用场景
• 预期的响应格式
• 改进交互的技巧
• 新增： VSCode/Copilot 专用示例

使用示例：

Você: "Quero analisar eficiência energética"
Cursor/Copilot: (consulta AI_CONTEXT.md) "Baseado nos exemplos, sugiro consultar consumo por período específico..."
Resultado: Prompt mais eficaz e dados mais relevantes

---

📖 README.md - 完整文档

用途： 项目的完整官方文档，是所有信息的主要参考资料。

使用场景：

• 📚 完整参考 - 所有工具的详细信息
• 🔍 特定内容搜索 - 参数和响应的详情
• 📋 官方文档 - 外部链接和参考资料
• 🎓 深入学习 - 全面了解项目
• 📝 第三方文档 - 官方材料

使用方式：

• 官方参考： 链接到外部文档
• 详细查询： QUICKSTART 无法满足需求时
• 集成： 提供给其他系统的信息
• 培训： 团队的完整材料

内容：

• MCP 工具的详细介绍
• 完整的使用示例
• 详细配置说明
• 新增： 与 VSCode/Copilot 集成
• 数据库结构
• 限制和注意事项

---

🎯 推荐使用流程

对于首次使用：

1. QUICKSTART.md → 快速设置和测试
2. 配置 VSCode → 自动配置 .vscode/mcp.json
3. README.md → 全面了解项目
4. docs/AI_CONTEXT.md → 使用示例

对于开发：

1. .cursorrules → 自动上下文（Cursor）
2. .github/copilot-instructions.md → 自动上下文（VSCode/Copilot）
3. docs/DEVELOPMENT.md → 规范和架构
4. README.md → API 参考

对于日常使用：

1. VSCode/Copilot → 与 MCP 自动集成
2. docs/AI_CONTEXT.md → 有效提示词
3. QUICKSTART.md → 快速命令
4. README.md → 具体详情

对于遇到问题：

1. QUICKSTART.md → 基础故障排查
2. docs/DEVELOPMENT.md → 高级调试
3. 日志 → logs/server.log
4. VSCode → 检查 MCP 配置

💡 提高效率的技巧

• Cursor 用户： .cursorrules 和 AI_CONTEXT.md 配合使用，可自动提供上下文
• VSCode 用户： .github/copilot-instructions.md 和 .vscode/mcp.json 提供完整集成
• 开发： DEVELOPMENT.md 可避免违反约定
• 演示： QUICKSTART.md + 自动配置 = 几分钟内完成设置
• 维护： 每个文件都有特定职责，便于更新

配置

选项 1：使用 GitHub Copilot 的 VSCode（推荐）

1. 安装依赖：

npm install

2. 在 VSCode 中打开项目：

code .

3. VSCode 将自动检测 .vscode/mcp.json 文件，并提示配置 MongoDB

4. 启动数据库：

cd db-init && docker-compose up --build -d

5. 编译并启动服务：

npm run build
npm start

选项 2：Cursor（传统方式）

1. 安装依赖：

npm install

2. 配置环境变量（可选）：

MONGO_URI=mongodb://cursor-mcp-client:cursor-mcp-password@localhost:27017/smart_city_iot

3. 启动服务：

npm start

可用工具

1. 列出照明设备

listLightingDevices({
    region?: string,    // Filtro opcional por região (nome ou busca geoespacial)
    status?: string,    // Filtro opcional por status
    geoJson?: boolean  // Se true, retorna FeatureCollection GeoJSON
})

• 返回公共照明设备列表。
• 如果提供了 region，则按地理位置邻近程度筛选（使用坐标和区域多边形）。
• 如果 geoJson=true，则以 GeoJSON（FeatureCollection）格式返回。

提示词示例：

• “列出东南部地区的所有照明设备”
• “以 GeoJSON 格式返回中西部附近的照明设备”
• “南部地区有哪些照明设备处于启用状态？”
• “给我一份东北部照明设备的 GeoJSON”

2. 查询照明遥测数据

getLightingTelemetry({
    deviceId: string,   // ID do dispositivo
    startTime: number,  // Timestamp inicial (UNIX)
    endTime: number     // Timestamp final (UNIX)
})

返回指定设备在一段时间内的遥测数据，包括：

• 温度
• 状态（开/关）
• 电流
• 电压
• 累积能耗
• 功率因数
• 照明级别
• 功耗
• 运行时长

3. 分析能耗

analyzeEnergyConsumption({
    deviceId: string,   // ID do dispositivo
    startTime: number,  // Timestamp inicial (UNIX)
    endTime: number     // Timestamp final (UNIX)
})

返回详细的能耗分析：

• 总能耗
• 平均功率
• 最大功率
• 最小功率

4. 检测漏水

detectWaterLeaks({
    startTime: number,  // Timestamp inicial (UNIX)
    endTime: number     // Timestamp final (UNIX)
})

返回指定时间段内检测到的所有漏水记录，包括：

• 设备 ID
• 位置
• 流量
• 压力
• 温度
• 用量

5. 分析燃气用量

analyzeGasConsumption({
    region: string,     // Nome da região
    startTime: number,  // Timestamp inicial (UNIX)
    endTime: number     // Timestamp final (UNIX)
})

返回按区域划分的燃气用量详细分析：

• 总用量
• 平均流量
• 检测到的漏水数量

🚀 高级工具（新增）

6. 区域对比统计

getRegionalStatistics({
    startTime: number,      // Timestamp inicial (UNIX)
    endTime: number,        // Timestamp final (UNIX)
    includeComparison?: boolean  // Se true, inclui comparações entre regiões
})

返回所有区域之间的详细对比统计：

• 各区域的能源、水和燃气用量
• 性能与效率指标
• 设备和漏水数量
• 在线时间与可靠性分析

7. 设备健康报告

getDeviceHealthReport({
    deviceType?: 'lighting' | 'water' | 'gas' | 'all',  // Tipo de dispositivo
    region?: string,        // Filtro por região
    healthThreshold?: number // Limiar de saúde (0-100)
})

返回设备“健康状况”的详细分析：

• 计算得出的健康评分（0-100）
• 按设备类型划分的具体指标
• 需要维护的设备
• 预计使用寿命

8. 城市完整仪表板

getCityDashboard({
    timeRange?: 'hour' | 'day' | 'week' | 'month',  // Período de análise
    includeAlerts?: boolean  // Se true, inclui alertas inteligentes
})

返回城市的完整概览：

• 所有系统的总体统计数据
• 用量与效率摘要
• 严重警报、警告和通知
• 智慧城市的主要 KPI

9. 维护预测

predictMaintenance({
    deviceType?: 'lighting' | 'water' | 'gas' | 'all',  // Tipo de dispositivo
    predictionDays?: number,    // Dias para predição (1-90)
    riskThreshold?: number      // Limiar de risco (0-100)
})

返回基于机器学习的预测：

• 有故障风险的设备
• 维护风险评分
• 预计故障前的天数
• 紧急维护与预防性维护

10. 异常检测

getAnomalyDetection({
    deviceType?: 'lighting' | 'water' | 'gas' | 'all',  // Tipo de dispositivo
    sensitivity?: 'low' | 'medium' | 'high',            // Sensibilidade
    timeRange?: 'hour' | 'day' | 'week'                 // Período de análise
})

返回智能异常检测结果：

• 基于统计偏差的异常
• 异常用量模式
• 可疑行为
• 按严重程度分类

11. 完整能源效率报告

getEnergyEfficiencyReport({
    startTime: number,      // Timestamp inicial (UNIX)
    endTime: number,        // Timestamp final (UNIX)
    includeRecommendations?: boolean,  // Se true, inclui recomendações
    region?: string         // Filtro por região
})

返回完整的能源效率分析：

• 各设备的效率评分
• 区域对比分析
• 表现最佳和最差的设备
• 优化建议
• 潜在节省量估算

12. 水质报告

getWaterQualityReport({
    startTime: number,      // Timestamp inicial (UNIX)
    endTime: number,        // Timestamp final (UNIX)
    region?: string,        // Filtro por região
    includeAlerts?: boolean // Se true, inclui alertas de segurança
})

返回详细的水质分析：

• 各设备的质量评分
• 压力、温度和流量指标
• 稳定性与可靠性
• 安全与质量警报
• 分类：优／良／差

13. 设备间关联分析

getCrossDeviceAnalysis({
    startTime: number,      // Timestamp inicial (UNIX)
    endTime: number,        // Timestamp final (UNIX)
    region?: string,        // Filtro por região
    analysisType?: 'consumption' | 'efficiency' | 'maintenance' | 'environmental'
})

返回不同类型设备之间的关联：

• 相关的用量模式
• 漏水对系统的影响
• 系统间的交叉效率
• 洞察与战略建议
• 时间和地理关联

使用示例

示例 1：能源效率分析

// Consultar consumo de energia de um poste
const consumo = await analyzeEnergyConsumption({
    deviceId: "LIGHT-000001",
    startTime: 1609459200,  // 01/01/2021
    endTime: 1640995200     // 01/01/2022
});

示例 2：漏水监控

// Detectar vazamentos de água
const vazamentos = await detectWaterLeaks({
    startTime: 1609459200,  // 01/01/2021
    endTime: 1640995200     // 01/01/2022
});

示例 3：区域分析

// Analisar consumo de gás por região
const consumoGas = await analyzeGasConsumption({
    region: "São Paulo",
    startTime: 1609459200,  // 01/01/2021
    endTime: 1640995200     // 01/01/2022
});

示例 4：城市仪表板

// No Cursor, você pode solicitar um dashboard completo:
"Gere um dashboard da cidade com alertas para o último dia"

// O Cursor irá gerar e executar o código:
const dashboard = await getCityDashboard({
    timeRange: "day",
    includeAlerts: true
});

示例 5：维护预测

// No Cursor, você pode solicitar predições:
"Quais dispositivos de água precisam de manutenção urgente?"

// O Cursor irá gerar e executar o código:
const predicao = await predictMaintenance({
    deviceType: "water",
    riskThreshold: 80
});

示例 6：异常检测

// No Cursor, você pode detectar comportamentos anômalos:
"Detecte anomalias na iluminação com alta sensibilidade na última semana"

// O Cursor irá gerar e executar o código:
const anomalias = await getAnomalyDetection({
    deviceType: "lighting",
    sensitivity: "high",
    timeRange: "week"
});

示例 7：能源效率报告

// No Cursor, você pode gerar relatórios completos:
"Gere um relatório de eficiência energética do último mês com recomendações"

// O Cursor irá gerar e executar o código:
const eficiencia = await getEnergyEfficiencyReport({
    startTime: Date.now()/1000 - (30 * 24 * 60 * 60),
    endTime: Date.now()/1000,
    includeRecommendations: true
});

示例 8：关联分析

// No Cursor, você pode analisar correlações:
"Analise a correlação entre consumo de energia e água na região Sudeste"

// O Cursor irá gerar e executar o código:
const correlacao = await getCrossDeviceAnalysis({
    startTime: Date.now()/1000 - (7 * 24 * 60 * 60),
    endTime: Date.now()/1000,
    region: "Sudeste",
    analysisType: "consumption"
});

数据库结构

服务连接到 MongoDB 数据库 smart_city_iot，其中包含以下集合：

设备

• lighting_devices：10.000 个照明设备
• water_devices：50.000 个水表
• gas_devices：50.000 个燃气表

遥测数据

• lighting_telemetry：照明数据
• water_telemetry：水数据
• gas_telemetry：燃气数据

优化索引

数据库针对常见查询进行了索引优化：

• lighting_telemetry：{ deviceId: 1, timestamp: 1 }
• water_telemetry：{ deviceId: 1, timestamp: 1 }
• gas_telemetry：{ deviceId: 1, timestamp: 1 }

安全性

• 使用专用用户进行 MongoDB 身份验证
• 仅允许读取操作
• 使用 Zod 验证输入
• 稳健的错误处理

限制

• 时间戳必须采用 UNIX 格式（自 1970 年以来的秒数）
• 查询仅限于特定时间段
• 对于较长时间段，某些分析可能需要大量计算资源

关于数据库的重要说明

服务器正常运行需要本地 MongoDB 实例中存在 smart_city_iot 数据库。

如何初始化数据库：

1. 打开终端并导航到 db-init 文件夹：

   cd db-init
   

2. 执行 docker-compose 以初始化 MongoDB 并填充示例数据：

   docker-compose up --build -d
   

   此命令将：

   • 初始化本地 MongoDB 实例
   • 自动向数据库填充示例数据
   • 配置访问凭据

备选方案：手动填充数据库

如果你已经有正在运行的 MongoDB 实例，可以使用以下脚本手动填充数据库：

node populate_mongodb.js

该脚本将在 smart_city_iot 数据库中创建并填充以下集合：

• lighting_devices：公共照明设备，每个设备包含 deviceId、latitude、longitude、status 等字段。
• water_devices：水表
• gas_devices：燃气表
• lighting_telemetry、water_telemetry、gas_telemetry：为每种设备类型模拟的遥测数据

注意：

• 执行脚本前，请确保 MongoDB 已在本地运行。
• 创建的数据仅供测试和开发使用。

与 IDE 集成

🆕 配置 VSCode 与 GitHub Copilot

VSCode 通过 .vscode/mcp.json 配置原生支持与 MCP 服务集成：

{
    "inputs": [
        {
            "type": "promptString",
            "id": "mongo-uri",
            "description": "MongoDB Connection URI",
            "default": "mongodb://cursor-mcp-client:cursor-mcp-password@localhost:27017/smart_city_iot?authSource=admin"
        }
    ],
    "servers": {
        "smart-city": {
            "type": "stdio",
            "command": "node",
            "args": [
                "~/Wesley/Github/mcp-server/dist/server.js"
            ],
            "env": {
                "MONGO_URI": "${input:mongo-uri}",
                "READ_ONLY": "false"
            }
        }
    }
}

VSCode 配置的优势：

• ✅ 安全：交互式请求凭据（不会将凭据硬编码）
• ✅ 自动化：VSCode 会自动检测并加载配置
• ✅ Copilot：GitHub Copilot 可直接访问 MCP 工具
• ✅ 安全输入：由 VSCode 管理环境变量

配置 Cursor（传统方式）

1. 使用以下配置设置 .cursor/mcp.json 文件：

{
    "mcpServers": {
        "smart-city": {
            "command": "node",
            "args": [
                "/CAMINHO/ABSOLUTO/PARA/dist/server.js"
            ],
            "env": {
                "MONGO_URI": "mongodb://cursor-mcp-client:cursor-mcp-password@localhost:27017/smart_city_iot?authSource=admin",
                "READ_ONLY": "false"
            }
        }
    }
}

重要：

• server.js 文件的路径必须为绝对路径（例如：/home/usuario/projeto/dist/server.js）。
• 如果使用 TypeScript，请先运行 npm run build，然后使用生成的 dist/server.js 文件（或根据你的构建输出配置使用相应文件）。

使用 VSCode/GitHub Copilot 的示例

示例 1：在 VSCode 中查询设备

// No VSCode com Copilot, você pode usar linguagem natural:
// Digite: "Liste dispositivos de iluminação no Sudeste"

// O Copilot sugere automaticamente:
const dispositivos = await listLightingDevices({
    region: "Sudeste",
    limit: 100
});
console.log(`Encontrados ${dispositivos.total} dispositivos`);

示例 2：使用 Copilot 自动分析

// Digite: "Analise energia do LIGHT-000001 último mês"

// Copilot gera código otimizado baseado nas instruções:
const endTime = Math.floor(Date.now() / 1000);
const startTime = endTime - (30 * 24 * 60 * 60); // 30 dias em segundos

const analise = await analyzeEnergyConsumption({
    deviceId: "LIGHT-000001",
    startTime,
    endTime
});

// Copilot também sugere tratamento de erros e formatação
if (analise.totalEnergy > 0) {
    console.log(`Consumo total: ${analise.totalEnergy.toFixed(2)} kWh`);
}

示例 3：智能仪表盘

// Digite: "Crie dashboard cidade com alertas hoje"

// Copilot gera solução completa:
const dashboard = await getCityDashboard({
    timeRange: "day",
    includeAlerts: true
});

// Copilot sugere análise dos alertas
const alertasCriticos = dashboard.alerts.critical.length;
if (alertasCriticos > 0) {
    console.log(`⚠️ ${alertasCriticos} alertas críticos detectados`);
    dashboard.alerts.critical.forEach(alert => {
        console.log(`- ${alert.type}: ${alert.message}`);
    });
}

使用 Cursor（传统方式）的示例

示例 1：查询设备

// No Cursor, você pode usar o prompt para consultar dispositivos:
"Liste todos os dispositivos de iluminação na região Sudeste"

// O Cursor irá gerar e executar o código:
const dispositivos = await listLightingDevices({
    region: "Sudeste"
});

示例 2：数据分析

// No Cursor, você pode solicitar análises específicas:
"Analise o consumo de energia do dispositivo LIGHT-000001 no último mês"

// O Cursor irá gerar e executar o código:
const consumo = await analyzeEnergyConsumption({
    deviceId: "LIGHT-000001",
    startTime: Date.now() - (30 * 24 * 60 * 60 * 1000),
    endTime: Date.now()
});

示例 3：泄漏监测

// No Cursor, você pode solicitar monitoramento:
"Verifique se há vazamentos de água nas últimas 24 horas"

// O Cursor irá gerar e executar o código:
const vazamentos = await detectWaterLeaks({
    startTime: Date.now() - (24 * 60 * 60 * 1000),
    endTime: Date.now()
});

MCP 工具的结果分页

此 MCP 服务中的某些工具可能会返回大量数据。为避免超时并提升性能，以下工具已实现分页：

• listLightingDevices
• getLightingTelemetry
• detectWaterLeaks

如何使用分页

这些工具接受以下可选参数：

• limit（数字）：每次请求返回的最大记录数。默认值：100。
• offset（数字）：开始返回结果前跳过的记录数。默认值：0。

调用示例

{
  "limit": 100,
  "offset": 200
}

分页响应格式

这些工具的响应将是一个 JSON 对象，包含：

• 请求的数据（例如：devices、telemetry、leaks）
• total：查询可用的记录总数
• offset：查询使用的偏移量
• limit：查询使用的限制值
• hasNext：布尔值，表示是否还有后续数据页

响应示例

{
  "devices": [ ... ],
  "total": 60819,
  "offset": 200,
  "limit": 100,
  "hasNext": true
}

说明： 如果在 listLightingDevices 中使用 geoJson 参数，响应将是一个 GeoJSON 对象，并包含额外的 pagination 字段，其中包含上述元数据。

建议

• 如需获取所有数据，请发送多次请求，并根据 limit 递增 offset，直到 hasNext 为 false。
• 请勿使用过高的 limit 值，以免服务器过载。

使用技巧

1. 使用自然语言描述你的需求
2. Cursor 会理解上下文并生成合适的代码
3. 你可以在单个请求中组合多个查询
4. Cursor 会保留查询历史，供日后参考

高级功能

• 趋势分析：“显示南部地区的燃气消耗趋势”
• 比较：“比较两台设备的能耗”
• 警报：“设置漏水警报”
• 报告：“生成能源效率报告”

与其他 MCP 客户端配合使用及身份验证

如果需要使用其他 MCP 客户端（Cursor 以外的客户端）或与外部应用程序集成，可能需要启用 HTTP 传输和基于令牌的身份验证（最好使用 OAuth 2.1）。

如何启用 HTTP 和身份验证

1. 添加 HTTP 传输：

   • 在 src/server.ts 文件中，创建 MCP 服务（const server = new McpServer(...)）后，添加 HTTP 传输的导入和初始化代码，例如：

     import { HttpServerTransport } from "@modelcontextprotocol/sdk/server/http.js";
     // ...
     const httpTransport = new HttpServerTransport({ port: 3000 });
     await server.connect(httpTransport);
     

   • 这样服务器便可在指定端口接受 HTTP 连接。

2. 添加基于令牌的身份验证（OAuth 2.1）：

   • 在 HTTP 传输的初始化位置实现身份验证中间件。
   • 有关集成详情，请参阅 MCP SDK 和你的 OAuth 提供商的文档。
   • 可添加到以下位置：

     // 创建 httpTransport 后，在接受请求前添加身份验证逻辑
     //（有关钩子或中间件的详情，请参阅 SDK 文档）
     

重要：

• 本项目默认未启用 HTTP 和身份验证支持。
• 在生产环境中，实施安全的身份验证至关重要。