Pincer MCP

🚀 Pincer MCP 🦀

Pincer MCP 是一個經過安全強化的模型上下文協議（MCP）網關，它消除了自主人工智能系統中的“致命三重威脅”漏洞。通過充當無狀態中介，Pincer 確保代理程序永遠不會看到您的真實 API 密鑰。

🚀 快速開始

前提條件

• Node.js 18+
• 支持原生密鑰鏈的 macOS、Windows 或 Linux 系統

安裝

選項 1：全局安裝（推薦）

npm install -g pincer-mcp
# 現在 'pincer' 命令可在系統全局使用

選項 2：本地開發

git clone https://github.com/VouchlyAI/Pincer-MCP.git
cd Pincer-MCP
npm install
npm run build
npm link  # 使 'pincer' 命令在本地可用

設置密鑰庫

# 1. 初始化密鑰庫（在操作系統密鑰鏈中創建主密鑰）
pincer init

# 2. 存儲您的真實 API 密鑰（加密存儲）
pincer set gemini_api_key "AIzaSyDpxPq..."
pincer set openai_api_key "sk-proj-..."

# 3. 註冊一個代理程序並生成代理令牌
pincer agent add openclaw
# 輸出: 🎫 代理令牌: pxr_V1StGXR8_Z5jdHi6B-myT

# 4. 授權代理程序使用特定工具
pincer agent authorize openclaw gemini_generate

多密鑰支持

為同一工具存儲多個密鑰並將它們分配給不同的代理程序：

# 存儲兩個不同的 Gemini API 密鑰
pincer set gemini_api_key "AIzaSy_KEY_FOR_CLAWDBOT..." --label key1
pincer set gemini_api_key "AIzaSy_KEY_FOR_MYBOT..." --label key2

# 查看所有存儲的密鑰
pincer list

# 為每個代理程序分配特定的密鑰
pincer agent add clawdbot
pincer agent authorize clawdbot gemini_generate --key key1

pincer agent add mybot  
pincer agent authorize mybot gemini_generate --key key2

# 查看代理程序權限
pincer agent list

結果：clawdbot 使用 key1，mybot 使用 key2，非常適合進行速率限制或成本跟蹤！

運行服務器

npm run dev

配置您的代理程序

為您的代理程序提供代理令牌（而非真實的 API 密鑰）：

export PINCER_PROXY_TOKEN="pxr_V1StGXR8_Z5jdHi6B-myT"

進行工具調用

您的代理程序在請求體中攜帶代理令牌發送請求：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "gemini_generate",
    "arguments": {
      "prompt": "Hello world",
      "model": "gemini-2.0-flash"
    },
    "_meta": {
      "pincer_token": "pxr_V1StGXR8_Z5jdHi6B-myT"
    }
  }
}

Pincer 會將代理令牌映射到真實的 API 密鑰並安全地執行調用。

✨ 主要特性

Pincer-MCP 實現了一種**“矇眼”安全模型**：

1. 代理程序知曉：僅知曉唯一的代理令牌（pxr_abc123...）
2. Pincer 知曉：代理令牌到真實 API 密鑰的映射（加密存儲在操作系統密鑰鏈中）
3. 代理程序永遠看不到：實際的憑證

sequenceDiagram
    participant Agent
    participant Pincer
    participant Vault (OS Keychain)
    participant External API

    Agent->>Pincer: tools/call + proxy_token: pxr_abc123
    Pincer->>Vault: Decrypt real API key
    Vault-->>Pincer: gemini_api_key: AIzaSy...
    Pincer->>External API: API call with real key
    External API-->>Pincer: Response
    Pincer->>Pincer: Scrub key from memory
    Pincer-->>Agent: Response (no credentials)

📦 安裝指南

全局安裝（推薦）

npm install -g pincer-mcp

本地開發安裝

git clone https://github.com/VouchlyAI/Pincer-MCP.git
cd Pincer-MCP
npm install
npm run build
npm link

💻 使用示例

基礎用法

以下是一個使用 Pincer 進行工具調用的示例請求：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "gemini_generate",
    "arguments": {
      "prompt": "Hello world",
      "model": "gemini-2.0-flash"
    },
    "_meta": {
      "pincer_token": "pxr_V1StGXR8_Z5jdHi6B-myT"
    }
  }
}

高級用法

GPG 密鑰管理示例

# 生成一個新的 GPG 密鑰對（私鑰存儲在密鑰庫中）
pincer key generate --name "Release Signing" --email dev@example.com

# 導入現有的 PGP 私鑰
pincer key import ./my-key.asc --passphrase "my-passphrase"

# 列出所有存儲的 GPG 密鑰
pincer key list

# 導出公鑰（可安全共享）
pincer key export <key-id>

# 授權代理程序進行簽名
pincer agent authorize mybot gpg_sign_data --key <key-id>

📚 詳細文檔

• 設置指南 - 開始使用 Pincer-MCP
• IDE 集成 - 在 VSCode、Claude Desktop、Cursor 等工具中使用 Pincer
• OpenClaw 集成 - 將 Pincer 與 OpenClaw 代理程序集成
• 測試指南 - 綜合測試套件文檔
• 功能參考 - 完整的 API 和功能文檔
• 安全策略 - 漏洞報告和安全最佳實踐
• 更新日誌 - 版本歷史和發佈說明

🔧 技術細節

兩層密鑰庫系統

第一層：主密鑰（操作系統密鑰鏈）

• 存儲在 macOS 鑰匙串、Windows 憑據管理器或 GNOME 密鑰環中
• 從不接觸文件系統
• 僅用於加密/解密操作

第二層：加密存儲（SQLite）

• 數據庫位於 ~/.pincer/vault.db
• 包含三個表：
  • secrets：真實的 API 密鑰（使用 AES-256-GCM 加密）
  • proxy_tokens：代理令牌到代理程序 ID 的映射
  • agent_mappings：代理程序 ID 到工具授權的映射

認證流程

Request (_meta.pincer_token: pxr_xxx)
  ↓
Gatekeeper: Extract proxy token from body
  ↓
Vault: Resolve pxr_xxx → agent_id → tool_name → real_api_key
  ↓
Injector: JIT decrypt & inject real key
  ↓
Caller: Execute external API call
  ↓
Scrubber: Overwrite key in memory with zeros
  ↓
Audit: Log to tamper-evident chain

🔐 安全與合規

Pincer 專為企業級安全而構建：

• 硬件支持的加密：主加密密鑰永遠不會離開操作系統原生密鑰鏈。
• 代理令牌隔離：代理程序僅處理臨時的 pxr_ 令牌，從不接觸真實的憑證。
• 即時解密：僅在 API 調用期間解密機密信息。
• 零內存殘留：敏感數據在使用後立即從內存中清除（歸零）。
• 細粒度授權：嚴格的按代理程序、按工具的訪問控制策略。
• 防篡改審計日誌：使用 SHA-256 鏈式哈希的追加式工具調用歷史記錄。
• 強化執行：對所有輸入進行模式驗證並在受保護的環境中執行。
• 標準輸入輸出兼容：與標準的模型上下文協議傳輸完全兼容。

🔍 審計日誌

每次工具調用都會記錄到 ~/.pincer/audit.jsonl 中，包含 UTC 和本地時間戳、字符計數和估計的令牌使用情況：

{
  "agentId": "openclaw",
  "tool": "gemini_generate",
  "duration": 234,
  "status": "success",
  "input_chars": 156,
  "output_chars": 423,
  "estimated_input_tokens": 39,
  "estimated_output_tokens": 106,
  "timestamp_utc": "2026-02-05T08:32:00.000Z",
  "timestamp_local": "2/5/2026, 2:02:45 PM",
  "chainHash": "a1b2c3d4e5f6g7h8",
  "prevHash": "0000000000000000"
}

令牌估計：Pincer 使用 4:1 的字符到令牌比率（平均約 4 個字符對應 1 個令牌）自動估計令牌使用情況。這提供了跨所有 AI 提供商的一致成本跟蹤，而無需依賴特定提供商的 API。鏈式哈希提供篡改檢測功能 - 任何修改都會破壞 SHA-256 鏈。

📦 可用工具

• gemini_generate：安全的 Google Gemini API 調用。
• openai_chat：使用 OpenAI GPT 模型（gpt-4o、gpt-4-turbo、gpt-3.5-turbo 等）進行聊天完成。
• openai_list_models：列出所有可用的 OpenAI 模型。
• openai_compatible_chat：使用任何與 OpenAI 兼容的 API（Azure OpenAI、Ollama、vLLM 等）進行聊天完成。
• openai_compatible_list_models：列出自定義 OpenAI 兼容端點的模型。
• claude_chat：使用 Anthropic Claude 模型（Claude 3.5 Sonnet、Opus、Haiku）進行聊天完成。
• openrouter_chat：統一的 API 訪問，可訪問來自多個提供商（OpenAI、Anthropic、Google、Meta 等）的 100 多個模型。
• openrouter_list_models：列出 OpenRouter 提供商提供的所有可用模型。
• openwebui_chat：用於自託管大語言模型的 OpenAI 兼容接口。
• openwebui_list_models：發現 OpenWebUI 實例上的可用模型。
• gpg_sign_data：使用存儲在 Pincer 密鑰庫中的 GPG/PGP 私鑰對數據或文件進行簽名。(無密鑰執行 — 代理程序永遠不會看到密鑰)
• gpg_decrypt：使用存儲在密鑰庫中的私鑰解密 PGP 加密的數據。

🧪 開發

# 安裝依賴項
npm install

# 運行測試
npm test

# 以監聽模式運行
npm run dev

# 構建生產版本
npm run build

🤝 貢獻

歡迎貢獻代碼！請參閱 CONTRIBUTING.md 瞭解貢獻指南。

📄 許可證

本項目採用 BSL 1.1（商業源許可證），詳情請參閱 LICENSE。該許可證將於 2028 年 4 月 1 日轉換為 Apache 2.0 許可證。

• 模型上下文協議 - AI 工具集成的標準。
• keytar - 安全的跨平臺密鑰鏈訪問。
• better-sqlite3 - 高性能的本地持久化存儲。

為更安全的 AI 未來用心打造 ❤️