Safe Coder MCP 服务

一个基于 Model Context Protocol (MCP) 的服务器，提供以下功能：

• 最新库文档 - 从 npm、GitHub 和 HTTP 源获取文档
• 全面错误检测 - 使用 ESLint、TypeScript、模式匹配和上下文分析
• 代码验证 - 带自动修复功能
• 错误解决方案建议 - 针对常见编码问题

功能特性

文档获取

• 从 npm 注册表获取
• 从 GitHub 仓库获取
• 从直接 HTTP 文档站点获取
• 智能缓存，基于版本键和 TTL
• 热门包的背景刷新

错误检测

• 多层检测：
  1. ESLint - 代码质量检查
  2. TypeScript 编译器 - 类型检查
  3. 模式匹配 - 常见错误模式
  4. 上下文分析 - 未定义变量和 API 使用错误
• 优先级错误报告（语法 → 类型 → 运行时 → 逻辑 → 警告）

代码验证

• 完整的验证管道
• 自动修复常见错误（语法、缺失导入）
• 错误解决方案数据库
• 在代码展示前进行验证

安装方式

方式一：通过 npm 安装（推荐）

如果已发布到 npm：

# 全局安装
npm install -g @gulibs/safe-coder

# 或者本地安装到项目
npm install @gulibs/safe-coder

方式二：从源码安装

# 克隆或下载项目
git clone <repository-url>
cd safe-coder

# 安装依赖
npm install

# 构建项目
npm run build

配置

设置环境变量（可选）：

• CACHE_TTL_MINUTES - 文档缓存 TTL（分钟），默认：60
• GITHUB_TOKEN - GitHub API token（用于访问私有仓库，可选）
• ENABLE_AUTO_FIX - 启用自动修复，默认：true
• RATE_LIMIT_REQUESTS - 每个窗口的最大请求数，默认：100
• RATE_LIMIT_WINDOW_MS - 速率限制窗口（毫秒），默认：60000
• LOG_LEVEL - 日志级别：DEBUG、INFO、WARN、ERROR，默认：INFO
• LOG_COLORS - 启用彩色日志输出，默认：true（设置为 false 禁用）

代理配置（适用于国内网络环境）

如果无法直接访问 npm registry 或 GitHub API，可以配置代理：

• HTTP_PROXY 或 http_proxy - HTTP 代理地址，例如：http://127.0.0.1:7890
• HTTPS_PROXY 或 https_proxy - HTTPS 代理地址，例如：http://127.0.0.1:7890
• NO_PROXY 或 no_proxy - 不使用代理的地址列表（逗号分隔），例如：localhost,127.0.0.1

示例配置：

# 使用 HTTP/HTTPS 代理
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# 或者使用 SOCKS5 代理（如果代理支持）
export HTTP_PROXY=socks5://127.0.0.1:1080
export HTTPS_PROXY=socks5://127.0.0.1:1080

# 排除本地地址
export NO_PROXY=localhost,127.0.0.1,*.local

在 Cursor 配置文件中设置：

{
  "mcpServers": {
    "safe-coder": {
      "command": "npx",
      "args": ["-y", "@gulibs/safe-coder"],
      "env": {
        "HTTP_PROXY": "http://127.0.0.1:7890",
        "HTTPS_PROXY": "http://127.0.0.1:7890",
        "NO_PROXY": "localhost,127.0.0.1"
      }
    }
  }
}

使用方法

1. 运行服务器

# 开发模式（使用 tsx）
npm run dev

# 生产模式（需要先构建）
npm run build
npm start

服务器通过 stdio 运行，使用 MCP 协议进行通信。

2. 监控服务状态

查看日志

所有日志输出到 stderr（标准错误输出），包括：

• 服务器启动信息
• 工具调用记录（请求 ID、参数、执行时间）
• 错误和警告信息

日志格式示例：

[2024-01-01T12:00:00.000Z] [INFO] Safe Coder MCP server started {"version":"1.0.0","pid":12345}
[2024-01-01T12:00:00.100Z] [INFO] MCP server connected to transport
[2024-01-01T12:00:00.200Z] [INFO] Tool invoked: get_documentation {"requestId":"req-1234567890-1","tool":"get_documentation","params":{"packageName":"react"}}
[2024-01-01T12:00:00.500Z] [INFO] Tool completed: get_documentation {"requestId":"req-1234567890-1","tool":"get_documentation","duration":"500ms","success":true}

日志级别（通过 LOG_LEVEL 环境变量设置）：

• DEBUG - 详细调试信息
• INFO - 一般信息（工具调用、完成）默认
• WARN - 警告信息
• ERROR - 错误信息

使用 get_status 工具

在 Cursor 中，你可以调用 get_status 工具来查看服务器状态：

{
  "status": "running",
  "uptime": 3600,
  "version": "1.0.0",
  "tools": ["get_documentation", "detect_errors", "validate_code", "resolve_error", "get_status"],
  "cacheSize": 10,
  "pid": 12345
}

在 Cursor 中查看日志

1. 打开 Cursor 的开发者工具：

   • macOS: Cmd + Shift + P → "Developer: Toggle Developer Tools"
   • Windows/Linux: Ctrl + Shift + P → "Developer: Toggle Developer Tools"

2. 查看控制台：

   • 在开发者工具中切换到 "Console" 标签
   • MCP 服务器的日志会显示在这里

3. 启用调试模式：

在 Cursor 配置中添加：

{
  "mcpServers": {
    "safe-coder": {
      "command": "npx",
      "args": ["-y", "@gulibs/safe-coder"],
      "env": {
        "LOG_LEVEL": "DEBUG",
        "LOG_COLORS": "true"
      }
    }
  }
}

3. 在 Cursor 中配置

⚠️ 重要提示：如果包还没有发布到 npm，请使用"本地开发配置"方式。

步骤 1：找到 Cursor 配置文件

Cursor 的 MCP 配置文件位置：

• macOS: ~/Library/Application Support/Cursor/User/globalStorage/mcp.json
• Windows: %APPDATA%\Cursor\User\globalStorage\mcp.json
• Linux: ~/.config/Cursor/User/globalStorage/mcp.json

或者通过 Cursor 设置界面：

1. 打开 Cursor 设置（Cmd/Ctrl + ,）
2. 搜索 "MCP" 或 "Model Context Protocol"
3. 找到 MCP 服务器配置

步骤 2：添加配置

根据你的安装方式选择对应的配置：

方式 A：本地开发配置（推荐，如果包未发布）

使用项目的绝对路径：

{
  "mcpServers": {
    "safe-coder": {
      "command": "node",
      "args": ["/Users/wormhole/Documents/Developments/Our/mcp/safe-coder/dist/index.js"],
      "env": {
        "CACHE_TTL_MINUTES": "60",
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

获取你的项目路径：

# 在项目目录下运行
pwd

方式 B：通过 npm 安装（需要先发布到 npm）

如果包已发布到 npm，可以使用 npx：

{
  "mcpServers": {
    "safe-coder": {
      "command": "npx",
      "args": ["-y", "@gulibs/safe-coder"],
      "env": {
        "CACHE_TTL_MINUTES": "60",
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

或者全局安装后使用：

# 全局安装
npm install -g @gulibs/safe-coder

# 查看全局安装路径
npm root -g

然后配置（替换 <global-node-modules-path> 为实际路径）：

{
  "mcpServers": {
    "safe-coder": {
      "command": "node",
      "args": ["<global-node-modules-path>/@gulibs/safe-coder/dist/index.js"],
      "env": {
        "CACHE_TTL_MINUTES": "60",
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

如果从源码安装：

找到你安装的路径，然后配置：

{
  "mcpServers": {
    "safe-coder": {
      "command": "node",
      "args": ["/绝对路径/to/safe-coder/dist/index.js"],
      "env": {
        "CACHE_TTL_MINUTES": "60",
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

获取绝对路径的方法：

在项目目录下运行：

# macOS/Linux
pwd

# Windows PowerShell
(Get-Location).Path

如果使用本地项目安装（node_modules）：

{
  "mcpServers": {
    "safe-coder": {
      "command": "node",
      "args": ["./node_modules/@gulibs/safe-coder/dist/index.js"],
      "env": {
        "CACHE_TTL_MINUTES": "60",
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

步骤 3：验证配置

1. 检查配置文件格式：确保 JSON 格式正确，可以使用在线 JSON 验证器
2. 重启 Cursor：保存配置后，完全重启 Cursor
3. 检查连接状态：
   • 在 Cursor 设置中查看 MCP 服务器列表
   • 应该能看到 "safe-coder" 服务器
   • 状态应该显示为已连接（绿色）

步骤 4：测试工具

在 Cursor 的 AI 对话中测试：

请使用 get_documentation 工具获取 axios 库的文档

如果工具正常工作，说明配置成功！

3. 使用 MCP 工具

配置完成后，你可以在 Cursor 的 AI 对话中使用以下工具：

get_documentation - 获取文档

获取库或包的文档。

参数：

• packageName（必需）：包名（npm）、仓库（owner/repo）或 URL
• version（可选）：版本或分支 / 标签
• source（可选）：源类型（'npm'、'github'、'http'）- 如果不指定会自动检测

使用示例：

请帮我获取 axios 库的文档

或者直接调用：

{
  "packageName": "axios",
  "version": "latest",
  "source": "npm"
}

detect_errors - 检测错误

检测代码中的错误和警告。

参数：

• code（必需）：要分析的代码
• filename（可选）：用于上下文的文件名（默认：'code.ts'）

使用示例：

请检测这段代码的错误：
const x = y;
console.log(z);

validate_code - 验证代码

验证代码并可选择自动修复常见错误。

参数：

• code（必需）：要验证的代码
• filename（可选）：用于上下文的文件名
• autoFix（可选）：启用自动修复（默认：true）

使用示例：

请验证并修复这段代码：
function test() {
  return x
}

resolve_error - 解决错误

获取特定错误的解决方案建议。

参数：

• errorType（必需）：错误类型
• message（必需）：错误消息
• line（可选）：错误发生的行号

使用示例：

我遇到了一个 undefined-variable 错误，消息是 "Variable 'x' is used but not defined"，在第 5 行

4. 使用 MCP 资源

safe-coder://documentation - 缓存的文档

访问缓存的文档条目，查看缓存状态。

safe-coder://error-patterns - 错误模式数据库

访问错误模式数据库，查看已知的错误模式和解决方案。

开发

项目结构

safe-coder/
├── src/
│   ├── documentation/  # 文档获取和缓存
│   ├── errors/         # 错误检测（ESLint、TypeScript、模式、上下文）
│   ├── validation/     # 代码验证和自动修复
│   ├── server/         # MCP 服务器实现
│   ├── types/          # TypeScript 类型定义
│   ├── utils/          # 配置和工具函数
│   └── index.ts        # 入口文件
├── tests/              # 测试文件
├── dist/               # 编译输出
└── package.json

开发命令

# 安装依赖
npm install

# 构建项目
npm run build

# 开发模式运行（自动重新编译）
npm run dev

# 运行测试
npm test

# 监听模式运行测试
npm run test:watch

# 类型检查
npm run type-check

# 代码检查
npm run lint

调试

如果遇到问题，可以：

1. 检查服务器是否正常运行：

   npm run dev

   应该看到：Safe Coder MCP server running on stdio

2. 查看 Cursor 的 MCP 日志：

   • 在 Cursor 中打开开发者工具
   • 查看控制台中的 MCP 相关错误

3. 测试工具调用： 可以在 Cursor 的 AI 对话中直接请求使用工具，例如：

   请使用 get_documentation 工具获取 react 的文档

常见问题

Q: 服务器无法启动？

A: 检查以下几点：

• 确保已运行 npm install 和 npm run build
• 检查 Node.js 版本（建议 18+）
• 查看错误日志

Q: 无法获取 GitHub 文档？

A:

• 如果访问私有仓库，需要设置 GITHUB_TOKEN 环境变量
• 公开仓库通常不需要 token，但设置 token 可以提高速率限制

Q: 错误检测不准确？

A:

• 确保代码文件扩展名正确（.ts 用于 TypeScript，.js 用于 JavaScript）
• 某些复杂的错误可能需要更多上下文
• 可以尝试使用 validate_code 工具获得更全面的分析

Q: 如何更新错误模式数据库？

A:

• 编辑 src/errors/patterns.json 文件
• 添加新的错误模式
• 重新构建项目

发布到 npm（开发者）

如果你想将这个包发布到 npm：

1. 准备发布

# 确保已登录 npm
npm login

# 检查包名是否可用（如果已发布，需要更新版本号）
npm view @gulibs/safe-coder

# 更新版本号
npm version patch  # 或 minor, major

2. 发布

# 发布到 npm
npm publish

# 如果使用作用域包且是首次发布，需要添加访问权限
npm publish --access public

3. 验证发布

# 检查包是否已发布
npm view @gulibs/safe-coder

# 测试安装
npm install -g @gulibs/safe-coder

本地开发配置示例

如果你在本地开发，可以创建一个测试配置：

创建测试配置文件

在项目根目录创建 cursor-mcp-config.json：

{
  "mcpServers": {
    "safe-coder": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "CACHE_TTL_MINUTES": "60",
        "GITHUB_TOKEN": ""
      }
    }
  }
}

然后将此配置复制到 Cursor 的配置目录。

快速测试脚本

创建 test-mcp.sh（macOS/Linux）或 test-mcp.bat（Windows）：

#!/bin/bash
# test-mcp.sh

echo "构建项目..."
npm run build

echo "测试 MCP 服务器..."
node dist/index.js

故障排除

问题：Cursor 无法找到服务器

解决方案：

1. 检查路径是否正确（使用绝对路径）
2. 确保 dist/index.js 文件存在
3. 检查 Node.js 是否在 PATH 中：which node 或 where node

问题：服务器启动失败

解决方案：

1. 检查依赖是否安装：npm install
2. 检查构建是否成功：npm run build
3. 查看错误日志

问题：工具无法使用

解决方案：

1. 确认服务器在 Cursor 中显示为已连接
2. 检查 Cursor 版本是否支持 MCP
3. 查看 Cursor 开发者工具中的错误信息

问题：权限错误

解决方案：

# 确保 dist/index.js 有执行权限
chmod +x dist/index.js

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！