pincer

Pincer MCP 🦀

Pincer-MCP は、エージェント型 AI システムにおける「致命的な三位一体」の脆弱性を排除する、セキュリティ強化型の Model Context Protocol（MCP）ゲートウェイです。ステートレスな仲介役として動作することで、エージェントに実際の API キーを決して見せません。

🔒 問題

現在の AI エージェントは、有効期間の長い API キーを平文の .env ファイルやローカルデータベースに保存しています。プロンプトインジェクションやホストへの侵入によって侵害された場合、攻撃者は次の情報に直接アクセスできます。

• データベースのパスワード
• サードパーティの API キー

✨ 解決策：プロキシトークンアーキテクチャ

Pincer は、「目隠し」セキュリティモデルを実装しています。

1. エージェントが知る情報：一意のプロキシトークン（pxr_abc123...）のみ
2. Pincer が知る情報：プロキシトークンから実際の API キーへの対応関係（OS のキーチェーン内で暗号化）
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)

📦 利用可能なツール

• 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：複数のプロバイダー（OpenAI、Anthropic、Google、Meta など）の 100 以上のモデルに統一 API でアクセス。
• openrouter_list_models：OpenRouter プロバイダー全体で利用可能なモデルをすべて一覧表示。
• openwebui_chat：セルフホスト型 LLM 向けの OpenAI 互換インターフェース。
• openwebui_list_models：OpenWebUI インスタンスで利用可能なモデルを検出。
• gpg_sign_data：Pincer の保管庫に保存された GPG/PGP 秘密鍵を使ってデータまたはファイルに署名します。(鍵を使わない実行 — エージェントに鍵が見えることはありません)
• 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

複数のキーへの対応

同じツール用に複数のキーを保存し、それぞれを異なるエージェントに割り当てられます。

# 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

エージェントの設定

実際の API キーではなく、プロキシトークンをエージェントに渡してください。

export PINCER_PROXY_TOKEN="pxr_V1StGXR8_Z5jdHi6B-myT"

ツールとシークレット名の対応

シークレットを保存する際は、各ツールに正しいシークレット名を使用する必要があります。詳細については、**ツール対応ガイド**を参照してください。

pincer agent authorize myagent gemini_generate を実行すると、そのツールの呼び出し時に Pincer が gemini_api_key シークレットを注入します。

ツールを呼び出す

エージェントは、プロキシトークンを本文に含めてリクエストを送信します。

{
  "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 キーに対応付け、安全に呼び出しを実行します。

🏗️ アーキテクチャ

2 層のボールトシステム

第 1 層：マスターキー（OS キーチェーン）

• macOS Keychain、Windows Credential Manager、または GNOME Keyring に保存されます
• ファイルシステムに触れることはありません
• 暗号化と復号にのみ使用されます

第 2 層：暗号化ストア（SQLite）

• データベースは ~/.pincer/vault.db にあります
• 3 つのテーブルがあります：
  • 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 は、エンタープライズレベルのセキュリティを実現するよう設計されています。

• ハードウェアで保護された暗号化：マスター暗号化キーが OS ネイティブのキーチェーンから外部に出ることはありません。
• プロキシトークンの分離：エージェントが扱うのは一時的な pxr_ トークンのみで、実際の認証情報に触れることはありません。
• JIT 復号：シークレットは API 呼び出しの実行中に限り復号されます。
• メモリ上の痕跡をゼロに：機密データは使用後すぐにメモリから消去（ゼロ化）されます。
• きめ細かな認可：エージェントごと、ツールごとの厳格なアクセス制御ポリシーを適用します。
• 改ざん検知可能な監査ログ：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 トークン）として、トークン使用量を自動的に推定します。これにより、プロバイダー固有の API に依存することなく、すべての AI プロバイダーで一貫したコスト追跡が可能になります。

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 連携 - VSCode、Claude Desktop、Cursor などで Pincer を使用する
• OpenClaw 連携 - Pincer を OpenClaw エージェントと連携する
• テストガイド - テストスイートの詳細なドキュメント
• 機能リファレンス - API と機能の完全なドキュメント
• セキュリティポリシー - 脆弱性の報告方法とセキュリティのベストプラクティス
• 変更履歴 - バージョン履歴とリリースノート

🤝 貢献

貢献を歓迎します！ガイドラインについては、CONTRIBUTING.md を参照してください。

📄 ライセンス

BSL 1.1（Business Source License）— 詳細については LICENSE を参照してください。2028-04-01 に Apache 2.0 に移行します。

• Model Context Protocol - AI ツール連携の標準です。
• keytar - クロスプラットフォームで安全なキーチェーンアクセスを提供します。
• better-sqlite3 - 高性能なローカル永続化を実現します。

---

より安全な AI の未来を目指して、心を込めて開発しました。