Wangsu Terraform Knowledge Base MCP Server

Wangsu Terraform Provider 知识库检索服务，通过 MCP（Model Context Protocol）向 Claude Code 等客户端提供工具调用接口。

这是什么

这是一个纯检索型 MCP 服务器：它只负责从向量数据库中检索与 Wangsu Terraform Provider 相关的文档片段，不在服务端调用任何 LLM 生成答案。真正"读懂片段、综合出回答"的是调用方自己的 Claude 客户端，消耗的是调用方自己的账号额度。

这样设计有两个好处：

• 服务端不需要配置 ANTHROPIC_API_KEY，团队所有人的调用费用不会集中记在某一个人的账号上

• 攻击面更小——服务端唯一需要保护的敏感信息只有一个鉴权 token

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 段）

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

轮换 / 撤销 Token

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

新 token 需要通过密码管理器或私聊重新分发给团队成员，团队成员需要重新执行一次 claude mcp add（先 claude mcp remove wangsu-kb，再用新 token 重新添加）。

注意：token 是唯一的访问门禁，不要贴进任何会提交 git 的地方，也尽量避免在命令行历史中留下明文（建议用环境变量或密码管理器传递）。

Elastic IP 变更

如果 Elastic IP 发生变化，以下三处需要同步更新，缺一不可：

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 用户 home 目录不存在或无写权限、磁盘空间不足、网络连通性问题。

安全设计要点

• 服务端不持有 Anthropic API Key，推理成本和额度完全由调用方自己承担

• MCP_AUTH_TOKEN 用 openssl rand -hex 32 生成，权限 600，仅 wangsu-mcp 用户可读

• 运行服务的系统账号 wangsu-mcp 为专用账号，非登录 shell（/usr/sbin/nologin），遵循权限最小化原则

• 源站 Caddy 使用 tls internal 自签证书，仅供网宿 CDN 回源信任，不面向公网浏览器

• MCP SDK 内置的 DNS rebinding 防护（TransportSecuritySettings）已配置好允许的 Host / Origin 白名单

License

"Internal use only"