Agent Pattern MCP

agent-pattern-mcp

AI コーディングエージェントにエージェントシステム設計の専門知識を提供する MCP（Model Context Protocol）サーバーです。要件文字列とドメインを受け取ると、問題を分析し、一致するエージェントパターン（組み込みの 68 パターンから）を選択して、エージェント、関係、ツールの契約、状態モデル、メッセージ契約を含む具体的なエージェントシステム設計を生成し、品質属性（信頼性、コスト効率、レイテンシ、出力品質、可観測性、安全性、シンプルさ）に照らして評価します。実装を自ら記述するコーディングエージェントは、設計を生成せずに、トポロジーとスコア付きパターンの指針を得るため analyze_agent_system を呼び出せます。

---

目次

• ⚡ クイックスタート
• AI エージェント経由でインストール
• 🔌 エージェントを接続
  • Claude Code
  • OpenCode
  • Codex CLI
• 🧑‍🏫 AI エージェント向け SKILL
• 🧪 ツールを使う
  • 最初のエージェントシステムを設計する
  • パターンカタログを確認する
• 🛠️ ツールの概要
• 📖 パターンカタログ
• インストール方法の選択肢
  • Docker（手動）
  • ローカル開発（uv）
• 設定
• 構造化推論（shannonthinking / code-reasoning）
• カスタムパターンによる拡張
• 長時間実行されるツールとタイムアウト
• トラブルシューティング
• ビルドと開発
• 公開
• systemd サービス（Linux）
• ライセンス

⚡ クイックスタート

# 1. Clone
git clone https://github.com/olk/agent-pattern-mcp.git && cd agent-pattern-mcp

# 2. Add your API key (the dev compose reads MINIMAXAI_API_KEY and pins
#    GENERATOR_PROVIDER=minimax)
export MINIMAXAI_API_KEY=sk-...

# 3. Start (needs images: `make docker-build-all` once, or prebuilt pulls
#    per INSTALL.md Path A)
docker compose -f docker/docker-compose.yml up -d

# 4. Demo (analyze-only: fast. For the full design: make client-design)
make client-analyze

サーバーは http://localhost:8821/mcp で streamable-http として起動します（開発用 compose のホストポート。systemd では 8811 を使用）。その後、以下の手順でエージェントを接続してください。

---

AI エージェント経由でインストール

AI コーディングエージェントに、事前ビルド済みイメージから Docker スタックをインストールさせる場合（ローカルでのビルド不要）、非対話型のエージェント向け手順書である INSTALL.md（コピー＆ペースト用コマンド、想定される出力、検証プローブ）を参照させてください。

Clone this repo, then follow INSTALL.md Path A (compose stack, port 8821).
My generator API key is: sk-...

INSTALL.md のいずれかの方法を選択してください。

• 方法 A — Compose スタック（:8821）：評価／開発向け。sudo は不要です。TEI サイドカーのコピーを独自に使用します。
• 方法 B — systemd スタック（:8811）：永続的なホストサービスで、ブート時に起動します。sudo が必要です。共有の pattern-tei-infra TEI スタックを使用します。

エージェントには、リポジトリのクローン、グループへの所属設定が済んだ Docker ≥ v2.20、約 5 GB の空き容量、MINIMAXAI_API_KEY（または INSTALL.md#switching-the-generator-llm に記載された別のプロバイダー）、および linux/amd64 が必要です（arm64 では make docker-build-all を使ってローカルでビルドします）。インストール後、以下のエージェントを接続に進んでください。

---

🔌 エージェントを接続

Claude Code

# Install (one-time)
uv pip install -e .

# Run as stdio subprocess — pass API key via env
claude mcp add agent-pattern \
  -e GENERATOR_API_KEY=your_key \
  -e GENERATOR_PROVIDER=openai \
  -- agent-pattern-mcp --transport stdio

または、チーム全体で使えるようにプロジェクトに追加します。

claude mcp add --scope project agent-pattern \
  -e GENERATOR_API_KEY=your_key \
  -- agent-pattern-mcp --transport stdio

OpenCode

OpenCode は HTTP トランスポートを使用します。先にサーバーを起動してから、opencode を設定してください。

# Terminal 1: start the server
docker compose -f docker/docker-compose.yml up --build   # serves :8821
# or locally on the same port:
uv run python -m src.main --port 8821

# Terminal 2: add to ~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agent-pattern": {
      "type": "remote",
      "url": "http://localhost:8821/mcp"
    }
  }
}

注： GENERATOR_API_KEY は opencode の環境変数からではなく、サーバーの設定ファイル（~/.config/agent-pattern-mcp/config.json）から読み込まれます。

Codex CLI

# Install (one-time)
uv pip install -e .

~/.codex/config.toml に追加します。

[mcp_servers.agent-pattern]
command = "agent-pattern-mcp"
args = ["--transport", "stdio"]

[mcp_servers.agent-pattern.env]
GENERATOR_API_KEY = "your_key"
GENERATOR_PROVIDER = "openai"

または CLI 経由で追加します。

codex mcp add agent-pattern \
  -e GENERATOR_API_KEY=your_key \
  -- agent-pattern-mcp --transport stdio

---

🧑‍🏫 AI エージェント向け SKILL

skills/agent-pattern-mcp/ の SKILL は Oh My Pi（OMP） 向けに書かれており、このサーバーのツールには xd://mcp__agent_pattern_* デバイスとしてアクセスします。また、すべての MCP リクエストにはデッドラインが設定されています（OMP_MCP_TIMEOUT_MS → サーバーごとの timeout → 30 s）。この SKILL では、デッドラインに適したエントリーポイント、結果の読み方、ワークフローのレシピ一式をエージェントに説明します。

skills/agent-pattern-mcp/
├── SKILL.md                 # OMP constraints, entry-point decision guide, device quick reference
└── references/
    ├── tools.md             # 9 tool signatures, output schemas, error codes, design-dict shape
    └── workflows.md         # recipes, result interpretation, OMP troubleshooting

OMP へのインストール — スキルディレクトリをユーザースキルのルートにコピーするか、OMP の設定で skills.customDirectories がこのリポジトリの skills/ ディレクトリを指すようにします。

cp -r skills/agent-pattern-mcp ~/.omp/agent/skills/

その後、スキルはエージェントに次の内容を説明します。

• OMP のデッドラインに適したエントリーポイント：デフォルトでは非同期ジョブの 3 つのツールを使用し、単発の design_agent_system はサーバーの timeout を延長した場合にのみ使用します（デフォルトの 30 s ではすべての LLM ツールが中断されます。submit_agent_design_job は約 0.05 s で応答します）
• analyze_agent_system は、コードを自分で書くコーディングエージェント向けの分析専用パスであり、トポロジー、スコア付きパターン、品質メトリクスを返すものの、設計は生成しません。一方、design_agent_system は設計成果物を必要とする呼び出し元向けです
• requirements、domain、topology を、それぞれ独立した構造化引数として指定する方法
• final_quality_score、attempts > 1、evaluation.recommendations の解釈方法
• 兄弟関係にある architecture-pattern サーバーが接続されている場合、read mcp://pattern://… は曖昧なため、ツールルート（get_agent_pattern）を正とすること

references/ にあるツールスキーマ、エラーコード、設計辞書の形式はクライアントに依存しません。デッドラインとデバイスに関する説明のみが OMP 固有です。

---

🧪 ツールを使う

すべてのツールは、引数として requirements（自由記述）と domain（例：tool-use-tasks、data-processing、customer-support）を受け取ります。以下の例では、どの MCP クライアントや API コンシューマーでも使えるよう、正確なツール呼び出しの形式を示します。

最初のエージェントシステムを設計する

Claude Code（または任意の MCP クライアント）で、次の自然言語の指示を貼り付けます。

Build a research assistant agent that answers multi-hop questions by combining
web search results with sandboxed Python computation, iterating until it can
synthesise a final cited answer.

エージェントは内部で design_agent_system を呼び出します。サーバーは、エージェント（planner、searcher、coder、synthesizer）、品質属性のスコア（reliability：8.0、output_quality：8.5、…）、具体的な推奨事項を含む、エージェントシステムの設計一式を返します。

これが設計パスです。サーバーの LLM が設計成果物を生成するため、呼び出しには数分かかります。エージェントが自分で実装を書き、パターンの専門知識だけが必要な場合は、代わりに analyze_agent_system を呼び出してください。設計を生成せずに、推奨トポロジー、スコア付きで選択されたパターン、属性ごとに 0～10 で示される quality_metrics、該当するドメインを返すため、生成フェーズと評価フェーズは実行されません。計測結果：このホストで analyze_agent_system を 1 回実行したところ 23.3 s で応答しました。一方、コミット済みのフルパイプラインコーパスでは、20 のシナリオで p50 が約 304 s、p95 が約 375 s でした（benchmarks/base/summary.json）。

**または、**エージェントからツールを直接呼び出します。

Call analyze_agent_system with:
  requirements: "Research assistant combining web search with sandboxed code execution for multi-hop questions"
  domain: "tool-use-tasks"

Call generate_agent_system with:
  requirements: "Research assistant: decompose into sub-questions, search or code per sub-question, synthesise cited answer"
  domain: "tool-use-tasks"
  selected_patterns: ["react"]

Call evaluate_agent_system with:
  agent_system: { ... paste a design dict here ... }
  criteria: "reliability, safety"

Call list_agent_patterns()  # all 68 patterns
Call list_agent_patterns(category="multi_agent")  # filter by category
Call get_agent_pattern(name="supervisor-worker")   # full pattern JSON

非同期ジョブパターン：submit_agent_design_job + get_agent_design_status

リクエストのタイムアウトが短いクライアント（Cursor、Claude Desktop、TS-SDK）でのみ使用してください。デフォルトの設計パスは、ハートビートによる防御を備えた design_agent_system です。submit_agent_design_job は直ちに job_id を返します。完了するまで get_agent_design_status をポーリングします。

# Step 1: start the job
Call submit_agent_design_job with:
  requirements: "Research assistant combining web search with sandboxed code execution for multi-hop questions"
  domain: "tool-use-tasks"

# Step 2: poll every 10-30 seconds
Call get_agent_design_status with:
  job_id: "<job_id from step 1>"

# → status is "pending" | "running" | "completed" | "failed" | "cancelled"
# When status is "completed", the full design is in result.design
# When status is "failed", the error is in result.error

Python での例（MCP HTTP API を直接使用。examples/agent_client_async.py を参照）：

import asyncio
from fastmcp import Client

SERVER = "http://localhost:8821/mcp"
POLL_EVERY = 15  # seconds

async def main():
    async with Client(SERVER) as client:
        # Start
        started = await client.call_tool("submit_agent_design_job", {
            "requirements": "Research assistant: web search + sandboxed code for multi-hop questions",
            "domain": "tool-use-tasks",
        })
        job_id = started.data["job_id"]
        print(f"Job started: {job_id}")

        # Poll
        while True:
            await asyncio.sleep(POLL_EVERY)
            status = await client.call_tool("get_agent_design_status", {"job_id": job_id})
            data = status.data
            print(f"  status={data['status']}  message={data['message']}")
            if data["status"] in ("completed", "failed", "cancelled"):
                break

        print(data.get("result", data))  # full design when completed

実行可能な完全な例は examples/agent_client_async.py を参照してください。次のコマンドで実行します。

docker compose -f docker/docker-compose.yml up --build   # Terminal 1
make client-async                                      # Terminal 2

パターンカタログを確認する

Call list_agent_patterns() with no filters to see all patterns.

または、特定のパターンの詳細を取得します。

Show me details about the react agent pattern.

---

🛠️ ツール一覧

ツール	説明
analyze_agent_system	コードを自分で記述するエージェント向けの分析専用パス：要件＋ドメイン → 推奨トポロジー、スコア付きの選定パターン、品質指標（属性ごとに0～10）、一致したドメインを返します。設計は生成しません。LLM 呼び出し1回（実測23秒）。冪等ではありません。
generate_agent_system	要件と選定したパターンに基づいてエージェントシステムの設計を生成します。実行時間が長くなります（LLM 呼び出し）。冪等ではありません。
evaluate_agent_system	既存の設計を品質属性に照らして採点します。実行時間が長くなります（LLM 呼び出し）。冪等ではありません。
design_agent_system	設計パス：完全なパイプライン（分析 → 生成 → 評価 → 改良、最大3回）を実行し、エージェント、関係、ツール契約、状態モデルに加えて評価を返します。実行時間が長くなります（5～10分）。呼び出し元が設計成果物を求めている場合はこれを使用してください。クライアントのリクエストタイムアウトが短い場合は、ジョブ用の3つのツールを使用してください。
submit_agent_design_job	バックグラウンド設計ジョブを開始し、job_id をすぐに返します。リクエストタイムアウトが短いクライアント（Cursor、Claude Desktop、TS-SDK）専用です。 それ以外のクライアントでは design_agent_system を使用してください。10～30秒ごとに get_agent_design_status をポーリングします。
get_agent_design_status	ジョブのステータスをポーリングします。現在のステータス、進捗メッセージ、および completed 時には設計の全出力を返します。
cancel_agent_design	実行中のジョブをキャンセルします（ベストエフォート。次のパイプラインステージの境界で有効になります。LLM 呼び出し1回分かかる場合があります）。
list_agent_patterns	すべての68パターンを一覧表示します。category および／または domain で絞り込みできます。
get_agent_pattern	名前を指定して、特定のパターンの完全な JSON を取得します。

ドメインとトポロジーは構造化パラメーターです — 要件のテキストに埋め込まず、個別のツール引数として渡してください。

プロンプトの例：

Build a research assistant that answers multi-hop questions by combining
web search with sandboxed code execution, with full audit logging.

Design an agent system for customer-support automation handling 1M
conversations/day. Domain: customer-support. Topology: hierarchical.

Show me details about the reflexion pattern.

Call design_agent_system with:
  requirements: "Research assistant combining web search with sandboxed code execution for multi-hop questions"
  domain: "tool-use-tasks"

---

💬 プロンプト

このサーバーは、ユーザーが呼び出す4つのワークフロープロンプト（MCP クライアントのスラッシュコマンド）も公開します。ツールとは異なり、LLM がプロンプトを自律的に呼び出すことはありません。ユーザーがプロンプトを選択し、引数を入力します。各プロンプトには、テスト済みのツールオーケストレーション手順が組み込まれています。

プロンプト	引数	内容
/design_agent_system_workflow	requirements*	分析 → 生成 → 評価の完全なパイプライン
/explore_pattern_catalog	domain、category	パターン名を埋め込んだ、カタログのライブ探索
/evaluate_my_agent_system	focus	評価基準のガイド＋所見の優先順位付け
/compare_agent_topologies	topology_a*、topology_b*、requirements*	2つの設計を並べて比較します。トークンコストは約2倍です。

* = 必須の引数

ツールのみ対応のクライアント

ツールプロトコルのみをサポートするクライアント（ネイティブの prompts/list または prompts/get に非対応）からは、生成された list_prompts ツールと get_prompt ツールを通じて4つすべてのワークフロープロンプトにアクセスできます。これらのツールは、ネイティブのプロンプト呼び出しと同じようにサーバーのミドルウェアチェーンを経由します。

---

📖 パターンカタログ

MCP ツール経由（推奨 — すべてのクライアントで使用可能）

list_agent_patterns()                                  # all 68 patterns
list_agent_patterns(category="multi_agent")            # filter by category
list_agent_patterns(domain="tool-use-tasks")           # filter by domain
get_agent_pattern(name="supervisor-worker")            # full pattern JSON

有効な category の値：reasoning、tool_use、planning、reflection、research_synthesis、multi_agent、memory、retrieval、safety_control、observability。

MCP リソース経由

pattern://                    → list of all patterns
pattern://{name}              → full pattern JSON
template://{name}             → curated design templates (react, supervisor-worker, multi-agent-debate, agentic-rag)
component://{type}            → component blueprints derived from pattern data

注記： 隣接する architecture-pattern-mcp サーバーも接続されているホストでは、pattern://{name} は曖昧です（両方のサーバーがこのスキームを登録します）。ツール経由のルート（get_agent_pattern）が正規の手段です。

パターン JSON の構造

各パターンには、name、category、topology、context、benefits、tradeoffs、quality_attributes（reliability／cost_efficiency／latency／output_quality／observability／safety／simplicity、数値スコア）、suitable_domains、component_types、technology_stack、design_principles、best_practices が含まれます。

必須フィールド：name、context、category、topology、suitable_domains、quality_attributes（7つすべてのキー）。

---

インストール方法の選択肢

Docker（手動）

# Build the image
make docker-build

# Run with your API key
MINIMAXAI_API_KEY=your_key docker compose -f docker/docker-compose.yml up -d

ローカル開発（uv）

前提条件： Python 3.12 以降、uv

# Install
make install

# Configure
cp config/config.json ~/.config/agent-pattern-mcp/config.json
# Edit ~/.config/agent-pattern-mcp/config.json and set your GENERATOR_API_KEY

# Run the server
uv run python -m src.main --transport stdio              # for Claude Code / Codex
uv run python -m src.main --port 8050                    # for OpenCode (HTTP, default)

または、インストール済みのコンソールスクリプトを使用します（make install の実行後）。

agent-pattern-mcp --transport stdio

ドメインにスコープを限定したパターン検索には、TEI エンベッダー（Qwen3-Embedding-0.6B）が必要です。利用できない場合、サーバーはデフォルトのパターンにフォールバックします。Docker Compose は自動的に起動しますが、ローカル環境ではポート 8080 で別途実行する必要があります。

検索処理はサーバーの起動時に構築されます。BM25 は常に使用され、有効なスナップショットがある場合は埋め込みインデックスのキャッシュから FAISS の高密度検索処理が構築されます（ない場合は最初から埋め込みを生成します）。起動時のフェイルファスト動作は維持されます。起動のたびにプローブ用の埋め込み呼び出しが 1 回行われるため、TEI サイドカーの設定ミスや到達不能があると、ユーザーの最初の設計リクエストを妨げるのではなく、ウォームアップを中止します。Docker Compose の service_healthy による依存関係の順序付けにより、アプリの起動前に TEI の準備が完了します。

TEI の起動： 2 つのサイドカーイメージ（docker/Dockerfile.tei-embed、docker/Dockerfile.tei-rerank）には、独自にビルドした TEI ルーター（v1.9.4 + 未マージの PR #884）が含まれており、デフォルトで WARMUP_TOKENS=0 が設定されています。これにより、合成ウォームアップ処理（実測で埋め込みが約 131 秒、再ランキングが約 78 秒）を省略し、モデルの重みの読み込み後にコンテナが準備完了となります。各サイドカーの TEI_WARMUP_TOKENS / TEI_RERANK_WARMUP_TOKENS で上書きできます（正の整数 N を指定すると N トークンでウォームアップします。MAX_BATCH_TOKENS を超える値を指定すると起動時に拒否されます）。

GPU TEI： 同梱のサイドカーは CPU イメージ（FROM ghcr.io/huggingface/text-embeddings-inference:cpu-1.9、ORT バックエンド。このモデルのバッチ上限は 8）で、Stage-0 ルーターも CPU 専用（--features ort,http）としてビルドされています。このリポジトリにはGPU 向けのビルド手順はありません。CUDA で実行するには、ランタイムのベースイメージを :cuda-1.9 に変更し、さらにルーターを CUDA 機能セットで再ビルドする必要がありますが、ここではサポートされる手順ではありません（これを提供しているのは design-pattern-mcp-local のみで、make docker-build-tei-embed-gpu を使用します）。PR #884 を含まない標準の上流 TEI イメージは、WARMUP_TOKENS を警告なしに無視します。

すでに稼働しているエンベッダー／リランカー： エンベッディングと再ランキングのエンドポイントがすでに別のサーバーで稼働している場合は、MCP サーバーの接続先にそれらを指定し、サイドカーを省略できます（docker/docker-compose.hub.yml は MCP サーバーのみを起動し、まさにこの構成を行います）。リモートエンベッダーは、同じモデルを提供する TEI である必要があります。EMBEDDER_PROVIDER=tei のままにし、EMBEDDER_BASE_URL に OpenAI 互換ルート（http://<host>:8080/v1、config.json のデフォルト）を設定します。このサーバーのエンベッダー設定には model フィールドがありません（src/patterns/embedder.py::build_embedder は tei 以外のプロバイダーに空のモデル名を送信します）。そのため、コードを変更せずに openai / ollama / vllm / hosted_vllm から任意のリモートモデルを指定することはできません。リランカーは LiteLLM クライアントではありません。{RERANKER_BASE_URL}/rerank に直接 POST します（デフォルトは http://pattern-tei-rerank:8080 で、/v1 は付けません）。LiteLLM のエンベッディングに関するドキュメントにあるプロバイダー／モデルの構文が適用されるのは、エンベッダーのみです。EMBEDDER_API_KEY は LiteLLM の api_key として転送されます（認証なしの TEI では、空でない文字列であれば何でも使用できます）。

---

設定

config.json

サーバーは ~/.config/agent-pattern-mcp/config.json を読み込みます（--config-path で変更できます）。

{
  "generator": {
    "provider": "openai",
    "config": {
      "model": "gpt-4o-mini",
      "base_url": "https://api.openai.com/v1",
      "api_key": "{env:GENERATOR_API_KEY}",
      "temperature": 0.1,
      "top_p": 1.0,
      "top_k": 20
    }
  },
  "embedder": {
    "provider": "tei",
    "config": {
      "base_url": "http://pattern-tei-embed:8080/v1"
    }
  },
  "retrieval": {
    "bm25_top_k": 0,
    "dense_top_k": 0,
    "top_k_patterns": 5,
    "min_quality_score": 50.0
  },
  "pattern_directory": "~/.config/agent-pattern-mcp/pattern",
  "transport": "streamable-http",
  "host": "0.0.0.0",
  "port": 8050,
  "logging_level": "INFO",
  "logging_format": "json"
}

{env:VAR:-default} 構文を使用すると、読み込み時に環境変数が展開されます。

Generator LLM（LlamaIndex LiteLLM）

Generator LLM には、LlamaIndex LiteLLM インテグレーション（llama-index-llms-litellm）を通じてアクセスします。そのため、すべてのプロバイダー設定は LiteLLM のモデル構文 <provider>/<model> に従います（例：openai/gpt-4o-mini、anthropic/claude-sonnet-4-5、openrouter/minimax/minimax-m2）。

サーバーは、設定の generator.provider と generator.config.model を組み合わせて LiteLLM のモデル文字列を作成します。

Config / env	例	生成される LiteLLM のモデル文字列
provider: "openai"、model: "gpt-4o-mini"	GENERATOR_PROVIDER=openai、GENERATOR_MODEL=gpt-4o-mini	openai/gpt-4o-mini
provider: "anthropic"、model: "claude-sonnet-4-5"	GENERATOR_PROVIDER=anthropic、GENERATOR_MODEL=claude-sonnet-4-5	anthropic/claude-sonnet-4-5
provider: "openrouter"、model: "minimax/minimax-m2"	GENERATOR_PROVIDER=openrouter、GENERATOR_MODEL=minimax/minimax-m2	openrouter/minimax/minimax-m2

設定したモデルにプロバイダーのプレフィックス（例：openai/gpt-4o-mini）がすでに含まれている場合、そのプレフィックスは削除され、設定した provider に置き換えられます。

• プロバイダーの一覧、モデル名、および正確な <provider>/<model> 構文： LiteLLM プロバイダーのドキュメント
• カスタム／OpenAI 互換エンドポイント（プロキシ、vLLM、Ollama、…）：GENERATOR_BASE_URL（generator.config.base_url）を設定します。LiteLLM の api_base として渡されます。
• GENERATOR_API_KEY は LiteLLM の api_key として渡されます。temperature、top_p、top_k、stream は、それぞれ対応する LiteLLM パラメーターにマッピングされます。

主な環境変数

変数	デフォルト	説明
GENERATOR_API_KEY	(required)	LLM プロバイダーの API キー（api_key として LiteLLM に渡されます）
GENERATOR_PROVIDER	openai	LiteLLM のプロバイダープレフィックス：openai、anthropic、openrouter、…。LiteLLM Providersを参照してください
GENERATOR_BASE_URL	https://api.openai.com/v1	API のベース URL（api_base として LiteLLM に渡されます）
GENERATOR_MODEL	gpt-4o-mini	モデル名。最終的なモデル文字列は <GENERATOR_PROVIDER>/<GENERATOR_MODEL> です（LiteLLM の構文）
GENERATOR_TEMPERATURE	0.1	サンプリング温度
GENERATOR_TOP_P	1.0	Top-p サンプリング
GENERATOR_TOP_K	20	Top-k サンプリング
GENERATOR_STREAM	false	ストリーミング応答を有効にします
EMBEDDER_PROVIDER	tei	埋め込みプロバイダー
EMBEDDER_BASE_URL	http://pattern-tei-embed:8080/v1	TEI 埋め込み URL
EMBEDDER_BATCH_SIZE	16	埋め込みのバッチサイズ
EMBEDDER_QUERY_INSTRUCTION	(empty)	クエリ指示のプレフィックス
EMBEDDER_TEXT_INSTRUCTION	(empty)	テキスト指示のプレフィックス
EMBEDDING_CACHE	image: /var/cache/agent-pattern-mcp/embedding-index · host: ~/.config/agent-pattern-mcp/embedding-index	Dense-leg スナップショットのパス。再起動時に再読み込みされます（コーパスの再埋め込みは不要）。埋め込み器、コーパス、プローブのいずれかが変更されると再構築されます。0／false／off／no を指定すると無効になります。埋め込みインデックスキャッシュを参照してください
RETRIEVAL_BM25_TOP_K	0	BM25 第 1 段階の再現率上限（0＝コーパス全体）
RETRIEVAL_DENSE_TOP_K	0	Dense 第 1 段階の再現率上限（0＝コーパス全体）
RETRIEVAL_DENSE_WEIGHT	0.7	第 1 段階の融合における Dense 側の重み。RETRIEVAL_BM25_WEIGHT と組み合わせて使用します。両方とも 0 より大きく、合計が 1.0 である必要があります。
RETRIEVAL_BM25_WEIGHT	0.3	第 1 段階の融合における BM25 側の重み。RETRIEVAL_DENSE_WEIGHT を参照してください。
RETRIEVAL_TOP_K_PATTERNS	5	選択するパターンの数
RETRIEVAL_MIN_FUSION_SCORE	0.0	rank_fusion のブレンド値に対する関連性の下限。デフォルトは 0.0（ゲートは無効）です。
RETRIEVAL_RERANK_TOP_N	10	再ランキングの上位 N 件（CE 適用後にスラッグで絞り込み）
RETRIEVAL_USE_LEAN_WIRE_SCHEMA	false	簡潔な応答スキーマを使用します（自由形式のコントラクト一覧を省略します。dev／systemd の compose ファイルでは MiniMax ジェネレーター用にデフォルトで true に設定されています）
RETRIEVAL_TOPOLOGY_SCORE_THRESHOLD	50.0	トポロジー推奨に必要な分析スコアの最小値
REASONING_ENABLED	true	サーバー側の推論 MCP 統合。デフォルトで有効です（構造化推論を参照してください）
REASONING_SPAWN_TIMEOUT_SECONDS	10	推論ツールごとのサブプロセス起動タイムアウト
REASONING_STEP_TIMEOUT_SECONDS	20	思考ごとのツール呼び出しタイムアウト
REASONING_MAX_TOTAL_STEPS	8	フェーズごとの推論ステップ数の上限
REASONING_QUIET_STDERR	true	推論サブプロセスの stderr（ASCII 形式の進捗ボックス、[info] バナー）を抑制します。起動失敗のデバッグ時は false に設定してください
REASONING_FAIL_FAST	true	推論ツールに到達できない場合、サーバーの起動を失敗させます
REASONING_SHANNONTHINKING_CMD	(embedded)	shannonthinking 用の JSON リスト形式のコマンド（例：["npx","-y","server-shannon-thinking@latest"]）
REASONING_CODE_REASONING_CMD	(embedded)	code-reasoning 用の JSON リスト形式のコマンド
RETRIEVAL_ANALYSIS_BLEND_WEIGHT	0.7	ブレンドにおける分析スコアの重み
RETRIEVAL_FUSION_BLEND_WEIGHT	0.3	ブレンドにおける融合スコアの重み
RETRIEVAL_WEIGHT_SMOOTHING_ALPHA	0.7	重み平滑化アルファ
PIPELINE_TIMEOUT_SECONDS	1200	1 回の設計実行全体（すべてのフェーズ：分析 → 生成 → 評価 → 改良、およびすべての再試行）に対する実時間の上限（秒）。期限を過ぎると実行はキャンセルされ、ツール呼び出しは WorkflowTimeoutError で失敗します。途中までの設計は破棄されます。プロバイダーの応答が遅く、REASONING_ENABLED=true の場合は値を大きくし、速やかに失敗させる場合は小さくしてください。設定キー：pipeline.timeout_seconds。
RETRIEVAL_VERBOSE_TIMING	false	INFO レベルでフェーズごとの所要時間を記録します
RETRIEVAL_MAX_TRIES	2	設計ループの最大試行回数
RETRIEVAL_MIN_QUALITY_SCORE	50.0	早期終了の品質しきい値
RERANKER_BASE_URL	http://pattern-tei-rerank:8080	TEI 再ランカーのエンドポイント
RERANKER_TIMEOUT	30.0	再ランカーのタイムアウト（秒）
RERANKER_MAX_BATCH_SIZE	48	TEI /rerank リクエストあたりのテキストの最大数。再ランカーサイドカーの MAX_CLIENT_BATCH_SIZE と MAX_CONCURRENT_REQUESTS の小さい方以下である必要があります。HybridPatternRetriever は大きなプールを自動的に分割します。
PATTERN_DIRECTORY	~/.config/agent-pattern-mcp/pattern	パターンファイルのディレクトリ
VALIDATION_MAX_RETRIES	2	自己修復の最大再試行回数
VALIDATION_RETRY_ON_FAIL	true	検証に失敗した場合に再試行します
AGENT_PATTERN_JOBS_DB	~/.config/agent-pattern-mcp/jobs.db	非同期ジョブの 3 点セットで使用する SQLite のパス。テストを分離する場合は上書きしてください
TASKS_HEARTBEAT_ENABLED	true	長時間のツール呼び出し中に進捗通知を送信します
TASKS_HEARTBEAT_INTERVAL_SECONDS	30	ハートビートの間隔（秒）。クライアントのアイドルタイムアウトより短くしてください
TRANSPORT	streamable-http	トランスポートモード：stdio、streamable-http
HOST	0.0.0.0	HTTP のバインド先ホスト
PORT	8050	HTTP のバインド先ポート（コンテナー内。dev compose はホストポート 8821 を、systemd は 8811 を公開します）
LOGGING_LEVEL	INFO	ログレベル
LOGGING_FORMAT	json	ログ形式：json、text
CONFIG_PATH	~/.config/agent-pattern-mcp/config.json	設定ファイルのパス

注記： dev および systemd の compose ファイルでは、RETRIEVAL_BM25_TOP_K=20／RETRIEVAL_DENSE_TOP_K=20（各検索段階の第 1 段階の上限）と RETRIEVAL_MIN_FUSION_SCORE=0.015 が設定され、上記の設定デフォルト値を上書きします。また、デプロイされる MiniMax の生成ブロック（GENERATOR_PROVIDER=minimax、GENERATOR_MODEL=minimax/MiniMax-M2.7、GENERATOR_BASE_URL=https://api.minimax.io/v1、RETRIEVAL_USE_LEAN_WIRE_SCHEMA=true）も OpenAI の設定デフォルト値とは異なります。

埋め込みインデックスのキャッシュ（密検索スナップショット）

密検索のレグでは、カタログ内のすべてのドメインスラッグ（提供される 68 パターンのカタログでは 36 個）を対象とする 1 つの FAISS インデックスを使用します。コールドビルド後に埋め込みをディスクへスナップショットとして保存し、次回の起動時に再読み込みします。そのため、ウォームスタートではコーパス全体の処理ではなく、プローブ埋め込み 1 回だけで済みます（開発用 TEI サイドカーコンテナで測定。36 スラッグで 3.3 秒 → 0.28 秒）。BM25 は低コストなため、起動のたびに再構築されます。

• パス：EMBEDDING_CACHE。イメージには /var/cache/agent-pattern-mcp/embedding-index が含まれています。ホスト上で実行する場合（uv）は、 ~/.config/agent-pattern-mcp/embedding-index を使用します。
• ファイルの保存場所：ログに表示されるパスは、コンテナ内から見たパスです。Docker は名前付きボリュームを /var/lib/docker/volumes/<volume-name>/_data（root 所有）に保存するため、ホスト上の /var/cache は仕様上空のままです。sudo を使わずに確認するには、docker exec <container> ls /var/cache/agent-pattern-mcp/embedding-index を実行するか、ホスト側の場所を確認するには docker volume inspect -f '{{.Mountpoint}}' <volume-name> を実行してください。
• コンテナでは名前付きボリュームに保存されます （agent-pattern-mcp-dev-embedding-index／ agent-pattern-mcp-systemd-embedding-index）。そのため、イメージの再ビルド、コンテナの再作成、docker compose down の後もスナップショットは保持されます。リセットするには docker compose down -v または docker volume rm <name> を実行してください。単独の docker run では -v agent-pattern-mcp-embedding-index:/var/cache/agent-pattern-mcp/embedding-index が必要です。
• 埋め込み関数が変更された場合（プロバイダー、base_url、解決されたモデル名、クエリ／テキストの指示プレフィックス）、スラッグコーパスが変更された場合、またはプローブベクトルから 設定に変更がないままモデルが異なっている と判明した場合（例：TEI サイドカーの再デプロイ時）に、自動的に再構築されます。ログ行： Embedding index cache hit: N slugs, 0 corpus embed calls (snapshot <cache-dir>)／Embedding index cache miss (<reason>); embedding corpus／ Embedding index snapshot written: N slugs (path <cache-dir>) — 埋め込み処理の直後、ほかの起動手順より前に出力されます。キャッシュを無効にした場合は Embedding index cache disabled; embedding corpus が出力されます（キャッシュミスとは報告されません）。
• 単一の書き込み元：ロック機構はありません。キャッシュディレクトリごとにサーバープロセスを 1 つだけ実行してください。スナップショットの書き込みに失敗した場合は警告を記録します。サーバーはキャッシュなしで動作し、起動に失敗することはありません。
• 運用上の注意（ボリューム、権限、無効化スイッチ）：INSTALL.md。

CLI フラグ

フラグ	説明
--transport {stdio,streamable-http}	トランスポートモードを上書きします
--host	HTTP のバインドホストを上書きします（デフォルト：0.0.0.0）
--port	HTTP ポートを上書きします（デフォルト：8050）
--config-path	設定ファイルのパス
--health	ヘルスチェックを実行して終了します

---

構造化推論（shannonthinking / code-reasoning）

各 LLM フェーズ呼び出し（ANALYZE / GENERATE / EVALUATE / RETRY）の前に、サーバーは任意で、上限付きの ThoughtGenerator ループを実行します。このループでは、ジェネレーター自身の LLM（LlamaIndex LiteLLM。各ステップにつき補完を 1 回）を使って各推論ステップを作成し、shannonthinking および／または code-reasoning の MCP サーバーに送信します。これらは各ステップを検証、番号付け、記録する構造化思考のスクラッチパッドです。生成されたトレースは、<reasoning_context> ブロックとしてフェーズプロンプトに挿入されます。仕様：各思考につき、LLM 補完 1 回と MCP ツール呼び出し 1 回。上限は REASONING_MAX_TOTAL_STEPS（デフォルトは 8）です。

主な特性：

• Docker に組み込み — build-mcps ステージで両方の npm パッケージ（[email protected]、@mettamatt/[email protected]）を /usr/local/lib/node_modules/... にイメージとして組み込みます。実行時には node で直接呼び出すため、ネットワークも npx も不要です。
• Docker 外では npx に自動フォールバック — 組み込みのエントリーポイントが見つからない場合、クライアントは npx -y <pkg> にフォールバックします（初回の呼び出し時にダウンロードします）。
• 呼び出しごとにプロセスを分離 — 各ツール呼び出しは新しいサブプロセスで実行されます（keep_alive=False）。呼び出し間で状態は保持されません。
• 呼び出し単位でのサイレントな縮退 — 起動、タイムアウト、ツールのいずれかに障害があると、WARNING を記録し、フェーズはプロンプト内の簡易思考スキャフォールド（分解 → 分類 → 調整 → 解決 → 検証）で続行します。例外は発生しません。
• 起動時は明示的に通知 — 起動時のヘルスチェックで両方のツールをプローブし、いずれかに接続できない場合は解決のヒントとともに ERROR を記録します。代わりに起動を失敗させるには、REASONING_FAIL_FAST=true を設定します。
• トレースをキャッシュ — ANALYZE と GENERATE のトレースは、設計リクエストごとに一度だけ計算され、設計ループの各試行で再利用されます。

有効化と調整

このリポジトリのデプロイ済みスタックでは、推論はデフォルトで有効です（両方の compose ファイルで REASONING_ENABLED=true が設定されています）。

export REASONING_ENABLED=true           # enable the reasoning MCP integration
export REASONING_FAIL_FAST=true         # refuse to start with broken MCPs

フェーズごとのツール選択（デフォルト値は src/reasoning/config.py::_default_per_phase）： analyze は ["code", "shannon"] を使い思考を 4 回、generate は ["code"] を使い 3 回、evaluate は ["shannon"] を使い 3 回、refine は ["code", "shannon"] を使い 2 回です。 設計を 1 回実行すると、推論ツールの呼び出しがシリアルなサブプロセスとして最大 24 回発生します。数秒ではなく数分かかります。

ローカル（Docker を使わない）での開発には Node.js が必要です。パッケージをグローバルにインストールする（npm install -g server-shannon-thinking @mettamatt/code-reasoning）か、初回使用時に npx のフォールバックでダウンロードさせてください。

各ステップの推論呼び出しで作成された thought とツールの応答を記録するには、LOGGING_LEVEL=DEBUG を設定します。Docker/systemd スタックのデフォルトは INFO です。make docker-up の前に LOGGING_LEVEL=DEBUG をエクスポートしてください。

---

カスタムパターンによる拡張

パターンファイルは ~/.config/agent-pattern-mcp/pattern/（PATTERN_DIRECTORY で変更可能）から読み込まれます。組み込みの 68 個のパターンと同じディレクトリに JSON ファイルを配置してください。

最小限のパターン構造：

{
  "category": "tool_use",
  "name": "my-custom-pattern",
  "topology": "single-agent-loop",
  "context": "Describe when this pattern applies.",
  "benefits": ["Benefit 1", "Benefit 2"],
  "tradeoffs": ["Tradeoff 1"],
  "quality_attributes": {
    "reliability": 7,
    "cost_efficiency": 6,
    "latency": 7,
    "output_quality": 7,
    "observability": 6,
    "safety": 7,
    "simplicity": 5
  },
  "suitable_domains": ["tool-use-tasks"]
}

必須フィールド：name、context、category、topology、suitable_domains、quality_attributes（7 個すべてのキー）。

有効な category の値：reasoning、tool_use、planning、reflection、research_synthesis、multi_agent、memory、retrieval、safety_control、observability。

すべての列挙値を含む完全な JSON Schema：docs/pattern-schema.json

---

長時間実行されるツールとタイムアウト

design_agent_system は複数段階の LLM パイプラインを実行するため、1 回の呼び出しに 5〜10 分かかることがあります。単一フェーズのツールははるかに軽量です。analyze_agent_system は 1 回の分析 LLM 呼び出し（このホストでの実測値は 23.3 秒）で、設計を生成せずにトポロジーとスコア付きパターンを返します。一方、generate_agent_system と evaluate_agent_system は、それぞれ 1 回の大規模な生成で完了します。設計呼び出しが長時間かかるのはワークロードに起因するもので、バグではありません。生成 LLM は、大規模な入力ペイロード（68 種類のパターンカタログから選択されたパターン定義、要件、前段階すべての完全な出力）を処理し、エージェント、関係性、ツールコントラクト、状態モデル、メッセージコントラクト、品質スコアを含む、大規模で厳密に構造化された JSON ドキュメントを 1 トークンずつ生成する必要があります。design_agent_system パイプラインでは、生成 → 評価を最大 3 回繰り返すため、1 回の呼び出しで 9 回以上の LLM とのやり取りが発生することがあります。

タイムアウトの問題

MCP クライアント（AI コーディングエージェント、MCP SDK）は、サーバーと LLM の間に位置します。多くのクライアントにはクライアント側のアイドルタイムアウトが実装されています。HTTP 接続で一定時間（通常は 30〜120 秒）データを受信しないと、クライアントはリクエストを中断します。サーバーは処理を続けており、LLM もまだ生成中ですが、クライアントは接続を閉じ、エージェントにタイムアウトエラーを報告します。

これはクライアント側の動作であり、サーバー側のものではありません。サーバーはリクエスト全体を正しく処理しますが、クライアントは応答が届く前に単に処理を諦めます。

影響を受けるクライアント（短いタイムアウトがハードコードされています）：

クライアント	タイムアウト	備考
Claude Desktop（TS-SDK）	60 s	ハードコードされており、進捗通知ではリセットされません
Cursor（TS-SDK）	60 s	Claude Desktop と同様です
その他の TS-SDK ベースのエージェント	さまざま	ほとんどは 60〜120 s に制限されています

これらのクライアントは、より長いタイムアウトを受け入れるように再設定できません。タイムアウトは SDK に組み込まれています。

ハートビートによる対策が有効なクライアント：

クライアント	タイムアウト	対策
Claude Code	約 300 s	30 秒ごとのハートビートでアイドルタイマーをリセットします
OpenCode	約 300 s	30 秒ごとのハートビートでアイドルタイマーをリセットします
Codex CLI	約 300 s	30 秒ごとのハートビートでアイドルタイマーをリセットします
その他の HTTP トランスポートを使用するエージェント	さまざま	ほとんどはデータを受信するとリセットされます

アイドルタイマーが受信データによってリセットされるため、これらのクライアントでは機能します。サーバー上の並列非同期タスクから送信されるハートビートの progress 通知がクライアントに届き、タイマーがリセットされます。

ハートビートによる対策（デフォルトで適用）

長時間実行されるすべてのツールは、30 秒ごとに並列コルーチンから progress 通知を送信します（TASKS_HEARTBEAT_INTERVAL_SECONDS で設定可能）。受信データによってアイドルタイマーをリセットするクライアントであれば、パイプラインの実行中もリクエストが維持されます。

TS-SDK クライアント（Claude Desktop、Cursor など）は、進捗通知ではタイムアウトをリセットしません。

非同期ジョブの 3 ツール（タイムアウトに制約のあるクライアント向け）

タイムアウトが制限されたクライアントとの完全な制御と互換性を実現するため、3 つのツールで永続的なジョブハンドルを利用できます。

submit_agent_design_job(requirements, domain, override_topology)  → job_id
get_agent_design_status(job_id)                                     → {status, result, error}
cancel_agent_design(job_id)                                         → {cancelled, status}

submit_agent_design_job はミリ秒単位で job_id を返します。パイプラインはバックグラウンドタスクとして実行されます。10〜30 秒ごとに get_agent_design_status(job_id) をポーリングしてください。ステータスが completed になったら、完全な設計が result フィールドに格納されています。キャンセルはベストエフォートであり、ジョブは次のパイプライン段階の境界で終了します。

TS-SDK クライアント（Claude Desktop、Cursor）で機能する唯一の解決策です。

ジョブストアは ~/.config/agent-pattern-mcp/jobs.db の SQLite です（AGENT_PATTERN_JOBS_DB で設定可能です）。

直接 HTTP クライアントでクライアントのタイムアウトを回避する

examples/agent_client.py のクライアント例は、直接 Python HTTP クライアントです。MCP エージェントではありません。MCP SDK を使わずに HTTP 経由でサーバーを呼び出すため、クライアント側のアイドルタイムアウトはありません。ブロッキングリクエストを 1 回だけ実行し、応答がすべて返るまで待機します。

# Start the server (from project root)
docker compose -f docker/docker-compose.yml up --build

# In another terminal: fast analyze demo / full design demo (minutes)
make client-analyze        # analyze_agent_system only
make client-design         # design_agent_system, the long synchronous call

どちらのターゲットも、同じ直接クライアントを実行します（--tool analyze|design）。make client-design を実行すると、サーバーが長時間かかるリクエストを正常に完了することを確認できます。タイムアウトの問題は、純粋にクライアント側の問題です。MCP エージェントを本番環境で使用する場合、ハートビートによる対策で大半のクライアントをカバーできます。非同期ジョブの 3 つ組は、あらゆる状況に対応するフォールバックです。

---

トラブルシューティング

サーバーは起動するが、ツールが表示されない

1. エージェントの MCP 接続を確認します：Claude Code /mcp、OpenCode opencode mcp list、Codex codex mcp list
2. サーバープロセスが起動したことを確認します：compose のログに MCPAgentPatternServer initialized と表示されているはずです
3. TEI エンベッダーが正常に動作していることを確認します：docker exec agent-pattern-mcp python -c "import urllib.request; print(urllib.request.urlopen('http://pattern-tei-embed:8080/health').status)"

「Connection refused」またはタイムアウトエラー

サーバーは、TEI エンベッダーが正常な状態になるまで待機します。

docker compose -f docker/docker-compose.yml logs agent-pattern-mcp

LLM プロバイダーのエラー（502／401）

• GENERATOR_API_KEY が設定され、有効期限が切れていないことを確認します
• GENERATOR_BASE_URL がプロバイダーのエンドポイントと一致していることを確認します
• プロキシを使用している場合は、コンテナー内から接続できることを確認します

パターンの JSON ファイルが読み込まれない

• ファイルの拡張子は .json で、*-pattern.json に一致している必要があります
• 必須フィールド：name、context、category、topology、suitable_domains、quality_attributes（7 つすべてのキー）
• 起動ログに Pattern validation failed の警告がないか確認します

---

ビルドと開発

よく使う make ターゲット（全リファレンス：docs/make_rules.md）：

ターゲット	説明
make install	開発用依存関係とともに、パッケージを編集可能モードでインストールします
make check-lint	ruff によるリンティングを実行します
make check-static-typing	src/ を対象に mypy --strict による型チェックを実行します
make check-all	すべての check-* 品質ゲート（リンティング、型チェック、デッドコード、依存関係）を実行します
make test-unit	uv を使ってユニットテスト（tests/unit/）を実行します
make test-oracles	実行可能な検証オラクル（tests/verification/）を実行します
make client-analyze	analyze のみを実行する MCP クライアントのデモを実行します（サーバーの起動が必要です）
make client-design	同期型の design_agent_system クライアントのデモを実行します（長時間実行。サーバーの起動が必要です）
make client-async	非同期ジョブの 3 つ組のデモを実行します（サーバーの起動が必要です）
make docker-build	MCP サーバーの Docker イメージをビルドします
make docker-build-all	MCP サーバー、TEI エンベッダー、リランカーのイメージをビルドします
make docker-publish	イメージを Docker Hub と GHCR にプッシュします（バージョンと latest）
make docker-up	すべてのサービスをビルドして起動します
make docker-down	すべてのサービスを停止します

開発ワークフロー：

make install                      # First-time setup
uv run pre-commit install         # First-time setup: commit hook
make check-all                    # Before pushing (lint + types + dead code + deps)
make docker-build-all             # Build both images (first time and after code changes)
make docker-up                    # Start services
make docker-logs-follow           # Watch logs
make docker-down                  # Stop

---

公開

3 つすべてのイメージを 2 つのレジストリに同時に公開します。

イメージ	Docker Hub	GHCR	タグ
MCP サーバー	olkowa/agent-pattern-mcp	ghcr.io/olk/agent-pattern-mcp	$(DOCKER_TAG)、latest
TEI エンベッダー	olkowa/pattern-tei-embed	ghcr.io/olk/pattern-tei-embed	$(DOCKER_TAG)、latest
TEI リランカー	olkowa/pattern-tei-rerank	ghcr.io/olk/pattern-tei-rerank	$(DOCKER_TAG)、latest

3 つすべてのイメージで同じ $(DOCKER_TAG)（pyproject.toml に記載されたバージョン）を共有するため、tei:1.0.3 は常に mcp:1.0.3 とともに公開されます。Blob の重複排除により、変更のない TEI イメージのタグ付けを低コストで行えます。

帯域幅に関する注意： TEI エンベッダーのイメージは約 5 GB です（ONNX fp32 の重みが組み込まれています）。各レジストリへの初回プッシュでは、約 5 GB のアップロードが発生します。2 回目以降のプッシュは差分のみとなり、変更されたレイヤーだけが転送されます。

前提条件

Docker Hub — ローカルで認証済みであること（docker login）。

GitHub Container Registry — write:packages スコープを持つクラシック PATが必要です。2FA は問題ありません。PAT では回避されます。ログイン後、トークンは破棄されます。認証情報はログアウトするまで ~/.docker/config.json に保持されます。

公開（初回セットアップとセッションごとの作業）

# 1. Login to GHCR (interactive — paste token at the password prompt)
docker login ghcr.io -u olk

# 2. Build and push all three images (MCP + TEI embedder + TEI reranker)
#    The umbrella target builds the MCP image, tags it, pushes it, creates the git tag,
#    then builds and pushes each TEI image in sequence.
make docker-publish-all

# 3. Logout from GHCR immediately after publishing
#    (removes the ghcr.io credential from ~/.docker/config.json)
docker logout ghcr.io

以降の公開では、手順 1～3 を繰り返してください。PAT の有効期限が切れている場合は、上記のリンクから新しいものを生成してください。

初回のプッシュ — パッケージを公開に設定（GHCR のみ）

GHCR のパッケージは、デフォルトでプライベートです。最初の make docker-publish-all の実行後、3 つすべてのパッケージを公開に切り替えてください。

パッケージ	設定 URL
MCP サーバー	https://github.com/users/olk/packages/container/agent-pattern-mcp/settings
TEI エンベッダー	https://github.com/users/olk/packages/container/pattern-tei-embed/settings
TEI リランカー	https://github.com/users/olk/packages/container/pattern-tei-rerank/settings

それぞれを公開に設定して保存してください。

部分的な失敗からの復旧

プッシュの途中で失敗した場合（例：GHCR の認証が設定されていなかった場合）、Docker Hub へのレイヤーのアップロードはすでに完了しています。認証を修正した後、make docker-publish-all を再実行しても問題ありません。各レジストリはアップロード済みのレイヤーをキャッシュヒットとして報告し、残りのプッシュを完了します。対象を絞って再試行するには、make docker-publish-tei または make docker-publish-tei-rerank で個別のイメージをプッシュできます。

---

systemd サービス（Linux）

このサーバーは、systemd ベースの任意の Linux ホストで systemd サービスとして実行できます。起動時に Docker Compose スタックを自動的に開始します。

ファイル構成

systemd/ ディレクトリには 3 つのファイルがあります。

ファイル	用途
systemd/agent-pattern-mcp.service	systemd ユニット
systemd/docker-compose.yml	本番用 Compose バリアント（build: なし、絶対パスを使用）
systemd/README.md	インストール、確認、トラブルシューティングを含む完全な運用手順書

本番用 Compose ファイルは docker/docker-compose.yml のデプロイ用バリアントです。build: セクションはなく（イメージは事前にビルドする必要があります）、絶対パスを使用し、ホスト上の /etc/agent-pattern-mcp/ に配置されます。systemd 管理下のプロジェクトでは、開発用 Compose および兄弟プロジェクトである architecture-pattern-mcp の systemd スタック（apmcp-systemd）とは異なる名前 agpmcp-systemd を使用します。そのため、どちらのスタックの up -d --remove-orphans も、もう一方のコンテナーを孤立コンテナーとして扱いません。

TEI サイドカーはこのスタックでは定義されていません — pattern-tei-embed エンベッダーと pattern-tei-rerank リランカーのコンテナーは、共有の pattern-tei-infra スタック内で実行されます。この スタックは pattern-tei-shared Docker ネットワークを管理し、サイドカーを http://pattern-tei-embed:8080/v1（エンベッダー）および http://pattern-tei-rerank:8080 （リランカー）で公開します。systemd の MCP スタックはそのネットワークに接続し、 これらの DNS 名を使ってサイドカーにアクセスします。

前提条件 — TEI インフラの初回セットアップ：

# インフラスタックをクローンします（ホストにまだない場合）
git clone https://github.com/olk/pattern-tei-infra.git ~/pattern-tei-infra

# pattern-tei-infra の systemd ユニットをインストールして有効化します
sudo install -m 644 ~/pattern-tei-infra/pattern-tei-infra.service \
                /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now pattern-tei-infra.service
# TEI サイドカーが正常な状態になるまで約 2 分待ちます

agent-pattern-mcp.service を開始するのは、pattern-tei-infra.service が active (running) になった後にしてください。 詳細については、 pattern-tei-infra/README.md を参照してください。

前提条件

• Docker がインストールされた systemd ベースの Linux ホスト（docker compose version）。
• <user> が docker グループに属していること。
• 両方のイメージがローカルで事前にビルドされていること（リポジトリで make docker-build-all を実行）。
• 共有 TEI インフラスタックがインストールされ、有効化されていること（tei-infra README を参照）。

インストール

# 0. Install + enable shared TEI infra (once)
sudo install -m 644 {HOME}/pattern-tei-infra/pattern-tei-infra.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now pattern-tei-infra.service

# 1. Build images (once)
make docker-build-all

# 2. Deploy /etc/agent-pattern-mcp/
sudo install -d /etc/agent-pattern-mcp/config
sudo install -m 644 systemd/docker-compose.yml /etc/agent-pattern-mcp/
sudo install -m 644 ~/.config/agent-pattern-mcp/config.json /etc/agent-pattern-mcp/config/

# 3. Create the .env file (root:docker 640) and edit it.
#     640 root:docker — not 600 root:root — so the systemd service
#     running as User=graemer (a member of the `docker` group) can read this
#     file when docker compose auto-loads it.  The `docker` group is
#     effectively privileged; this is the standard trade-off for non-root
#     systemd services that manage Docker containers.
sudo install -o root -g docker -m 640 /dev/null /etc/agent-pattern-mcp/.env
sudo $EDITOR /etc/agent-pattern-mcp/.env
# Contents:
#   MINIMAXAI_API_KEY=sk-...
#   COMPOSE_PROJECT_NAME=agpmcp-systemd

# 4. Install and enable the service.
sudo install -m 644 systemd/agent-pattern-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now agent-pattern-mcp.service

ビルド不要のショートカット： Docker Hub からビルドせずにインストールする方法 （プルとタグ付け、JSON-RPC のプローブ、運用開始後の操作）については、 INSTALL.md のパス B を参照してください。

検証

systemctl status は数秒以内に active (exited) を表示しますが、コンテナーが 正常な状態になるまで 最大約40秒 かかります（MCP の start_period: 40s。TEI の準備状態は、 start_period: 120s の pattern-tei-infra が管理します）。 ユニットはヘルスチェックを待機しません。

systemctl status agent-pattern-mcp
journalctl -u agent-pattern-mcp -n 50
docker compose -p agpmcp-systemd -f /etc/agent-pattern-mcp/docker-compose.yml ps
docker inspect -f '{{.State.Health.Status}}' agent-pattern-mcp  # "healthy"
# Probe the MCP endpoint — must print 200 (GET /health is 404 by design).
curl -s -o /dev/null -w '%{http_code}\n' -X POST "http://localhost:8811/mcp" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"0.0.0"}},"id":1}'

日常の操作

sudo systemctl start|stop|restart|reload agent-pattern-mcp
journalctl -u agent-pattern-mcp -n 200 -f
docker compose -p agpmcp-systemd -f /etc/agent-pattern-mcp/docker-compose.yml logs -f

スタックの更新

make docker-build-all                     # rebuild both images
sudo systemctl reload agent-pattern-mcp   # recreate containers

アンインストール

sudo systemctl disable --now agent-pattern-mcp.service
sudo rm /etc/systemd/system/agent-pattern-mcp.service
sudo systemctl daemon-reload
sudo rm -rf /etc/agent-pattern-mcp

トラブルシューティング、ネットワークの詳細、共存ガイドについては、 systemd/README.md を参照してください。

---

検証プログラム

このリポジトリには、階層化された検証プログラムが用意されています（docs/verification.md と docs/testing-strategies.md を参照）。

層	検証内容	実行コマンド
L1	ユニットテストスイート（動作のオラクル）＋シークレット・カナリア	make test-unit
L1b	MCP ツールのサーフェス境界ファジング	make test-oracles
L2	意思決定モジュールに対する Hypothesis のプロパティ・オラクル	make test-oracles
L3	ミューテーションテスト（mutmut ラチェット）＋意図的にバグを仕込んだガーデン	make test-mutations（夜間実行）
L4	FizzBee の網羅的なモデルチェック＋FG 仕様ガーデン	make verify-fizz、make verify-fizz-garden
L6	ジョブストアに対する決定論的シミュレーションの競合テスト	make test-oracles
L8	プロパティ ID 台帳＋NL-Doc の相互整合性	make verify-ledger、make verify-cross-consistency
L9	LLM 出力の構造的不変条件（オプトインのライブパイプライン）	uv run pytest tests/eval/ -m llm（AGENT_BENCH_LLM=1）
L10	パフォーマンス・スモーク・カナリア（RUN_PERF=1）	夜間ワークフロー

高速ゲート：make check-all（Lint＋型＋デッドコード＋依存関係）と make test-all（ユニットテスト＋オラクル）です。夜間カナリアは .github/workflows/verification.yml にあります。

---

ライセンス

MIT ライセンスです。LICENSE を参照してください。