Onetimesecret MCP

🚀 Amp CLI Bridge - ファイルベースの通信システム

このディレクトリには、ファイルベースのメッセージキューシステムが含まれており、Claude CodeがClaude Codeのクレジットを消費することなくAmp CLIの機能を利用できるようにします。

🚀 クイックスタート

1. ウォッチャーの起動

別のターミナルで以下のコマンドを実行します。

./scripts/amp/start-amp-watcher.sh

これにより、prompts/pending/ ディレクトリの新しいファイルを監視するバックグラウンドのウォッチャープロセスが起動します。

2. Claude Codeからの使用

Claude Codeのセッションで以下のように入力します。

You: "Use @agent-amp-bridge to research TypeScript 5.0 features"

エージェントは以下の手順を実行します。

1. prompts/pending/ にプロンプトファイルを作成します。
2. ウォッチャーがそれを処理するのを待ちます。
3. responses/ready/ からレスポンスを読み取ります。
4. 結果を表示します。

3. ウォッチャーの停止

作業が終了したら、以下のコマンドを実行します。

./scripts/amp/stop-amp-watcher.sh

✨ 主な機能

• クレジット不要: Claude Codeのクレジットを一切消費しません。
• 非同期処理: Claude Codeはレスポンスを待つ間にブロックされません。
• 耐障害性: ファイルベースのキューなので、クラッシュや再起動にも耐えます。
• 監査証跡: すべてのプロンプトとレスポンスが保存され、デバッグやレビューに利用できます。
• 再利用性: プロンプトを再実行したり、過去のレスポンスを確認できます。

📦 インストール

このディレクトリが存在しないか不完全な場合、以下のコマンドで作成します。

# プロジェクトのルートから
mkdir -p .claude/amp/prompts/pending
mkdir -p .claude/amp/responses/{ready,consumed}

注意: このディレクトリはgitignoredに設定されており（ユーザー固有の作業スペース）、必要に応じてローカルで作成されます。

💻 使用例

基本的な使用法

Claude Codeのセッションで以下のように入力します。

You: "Use @agent-amp-bridge to research TypeScript 5.0 features"

高度な使用法

カスタムタイムアウトを設定する場合、以下のようなJSONを使用します。

{
  "prompt": "Complex analysis task",
  "options": {
    "timeout": 600000  // 10分
  }
}

📚 ドキュメント

概要

Amp CLI Bridgeを使用すると、Claude Code内からAmp CLIに調査リクエスト、コード分析タスク、その他のプロンプトを送信でき、結果はファイルベースのキューを通じて非同期に返されます。

アーキテクチャ

Claude Code (@agent-amp-bridge)
    ↓
    writes prompt to → prompts/pending/{uuid}.json
                              ↓
                    amp-watcher.js (separate process)
                              ↓
                    executes → amp -x "prompt"
                              ↓
                    writes → responses/ready/{uuid}.json
                              ↓
    Claude Code reads ← response

ディレクトリ構造

.claude/amp/
├── prompts/
│   ├── pending/        # 新しいプロンプトのキュー (amp-watcher.jsによって監視される)
│   └── processed/      # 完了したプロンプトのアーカイブ
├── responses/
│   ├── ready/          # Ampからのレスポンス (Claude Codeによって読み取られる)
│   └── consumed/       # 消費されたレスポンスのアーカイブ
├── amp-watcher.js      # プロンプトを処理するNode.jsのファイルウォッチャー
├── config.json         # 設定ファイル
├── amp-watcher.log     # ウォッチャーのログ
└── README.md           # このファイル

設定

.claude/amp/config.json を編集します。

{
  "pollInterval": 1000,      // 新しいプロンプトを1秒ごとにチェック
  "timeout": 300000,         // プロンプトごとに5分のタイムアウト
  "debug": false,            // デバッグログを有効にする
  "ampCommand": "amp"        // Amp CLIコマンドのパス
}

メッセージ形式

プロンプトファイル

場所: prompts/pending/{uuid}.json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-11-04T20:00:00.000Z",
  "prompt": "Your research question or task here",
  "context": {
    "project": "mcp-memory-service",
    "cwd": "/path/to/project",
    "tags": ["research", "typescript"]
  },
  "options": {
    "timeout": 300000,
    "format": "markdown"
  }
}

レスポンスファイル

場所: responses/ready/{uuid}.json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-11-04T20:05:00.000Z",
  "success": true,
  "output": "Amp CLI response content here...",
  "error": null,
  "duration": 300000,
  "originalPrompt": { /* echo of prompt for reference */ }
}

ヘルパースクリプト

scripts/amp/ にあるスクリプトです。

• start-amp-watcher.sh - ウォッチャーをバックグラウンドで起動します。
• stop-amp-watcher.sh - ウォッチャーを正常に停止します。
• test-amp-bridge.sh - 統合テストを実行します（テスト用のプロンプトを作成し、レスポンスを待ちます）。

トラブルシューティング

ウォッチャーが処理していない場合

実行中か確認する

cat .claude/amp/amp-watcher.pid
ps -p $(cat .claude/amp/amp-watcher.pid)

ログを確認する

tail -50 .claude/amp/amp-watcher.log

再起動する

./scripts/amp/stop-amp-watcher.sh
./scripts/amp/start-amp-watcher.sh

Amp CLIエラーの場合

Ampを直接テストする

amp -x "What is 2+2?"

一般的なエラーと解決策

• Insufficient credit balance - 無料枠の上限に達しました。
  • 解決策: クレジットの更新を待つか、https://ampcode.com/settings でアップグレードします。
• Command not found: amp - Amp CLIがインストールされていません。
  • 解決策: npm install -g @sourcegraph/amp

統合テスト

./scripts/amp/test-amp-bridge.sh

これにより、簡単なテストプロンプト（"What is 2+2?"）が作成され、レスポンスを待ち、成功を検証します。

使用例

✅ Web調査: "Research latest React 18 features and concurrent rendering" ✅ コード分析: "Analyze the storage backend architecture in src/storage/" ✅ ドキュメント生成: "Generate comprehensive API docs for MCP tools" ✅ コード生成: "Create TypeScript type definitions for the API" ✅ ベストプラクティス: "Find OAuth 2.1 security recommendations and implementation patterns"

制限事項

• ⏱️ レイテンシー - ファイルポーリングにより、リクエストごとに約1秒のオーバーヘッドが追加されます。
• 💰 Ampクレジット - 依然としてAmp APIのクレジットを消費します（無料枠の制限が適用されます）。
• 🔄 手動起動 - ウォッチャーは別のターミナルで手動で起動する必要があります。
• 📝 調査に最適 - 非同期の調査タスクに最適化されており、リアルタイムの対話には向いていません。

🔧 技術詳細

ウォッチャーの実装

amp-watcher.js スクリプトは以下の処理を行います。

1. prompts/pending/ を1秒ごとにポーリングします（設定可能）。
2. 見つかった各 .json ファイルに対して、以下の処理を行います。
   • プロンプトを読み取ります。
   • amp -x "{prompt}" を実行します。
   • stdout/stderrをキャプチャします。
   • レスポンスを responses/ready/ に書き込みます。
   • プロンプトを prompts/processed/ に移動します。
3. エラーを適切に処理します（エラーレスポンスを書き込みます）。
4. 正常なシャットダウンをサポートします（SIGTERM/SIGINT）。

エージェントの実装

@agent-amp-bridge Claude Codeエージェントは以下の処理を行います。

1. リクエスト追跡用のUUIDを生成します。
2. プロンプトJSONを prompts/pending/ に書き込みます。
3. responses/ready/ をポーリングして、一致するUUIDを探します。
4. 利用可能になったらレスポンスを読み取り、解析します。
5. レスポンスを responses/consumed/ に移動します。
6. フォーマットされた出力をユーザーに表示します。

ファイルのクリーンアップ

デバッグ用にアーカイブが保持されます。

• prompts/processed/ - 完了したプロンプト
• responses/consumed/ - 消費されたレスポンス

手動でのクリーンアップ（オプション）

# 7日以上前のアーカイブを削除
find .claude/amp/prompts/processed -name "*.json" -mtime +7 -delete
find .claude/amp/responses/consumed -name "*.json" -mtime +7 -delete

開発者向け情報

システムの拡張

リクエストごとのカスタムタイムアウト

{
  "prompt": "Complex analysis task",
  "options": {
    "timeout": 600000  // 10分
  }
}

デバッグモード

node .claude/amp/amp-watcher.js --debug

カスタムポーリング間隔

node .claude/amp/amp-watcher.js --interval 500  // 500ms

変更のテスト

1. amp-watcher.js またはエージェントに変更を加えます。
2. ウォッチャーを再起動します: ./scripts/amp/stop-amp-watcher.sh && ./scripts/amp/start-amp-watcher.sh
3. 統合テストを実行します: ./scripts/amp/test-amp-bridge.sh

サポート

• ドキュメント: CLAUDE.mdの "Amp CLI Bridge" セクションを参照してください。
• 問題報告: https://github.com/doobidoo/mcp-memory-service/issues で報告してください。
• Amp CLIドキュメント: https://ampcode.com/manual