Wangsu Terraform Knowledge Base MCP Server

Wangsu Terraform Provider 지식 베이스 검색 서비스로, MCP(Model Context Protocol)를 통해 Claude Code 등 클라이언트에 도구 호출 인터페이스를 제공합니다.

이게 뭔가요?

이것은 순수 검색형 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 대역)만 개방

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가 변경되면 다음 세 곳을 동기화해야 하며, 하나라도 빠지면 안 됩니다:

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는 전용 계정이며, 로그인 셸이 아닙니다(/usr/sbin/nologin), 권한 최소화 원칙을 따릅니다.

• 원본 서버 Caddy는 tls internal 자체 서명 인증서를 사용하며, 网宿 CDN 회귀 소스 신뢰용으로만 사용되고 공개 브라우저에는 노출되지 않습니다.

• MCP SDK 내장 DNS rebinding 보호(TransportSecuritySettings)에 허용된 Host / Origin 화이트리스트가 구성되어 있습니다.

License

"Internal use only"