Architecture Pattern MCP

architecture-pattern-mcp

AI コーディングエージェントにアーキテクチャ設計の専門知識を提供する MCP（Model Context Protocol）サーバーです。要件の文字列とドメインを受け取ると、問題を分析し、一致するアーキテクチャパターン（組み込みの 128 パターンから）を選択して、コンポーネント、関係、API コントラクト、データモデル、イベントコントラクトを含む具体的なアーキテクチャ設計を生成し、品質特性（保守性、スケーラビリティ、信頼性、セキュリティ、パフォーマンス）に照らして評価します。

---

目次

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

---

⚡ クイックスタート

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

# 2. Add your API key
export GENERATOR_API_KEY=your_key_here

# 3. Start (Docker builds + starts everything)
docker compose -f docker/docker-compose.yml up --build

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

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

---

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

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

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

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

• 方法 A — Compose スタック（:8820）：評価／開発向け。sudo は不要です。TEI サイドカーのコピーを個別に使用します。
• 方法 B — systemd スタック（:8810）：永続的なホストサービスで、起動時に開始します。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 architecture-pattern \
  -e GENERATOR_API_KEY=your_key \
  -e GENERATOR_PROVIDER=openai \
  -- architecture-pattern-mcp --transport stdio

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

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

OpenCode

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

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

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

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

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

Codex CLI

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

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

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

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

または、CLI 経由で設定します。

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

---

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

skills/architecture-pattern-mcp/ の SKILL は Oh My Pi (OMP) 向けに書かれています。この環境では、このサーバーのツールは xd://mcp__architecture_pattern_* デバイスとしてアクセスされ、すべての MCP リクエストに期限が設定されています（OMP_MCP_TIMEOUT_MS → サーバーごとの timeout → 30 s）。この SKILL では、期限に適したエントリーポイントの選び方、結果の読み方、ワークフロー全体のレシピをエージェントに説明します。

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

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

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

この SKILL では、エージェントに次の内容を説明します。

• OMP の期限に適したエントリーポイント。デフォルトでは非同期ジョブの 3 つのツールを使用します。ワンショットの design_architecture は、サーバーの timeout を引き上げた場合にのみ使用します（analyze_architecture 単体の実測値は 66 s、evaluate_architecture は 197 s）。
• requirements、domain、style を別々の構造化引数として指定する方法
• final_quality_score、attempts > 1、evaluation.recommendations の解釈方法
• 兄弟の agent-pattern サーバーに接続している場合、read mcp://pattern://… は曖昧になるため、ツールのルート（get_architecture_pattern）を正とすること

references/ のツールスキーマ、エラーコード、設計ディクショナリの形式はクライアントに依存しません。期限とデバイスに関するガイダンスのみが OMP 固有です。

---

ツールを使用する

すべてのツールは、引数として requirements（自由形式のテキスト）と domain（例：data-processing、microservices、e-commerce）を受け取ります。以下の例では正確なツール呼び出しの形式を示しているため、任意の MCP クライアントまたは API 利用者で使用できます。

各ツールを試す

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

Build a scalable ETL pipeline for IoT sensor data: ingest 10k events/sec
from Kafka, parse JSON, enrich with geolocation from Redis, write to InfluxDB
and S3.

エージェントは内部で design_architecture を呼び出します。サーバーは、コンポーネント（Kafka ソース、JSON パーサーフィルター、ジオロケーションエンリッチャー、InfluxDB シンク、S3 シンク）、品質属性スコア（スケーラビリティ：9.1、保守性：8.2、…）、具体的な推奨事項を含む完全なアーキテクチャ設計を返します。

これが設計の経路です。サーバーの LLM が設計成果物を生成するため、呼び出しには数分かかります。エージェントが自らコードを書き、必要なのがパターンに関する専門知識だけであれば、代わりに analyze_architecture を呼び出してください。こちらは設計を生成せずに、推奨スタイル、選択されたパターンとスコア、要件の重み、品質指標、一致したドメインを返します。コミット済みのベンチマークコーパスで計測した事実が 2 つあります。生成と評価で、設計呼び出しの実行時間の約 92 % を占めています（benchmarks/base-noreasoning/）。また、完了した 31 件すべての記録で、2 つの経路のスタイル選択は一致しています（base が 15 件、no-reasoning が 16 件。残りの base 1 件は、不正な JSON の検証エラーで失敗し、設計を生成できなかった設計呼び出しです）。つまり、設計呼び出しで得られるのは成果物であり、より優れたパターン選択ではありません。

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

Call analyze_architecture with:
  requirements: "Real-time data processing pipeline for 10k events/sec IoT sensor data"
  domain: "data-processing"

Call generate_architecture with:
  requirements: "ETL pipeline: Kafka → JSON parse → Redis geo-enrich → InfluxDB + S3"
  domain: "data-processing"
  selected_patterns: ["pipe-and-filter"]

Call evaluate_architecture with:
  architecture: { ... paste a design dict here ... }
  criteria: "scalability, reliability"

Call list_architecture_patterns()  # all 128 patterns
Call list_architecture_patterns(category="messaging")  # filter by category
Call get_architecture_pattern(name="event-driven")   # full pattern JSON

非同期ジョブのパターン：submit_architecture_design_job + get_architecture_design_status

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

# Step 1: start the job
Call submit_architecture_design_job with:
  requirements: "ETL pipeline for IoT: Kafka → JSON → Redis geo-enrich → InfluxDB + S3"
  domain: "data-processing"

# Step 2: poll every 10-30 seconds
Call get_architecture_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/architecture_client_async.py を参照）：

import asyncio, aiohttp

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

async def main():
    async with aiohttp.ClientSession() as sess:
        # Start
        async with sess.post(SERVER, json={
            "jsonrpc": "2.0",
            "method": "tools/call",
            "params": {
                "name": "submit_architecture_design_job",
                "arguments": {
                    "requirements": "ETL pipeline for IoT: Kafka → JSON → Redis → InfluxDB + S3",
                    "domain": "data-processing",
                }
            },
            "id": 1
        }) as resp:
            job_id = (await resp.json())["result"]["content"][0]["data"]["job_id"]

        print(f"Job started: {job_id}")

        # Poll
        while True:
            await asyncio.sleep(POLL_EVERY)
            async with sess.post(SERVER, json={
                "jsonrpc": "2.0",
                "method": "tools/call",
                "params": {"name": "get_architecture_design_status", "arguments": {"job_id": job_id}},
                "id": 2
            }) as resp:
                result = (await resp.json())["result"]["content"][0]["data"]
                print(f"  status={result['status']}")
                if result["status"] in ("completed", "failed", "cancelled"):
                    break

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

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

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

パターンカタログを調べる

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

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

Show me details about the event-driven architecture pattern.

---

🛠️ ツールの概要

ツール	説明
analyze_architecture	コードを自ら記述するエージェント向けの分析専用パスです。要件とドメインから、推奨スタイル、選択されたパターン、品質指標、一致するドメインを提示します。設計は生成しません。軽量な LLM 呼び出しを 1 回実行します。べき等ではありません。
generate_architecture	要件と選択されたパターンから、アーキテクチャ設計を生成します。処理に時間がかかります（LLM 呼び出し）。べき等ではありません。
evaluate_architecture	既存の設計を品質特性に照らして評価します。処理に時間がかかります（LLM 呼び出し）。べき等ではありません。
design_architecture	生成された設計を必要とする呼び出し元向けの設計成果物パスです。分析 → 生成 → 評価 → 改善を最大 3 回試行し、コンポーネント、関係、API コントラクト、データモデルを返します。処理に時間がかかります（5～10 分）。クライアントのリクエストタイムアウトが短い場合を除き、こちらを使用してください。
submit_architecture_design_job	バックグラウンドの設計ジョブを開始し、すぐに job_id を返します。リクエストタイムアウトが短いクライアント（Cursor、Claude Desktop、TS-SDK）専用です。それ以外のクライアントでは design_architecture を使用してください。get_architecture_design_status を 10～30 秒ごとにポーリングしてください。
get_architecture_design_status	ジョブのステータスをポーリングします。現在のステータス、進捗メッセージ、および completed 時の設計出力全体を返します。
cancel_architecture_design	実行中のジョブをキャンセルします（ベストエフォート。次のパイプラインステージ境界で反映されます。LLM 呼び出し 1 回分かかることがあります）。
list_architecture_patterns	すべての 128 パターンを一覧表示します。category や domain で絞り込めます
get_architecture_pattern	名前を指定して、特定のパターンの JSON 全体を取得します

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

プロンプトの例：

Build a scalable distributed system for processing IoT sensor data with
100k events per second throughput, written in Python, deployed on Kubernetes.

Design an architecture for an e-commerce platform handling flash-sales events.
Domain: e-commerce. Style: microservices.

Show me details about the blackboard pattern.

Call design_architecture with:
  requirements: "ETL pipeline for IoT: Kafka → JSON → Redis geo-enrich → InfluxDB + S3"
  domain: "data-processing"

---

💬 プロンプト

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

プロンプト	引数	機能
/design_architecture_workflow	requirements*	分析 → 生成 → 評価の一連のパイプライン
/explore_pattern_catalog	domain、category	パターン名を埋め込んだ、最新のカタログ検索
/evaluate_my_architecture	focus	評価基準のガイドと、評価結果の優先順位付け
/compare_architecture_styles	style_a*、style_b*、requirements*	2 つの設計を並べて比較します。トークンコストは約 2 倍です

* = 必須の引数

ツールのみをサポートするクライアント

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

---

📖 パターンカタログ

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

list_architecture_patterns()                                  # all 128 patterns
list_architecture_patterns(category="messaging")               # filter by category
list_architecture_patterns(domain="microservices")            # filter by domain
get_architecture_pattern(name="event-driven")                 # full pattern JSON

有効な category 値：messaging、structural、cloud、data、ai_cognitive、specialized、api_gateway、coordination、dataflow、presentation。

MCP リソース経由

mcp_list_resources(server="architecture-pattern")
mcp_read_resource(server="architecture-pattern", uri="pattern://microservices")

パターン JSON の構造

各パターンには、name、category、context、benefits、tradeoffs、quality_attributes（スケーラビリティ／保守性／信頼性／セキュリティ／パフォーマンス／シンプルさ。スコアは 1～10）、suitable_domains、component_types、technology_stack、design_principles、best_practices が含まれます。

---

design-pattern-mcp-local と連携する

このサーバーは どのようなシステム構造を構築するか（アーキテクチャ）に答えます。姉妹プロジェクトの design-pattern-mcp-local は、その内部の各ユニットをどのようにコーディングするか（デザインパターン）に答えます。アーキテクチャパターンはシステム全体（コンポーネント、その関係、API／データ／イベントの契約など）を構成します（例：上記の128パターンのカタログから選ぶ event-driven、pipe-and-filter、microservices）。デザインパターンは、単一のコンポーネント内で繰り返し発生する実装上の問題（参加者、相互作用、言語に依存するコードなど）を解決します（例：姉妹プロジェクトの438パターンのカタログから選ぶ observer、process-manager、circuit-breaker。各パターンには13種類の言語バインディングがあります）。

推奨される順序は、まずマクロ、次にミクロです。

1. Call design_architecture with:
     requirements: "ETL pipeline for IoT: Kafka → JSON → Redis geo-enrich → InfluxDB + S3"
     domain: "data-processing"
   # → components (Kafka source, parser filter, enricher, sinks),
   #   relationships, API contracts, data models, event contracts

2. For each component with non-trivial internal logic, call the sibling's
   select_design_patterns with:
     description: "<component name + responsibilities + constraints from step 1>"
     language: "python"
   # → primary + supporting patterns, participants, implementation_steps,
   #   code_sketch with the bound language variant

IoT の例で具体的な引き継ぎの流れを示します。このサーバーは pipe-and-filter アーキテクチャを出力します（Kafka ソース → JSON パーサーフィルター → ジオロケーションエンリッチャー → InfluxDB／S3 シンク。契約には少なくとも1回の配信とバックプレッシャーが含まれます）。次に、ジオロケーションエンリッチャーのキャッシュミス時の経路について、select_design_patterns を使って「Redis フォールバックを使ったキャッシュアサイド方式のエンリッチメント、Python」と指定します。たとえば、参加者、implementation_steps、Python の code_sketch を含む circuit-breaker と retry のデザインパターンが選ばれます。これはアーキテクチャレベルのコンポーネント契約で参照されますが、実装されることはありません。

両方のサーバーを並行して実行してください（開発ホストのポートはアーキテクチャが :8820、デザインパターンが :8062、systemd は :8810／:8062）。両者は独立しているため、探索時はどちらの順序でも構いません。ただし、アーキテクチャを先に決めることでコンポーネントの境界が安定し、その後、デザインパターンサーバーで内部の詳細を補えます。

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

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/architecture-pattern-mcp/config.json
# Edit ~/.config/architecture-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 の実行後）。

architecture-pattern-mcp --transport stdio

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

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

TEI の起動： どちらのサイドカーイメージ（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 互換ルートを設定します（開発用 Compose の慣例では http://<host>:8080/v1、config.json のデフォルトは末尾に /v1 がない http://pattern-tei-embed:8080 です）。このサーバーのエンベッダー設定には 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/architecture-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://127.0.0.1:8080"
    }
  },
  "retrieval": {
    "bm25_top_k": 0,
    "dense_top_k": 0,
    "top_k_patterns": 5,
    "min_quality_score": 50.0
  },
  "pattern_directory": "~/.config/architecture-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	(必須)	LLM プロバイダーの API キー（LiteLLM に api_key として渡されます）
GENERATOR_PROVIDER	openai	LiteLLM のプロバイダープレフィックス：openai、anthropic、openrouter、…。LiteLLM Providersを参照してください
GENERATOR_BASE_URL	https://api.openai.com/v1	API のベース URL（LiteLLM に api_base として渡されます）
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://127.0.0.1:8080	TEI 埋め込み URL
EMBEDDER_BATCH_SIZE	16	埋め込みバッチサイズ
EMBEDDER_QUERY_INSTRUCTION	(空)	クエリ指示のプレフィックス
EMBEDDER_TEXT_INSTRUCTION	(空)	テキスト指示のプレフィックス
EMBEDDING_CACHE	image: /var/cache/architecture-pattern-mcp/embedding-index · host: ~/.config/architecture-pattern-mcp/embedding-index	Dense レッグのスナップショットパス。再起動時に再読み込みされ（コーパスの再埋め込みは不要）、埋め込み器／コーパス／プローブに変更があると再構築されます。0／false／off／no で無効になります。Embedding-index cacheを参照してください
RETRIEVAL_BM25_TOP_K	0	BM25 ステージ 1 の再現率上限（0=コーパス全体）
RETRIEVAL_DENSE_TOP_K	0	Dense ステージ 1 の再現率上限（0=コーパス全体）
RETRIEVAL_DENSE_WEIGHT	0.7	Dense レッグのステージ 1 フュージョンレッグの重み。RETRIEVAL_BM25_WEIGHT と組み合わせます。両方とも 0 より大きく、合計が 1.0（±1e-3）である必要があります（起動時に検証）。いずれかの重みが 0.05 未満の場合、起動時に警告が記録されます。ステージ 2 の選択ブレンド重み（RETRIEVAL_ANALYSIS_BLEND_WEIGHT／RETRIEVAL_FUSION_BLEND_WEIGHT）とは異なります。注：古いイメージで認識されない設定キーがある場合、起動時に即座に失敗します。
RETRIEVAL_BM25_WEIGHT	0.3	BM25 レッグのステージ 1 フュージョンレッグの重み。RETRIEVAL_DENSE_WEIGHT を参照してください。
RETRIEVAL_TOP_K_PATTERNS	5	選択するパターンの数
RETRIEVAL_MIN_FUSION_SCORE	0.0	rank_fusion ブレンド値に対する関連性の下限（範囲 [0, 2/60] ≈ [0, 0.033]）。デフォルトは 0.0（ゲート無効）。ブレンドの最大値を超える値は起動時に拒否されます。
RETRIEVAL_RERANK_TOP_N	10	再ランキングする上位 N 件（CE 適用後にスラッグでカット）
RETRIEVAL_USE_LEAN_WIRE_SCHEMA	false	簡潔な応答スキーマを使用します
RETRIEVAL_STYLE_SCORE_THRESHOLD	50.0	スタイル推奨に必要な分析スコアの最小値
REASONING_ENABLED	false	サーバー側の推論 MCP 統合 — オプトインで、デフォルトでは無効です（Structured Reasoningを参照）
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	(埋め込み)	shannonthinking 用の JSON リスト形式のコマンド（例：["npx","-y","server-shannon-thinking@latest"]）
REASONING_CODE_REASONING_CMD	(埋め込み)	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	3	設計ループの最大試行回数
RETRIEVAL_MIN_QUALITY_SCORE	50.0	早期終了する品質しきい値
RERANKER_BASE_URL	(デフォルトのリランカー URL)	TEI リランカーのエンドポイント（ホスト:ポート）。モデルは gte-reranker-modernbert-base に固定されています
RERANKER_TIMEOUT	30.0	リランカーのタイムアウト（秒）
RERANKER_MAX_BATCH_SIZE	48	TEI /rerank リクエストあたりのテキスト数の上限。リランカー側のサイドカーの MAX_CLIENT_BATCH_SIZE と MAX_CONCURRENT_REQUESTS の最小値以下である必要があります。HybridPatternRetriever は大きなプールを自動的に分割します。
PATTERN_DIRECTORY	~/.config/architecture-pattern-mcp/pattern	パターンファイルのディレクトリ
VALIDATION_MAX_RETRIES	2	自己修復リトライの最大試行回数
VALIDATION_RETRY_ON_FAIL	true	検証に失敗した場合に再試行します
ARCHITECTURE_PATTERN_JOBS_DB	~/.config/architecture-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 バインドポート
LOGGING_LEVEL	INFO	ログレベル
LOGGING_FORMAT	json	ログ形式：json、text
CONFIG_PATH	~/.config/architecture-pattern-mcp/config.json	設定ファイルのパス

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

密検索レグは、カタログ内のすべてのドメインスラッグ（約254件）を対象とする1つのFAISSインデックスです。コールドビルド後に埋め込みをディスクにスナップショットとして保存し、次回の起動時に再読み込みするため、ウォームスタートではコーパス全体を処理する代わりにプローブ埋め込み1回で済みます（開発用Composeスタックでの測定値：16.5秒 → 0.3秒）。BM25は低コストなので、起動ごとに再構築されます。

• パス：EMBEDDING_CACHE。イメージには /var/cache/architecture-pattern-mcp/embedding-index が組み込まれています。ホスト上で実行する場合（uv）は ~/.config/architecture-pattern-mcp/embedding-index を使用します。
• ファイルの保存場所：ログに表示されるパスはコンテナ内から見たものです。Docker は名前付きボリュームを /var/lib/docker/volumes/<volume-name>/_data に保存します（root が所有するため、ホスト側の /var/cache は仕様上空のままです）。sudo を使わずに確認するには、docker exec <container> ls /var/cache/architecture-pattern-mcp/embedding-index を実行するか、ホスト側の保存場所を確認するには docker volume inspect -f '{{.Mountpoint}}' <volume-name> を実行します。
• コンテナでは名前付きボリュームに保存されます （architecture-pattern-mcp-dev-embedding-index / architecture-pattern-mcp-systemd-embedding-index）。そのため、イメージの再ビルド、コンテナの再作成、docker compose down の後もスナップショットは保持されます。リセットするには docker compose down -v または docker volume rm <name> を実行します。通常の docker run では -v apmcp-embedding-index:/var/cache/architecture-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。

---

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

各 LLM フェーズの呼び出し（ANALYZE / GENERATE / EVALUATE / RETRY）の前に、サーバーはオプションで、上限付きの ThoughtGenerator ループを実行します。各推論ステップをジェネレーター独自の LLM（LlamaIndex LiteLLM。1 ステップにつき 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）。呼び出し間で状態は保持されません。
• 呼び出しごとのサイレントな縮退 — spawn／タイムアウト／ツールのエラーが発生すると WARNING をログに記録し、フェーズは縮退したプロンプト内思考の足場（分解 → 分類 → 調整 → 解決 → 検証）を使って続行します。例外は発生しません。
• 起動時には明示的に通知 — ライフサイクルのヘルスチェックで両方のツールを検査し、いずれかに到達できない場合は解決のヒントとともに ERROR をログに記録します。代わりに起動を失敗させるには、REASONING_FAIL_FAST=true を設定します。
• トレースのキャッシュ — ANALYZE と GENERATE のトレースは設計リクエストごとに 1 回だけ計算され、設計ループの試行間で再利用されます。

有効化と調整

推論はデフォルトで無効です。Stage-0 ベンチマークでは、選択品質の向上がない一方で、エンドツーエンドの設計レイテンシーの約 55%（1 回の実行あたり中央値で 517 秒中 286 秒。トレースがない場合はジェネレーター時間がさらに約 77 秒）が測定されました。16 のシナリオ全体でヒット率と許容可能なプライマリ F1 は同一でした。有効にするには REASONING_ENABLED=true を設定します。

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

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

レイテンシーに関する注意：設計の実行では、推論ツールが 14 回呼び出されます（analyze 8 回、generate 3 回、evaluate 3 回）。これらはシリアルなサブプロセスとして実行されます。Stage-0 ベンチマーク（MiniMax-M2.7 ジェネレーター）での測定値は、1 回の呼び出しあたり 14～30 秒、1 回の実行あたりの推論時間は中央値で 286 秒です。秒ではなく、数分かかります。トレースキャッシュにより、設計ループの試行間で ANALYZE／GENERATE の作業を繰り返さずに済みますが、初回の処理は対象外です。

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

CLI フラグ

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

---

カスタムパターンでの拡張

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

最小限のパターン構造：

{
  "category": "structural",
  "name": "my-custom-pattern",
  "context": "Describe when this pattern applies.",
  "benefits": ["Benefit 1", "Benefit 2"],
  "tradeoffs": ["Tradeoff 1"],
  "quality_attributes": {
    "scalability": 7,
    "maintainability": 8,
    "reliability": 7,
    "security": 6,
    "performance": 7,
    "simplicity": 5
  }
}

必須フィールド：category、name、context、benefits、tradeoffs、quality_attributes。

category に指定できる値：messaging、structural、cloud、data、ai_cognitive、specialized、api_gateway、coordination、dataflow、presentation。

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

---

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

design_architecture と、それに対応するジョブトリオは、複数段階の LLM パイプラインを実行するため、1 回の呼び出しに 5～10 分かかることがあります。単一フェーズのツールははるかに高速です。analyze_architecture は軽量な LLM 呼び出しを 1 回行い（コミット済みベンチマークコーパスでの平均は約 20 秒、負荷が高いホストでの実測は 66 秒）、generate_architecture と evaluate_architecture はそれぞれ大規模な生成を 1 回行います（約 2～3 分）。設計処理に時間がかかるのはワークロードに起因するもので、バグではありません。生成側の LLM は、大量の入力ペイロード（128 パターンのカタログから選択されたパターン定義、要件、前段階すべての完全な出力）を処理し、構成要素、関係、API 契約、データモデル、イベント契約、品質スコアを含む、大規模で厳密に構造化された JSON ドキュメントをトークンごとに生成する必要があります。design_architecture パイプラインでは、生成 → 評価を最大 3 回繰り返すため、1 回の呼び出しで LLM とのラウンドトリップが 9 回以上発生することがあります。

タイムアウトの問題

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 つのツールが永続的なジョブハンドルを提供します。

submit_architecture_design_job(requirements, domain, override_style)  → job_id
get_architecture_design_status(job_id)                                  → {status, result, error}
cancel_architecture_design(job_id)                                      → {cancelled, status}

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

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

ジョブストアは ~/.config/architecture-pattern-mcp/jobs.db にある SQLite です（ARCHITECTURE_PATTERN_JOBS_DB で設定可能です）。

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

examples/architecture_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 (5-10 min)
make client-analyze        # analyze_architecture only
make client-design         # design_architecture, the long synchronous call

どちらのターゲットも同じ直接クライアントを実行します（--tool analyze|design）。make client-design を実行すると、サーバーが長時間のリクエストを正しく完了することを確認できます。タイムアウトの問題はクライアント側だけにあります。MCP をラップするホストアプリケーション（Claude Desktop、Cursor、…）では独自のタイムアウトが設定されています。その場合は非同期ジョブの 3 つの機能を使用してください。

トラブルシューティング

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

1. エージェントの MCP 接続を確認します。Claude Code では /mcp、OpenCode では opencode mcp list、Codex では codex mcp list を実行します。
2. サーバープロセスが起動したことを確認します。compose のログに MCPArchitectServer initialized と表示されるはずです。
3. TEI 埋め込みモデルが正常な状態であることを確認します。コンテナー内で curl http://127.0.0.1:8080/health を実行します。

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

サーバーは TEI 埋め込みモデルが正常な状態になるまで待機します。

docker compose -f docker/docker-compose.yml logs pattern-tei

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

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

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

• ファイルの拡張子は .json である必要があります。
• 必須フィールド：category、name、context、benefits、tradeoffs、quality_attributes
• docs/pattern-schema.json に照らして検証します。

---

ビルドと開発

よく使う 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 client-analyze	analyze のみを行う MCP クライアントのデモを実行します（サーバーの起動が必要です）
make client-design	同期型 design_architecture クライアントのデモを実行します（長時間実行。サーバーの起動が必要です）
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/architecture-pattern-mcp	ghcr.io/olk/architecture-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 は 2FA を迂回します。ログイン後にトークンは破棄されますが、ログアウトするまで認証情報は ~/.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/architecture-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/architecture-pattern-mcp.service	systemd ユニット
systemd/docker-compose.yml	本番用 Compose 構成（build: なし、絶対パスを使用）
systemd/README.md	インストール、確認、トラブルシューティングを網羅した手順書

本番用 Compose ファイルは、docker/docker-compose.yml のデプロイ用バリアントです。 build: セクションはなく（イメージは事前にビルドする必要があります）、絶対パスを使用し、 ホスト上の /etc/architecture-pattern-mcp/ に配置されます。systemd 管理下のプロジェクトでは、 必要に応じて開発用 Compose と共存できるよう、別の名前 apmcp-systemd を使用します。

このスタックには 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 分待ちます

pattern-tei-infra.service が active (running) になった後にのみ、 architecture-pattern-mcp.service を起動してください。詳しくは 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/architecture-pattern-mcp/
sudo install -d /etc/architecture-pattern-mcp/config
sudo install -m 644 systemd/docker-compose.yml /etc/architecture-pattern-mcp/
sudo install -m 644 ~/.config/architecture-pattern-mcp/config.json /etc/architecture-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/architecture-pattern-mcp/.env
sudo $EDITOR /etc/architecture-pattern-mcp/.env
# Contents:
#   MINIMAXAI_API_KEY=sk-...
#   COMPOSE_PROJECT_NAME=apmcp-systemd

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

確認

systemctl status は数秒以内に active (exited) を表示しますが、コンテナが正常な状態になるまで最大約 2 分かかります（TEI 埋め込みモデルの start_period: 120s）。 ユニットはヘルスチェックの完了を待ちません。

systemctl status architecture-pattern-mcp
journalctl -u architecture-pattern-mcp -n 50
docker compose -p apmcp-systemd -f /etc/architecture-pattern-mcp/docker-compose.yml ps
# GET /health is 404 by design; the JSON-RPC initialize POST is the probe.
curl -s -o /dev/null -w '%{http_code}\n' -X POST "http://localhost:8810/mcp" \

日常の操作

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

スタックの更新

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

アンインストール

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

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

---

ライセンス

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