Servidor MCP de la Base de Conocimientos de Wangsu Terraform

Servicio de recuperación de la base de conocimientos del Proveedor Wangsu Terraform, que proporciona una interfaz de invocación de herramientas a clientes como Claude Code a través de MCP (Protocolo de Contexto de Modelo).

Qué es esto

Este es un servidor MCP de solo recuperación: únicamente se encarga de recuperar fragmentos de documentación relacionados con el Proveedor Wangsu Terraform desde una base de datos vectorial, sin invocar ningún LLM en el servidor para generar respuestas. Quien realmente "lee los fragmentos y sintetiza la respuesta" es el propio cliente Claude del llamador, consumiendo la cuota de la cuenta del llamador.

Este diseño tiene dos ventajas:

• El servidor no necesita configurar ANTHROPIC_API_KEY, y los costes de invocación de todo el equipo no se concentran en la cuenta de una sola persona

• La superficie de ataque es menor: la única información sensible que el servidor necesita proteger es un token de autenticación

Related MCP server: NetApp AIDE MCP Server

Arquitectura

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

Componentes principales

Herramientas

search_wangsu_terraform(question: str) -> str

Recupera de la base de conocimientos de Wangsu Terraform y devuelve:

1. Un bloque fijo de reglas de respuesta (ANSWER_GUIDANCE) — para restringir el comportamiento del Claude llamador y evitar alucinaciones en nombres de parámetros/recursos exclusivos de Wangsu

2. Los fragmentos de documentación más relevantes recuperados (Top 8 por defecto), cada uno con el nombre del archivo de origen y la puntuación de relevancia

El Claude del llamador sintetizará la respuesta final basándose en este contenido y clasificará las preguntas en tres categorías según las reglas:

• Categoría A: detalles exclusivos del Proveedor Wangsu → debe basarse en el contenido recuperado; no se pueden inventar nombres de campos no recuperados textualmente

• Categoría B: conocimientos generales de Terraform/HCL → puede responder con su propio conocimiento si el contenido recuperado no lo cubre

• Categoría C: preguntas sobre otros proveedores de nube → no se debe aplicar contenido exclusivo de Wangsu a otros proveedores

Forma de conexión

Tras obtener el MCP_AUTH_TOKEN distribuido por el administrador, ejecute en su máquina local (sustituya <token> por el valor real):

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

Nota para usuarios de Windows PowerShell: el carácter de continuación de línea es el acento grave ` y no \; se recomienda escribir el comando directamente en una sola línea para evitar problemas de análisis del carácter de continuación que provoquen la pérdida de la cabecera de autenticación.

Verifique si la conexión se ha establecido correctamente:

claude mcp list

Debería mostrar wangsu-kb: ... (HTTP) — Connected. A partir de entonces, basta con hacer preguntas relacionadas con Wangsu Terraform en la conversación; Claude invocará automáticamente esta herramienta cuando sea necesario.

Despliegue en el servidor

Los pasos completos de despliegue se encuentran en deploy/DEPLOY.md; resumen:

1. Crear una instancia EC2 (Ubuntu 24.04 LTS, t3.small, 8-20GB gp3), asociar una IP Elástica

2. El grupo de seguridad solo abre el 22 (IP del administrador) y el 443 (rango de IPs de origen de Wangsu)

3. Configurar el CDN de Wangsu: el origen apunta a la IP Elástica, HTTPS de origen, desactivar la verificación del certificado del origen (el origen usa certificado autofirmado)

4. Subir los archivos del proyecto a /opt/wangsu-kb, crear un entorno virtual e instalar las dependencias

5. Crear un usuario de sistema dedicado wangsu-mcp para ejecutar el servicio (privilegios mínimos, no root)

6. /etc/wangsu-mcp/env almacena MCP_AUTH_TOKEN y PORT, permisos 600

7. systemd gestiona el ciclo de vida del servicio (auto-inicio al arrancar, reinicio automático ante caídas)

8. Caddy usa tls internal con certificado autofirmado como proxy inverso, sin pasar por Let's Encrypt

Operación y mantenimiento

Ver el estado del servicio / registros

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

Actualizar el contenido de la base de conocimientos

Tras modificar localmente los documentos fuente en el directorio data/, vuelva a ejecutar ingest.py para generar un nuevo chroma_db/, sincronícelo al servidor y reinicie el servicio:

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

Rotar / revocar Token

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

El nuevo token debe redistribuirse a los miembros del equipo mediante un gestor de contraseñas o un chat privado. Los miembros del equipo deben volver a ejecutar claude mcp add (primero claude mcp remove wangsu-kb y luego volver a añadirlo con el nuevo token).

Nota: el token es la única puerta de acceso; no lo pegue en ningún lugar que se vaya a enviar a git, y evite dejarlo en texto plano en el historial de la línea de comandos (se recomienda usar variables de entorno o un gestor de contraseñas para transmitirlo).

Cambio de IP Elástica

Si la IP Elástica cambia, los siguientes tres lugares deben actualizarse de forma sincronizada, sin que falte ninguno:

1. La IP de origen en la consola de Wangsu

2. La IP en /etc/caddy/Caddyfile (si el Caddyfile especifica explícitamente la IP)

3. La regla de entrada 443 del grupo de seguridad (si se ha restringido a rangos de IP específicos)

Problema conocido: la carga inicial del modelo de embeddings es lenta

Al iniciarse, mcp_server.py carga el modelo de embeddings BAAI/bge-small-en-v1.5. Si la caché local (/home/wangsu-mcp/.cache/huggingface) no existe, el servicio primero lo descargará de internet (aproximadamente 67MB); si la descarga falla, reintentará 3 veces (retroceso de 3s/9s/27s); si todos los intentos fallan, el proceso saldrá y systemd lo reiniciará automáticamente para reintentar.

Si el servicio falla repetidamente al reiniciarse, puede simular manualmente el entorno de ejecución del usuario wangsu-mcp para diagnosticar:

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(\"加载成功\")
"'

Causas comunes: el directorio home del usuario wangsu-mcp no existe o no tiene permisos de escritura, espacio en disco insuficiente, problemas de conectividad de red.

Puntos clave del diseño de seguridad

• El servidor no posee la API Key de Anthropic; el coste y la cuota de inferencia los asume completamente el llamador

• MCP_AUTH_TOKEN se genera con openssl rand -hex 32, permisos 600, solo legible por el usuario wangsu-mcp

• La cuenta de sistema wangsu-mcp que ejecuta el servicio es una cuenta dedicada, sin shell de inicio de sesión (/usr/sbin/nologin), siguiendo el principio de privilegios mínimos

• El Caddy del origen usa certificado autofirmado con tls internal, solo para que el CDN de Wangsu confíe en el origen, no expuesto a navegadores públicos

• La protección integrada contra rebinding de DNS del SDK de MCP (TransportSecuritySettings) ya está configurada con la lista blanca de Host / Origin permitidos

Licencia

"Uso interno únicamente"