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