Wangsu Terraform Knowledge Base MCP Server

Сервис поиска по базе знаний Wangsu Terraform Provider, предоставляющий клиентам, таким как Claude Code, интерфейс вызова инструментов через MCP (Model Context Protocol).

Что это

Это чисто поисковый MCP-сервер: он отвечает только за поиск фрагментов документации, связанных с Wangsu Terraform Provider, в векторной базе данных и не вызывает на сервере какие-либо LLM для генерации ответов. На самом деле «понимает фрагменты и формирует ответ» собственный клиент Claude вызывающей стороны, а расходуется квота учётной записи вызывающей стороны.

У такого решения два преимущества:

• На сервере не требуется настраивать ANTHROPIC_API_KEY — расходы на вызовы всех членов команды не будут привязаны к аккаунту одного человека.

• Поверхность атаки меньше: единственная чувствительная информация, которую нужно защищать на сервере, — это один токен аутентификации.

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 вызывающей стороны на основе этих материалов самостоятельно формирует итоговый ответ и по правилам разделяет вопросы на три категории:

• Категория 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: символом продолжения строки является обратная кавычка `, а не \; рекомендуется записать команду одной строкой, чтобы из-за проблем с разбором символа продолжения не потерялся заголовок аутентификации.

Проверьте успешность подключения:

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 (IP-диапазоны Wangsu для обратных запросов к источнику).

3. Настройте CDN Wangsu: укажите в качестве источника (origin) 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 изменился, необходимо одновременно обновить следующие три места — все они обязательны:

1. IP источника (origin) в консоли Wangsu.

2. IP в /etc/caddy/Caddyfile (если IP явно указан в Caddyfile).

3. Правила входящего трафика на порт 443 в группе безопасности (если они были ограничены конкретными IP-диапазонами).

Известная проблема: первая загрузка модели embedding выполняется медленно

При запуске mcp_server.py загружается модель embedding BAAI/bge-small-en-v1.5. Если локального кэша (/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 Wangsu и не рассчитан на публичные браузеры.

• Встроенная в MCP SDK защита от DNS rebinding (TransportSecuritySettings) настроена с разрешённым белым списком Host / Origin.

Лицензия

«Только для внутреннего использования»