Wangsu Terraform ナレッジベース MCP サーバー

Wangsu Terraform Provider ナレッジベース検索サービス。 MCP（Model Context Protocol）を通じて Claude Code などのクライアントにツール呼び出しインターフェースを提供します。

これは何か

これは純粋な検索型 MCP サーバーです。ベクトルデータベースから Wangsu Terraform Provider に関連するドキュメント断片を検索するだけで、サーバー側で LLM を呼び出して回答を生成することはありません。実際に「断片を読み解き、回答を総合する」のは呼び出し側の Claude クライアントであり、消費されるのは呼び出し側自身のアカウント枠です。

この設計には2つの利点があります：

• サーバー側で ANTHROPIC_API_KEY を設定する必要がなく、チーム全員の呼び出し費用が特定の個人のアカウントに集中することがありません

• 攻撃面が小さい——サーバー側で保護すべき機密情報は認証トークン1つだけです

Related MCP server: NetApp AIDE MCP Server

アーキテクチャ

团队成员的 Claude Code 客户端（用自己的账号做推理）
        │
        │ MCP over HTTP，携带 Bearer Token
        ▼
网宿 CDN（HTTPS，证书由网宿托管）
        │
        │ 回源 HTTPS，源站证书校验已关闭
        ▼
Caddy（反向代理，tls internal 自签证书，监听 443）
        │
        │ 转发到本地 8000 端口
        ▼
FastMCP + uvicorn（mcp_server.py）
        │
        │ 向量检索
        ▼
Chroma 向量数据库（本地持久化）

コアコンポーネント

ツール

search_wangsu_terraform(question: str) -> str

Wangsu Terraform ナレッジベースを検索し、以下を返します：

1. 固定の回答ルール説明（ANSWER_GUIDANCE）——呼び出し側の Claude の動作を制約し、Wangsu 固有のパラメータ名・リソース名での幻覚（ハルシネーション）を防止

2. 検索で見つかった最も関連性の高いドキュメント断片（デフォルト Top 8）。各断片にはソースファイル名と関連度スコアが付属

呼び出し側の Claude はこれらの内容に基づいて最終回答を自ら総合し、ルールに従って3種類の問題を分類します：

• A 類：Wangsu Provider 固有の詳細 → 検索内容を基準とし、逐語的に検索されていないフィールド名は捏造してはならない

• B 類：Terraform/HCL の一般的な知識 → 検索内容でカバーされていない場合は自身の知識で回答可能

• C 類：他のクラウドベンダーの問題 → Wangsu 固有の内容を他のベンダーに適用してはならない

接続方法

管理者から配布された MCP_AUTH_TOKEN を取得したら、ローカルマシンで実行します（<token> を実際の値に置き換えてください）：

claude mcp add --transport http wangsu-kb https://<你的加速域名>/mcp \
  --header "Authorization: Bearer <token>" -s user

Windows PowerShell ユーザーへの注意：継続行文字はバッククォート ` であり \ ではありません。継続行の解析問題による認証ヘッダー喪失を避けるため、コマンドは1行で記述することをお勧めします。

接続成功の確認：

claude mcp list

wangsu-kb: ... (HTTP) — Connected と表示されるはずです。その後、会話内で Wangsu Terraform 関連の質問を直接行えば、Claude が必要に応じて自動的にこのツールを呼び出します。

サーバー側デプロイ

完全なデプロイ手順は deploy/DEPLOY.md を参照してください。概要は以下の通りです：

1. EC2 インスタンスを作成（Ubuntu 24.04 LTS、t3.small、8-20GB gp3）、Elastic IP をバインド

2. セキュリティグループは 22（管理者 IP）と 443（網宿（Wangsu）オリジン IP レンジ）のみ開放

3. 網宿 CDN を設定：オリジンを Elastic IP に向け、HTTPS でオリジンに戻し、オリジン証明書検証を無効化（オリジンは自己署名証明書を使用）

4. プロジェクトファイルを /opt/wangsu-kb にアップロードし、仮想環境を作成して依存関係をインストール

5. 専用システムユーザー wangsu-mcp を作成してサービスを実行（権限最小化、root ではない）

6. /etc/wangsu-mcp/env に MCP_AUTH_TOKEN と PORT を保存、権限は 600

7. systemd でサービスのライフサイクルを管理（起動時自動起動、クラッシュ時自動再起動）

8. Caddy は tls internal で自己署名証明書を使用してリバースプロキシを実行。Let's Encrypt は使用しない

運用

サービス状態・ログの確認

sudo systemctl status wangsu-mcp
sudo systemctl status caddy
sudo journalctl -u wangsu-mcp -f
sudo journalctl -u caddy -f

ナレッジベース内容の更新

ローカルで data/ ディレクトリ配下のソースドキュメントを変更したら、ingest.py を再実行して新しい chroma_db/ を生成し、サーバーに同期してからサービスを再起動します：

rsync -avz --exclude '.git' -e "ssh -i your-key.pem" \
  ./chroma_db/ ubuntu@<Elastic IP>:/tmp/chroma_db_new/

# 登录服务器
sudo systemctl stop wangsu-mcp
sudo rm -rf /opt/wangsu-kb/chroma_db
sudo mv /tmp/chroma_db_new /opt/wangsu-kb/chroma_db
sudo chown -R wangsu-mcp:wangsu-mcp /opt/wangsu-kb/chroma_db
sudo systemctl start wangsu-mcp

トークンのローテーション / 失効

openssl rand -hex 32                          # 生成新token
sudo nano /etc/wangsu-mcp/env                  # 替换 MCP_AUTH_TOKEN
sudo systemctl restart wangsu-mcp

新しいトークンはパスワードマネージャーまたは個別チャットでチームメンバーに再配布する必要があります。チームメンバーは claude mcp add を再実行する必要があります（先に claude mcp remove wangsu-kb を実行し、新しいトークンで再追加）。

注意：トークンは唯一のアクセスゲートです。git にコミットされる場所には貼り付けず、コマンドライン履歴に平文が残らないようにしてください（環境変数またはパスワードマネージャーでの受け渡しを推奨）。

Elastic IP の変更

Elastic IP が変更された場合、以下の3箇所を同期して更新する必要があります。どれも欠かせません：

1. 網宿コンソールのオリジン IP

2. /etc/caddy/Caddyfile 内の IP（Caddyfile に IP が明示的に記述されている場合）

3. セキュリティグループの 443 インバウンドルール（特定の IP レンジに絞り込んでいる場合）

既知の問題：embedding モデルの初回ロードが遅い

mcp_server.py 起動時に BAAI/bge-small-en-v1.5 embedding モデルをロードします。ローカルキャッシュ（/home/wangsu-mcp/.cache/huggingface）が存在しない場合、サービスはまずネットワークからダウンロードします（約 67MB）。ダウンロード失敗時は3回再試行（3s/9s/27s のバックオフ）し、すべて失敗するとプロセスは終了し、systemd が自動再起動して再試行します。

サービスが繰り返し再起動に失敗する場合は、wangsu-mcp ユーザーの実行環境を手動でシミュレートして調査できます：

sudo -u wangsu-mcp bash -c '
cd /opt/wangsu-kb
set -a; source /etc/wangsu-mcp/env; set +a
./venv/bin/python -c "
from llama_index.embeddings.fastembed import FastEmbedEmbedding
FastEmbedEmbedding(model_name=\"BAAI/bge-small-en-v1.5\")
print(\"加载成功\")
"'

よくある原因：wangsu-mcp ユーザーのホームディレクトリが存在しない、または書き込み権限がない、ディスク容量不足、ネットワーク接続の問題。

セキュリティ設計の要点

• サーバー側は Anthropic API Key を保持しない。推論コストと枠は完全に呼び出し側が負担

• MCP_AUTH_TOKEN は openssl rand -hex 32 で生成し、権限 600、wangsu-mcp ユーザーのみ読み取り可能

• サービスを実行するシステムアカウント wangsu-mcp は専用アカウントで、ログインシェルなし（/usr/sbin/nologin）、権限最小化の原則に準拠

• オリジンの Caddy は tls internal の自己署名証明書を使用。網宿 CDN のオリジンへの信頼のみを目的とし、パブリックブラウザには公開しない

• MCP SDK 組み込みの DNS rebinding 対策（TransportSecuritySettings）で許可する Host / Origin のホワイトリストを設定済み

ライセンス

「内部使用のみ」