JinDaGe - pincer-mcp MCP Details

article

README

🚀 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 实现了一种**“蒙眼”安全模型**：

代理程序知晓：仅知晓唯一的代理令牌（pxr_abc123...）
Pincer 知晓：代理令牌到真实 API 密钥的映射（加密存储在操作系统密钥链中）
代理程序永远看不到：实际的凭证

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 未来用心打造 ❤️

pincer-mcp