mcp-server

🚀 SnapBack MCP Server

基于模型上下文协议（MCP），提供由人工智能驱动的代码分析和快照管理功能

将SnapBack的代码安全特性直接集成到Claude Desktop、Cursor以及任何支持MCP的人工智能工具中。

🚀 快速开始

npm install -g @snapback/mcp-server
snapback-mcp

立即生效，无需配置！

✨ 主要特性

🆓 免费版（无需账户）

• ✅ 风险分析：检测代码变更中的机密信息和安全漏洞
• ✅ 依赖检查：验证package.json文件的变更
• ✅ 本地分析：基础的机密信息检测和安全扫描
• ✅ 离线模式：无需网络连接即可使用
• ✅ Context7集成：库文档和代码搜索

☁️ 专业版（可选API密钥）

从 snapback.dev 获取免费的API密钥，解锁以下功能：

• 🔐 高级机器学习分析：由人工智能驱动的风险检测
• 🔐 快照管理：创建和恢复代码快照
• 🔐 云同步：跨设备访问代码快照
• 🔐 团队共享：在代码安全方面进行团队协作

📦 安装指南

Claude Desktop

在 ~/Library/Application Support/Claude/claude_desktop_config.json 文件中添加以下内容：

{
  "mcpServers": {
    "snapback": {
      "command": "npx",
      "args": ["-y", "@snapback/mcp-server"]
    }
  }
}

使用API密钥（可选）

{
  "mcpServers": {
    "snapback": {
      "command": "npx",
      "args": ["-y", "@snapback/mcp-server"],
      "env": {
        "SNAPBACK_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor / 其他MCP客户端

# 全局安装
npm install -g @snapback/mcp-server

# 使用标准输入输出传输运行
snapback-mcp

💻 使用示例

snapback.analyze_risk

在应用代码变更之前，分析潜在的安全风险。

使用场景：

• 在接受人工智能生成的代码之前
• 在审查复杂的代码变更时
• 对于关键文件（认证、数据库、配置文件）

示例：

// 人工智能检测到你要添加认证代码
// 在应用变更之前，调用以下代码：
snapback.analyze_risk({
  changes: [
    { added: true, value: "const API_KEY = 'sk_live_...';" }
  ]
})
// 返回：⚠️ 高风险：检测到硬编码的机密信息

snapback.check_dependencies

当 package.json 文件发生变更时，检查与依赖相关的风险。

示例：

snapback.check_dependencies({
  before: { "lodash": "^4.17.15" },
  after: { "lodash": "^4.17.21" }
})
// 返回：ℹ️ 有安全更新可用

snapback.create_snapshot（专业版）

在进行有风险的代码变更之前，创建代码快照。

示例：

snapback.create_snapshot({
  reason: "Before major refactor",
  files: ["src/auth.ts", "src/db.ts"]
})
// 返回：✅ 快照已创建：snap_xyz123

snapback.list_snapshots（专业版）

列出所有可用的代码快照。

snapback.restore_snapshot（专业版）

从之前的代码快照中恢复代码。

Context7工具

• ctx7.resolve-library-id：查找库文档
• ctx7.get-library-docs：获取库文档和示例

📚 详细文档

环境变量

# 可选：用于专业版功能的SnapBack API密钥
SNAPBACK_API_KEY=sk_...

# 可选：自定义API URL
SNAPBACK_API_URL=https://api.snapback.dev

# 可选：用于增强文档功能的Context7 API密钥
CONTEXT7_API_KEY=...

# 可选：日志级别
LOG_LEVEL=info

离线模式

无需任何配置或API密钥即可完美运行：

# 无需环境变量！
npx @snapback/mcp-server

离线可用功能：

• 风险分析（基础）
• 依赖检查
• 机密信息检测
• Context7库搜索（缓存）

需要API密钥的功能：

• 高级机器学习风险分析
• 快照创建/恢复
• 云同步
• 团队功能

架构

┌─────────────────┐
│   AI Tool       │  (Claude, Cursor, etc.)
│   (MCP Client)  │
└────────┬────────┘
         │ MCP Protocol
         │
┌────────▼─────────────────────────────────┐
│  SnapBack MCP Server                     │
│  ┌──────────────┐  ┌──────────────────┐ │
│  │ Free Tools   │  │  Pro Tools       │ │
│  │ - analyze    │  │  - snapshots     │ │
│  │ - check_deps │  │  - cloud sync    │ │
│  └──────────────┘  └──────────────────┘ │
└───────────┬──────────────────────────────┘
            │
        ┌───┴────┐
        │        │
   ┌────▼───┐ ┌─▼─────────┐
   │ Local  │ │ SnapBack  │
   │Analysis│ │    API    │
   └────────┘ └───────────┘

开发

本地运行

git clone https://github.com/snapback-dev/mcp-server.git
cd mcp-server

pnpm install
pnpm build
pnpm start

测试

# 运行测试
pnpm test

# 在无API密钥的情况下测试（离线模式）
unset SNAPBACK_API_KEY
pnpm start

# 使用API密钥进行测试
export SNAPBACK_API_KEY=sk_test_...
pnpm start

构建

pnpm build

# 输出：dist/index.js (ESM)

故障排除

服务器无法启动

1. 检查Node.js版本：node -v（需要18+）
2. 清除缓存：rm -rf node_modules && npm install
3. 检查权限：chmod +x $(which snapback-mcp)

API密钥无效

1. 验证密钥格式：sk_live_... 或 sk_test_...
2. 检查环境变量：echo $SNAPBACK_API_KEY
3. 获取新密钥：snapback.dev/settings/api

工具未在Claude中显示

1. 完全重启Claude Desktop
2. 检查配置文件语法（JSON必须有效）
3. 在Claude的控制台日志中查找错误信息

🔧 技术细节

• 所有机密信息通过环境变量处理
• 没有API密钥时，不会向SnapBack发送任何数据
• 本地分析可离线运行
• 开源项目 - 你可以自行审查代码

安全问题报告

如有安全问题，请发送邮件至 security@snapback.dev

📄 许可证

本项目采用Apache-2.0许可证，版权归SnapBack所有。

相关项目

• snapback VS Code扩展
• @snapback/sdk - TypeScript SDK
• @snapback/contracts - 类型定义

链接

• 文档：docs.snapback.dev
• 主仓库：Marcelle-Labs/snapback.dev
• 问题反馈：github.com/snapback-dev/mcp-server/issues
• NPM：@snapback/mcp-server