MCP 指南deprecated

MCP 历史集成草案（未公开）

保留的 MCP 集成架构草案，不代表 RailWise 已对外提供 AI 平台接入、工具调用或数据服务。

复核 2026-07-20入门不进入公开索引RailWise 技术团队

MCP 指南

RailWise MCP Server 集成指南

概述

RailWise MCP Server 是基于 Model Context Protocol（MCP） 标准构建的服务器，为 Cursor、Claude Desktop、Windsurf 等主流 AI 开发平台提供工程测量与安全监测领域的专业工具和资源访问能力。通过 MCP Server，AI 助手可以直接调用 RailWise 的监测数据、分析工具和报告生成功能，实现自然语言驱动的工程监测工作流。

支持的AI平台

AI平台	支持状态	配置方式
Cursor	✅ 已支持	`~/.cursor/mcp.json`
Claude Desktop	✅ 已支持	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windsurf	✅ 已支持	`~/.codeium/windsurf/mcp_config.json`
VS Code + Copilot	🔄 开发中	扩展插件
JetBrains	📋 规划中	插件市场

版本信息

项目	版本
RailWise MCP Server	1.0.0
MCP协议版本	2024-11-05
支持工具数	15+
支持资源类型	8+

什么是MCP

Model Context Protocol（MCP） 是 Anthropic 推出的开放协议，用于标准化 AI 助手与外部工具、数据源之间的通信。MCP 采用客户端-服务器架构：

┌─────────────────────────────────────────────────────────────┐
│                    MCP 架构                                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐         STDIO / SSE         ┌────────────┐│
│  │   AI 客户端   │  ◄─────────────────────►  │ MCP Server ││
│  │  (Cursor/    │      JSON-RPC 2.0         │ (RailWise) ││
│  │   Claude/    │                           │            ││
│  │   Windsurf)  │                           │ - Tools     ││
│  │              │                           │ - Resources ││
│  │              │                           │ - Prompts   ││
│  └──────────────┘                           └────────────┘│
│                                                             │
└─────────────────────────────────────────────────────────────┘

MCP 核心概念

概念	说明	示例
Tools	AI可调用的函数/工具	执行测量、生成报告、查询数据
Resources	AI可读取的数据资源	项目数据、测点信息、监测规范
Prompts	预定义的提示模板	监测日报模板、分析指令模板
Server	提供Tools和Resources的服务	RailWise MCP Server

安装配置

环境要求

项目	最低要求	推荐配置
操作系统	macOS 12+ / Windows 10+ / Linux	macOS 14 / Windows 11 / Ubuntu 22.04
Node.js	18+	20 LTS
RAILWISE-CLI	1.2.0+	最新版
网络	可访问RailWise API	稳定互联网连接

安装步骤

1. 安装 RAILWISE-CLI

# 使用 npm 全局安装
npm install -g @railwise/cli

# 或使用 Bun
bun install -g @railwise/cli

# 验证安装
railwise-cli --version
# 输出: RAILWISE-CLI v1.2.0

2. 配置 API Key

# 登录 RailWise 账号
railwise-cli auth login

# 或手动设置 API Key
railwise-cli config set api.key rw_live_xxxxxxxxxxxxxxxx

3. 配置 MCP Server

Cursor 配置

{
  "mcpServers": {
    "railwise": {
      "command": "railwise-cli",
      "args": ["mcp", "serve"],
      "env": {
        "RAILWISE_API_KEY": "rw_live_xxxxxxxxxxxxxxxx",
        "RAILWISE_BASE_URL": "https://api.railwise.cn/v2"
      }
    }
  }
}

Claude Desktop 配置（macOS）

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "railwise": {
      "command": "/usr/local/bin/railwise-cli",
      "args": ["mcp", "serve"],
      "env": {
        "RAILWISE_API_KEY": "rw_live_xxxxxxxxxxxxxxxx",
        "RAILWISE_BASE_URL": "https://api.railwise.cn/v2"
      }
    }
  }
}

Claude Desktop 配置（Windows）

{
  "mcpServers": {
    "railwise": {
      "command": "C:\\Users\\<用户名>\\AppData\\Roaming\\npm\\railwise-cli.cmd",
      "args": ["mcp", "serve"],
      "env": {
        "RAILWISE_API_KEY": "rw_live_xxxxxxxxxxxxxxxx",
        "RAILWISE_BASE_URL": "https://api.railwise.cn/v2"
      }
    }
  }
}

Windsurf 配置

{
  "mcpServers": {
    "railwise": {
      "command": "railwise-cli",
      "args": ["mcp", "serve"],
      "env": {
        "RAILWISE_API_KEY": "rw_live_xxxxxxxxxxxxxxxx",
        "RAILWISE_BASE_URL": "https://api.railwise.cn/v2"
      }
    }
  }
}

4. 验证配置

配置完成后，重启 AI 客户端，MCP Server 将自动启动。在 AI 客户端中输入以下指令验证：

列出可用的 RailWise 工具

AI 助手应返回可用的工具列表。

工具列表

RailWise MCP Server 提供以下工具：

1. 数据查询工具

`railwise_query_data`

查询监测数据。

参数	类型	必填	说明
project_id	string	是	项目ID
point_ids	array	否	测点ID列表，不传则查询全部
start_date	string	否	开始日期，ISO 8601格式
end_date	string	否	结束日期，ISO 8601格式
metric	string	否	指标类型：settlement/displacement/convergence/tilt

示例调用：

{
  "project_id": "proj_rw_2026_001",
  "point_ids": ["P1", "P2", "P3"],
  "start_date": "2026-07-01",
  "end_date": "2026-07-08",
  "metric": "settlement"
}

返回示例：

{
  "data": [
    {
      "point_id": "P1",
      "timestamp": "2026-07-08T08:00:00+08:00",
      "value": 12.35,
      "unit": "mm",
      "rate": 0.5,
      "alert_level": "normal"
    }
  ]
}

`railwise_query_project_info`

查询项目信息。

参数	类型	必填	说明
project_id	string	是	项目ID

返回示例：

{
  "project_id": "proj_rw_2026_001",
  "name": "绕城高速管廊工程1标段",
  "type": "subway_protection",
  "location": "宁波市鄞州区",
  "client": "宁波市轨道交通集团",
  "start_date": "2026-03-01",
  "status": "active",
  "total_points": 25,
  "alert_summary": {
    "normal": 18,
    "notice": 3,
    "yellow": 2,
    "orange": 1,
    "red": 1
  }
}

2. 分析工具

`railwise_analyze_trend`

分析变形趋势。

参数	类型	必填	说明
project_id	string	是	项目ID
point_ids	array	是	测点ID列表
metric	string	是	指标类型
period	string	否	分析周期，如 “7d”, “30d”, “90d”
include_forecast	boolean	否	是否包含预测，默认false
forecast_horizon	integer	否	预测时长（小时），默认72

返回示例：

{
  "trends": [
    {
      "point_id": "P1",
      "trend": "increasing",
      "trend_rate": 0.5,
      "r_squared": 0.92,
      "confidence": 0.95,
      "forecast": {
        "horizon": 72,
        "predictions": [
          {
            "timestamp": "2026-07-08T20:00:00+08:00",
            "value": 12.85,
            "lower_bound": 11.50,
            "upper_bound": 14.20
          }
        ]
      }
    }
  ]
}

`railwise_detect_anomalies`

检测数据异常。

参数	类型	必填	说明
project_id	string	是	项目ID
point_ids	array	否	测点ID列表
start_date	string	否	开始日期
end_date	string	否	结束日期
sensitivity	string	否	灵敏度：low/medium/high，默认medium

返回示例：

{
  "anomalies": [
    {
      "point_id": "P3",
      "timestamp": "2026-07-07T08:00:00+08:00",
      "type": "spike",
      "severity": "critical",
      "value": 25.8,
      "expected_range": [8.0, 15.0],
      "confidence": 0.98,
      "recommended_action": "立即复测，检查测点及周边环境"
    }
  ]
}

3. 报告工具

`railwise_generate_report`

生成监测报告。

参数	类型	必填	说明
project_id	string	是	项目ID
report_type	string	是	报告类型：daily/weekly/monthly/special/rapid
date	string	否	报告日期，默认今天
template	string	否	模板名称，默认gb50911
format	string	否	输出格式：pdf/word/html，默认pdf

返回示例：

{
  "report_id": "report_20260708_001",
  "status": "generating",
  "estimated_completion": "2026-07-08T14:05:00+08:00",
  "download_url": "https://api.railwise.cn/v2/reports/download/report_20260708_001"
}

4. 测量工具

`railwise_execute_survey`

执行测量任务。

参数	类型	必填	说明
project_id	string	是	项目ID
station_id	string	是	测站ID
point_ids	array	是	测点ID列表
rounds	integer	否	测回数，默认3
auto_retry	boolean	否	失败自动重试，默认true

返回示例：

{
  "survey_id": "survey_20260708_001",
  "status": "completed",
  "start_time": "2026-07-08T08:00:00+08:00",
  "end_time": "2026-07-08T08:15:30+08:00",
  "results": [
    {
      "point_id": "P1",
      "x": 100.001,
      "y": 200.002,
      "z": 10.003,
      "precision": 0.5
    }
  ]
}

5. 项目管理工具

`railwise_list_projects`

列出项目列表。

参数	类型	必填	说明
status	string	否	项目状态：active/completed/all，默认active
limit	integer	否	返回数量，默认20

`railwise_get_alert_status`

获取预警状态。

参数	类型	必填	说明
project_id	string	是	项目ID
include_history	boolean	否	是否包含历史预警，默认false

返回示例：

{
  "total_points": 25,
  "normal": 18,
  "notice": 3,
  "yellow": 2,
  "orange": 1,
  "red": 1,
  "alert_points": [
    {
      "point_id": "P7",
      "level": "red",
      "current_value": 18.5,
      "threshold": 15.0,
      "exceeded_ratio": 1.23
    }
  ]
}

6. 规范查询工具

`railwise_query_standard`

查询监测规范条文。

参数	类型	必填	说明
query	string	是	查询内容
standard	string	否	规范编号，如 “GB50911-2013”
section	string	否	章节号

返回示例：

{
  "results": [
    {
      "standard": "GB 50911-2013",
      "section": "5.2.3",
      "title": "监测频率",
      "content": "盾构施工期间，控制保护区监测频率应根据变形速率和累计变形量动态调整...",
      "relevance": 0.95
    }
  ]
}

资源访问

资源类型

RailWise MCP Server 提供以下资源类型：

资源类型	URI 格式	说明
项目信息	`railwise://projects/{project_id}`	项目基本信息
测点数据	`railwise://points/{project_id}/{point_id}`	测点详细信息
监测数据	`railwise://data/{project_id}/{point_id}`	监测时序数据
预警记录	`railwise://alerts/{project_id}`	预警历史记录
报告文件	`railwise://reports/{report_id}`	生成的报告文件
规范条文	`railwise://standards/{standard_id}`	监测规范内容
设备信息	`railwise://equipment/{equipment_id}`	设备详细信息
人员信息	`railwise://personnel/{user_id}`	人员信息（需权限）

资源访问示例

在 AI 客户端中，可以直接引用资源：

请分析 railwise://projects/proj_rw_2026_001 的最新监测数据

AI 助手会自动读取项目资源并分析数据。

使用示例

与 Cursor 集成

配置完成后，在 Cursor 的 Composer 或 Chat 中可以直接使用自然语言调用 RailWise 工具：

示例1：查询监测数据

用户: 查询绕城高速管廊项目最近7天P1-P5测点的沉降数据

AI: 我来为您查询这些数据。

[调用 railwise_query_data]
- project_id: proj_rw_2026_001
- point_ids: ["P1", "P2", "P3", "P4", "P5"]
- start_date: 2026-07-01
- end_date: 2026-07-08
- metric: settlement

AI: 已获取数据。P1-P5测点最近7天沉降数据如下：
- P1: 累计沉降 12.35mm，速率 0.5mm/天
- P2: 累计沉降 8.20mm，速率 0.3mm/天
- P3: 累计沉降 15.80mm，速率 1.2mm/天（黄色预警）
- P4: 累计沉降 6.50mm，速率 0.2mm/天
- P5: 累计沉降 9.10mm，速率 0.4mm/天

示例2：生成监测报告

用户: 生成本周绕城高速管廊项目的监测周报

AI: 我来为您生成周报。

[调用 railwise_generate_report]
- project_id: proj_rw_2026_001
- report_type: weekly
- date: 2026-07-08
- template: gb50911
- format: pdf

AI: 周报已生成，报告ID: report_20260708_001。
预计2分钟后可下载，下载链接将在生成完成后提供。

示例3：执行测量任务

用户: 执行3号线控制保护区TS-01测站的测量任务，测量P1-P5测点

AI: 我来执行测量任务。

[调用 railwise_execute_survey]
- project_id: proj_rw_2026_001
- station_id: TS-01
- point_ids: ["P1", "P2", "P3", "P4", "P5"]
- rounds: 3
- auto_retry: true

AI: 测量任务已启动。
测站: TS-01
测点: P1, P2, P3, P4, P5
测回数: 3
预计完成时间: 15分钟

[15分钟后]

AI: 测量任务已完成。
结果摘要：
- P1: X=100.001, Y=200.002, Z=10.003, 精度0.5mm
- P2: X=105.003, Y=205.001, Z=10.005, 精度0.4mm
- ...

示例4：异常检测

用户: 检查绕城高速管廊项目最近一周是否有异常数据

AI: 我来检查异常数据。

[调用 railwise_detect_anomalies]
- project_id: proj_rw_2026_001
- start_date: 2026-07-01
- end_date: 2026-07-08
- sensitivity: high

AI: 检测到1个异常：

⚠️ 严重异常 - 测点 P3
时间: 2026-07-07 08:00
类型: 数据突变
异常值: 25.8mm（预期范围: 8.0-15.0mm）
置信度: 98%

建议操作：
1. 立即对P3测点进行复测
2. 检查测点及周边环境是否有变化
3. 关注P3附近测点（P2、P4）的数据变化

示例5：规范查询

用户: 盾构施工期间控制保护区监测频率有什么要求？

AI: 我来查询相关规范。

[调用 railwise_query_standard]
- query: "盾构施工期间控制保护区监测频率"
- standard: "GB50911-2013"

AI: 根据《城市轨道交通结构安全保护技术规范》GB 50911-2013 第5.2.3条：

盾构施工期间，控制保护区监测频率应根据变形速率和累计变形量动态调整：

1. 变形速率 < 1mm/天：每天1次
2. 1mm/天 ≤ 变形速率 < 5mm/天：每天2次
3. 变形速率 ≥ 5mm/天：每4-6小时1次
4. 穿越期间：每4-6小时1次

此外，当累计变形达到预警值的60%时，应加密监测。

与 Claude Desktop 集成

Claude Desktop 的配置与 Cursor 类似，配置完成后在 Claude 的对话框中即可使用相同的自然语言指令。

与 Windsurf 集成

Windsurf 的配置方式相同，在 Cascade 或 Chat 中均可调用 RailWise 工具。

安全与认证

认证方式

RailWise MCP Server 使用 API Key 进行认证，通过环境变量传递：

export RAILWISE_API_KEY="rw_live_xxxxxxxxxxxxxxxx"
export RAILWISE_BASE_URL="https://api.railwise.cn/v2"

权限控制

权限级别	可操作工具	说明
读取	query_data, query_project_info, analyze_trend, detect_anomalies, query_standard	只读查询
报告	读取 + generate_report	可生成报告
测量	读取 + execute_survey	可执行测量
管理	全部工具	完整权限

数据安全

所有通信通过 HTTPS 加密
API Key 不存储在 MCP Server 中，仅通过环境变量传递
敏感数据（如人员信息）需要额外权限
操作日志记录所有工具调用

最佳实践

API Key 管理
- 使用环境变量而非硬编码
- 定期轮换 API Key
- 不同环境使用不同的 API Key
权限最小化
- 根据实际需求分配权限
- 避免使用管理员权限进行日常操作
审计日志
- 定期检查操作日志
- 关注异常调用模式

故障排查

常见问题

Q1: MCP Server 无法启动

排查步骤：

检查 railwise-cli 是否正确安装
Terminal window
```
which railwise-cli
railwise-cli --version
```
检查 API Key 是否设置
Terminal window
```
echo $RAILWISE_API_KEY
```
检查配置文件路径是否正确
查看 AI 客户端的错误日志

Q2: 工具调用失败

排查步骤：

检查 API Key 是否有效
Terminal window
```
railwise-cli auth status
```
检查网络连接
Terminal window
```
ping api.railwise.cn
```
检查项目ID是否正确
查看 MCP Server 的日志输出

Q3: 返回数据不完整

排查步骤：

检查参数是否完整
检查数据权限
检查日期范围是否合理
尝试缩小查询范围

Q4: 性能问题

优化建议：

避免一次性查询大量数据
使用分页查询
缓存常用数据
减少不必要的工具调用

日志查看

# 查看 MCP Server 日志
railwise-cli mcp logs --follow

# 查看详细日志
railwise-cli mcp logs --verbose

# 导出日志
railwise-cli mcp logs --export --output ./mcp_logs.txt

调试模式

# 启动调试模式
RAILWISE_DEBUG=1 railwise-cli mcp serve

# 或
railwise-cli mcp serve --debug

更新日志

版本	日期	变更内容
1.0.0	2026-07-08	初始版本发布；支持15+工具；支持Cursor/Claude/Windsurf

MCP 历史集成草案（未公开）

RailWise MCP Server 集成指南

目录

概述

支持的AI平台

版本信息

什么是MCP

MCP 核心概念

安装配置

环境要求

安装步骤

1. 安装 RAILWISE-CLI

2. 配置 API Key

3. 配置 MCP Server

Cursor 配置

Claude Desktop 配置（macOS）

Claude Desktop 配置（Windows）

Windsurf 配置

4. 验证配置

工具列表

1. 数据查询工具

railwise_query_data

railwise_query_project_info

2. 分析工具

railwise_analyze_trend

railwise_detect_anomalies

3. 报告工具

railwise_generate_report

4. 测量工具

railwise_execute_survey

5. 项目管理工具

railwise_list_projects

railwise_get_alert_status

6. 规范查询工具

railwise_query_standard

资源访问

资源类型

资源访问示例

使用示例

与 Cursor 集成

示例1：查询监测数据

示例2：生成监测报告

示例3：执行测量任务

示例4：异常检测

示例5：规范查询

与 Claude Desktop 集成

与 Windsurf 集成

安全与认证

认证方式

权限控制

数据安全

最佳实践

故障排查

常见问题

Q1: MCP Server 无法启动

Q2: 工具调用失败

Q3: 返回数据不完整

Q4: 性能问题

日志查看

调试模式

更新日志

相关文档

`railwise_query_data`

`railwise_query_project_info`

`railwise_analyze_trend`

`railwise_detect_anomalies`

`railwise_generate_report`

`railwise_execute_survey`

`railwise_list_projects`

`railwise_get_alert_status`

`railwise_query_standard`