MCP 指南deprecated

MCP 历史排查草案（未公开）

保留的 MCP 排查设计资料，不代表 RailWise 已对外提供可连接、可诊断的 MCP 服务。

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

MCP 指南

RailWise MCP Server 故障排查

1. 排查流程

遇到问题时，建议按照以下流程进行排查：

发现问题
    ↓
┌─────────────────┐
│ 1. 确认环境     │ ← 检查 Node.js 版本、网络连接
└─────────────────┘
    ↓
┌─────────────────┐
│ 2. 检查配置     │ ← 验证 API Key、配置文件格式
└─────────────────┘
    ↓
┌─────────────────┐
│ 3. 查看日志     │ ← 启用调试日志，分析错误信息
└─────────────────┘
    ↓
┌─────────────────┐
│ 4. 测试连接     │ ← 使用命令行工具验证 API 连通性
└─────────────────┘
    ↓
┌─────────────────┐
│ 5. 查阅文档     │ ← 参考本文档或联系技术支持
└─────────────────┘

2. 常见问题速查表

2.1 安装问题

问题	错误信息	原因	解决方案
Node.js 未安装	`command not found: npx`	系统未安装 Node.js	从 nodejs.org 下载安装 LTS 版本
npm 缓存损坏	`npm ERR! code E404`	npm 缓存损坏或网络问题	执行 `npm cache clean --force`
权限不足	`EACCES: permission denied`	全局安装权限不足	macOS/Linux 使用 `sudo` 或修复 npm 权限
网络超时	`ETIMEDOUT`	网络连接问题或防火墙	检查网络，配置代理或切换镜像源

2.2 配置问题

问题	错误信息	原因	解决方案
API Key 无效	`API Key 无效或已过期`	密钥错误、过期或权限不足	在开发者平台重新生成 API Key
配置文件格式错误	`JSON parse error`	配置文件 JSON 格式错误	使用 JSON 验证工具检查格式
环境变量未设置	`RAILWISE_API_KEY is required`	未设置必需的环境变量	检查环境变量配置
路径错误	`No such file or directory`	配置文件路径错误	确认路径正确，使用绝对路径

2.3 连接问题

问题	错误信息	原因	解决方案
API 服务不可达	`ECONNREFUSED`	API 服务端点错误或网络问题	检查 `RAILWISE_API_URL` 配置
TLS 证书错误	`UNABLE_TO_VERIFY_LEAF_SIGNATURE`	证书校验失败	检查系统时间，更新 CA 证书
连接超时	`ETIMEDOUT`	网络延迟高或服务器繁忙	增加 `RAILWISE_MCP_TIMEOUT`
代理问题	`ECONNRESET`	代理服务器配置问题	配置 `HTTP_PROXY`/`HTTPS_PROXY`

2.4 AI 客户端问题

问题	错误信息	原因	解决方案
MCP Server 未显示	客户端未识别	配置未加载或格式错误	重启客户端，检查配置文件路径
工具调用失败	`Tool execution failed`	权限不足或参数错误	检查权限配置，验证参数格式
响应为空	无返回数据	查询条件不匹配或数据为空	放宽查询条件，确认数据存在
客户端崩溃	客户端异常退出	MCP Server 输出异常	检查日志，确认 MCP Server 正常运行

3. 诊断工具

3.1 命令行诊断

RailWise MCP Server 提供内置诊断命令：

# 检查版本
npx @railwise/mcp-server --version

# 检查配置
npx @railwise/mcp-server --check-config

# 列出可用工具
npx @railwise/mcp-server --list-tools

# 列出可用资源
npx @railwise/mcp-server --list-resources

# 测试 API 连接
npx @railwise/mcp-server --test-connection

# 完整诊断
npx @railwise/mcp-server --diagnose

3.2 网络诊断

# 测试 API 端点连通性
curl -v https://api.railwise.cn/v1/health

# 测试带认证的 API 请求
curl -H "Authorization: Bearer rw_live_xxxxxxxx" \
     https://api.railwise.cn/v1/projects

# 检查 DNS 解析
dig api.railwise.cn

# 检查路由
 traceroute api.railwise.cn

3.3 启用调试日志

在环境变量中启用详细日志：

export RAILWISE_MCP_LOG_LEVEL=debug
export RAILWISE_MCP_LOG_FILE=/tmp/railwise-mcp-debug.log

# 运行 MCP Server
npx @railwise/mcp-server

日志级别说明：

级别	说明	使用场景
`error`	仅错误信息	生产环境
`warn`	警告和错误	生产环境
`info`	一般信息	正常运行监控
`debug`	详细调试信息	问题排查

4. 错误码详解

4.1 MCP 协议错误码

错误码	说明	解决方案
`-32700`	Parse Error	请求 JSON 格式错误，检查请求格式
`-32600`	Invalid Request	无效的请求对象，检查请求结构
`-32601`	Method Not Found	请求的方法不存在，检查方法名
`-32602`	Invalid Params	参数错误或缺失，检查参数格式
`-32603`	Internal Error	服务器内部错误，联系技术支持

4.2 RailWise API 错误码

HTTP 状态码	错误码	说明	解决方案
`400`	`INVALID_REQUEST`	请求参数无效	检查请求参数格式和值
`401`	`UNAUTHORIZED`	认证失败	检查 API Key 是否有效
`403`	`FORBIDDEN`	权限不足	检查 API Key 权限范围
`404`	`NOT_FOUND`	资源不存在	检查项目ID、测点ID是否正确
`429`	`RATE_LIMITED`	请求过于频繁	降低请求频率，等待配额重置
`500`	`INTERNAL_ERROR`	服务器内部错误	稍后重试，联系技术支持
`503`	`SERVICE_UNAVAILABLE`	服务暂时不可用	稍后重试

4.3 错误响应示例

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "请求参数错误",
    "details": {
      "field": "start_time",
      "reason": "时间格式不正确，应为 ISO 8601 格式",
      "example": "2025-01-15T00:00:00Z"
    }
  }
}

5. 典型问题排查

5.1 MCP Server 启动失败

症状：AI 客户端中不显示 RailWise MCP Server。

排查步骤：

检查 Node.js 版本：

node --version  # 应 >= 18.0.0
npm --version   # 应 >= 9.0.0

手动测试 MCP Server：
Terminal window
```
npx @railwise/mcp-server --version
```

检查配置文件：

# 验证 JSON 格式
cat ~/.cursor/mcp.json | python3 -m json.tool

# 或在线验证
curl -X POST https://jsonlint.com/validate -d @~/.cursor/mcp.json

检查环境变量：

echo $RAILWISE_API_KEY
echo $RAILWISE_API_URL

查看客户端日志：
- Claude Desktop：~/Library/Logs/Claude/mcp.log
- Cursor：开发者工具控制台（Cmd/Ctrl + Shift + P → “Toggle Developer Tools”）

5.2 API Key 认证失败

症状：工具调用返回 401 UNAUTHORIZED。

排查步骤：

验证 API Key 格式：

# 检查前缀
echo $RAILWISE_API_KEY | grep -E "^rw_(live|test|dev)_"

测试 API Key：

curl -H "Authorization: Bearer $RAILWISE_API_KEY" \
     https://api.railwise.cn/v1/auth/verify

检查密钥状态：
- 登录开发者平台，确认密钥状态为 “活跃”
- 检查密钥是否过期
- 检查 IP 白名单限制
检查权限范围：
Terminal window
```
npx @railwise/mcp-server --check-config
```

5.3 工具调用超时

症状：工具调用长时间无响应，最终返回超时错误。

排查步骤：

增加超时时间：

{
  "env": {
    "RAILWISE_MCP_TIMEOUT": "60000"
  }
}

检查网络延迟：

ping api.railwise.cn
curl -w "@curl-format.txt" https://api.railwise.cn/v1/health

简化查询条件：
- 缩小时间范围
- 减少查询测点数量
- 使用聚合查询代替原始数据
检查 API 服务状态：
Terminal window
```
curl https://api.railwise.cn/v1/health
```

5.4 数据查询无结果

症状：工具调用成功，但返回空数据。

排查步骤：

确认项目 ID 正确：

npx @railwise/mcp-server --list-projects

检查时间范围：
- 确认时间格式为 ISO 8601（2025-01-15T00:00:00Z）
- 确认时间范围在数据存在的时间段内
检查权限范围：
- 确认 API Key 有权限访问该项目
- 确认项目状态为 “active”

验证测点存在：

# 查询项目测点列表
npx @railwise/mcp-server --query-project PRJ-A1B2C3D4 --points

6. 性能优化

6.1 查询优化

优化建议	说明
使用聚合查询	使用 `hourly` 或 `daily` 聚合减少数据量
限制返回数量	设置合理的 `limit` 参数
缩小时间范围	查询必要的时间区间，避免全量查询
指定测点列表	使用 `point_ids` 参数精确查询

6.2 缓存策略

AI 客户端通常会在同一会话中缓存资源内容，合理利用缓存可以减少 API 调用：

首次查询 → 调用 API → 获取数据 → 缓存结果
    ↓
后续查询 → 检查缓存 → 命中缓存 → 直接返回

7. 获取帮助

7.1 自助排查

查阅本文档的对应章节
检查 RailWise 开发者社区的 FAQ
搜索 GitHub Issues

7.2 联系技术支持

如果以上方法无法解决问题，请通过以下方式联系技术支持：

渠道	联系方式	响应时间
技术支持邮箱	support@railwise.cn	1 工作日
企业微信	扫描官网二维码	实时（工作时间）
开发者社区	https://dev.railwise.cn/forum	社区互助
GitHub Issues	https://github.com/railwise/mcp-server/issues	2 工作日

7.3 提交问题报告

联系技术支持时，请提供以下信息：

环境信息：
- 操作系统及版本
- Node.js 版本
- MCP Server 版本
配置信息（脱敏后）：
- AI 客户端类型和版本
- 配置文件内容（隐藏 API Key）
错误信息：
- 完整的错误日志
- 复现步骤
- 预期行为和实际行为

诊断输出：

npx @railwise/mcp-server --diagnose > diagnose.log 2>&1

8. 更新日志

版本	日期	更新内容
1.0.0	2025-01-15	初始版本，包含常见问题排查指南

9. 相关文档

MCP Server 概述 — 功能介绍和适用场景
MCP Server 安装配置 — 详细的安装步骤
MCP Server 工具列表 — 完整的工具清单和参数说明
MCP Server 资源访问 — 可访问的资源类型和路径格式
MCP Server 集成示例 — 与主流 AI 平台的集成教程
MCP Server 安全与认证 — 认证方式和权限控制

本文档由 RailWise 技术文档团队维护，最后更新于 2025-01-15。