# 错误修复：MCP Inspector 连接错误
**修复时间**：2025-12-04
**错误级别**：High
## 问题详情
### 错误信息
```
Connection Error - Check if your MCP server is running and proxy token is correct
```
### 错误类型
- 类型：配置错误
- 影响：MCP Inspector 无法连接到 MCP 服务器
- 功能影响：无法使用 MCP Inspector 测试和调试工具
## 解决方案
### 根本原因
`.mcp-inspector.json` 配置文件引用了不存在的启动脚本：
```json
{
"mcpServers": {
"web-analysis": {
"command": "node",
"args": ["test-server.js"], // ❌ 文件不存在
"cwd": ".",
"env": {
"NODE_ENV": "test"
}
}
}
}
```
### 修改文件
- `.mcp-inspector.json`：配置文件（已存在，但引用了错误文件）
- `test-server.js`：创建缺失的启动脚本（新增）
### 代码变更
#### 1. 创建 test-server.js 启动脚本
```javascript
#!/usr/bin/env node
/**
* Test Server for MCP Inspector
* Simple wrapper to run the MCP server for testing
*/
// Check if build exists, if not build first
import { existsSync } from 'fs';
import { spawn } from 'child_process';
if (!existsSync('./dist/index.js')) {
console.error('❌ Build not found. Please run "npm run build" first.');
process.exit(1);
}
// Run the compiled server
const child = spawn('node', ['dist/index.js'], {
stdio: 'inherit',
env: process.env
});
child.on('error', (error) => {
console.error('❌ Failed to start server:', error.message);
process.exit(1);
});
child.on('exit', (code) => {
process.exit(code);
});
```
#### 2. 验证配置文件
```json
{
"mcpServers": {
"web-analysis": {
"command": "node",
"args": ["test-server.js"], // ✅ 现在文件存在
"cwd": ".",
"env": {
"NODE_ENV": "test"
}
}
}
}
```
## 技术分析
### 1. MCP Inspector 工作原理
- MCP Inspector 是一个用于测试 MCP 服务器的 Web 界面
- 它通过代理服务器连接到配置的 MCP 服务器
- 需要正确的配置文件来启动和连接服务器
### 2. 启动脚本设计
- **自动构建检查**：确保编译产物存在
- **错误处理**：提供清晰的错误信息
- **进程管理**：正确处理子进程和退出码
- **环境继承**：保持必要的环境变量
### 3. 配置文件格式
- **mcpServers**：定义要连接的 MCP 服务器
- **command**：启动服务器的命令
- **args**：命令参数
- **cwd**：工作目录
- **env**：环境变量
## 验证结果
- [x] 代码检查通过（`npm run typecheck`）
- [x] 启动脚本创建成功
- [x] 启动脚本测试正常（10秒超时测试通过）
- [x] MCP Inspector 成功启动
- [x] 代理服务器监听正常（localhost:6277）
- [x] 会话令牌生成成功
- [x] 浏览器自动打开
### 成功的启动日志
```
Starting MCP inspector...
⚙️ Proxy server listening on localhost:6277
🔑 Session token: 2f4e926ade2b4e0f266b696ff81c6872aa1f72f6e3e258cbfbca14a057c90518
🚀 MCP Inspector is up and running at:
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=2f4e926ade2b4e0f266b696ff81c6872aa1f72f6e3e258cbfbca14a057c90518
🌐 Opening browser...
```
## 使用说明
### 启动 MCP Inspector
```bash
npm run test:inspector
```
### 访问界面
1. 打开浏览器访问显示的 URL
2. 使用生成的会话令牌进行认证
3. 测试所有 MCP 工具功能
### 常见问题解决
- **端口冲突**：使用 `lsof -ti:6277 | xargs kill -9` 清理端口
- **构建缺失**：运行 `npm run build` 生成编译产物
- **权限问题**：使用 `chmod +x test-server.js` 添加执行权限
## 最佳实践
### 1. 开发工作流
- 修改代码后：`npm run build` → `npm run test:inspector`
- 使用 Inspector 测试工具功能
- 查看详细日志进行调试
### 2. 配置管理
- 保持 `.mcp-inspector.json` 配置正确
- 确保启动脚本可执行
- 定期清理端口占用
### 3. 错误排查
- 检查启动脚本是否存在：`ls -la test-server.js`
- 验证编译产物：`ls -la dist/index.js`
- 测试单独启动：`timeout 10 node test-server.js`
## 注意事项
- 确保在运行 MCP Inspector 前执行 `npm run build`
- 启动脚本需要执行权限（`chmod +x`）
- 端口 6277 和 6274 需要可用
- 测试完成后记得清理相关进程
## 影响范围
- **修复前**：无法使用 MCP Inspector 进行测试
- **修复后**：完全正常的开发和测试工作流
- **用户体验**：从连接错误到成功启动测试界面
