pincer

Pincer MCP 🦀

Pincer-MCP 是一个经过安全强化的模型上下文协议（MCP）网关，可消除智能 Agent 系统中的“致命三位一体”漏洞。通过充当无状态中间层，Pincer 可确保 Agent 永远看不到你的真实 API 密钥。

🔒 问题

当前的 AI Agent 会将长期有效的 API 密钥以明文形式存储在 .env 文件或本地数据库中。如果因提示词注入或主机入侵而遭到破坏，攻击者便可直接访问你的：

• 数据库密码
• 第三方 API 密钥

✨ 解决方案：代理令牌架构

Pincer 实现了一种**“蒙眼”安全模型**：

1. Agent 知道：只有唯一的代理令牌（pxr_abc123...）
2. Pincer 知道：代理令牌 → 真实 API 密钥的映射（加密存储在操作系统密钥链中）
3. Agent 永远看不到：实际凭据

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)

📦 可用工具

• 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：统一调用来自多个提供商的 100 多种模型（OpenAI、Anthropic、Google、Meta 等）。
• openrouter_list_models：列出 OpenRouter 各提供商的所有可用模型。
• openwebui_chat：为可自托管的大模型提供兼容 OpenAI 的接口。
• openwebui_list_models：发现 OpenWebUI 实例上可用的模型。
• gpg_sign_data：使用存储在 Pincer 保险库中的 GPG/PGP 私钥对数据或文件签名。（无密钥执行 — Agent 永远看不到密钥）
• gpg_decrypt：使用存储在保险库中的私钥解密 PGP 加密数据。

🔑 GPG 密钥管理

# Generate a new GPG keypair (private key stored in vault)
pincer key generate --name "Release Signing" --email [email protected]

# Import an existing PGP private key
pincer key import ./my-key.asc --passphrase "my-passphrase"

# List all stored GPG keys
pincer key list

# Export public key (safe to share)
pincer key export <key-id>

# Authorize an agent for signing
pincer agent authorize mybot gpg_sign_data --key <key-id>

（更多调用方即将推出！）

🚀 快速开始

前提条件

• Node.js 18+
• 支持原生密钥链的 macOS、Windows 或 Linux

安装

选项 1：全局安装（推荐）

npm install -g pincer-mcp
# Now 'pincer' command is available system-wide

选项 2：本地开发

git clone https://github.com/VouchlyAI/Pincer-MCP.git
cd Pincer-MCP
npm install
npm run build
npm link  # Makes 'pincer' command available locally

设置保险库

# 1. Initialize vault (creates master key in OS keychain)
pincer init

# 2. Store your real API keys (encrypted)
pincer set gemini_api_key "AIzaSyDpxPq..."
pincer set openai_api_key "sk-proj-..."

# 3. Register an agent and generate proxy token
pincer agent add openclaw
# Output: 🎫 Proxy Token: pxr_V1StGXR8_Z5jdHi6B-myT

# 4. Authorize the agent for specific tools
pincer agent authorize openclaw gemini_generate

多密钥支持

为同一工具存储多个密钥，并将它们分配给不同的 Agent：

# Store two different Gemini API keys
pincer set gemini_api_key "AIzaSy_KEY_FOR_CLAWDBOT..." --label key1
pincer set gemini_api_key "AIzaSy_KEY_FOR_MYBOT..." --label key2

# View all stored keys
pincer list

# Assign specific keys to each agent
pincer agent add clawdbot
pincer agent authorize clawdbot gemini_generate --key key1

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

# View agent permissions
pincer agent list

结果：clawdbot 使用 key1，mybot 使用 key2——非常适合速率限制或成本跟踪！

运行服务

npm run dev

配置 Agent

为你的 Agent 提供代理令牌（而非真实 API 密钥）：

export PINCER_PROXY_TOKEN="pxr_V1StGXR8_Z5jdHi6B-myT"

工具到密钥名称的映射

存储密钥时，必须为每个工具使用正确的密钥名称。完整参考请参阅 工具映射指南。

运行 pincer agent authorize myagent gemini_generate 时，Pincer 会在调用该工具时注入 gemini_api_key 密钥。

发起工具调用

你的 Agent 会在请求正文中发送代理令牌：

{
  "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 密钥，并安全地执行调用。

🏗️ 架构

双层保险库系统

第 1 层：主密钥（OS 钥匙串）

• 存储在 macOS Keychain、Windows Credential Manager 或 GNOME Keyring 中
• 绝不会接触文件系统
• 仅用于加密／解密

第 2 层：加密存储（SQLite）

• 数据库位于 ~/.pincer/vault.db
• 包含三张表：
  • secrets：真实 API 密钥（使用 AES-256-GCM 加密）
  • proxy_tokens：代理令牌 → Agent ID 映射
  • agent_mappings：Agent 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 专为企业级安全而打造：

• 硬件支持的加密：主加密密钥不会离开 OS 原生钥匙串。
• 代理令牌隔离：Agent 只处理临时的 pxr_ 令牌；绝不会接触真实凭据。
• 即时解密：密钥仅在 API 调用期间解密。
• 内存零残留：敏感数据使用后会立即从内存中清除（置零）。
• 细粒度授权：严格执行按 Agent、按工具的访问控制策略。
• 防篡改审计日志：仅追加的工具调用历史记录，并使用 SHA-256 链式哈希。
• 强化执行：对所有输入进行架构验证，并在受保护的环境中执行。
• 兼容 Stdio：完全兼容标准的 Model Context Protocol 传输方式。

🔍 审计日志

每次工具调用都会记录到 ~/.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。

Chain hashes provide tamper detection - any modification breaks the SHA-256 chain.

## 🧪 Development

```bash
# Install dependencies
npm install

# Run tests
npm test

# Run with watch mode
npm run dev

# Build for production
npm run build

📚 文档

• 设置指南 - 开始使用 Pincer-MCP
• IDE 集成 - 将 Pincer 与 VSCode、Claude Desktop、Cursor 等配合使用
• OpenClaw 集成 - 将 Pincer 集成到 OpenClaw Agent 中
• 测试指南 - 完整的测试套件文档
• 功能参考 - 完整的 API 和功能文档
• 安全策略 - 漏洞报告和安全最佳实践
• 更新日志 - 版本历史和发布说明

🤝 参与贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解相关指南。

📄 许可证

BSL 1.1（Business Source License）——详情请参阅 LICENSE。将于 2028-04-01 转为 Apache 2.0。

• Model Context Protocol - AI 工具集成标准。
• keytar - 安全的跨平台钥匙串访问。
• better-sqlite3 - 高性能本地持久化。

---

为更安全的 AI 未来倾心打造。