We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/wenxint/ocp-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
# MCP 服务器调试指南
> 本文档介绍如何调试 OCR MCP 服务器，帮助你排查问题和监控运行状态。
## 目录
1. [调试的挑战](#调试的挑战)
2. [方法一：MCP Inspector（推荐）](#方法一mcp-inspector推荐)
3. [方法二：Chrome DevTools 断点调试](#方法二chrome-devtools-断点调试)
4. [方法三：文件日志](#方法三文件日志)
5. [方法四：详细调试模式](#方法四详细调试模式)
6. [常见问题排查](#常见问题排查)
7. [日志模块说明](#日志模块说明)
---
## 调试的挑战
MCP 服务器的调试与普通 Node.js 应用不同，主要原因：
### stdio 通信机制
```
┌─────────────────────────────────────────────────────────────┐
│ MCP 通信机制 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Cursor MCP Server │
│ │ │ │
│ │ ──── stdin (请求) ──────────► │ │
│ │ │ │
│ │ ◄─── stdout (响应) ────────── │ │
│ │ │ │
│ │ stderr (日志) ──────────► │ (Cursor 不显示) │
│ │
└─────────────────────────────────────────────────────────────┘
```
- **stdout** 被 MCP 协议占用，用于发送响应
- **stdin** 被 MCP 协议占用，用于接收请求
- **stderr** 可以输出日志，但 Cursor 界面不会显示
- **console.log()** 会干扰 MCP 通信，导致协议错误
### 解决方案
1. 使用 `console.error()` 而不是 `console.log()`
2. 使用 MCP Inspector 调试工具
3. 将日志写入文件
---
## 方法一：MCP Inspector（推荐）
MCP Inspector 是官方提供的调试工具，提供 Web 界面来测试和调试 MCP 服务器。
### 启动 Inspector
```bash
cd /Users/taowenxin/Desktop/mcpTest
# 使用 npx 直接运行（会自动下载）
npx @modelcontextprotocol/inspector node index.js
```
### 启动后输出
```
Starting MCP inspector...
⚙️ Proxy server listening on localhost:6277
🔑 Session token: xxxx...
🚀 MCP Inspector is up and running at:
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=xxxx
🌐 Opening browser...
```
### Inspector 功能介绍
打开浏览器访问上述地址后，你可以：
#### 1. 查看工具列表
点击左侧 "Tools" 标签，可以看到服务器注册的所有工具：
- `recognize_text` - OCR 文字识别
- `list_ocr_languages` - 列出支持的语言
#### 2. 手动测试工具
选择一个工具后，在右侧面板输入参数并点击 "Run"：
```json
{
"image_path": "/Users/taowenxin/Desktop/mcpTest/img/20260120-190708.jpg"
}
```
#### 3. 查看请求/响应
Inspector 会显示完整的 JSON-RPC 通信内容：
**请求示例**：
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "recognize_text",
"arguments": {
"image_path": "/path/to/image.jpg"
}
}
}
```
**响应示例**：
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "## OCR 识别结果\n\n**置信度**: 86.0%\n\n..."
}
]
}
}
```
#### 4. 查看 stderr 日志
Inspector 底部会显示服务器的 `console.error()` 输出。
### 停止 Inspector
在终端中按 `Ctrl + C` 停止 Inspector。
---
## 方法二：Chrome DevTools 断点调试
如果你需要单步调试代码、查看变量值、追踪调用堆栈，可以使用 Chrome DevTools 进行断点调试。
### 重要提示
在 MCP 服务器中，**绝对不能使用 `console.log()`**，否则会破坏 stdio 通信！
```javascript
// ❌ 错误 - 会破坏 MCP 通信
console.log('调试信息');
// ✅ 正确 - 输出到 stderr，不影响通信
console.error('调试信息');
// ✅ 推荐 - 使用项目提供的 log 函数
import { log } from './logger.js';
log('调试信息');
```
### 完整调试步骤
#### 第一步：启动带调试功能的 Inspector
```bash
cd /Users/taowenxin/Desktop/mcpTest
# 清理可能存在的旧进程
pkill -f "inspector" 2>/dev/null
pkill -f "mcpTest" 2>/dev/null
# 启动 Inspector（带 --inspect 参数启用 Node.js 调试）
npx @modelcontextprotocol/inspector node --inspect index.js
```
启动成功后会显示：
```
Starting MCP inspector...
⚙️ Proxy server listening on localhost:6277
🔑 Session token: xxxx...
🚀 MCP Inspector is up and running at:
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=xxxx
🌐 Opening browser...
```
#### 第二步：打开 Inspector 网页并连接
1. 在浏览器中打开上面显示的 URL（包含 token）
2. 点击 **Connect** 按钮
3. 等待连接成功（按钮会变成 Disconnect）
```
┌─────────────────────────────────────────────────────────────────┐
│ Inspector 网页界面 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Arguments: index.js │
│ │
│ ┌─────────────────────┐ │
│ │ Connect │ ← 点击这个按钮 │
│ └─────────────────────┘ │
│ │
│ 连接成功后，左侧会出现 Tools 选项 │
│ │
└─────────────────────────────────────────────────────────────────┘
```
#### 第三步：打开 Chrome DevTools 连接调试器
1. **另开一个浏览器标签页**
2. 地址栏输入：`chrome://inspect`
3. 在 **Remote Target** 下面找到 `index.js`
4. 点击 **inspect** 链接
```
┌─────────────────────────────────────────────────────────────────┐
│ chrome://inspect 页面 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ DevTools │
│ │
│ Devices │
│ ☑ Discover USB devices │
│ ☑ Discover network targets │
│ │
│ [Open dedicated DevTools for Node] ← 或者点这个 │
│ │
│ Remote Target #LOCALHOST │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ index.js │ │
│ │ file:///Users/.../mcpTest/index.js │ │
│ │ [inspect] ← 点击这个 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**注意**：如果 Remote Target 下面是空的，说明还没有在 Inspector 网页中点击 Connect。
#### 第四步：在 DevTools 中设置断点
1. DevTools 窗口打开后，点击顶部的 **Sources**（源代码）标签
2. 左侧文件列表找到：`file://` → `Users` → `taowenxin` → `Desktop` → `mcpTest`
3. 点击 **index.js** 或 **ocr.js**
4. 找到你想调试的代码行，**点击行号** 设置断点（会出现蓝色标记）
```
┌─────────────────────────────────────────────────────────────────┐
│ Chrome DevTools │
├─────────────────────────────────────────────────────────────────┤
│ Elements Console Sources Network ... │
│ ───────────────── │
│ ┌──────────────┬────────────────────────────────────────────┐ │
│ │ 文件列表 │ 代码区域 │ │
│ │ │ │ │
│ │ ▼ file:// │ 170| server.setRequestHandler(... │ │
│ │ ▼ Users │ 171| // 断点设置在这里 │ │
│ │ ... │ ●172| console.error('收到请求'); │ │
│ │ index.js │ 173| │ │
│ │ ocr.js │ 174| const { name } = request.params; │ │
│ │ │ │ │
│ │ │ ● = 断点标记（点击行号设置） │ │
│ └──────────────┴────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
#### 第五步：触发断点
1. 回到 **Inspector 网页**
2. 点击左侧展开 **Tools**
3. 选择 **recognize_text**
4. 在参数输入框输入：
```json
{
"image_path": "/Users/taowenxin/Desktop/mcpTest/img/20260120-190708.jpg"
}
```
5. 点击 **Run** 按钮
#### 第六步：开始单步调试
点击 Run 后，代码会执行到你设置的断点处暂停。DevTools 会显示"已在断点处暂停"。
**调试快捷键**：
| 快捷键 | 功能 | 说明 |
|--------|------|------|
| **F8** | 继续执行 | 运行到下一个断点 |
| **F10** | 单步跳过 | 执行当前行，不进入函数 |
| **F11** | 单步进入 | 进入函数内部 |
| **Shift+F11** | 单步跳出 | 跳出当前函数 |
**调试面板功能**：
```
┌─────────────────────────────────────────────────────────────────┐
│ 调试时的 DevTools │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 代码区域 │ 右侧面板 │
│ ─────────────────────────────────│─────────────────────────── │
│ │ │
│ 170| server.setRequest... │ ▼ 监视 (Watch) │
│ ►171| console.error(... ← 暂停 │ 添加要监视的变量 │
│ 172| │ │
│ 173| const { name } = ... │ ▼ 断点 (Breakpoints) │
│ │ ☑ index.js:171 │
│ ► 表示当前执行位置 │ │
│ │ ▼ 作用域 (Scope) │
│ │ ▼ Local │
│ │ request: {...} │
│ │ name: "recognize..." │
│ │ │
│ │ ▼ 调用堆栈 (Call Stack) │
│ │ setRequestHandler │
│ │ ... │
│ │ │
└─────────────────────────────────────────────────────────────────┘
```
### 完整流程图
```
┌─────────────────────────────────────────────────────────────────┐
│ 断点调试完整流程 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 终端 │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ npx @modelcontextprotocol/inspector node --inspect ... │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 1. Inspector 网页: 点击 Connect │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 2. chrome://inspect: 点击 inspect │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 3. DevTools: 设置断点 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 4. Inspector 网页: 选择工具 → 输入参数 → 点击 Run │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 5. DevTools: 断点触发！使用 F10/F11 单步调试 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 常见问题
#### Remote Target 下面是空的
**原因**：还没有在 Inspector 网页中点击 Connect。
**解决**：先去 Inspector 网页点击 Connect，然后刷新 chrome://inspect 页面。
#### 断点不触发
**原因**：代码还没有执行到断点位置。
**解决**：在 Inspector 网页中点击 Run 触发工具调用。
#### Connection Error
**原因**：Inspector 进程已经停止或 token 已过期。
**解决**：重新启动 Inspector，使用新的 URL（包含新 token）。
```bash
# 重新启动
pkill -f "inspector"
npx @modelcontextprotocol/inspector node --inspect index.js
```
---
## 方法三：文件日志
本项目内置了日志模块，会将日志同时输出到 stderr 和文件。
### 日志文件位置
```
/Users/taowenxin/Desktop/mcpTest/mcp-server.log
```
### 查看日志
```bash
# 查看全部日志
cat /Users/taowenxin/Desktop/mcpTest/mcp-server.log
# 实时监控日志（推荐）
tail -f /Users/taowenxin/Desktop/mcpTest/mcp-server.log
# 查看最后 50 行
tail -n 50 /Users/taowenxin/Desktop/mcpTest/mcp-server.log
# 搜索错误日志
grep "ERROR" /Users/taowenxin/Desktop/mcpTest/mcp-server.log
```
### 日志格式
```
[时间戳] [级别] 日志内容
示例：
[2026-01-20T11:30:00.000Z] [INFO] OCR MCP Server 已启动，等待连接...
[2026-01-20T11:30:05.123Z] [INFO] 工具调用: recognize_text
[2026-01-20T11:30:05.124Z] [INFO] 开始识别图片: /path/to/image.jpg
[2026-01-20T11:30:05.125Z] [INFO] 使用语言: chi_sim, eng
[2026-01-20T11:30:08.456Z] [INFO] 识别成功，置信度: 86.0%
[2026-01-20T11:30:10.789Z] [ERROR] 识别失败: 文件不存在: /invalid/path.jpg
```
### 清空日志
```bash
# 清空日志文件
echo "" > /Users/taowenxin/Desktop/mcpTest/mcp-server.log
# 或者删除后重新创建
rm /Users/taowenxin/Desktop/mcpTest/mcp-server.log
```
---
## 方法四：详细调试模式
设置环境变量 `MCP_DEBUG=1` 可以启用详细调试日志。
### 配置 Cursor
编辑 `~/.cursor/mcp.json`：
```json
{
"mcpServers": {
"ocr-tool": {
"command": "node",
"args": ["/Users/taowenxin/Desktop/mcpTest/index.js"],
"env": {
"MCP_DEBUG": "1"
}
}
}
}
```
### 调试模式的额外日志
启用后，会输出更多详细信息：
```
[2026-01-20T11:30:05.123Z] [DEBUG] 调用参数: {"image_path":"/path/to/image.jpg","languages":["chi_sim","eng"]}
[2026-01-20T11:30:08.456Z] [DEBUG] 识别文字: 这是识别出的文字内容的前100个字符...
```
### 关闭调试模式
将 `MCP_DEBUG` 设为 `0` 或删除该环境变量：
```json
{
"mcpServers": {
"ocr-tool": {
"command": "node",
"args": ["/Users/taowenxin/Desktop/mcpTest/index.js"],
"env": {
"MCP_DEBUG": "0"
}
}
}
}
```
---
## 常见问题排查
### 问题 1：Cursor 中 MCP 服务器显示红色状态
**可能原因**：
1. 服务器启动失败
2. 路径配置错误
3. 依赖未安装
**排查步骤**：
```bash
# 1. 检查配置路径是否正确
cat ~/.cursor/mcp.json
# 2. 手动运行服务器，查看错误
cd /Users/taowenxin/Desktop/mcpTest
node index.js
# 3. 检查依赖是否安装
npm ls
```
### 问题 2：工具调用无响应
**可能原因**：
1. 图片路径错误
2. 图片格式不支持
3. OCR 引擎初始化失败
**排查步骤**：
```bash
# 1. 查看日志文件
tail -f /Users/taowenxin/Desktop/mcpTest/mcp-server.log
# 2. 检查图片是否存在
ls -la /path/to/your/image.jpg
# 3. 使用 Inspector 测试
npx @modelcontextprotocol/inspector node index.js
```
### 问题 3：识别结果乱码或为空
**可能原因**：
1. 语言包未下载完成
2. 语言参数错误
3. 图片质量太差
**排查步骤**：
```bash
# 1. 检查网络连接（首次需要下载语言包）
ping google.com
# 2. 查看日志中的置信度
grep "置信度" /Users/taowenxin/Desktop/mcpTest/mcp-server.log
# 3. 尝试使用高清图片测试
```
### 问题 4：console.log 导致协议错误
**错误现象**：
```
Error: Invalid JSON-RPC response
```
**原因**：
代码中使用了 `console.log()`，干扰了 stdout 通信。
**解决方法**：
将所有 `console.log()` 改为 `console.error()` 或使用 `log()` 函数。
```javascript
// ❌ 错误
console.log('调试信息');
// ✅ 正确
console.error('调试信息');
// ✅ 推荐
import { log } from './logger.js';
log('调试信息');
```
---
## 日志模块说明
本项目提供了 `logger.js` 日志模块，位于：
```
/Users/taowenxin/Desktop/mcpTest/logger.js
```
### 可用函数
| 函数 | 用途 | 输出位置 |
|------|------|----------|
| `log(...args)` | 普通日志 | stderr + 文件 |
| `logError(...args)` | 错误日志 | stderr + 文件 |
| `logDebug(...args)` | 调试日志 | 仅在 MCP_DEBUG=1 时 |
| `clearLog()` | 清空日志文件 | - |
### 使用示例
```javascript
import { log, logError, logDebug } from './logger.js';
// 普通日志
log('服务器启动');
log('处理请求', { tool: 'recognize_text' });
// 错误日志
logError('文件不存在', '/path/to/file');
// 调试日志（需要 MCP_DEBUG=1）
logDebug('详细参数', JSON.stringify(params));
```
### 自定义日志文件路径
如果需要修改日志文件位置，编辑 `logger.js`：
```javascript
// 修改这一行
const LOG_FILE = path.join(__dirname, 'mcp-server.log');
// 改为
const LOG_FILE = '/var/log/ocr-mcp-server.log';
```
---
## 调试流程推荐
### 开发阶段
1. 使用 MCP Inspector 进行交互式调试
2. 实时查看日志文件
3. 启用 `MCP_DEBUG=1` 获取详细信息
```bash
# 终端 1：启动 Inspector
npx @modelcontextprotocol/inspector node index.js
# 终端 2：监控日志
tail -f mcp-server.log
```
### 生产阶段
1. 关闭详细调试模式
2. 定期检查日志文件
3. 设置日志轮转（如果日志量大）
```bash
# 查看最近的错误
grep "ERROR" mcp-server.log | tail -20
# 统计调用次数
grep "工具调用" mcp-server.log | wc -l
```
---
## 附录：MCP 协议调试技巧
### 查看原始 JSON-RPC 消息
在 `index.js` 中添加：
```javascript
// 在 server.setRequestHandler 之前添加
server.onRequest = (request) => {
logDebug('收到请求:', JSON.stringify(request));
};
```
### 模拟 Cursor 调用
使用 `curl` 或 `echo` 直接发送 JSON-RPC 请求：
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node index.js
```
### 检查服务器是否正常响应
```bash
# 发送 initialize 请求
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{},"clientInfo":{"name":"test"}}}' | node index.js
```
---
## 总结
| 调试方法 | 适用场景 | 优点 | 缺点 |
|----------|----------|------|------|
| MCP Inspector | 开发测试 | 可视化、交互式 | 需要单独启动 |
| 文件日志 | 生产监控 | 持久化、可追溯 | 需要手动查看 |
| 详细调试模式 | 问题排查 | 信息全面 | 日志量大 |
建议：
- **开发时**：优先使用 MCP Inspector
- **部署后**：依赖文件日志 + 定期检查
- **出问题时**：启用详细调试模式