使用说明

🔌 bigtorig-mcp-hub

Hostinger基础架构的模型上下文协议（MCP）服务器

部署在Kubernetes（KIND）上的生产级FastMCP服务器，提供对上认知基础设施服务的统一访问 bigtorig.com此MCP中心使Claude和其他AI助手能够通过高可用、自动扩展的架构与您的自托管堆栈进行交互。

🌐 实时端点： https://mcp.bigtorig.com/sse

📋 目录

概述
建筑
当前状态
可用工具
部署
Kubernetes优势
用法
发展路线图
故障排除
资源

🌍 概述

什么是bigtorig mcp中心？

此存储库演示了 生产级MCP服务器 Kubernetes上的部署，展示了容器编排相对于仅使用Docker的部署的优势。它的作用是：

基础设施基金会 -基于Kubernetes的部署架构
高可用性演示 -自愈、负载平衡、多副本设置
可扩展性平台 -已准备好添加数据库工具（Postgres、Qdrant、Neo4j）

MCP服务器之旅的第二部分

这是 第二部分 由两部分组成的教程：

第一部分 (01.mcp服务器)：仅部署Docker，配备8个实用的监控工具
第二部分 （本项目）：Kubernetes部署展示编排优势

关键见解： 第一部分展示了MCP可以做什么。第二部分展示了如何将其部署到生产环境中。

🏗️ 建筑

基础结构拓扑

graph TB
    User[AI Assistant<br/>Claude Desktop] -->|HTTPS| CF[Cloudflare DNS<br/>mcp.bigtorig.com]
    CF --> Caddy[Caddy Reverse Proxy<br/>TLS Termination]
    Caddy --> NP[KIND NodePort<br/>172.23.0.3:30800]
    
    NP --> K8S[KIND Cluster<br/>3 Nodes]
    
    subgraph "Kubernetes Cluster"
        K8S --> SVC[mcp-hub-service<br/>Load Balancer<br/>ClusterIP: 10.96.81.155]
        SVC -->|Round-robin| POD1[Pod 1<br/>k8s-worker<br/>10.244.2.6]
        SVC -->|Round-robin| POD2[Pod 2<br/>k8s-worker2<br/>10.244.1.x]
    end
    
    subgraph "Future Services"
        PG[(Postgres<br/>Supabase)]
        QD[(Qdrant<br/>Vector DB)]
        NEO[(Neo4j<br/>Graph DB)]
    end
    
    POD1 -.->|Coming Soon| PG
    POD1 -.->|Coming Soon| QD
    POD1 -.->|Coming Soon| NEO
    POD2 -.->|Coming Soon| PG
    POD2 -.->|Coming Soon| QD
    POD2 -.->|Coming Soon| NEO

部署堆栈

层	组件	用途
域名系统	Cloudflare	域名管理
传输层安全	Caddy	HTTPS终止
编排	KIND（Kubernetes）	容器编排
负载均衡器	Kubernetes服务	流量分布
应用	FastMCP（Python）	MCP协议服务器
运行时	Python 3.11+UV	快速依赖管理

Kubernetes资源

Deployment: mcp-hub
├── Replicas: 2 (can scale to 10+)
├── Image: bigtorig-mcp-hub:latest
├── Resources:
│   ├── Requests: 100m CPU, 128Mi RAM
│   └── Limits: 500m CPU, 512Mi RAM
└── Environment: Secrets from mcp-hub-secrets

Service: mcp-hub-service
├── Type: NodePort
├── Port: 8000 (internal)
├── NodePort: 30800 (external)
└── Selector: app=mcp-hub

Secret: mcp-hub-secrets
├── postgres-user
├── postgres-password
├── qdrant-api-key
├── neo4j-user
└── neo4j-password

📊 当前状态

第一阶段：基础✅ 完成

集中： Kubernetes基础设施和部署架构

交付：

✅ 3节点KIND集群（1个控制平面，2个工人）
✅ Docker镜像构建并加载到集群中
✅ 带有2个副本的Kubernetes部署
✅ 具有负载平衡的NodePort服务
✅ 凭据的机密管理
✅ Caddy反向代理 https://mcp.bigtorig.com/sse
✅ 通过Cloudflare进行外部HTTPS访问
✅ 展示自我修复（自动吊舱更换）
✅ 演示了水平缩放（2→3→2个副本）

第二阶段：数据库集成✅ 完成

集中： 与会话管理完全集成生产数据库

交付：

✅ ClientIP会话关联 SSE兼容性（关键修复！）
✅ 已连接 affirmation_app Postgres数据库
✅ 5个类别共16个工具
✅ Postgres：5个工具（列表/创建数据库、查询、表、模式）
✅ MySQL：3个工具（查询、表、模式）
✅ Qdrant:3个工具（搜索、收藏、信息）
✅ Neo4j：3个工具（查询、节点、关系）
✅ 基础：2个工具（健康、服务）

🔧 关键配置： 该服务现在使用 ClientIP会话关联 以确保SSE会话与多个副本正确工作。如果没有这个，存储在内存中的FastMCP 2.x会话在Pod之间进行负载平衡时会导致“找不到会话”错误。

# k8s/service.yaml
sessionAffinity: ClientIP
sessionAffinityConfig:
  clientIP:
    timeoutSeconds: 10800  # 3 hours

第三阶段：高级功能🔮 未来

水平Pod自动缩放器（自动缩放）
高级健康探针（活性+准备状态）
Prometheus指标导出
多环境部署（开发、暂存、生产）
CI/CD管道集成

🧰 可用工具

总计：5个类别的16个工具

基础工具（2）

1.健康检查

检查MCP服务器是否运行正常。

例子： “检查bigtorig MCP集线器是否正常”

2.列表_服务

列出所有可用的基础设施服务及其工具。

例子： “MCP中心提供哪些服务？”

Postgres工具（5）

已连接到： affirmation_app Supabase数据库

3.postgres_list_databases

列出Postgres/Supabase服务器上的所有数据库。

例子： “列出我服务器上的所有Postgres数据库”

4.postgres_create_database

创建一个新的Postgres数据库（带有验证和安全检查）。

例子： “创建一个名为my_app_db的新数据库”

5.postgres_query

对当前数据库执行SELECT查询（为安全起见为只读）。

例子： “显示用户表的前10行”

6.postgres_list_tables

列出当前数据库架构中的所有表。

例子： “确认_应用程序数据库中存在哪些表？”

7.postgres_descripte_table

获取特定表的详细架构信息。

例子： “描述肯定表的结构”

MySQL工具（3）

已连接到： maui_app_db 数据库

8.mysql_query

对MySQL数据库执行SELECT查询（为安全起见为只读）。

例子： “查询MySQL中的用户表”

9.mysql_list_tables

列出MySQL数据库中的所有表。

例子： “显示maui数据库中的所有表”

10.mysql_describe_table

获取MySQL表的详细模式信息。

例子： “产品表的结构是什么？”

Qdrant工具（3）

用于语义搜索的矢量数据库

11.qdrant_search

执行语义向量搜索（占位符-需要嵌入模型）。

例子： “在Qdrant中搜索类似文档”

12.qdrant_list_collections

列出所有矢量集合。

例子： “Qdrant有哪些系列可供选择？”

13.qdrant_collection_info

获取特定收藏的详细信息。

例子： “显示文档收集的详细信息”

Neo4j工具（3）

用于关系查询的图形数据库

14.neo4j_query

执行Cypher查询（只读MATCH操作）。

例子： “查找Neo4j中的所有Person节点”

15.新4j_list_nodes

列出图形数据库中的节点，可选择按标签筛选。

例子： “列出所有电影节点”

16.neo4j_get关系

获取图中节点之间的关系。

例子： “显示Person节点的关系” “端点”：“qdrant:6333”， “状态”：“可用”， “工具”：[“即将推出”] }, “neo4j”：{ “name”：“Neo4j图形数据库”， “端点”：“neo4j：7687”， “状态”：“可用”， “工具”：[“即将推出”] } } }


**Example Usage:**

用户：“bigtorig提供哪些基础设施服务？” 克劳德：使用list_services工具结果：3个服务就绪（Postgres、Qdrant、Neo4j），工具即将推出


**Equivalent Command:**
```bash
kubectl get svc -n default | grep -E "postgres|qdrant|neo4j"

🚀 部署

先决条件

✅ 具有SSH访问权限的Hostinger服务器
✅ KIND集群正在运行（建议使用3节点设置）
✅ Docker已安装
✅ 为KIND集群配置kubectl
✅ Caddy反向代理正在运行
✅ 已配置域（mcp.bigtorig.com→ 服务器IP）

快速开始

# 1. Navigate to project directory
cd /home/charles/projects/02-StreamableHTTP-mcp-server/02.bigtorig-mcp-hub

# 2. Build Docker image
docker build -t bigtorig-mcp-hub:latest .

# 3. Load into KIND cluster
kind load docker-image bigtorig-mcp-hub:latest --name k8s

# 4. Create Kubernetes secrets
kubectl apply -f k8s/secrets-example.yaml
# (Edit secrets-example.yaml with real credentials first)

# 5. Deploy to Kubernetes
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml

# 6. Verify deployment
kubectl get pods -l app=mcp-hub
kubectl get svc mcp-hub-service

# 7. Configure Caddy (add to Caddyfile)
# mcp.bigtorig.com {
#     reverse_proxy http://172.23.0.3:30800
# }

# 8. Reload Caddy
docker exec caddy caddy reload --config /etc/caddy/Caddyfile

# 9. Test external access
curl -I https://mcp.bigtorig.com/sse

预期结果： HTTP/2 200 content-type: text/event-stream

有关详细的部署说明，请参阅部署.md.

⚡ Kubernetes优势

使用Kubernetes可以获得什么（仅与Docker相比）

特性	第一部分（Docker）	第二部分（Kubernetes）	优势
复制品	1个容器	2+个吊舱	高可用性
自动修复	手动重启	自动	零接触恢复
负载均衡	无	服务LB	流量分布
扩展	手册	`kubectl scale`	易于水平缩放
更新	所需停机时间	滚动更新	零停机时间
秘密	.env文件	Kubernetes机密	加密存储
分布	单主机	多节点	容错

已证明的好处

1.自我修复

# Delete a pod
kubectl delete pod mcp-hub-64c475c6b-gdq8x

# Watch automatic recreation
kubectl get pods -l app=mcp-hub
# New pod created in 3 seconds! Service never went down.

2.水平缩放

# Scale to 3 replicas
kubectl scale deployment mcp-hub --replicas=3

# Instant: 3 pods running across cluster
kubectl get pods -l app=mcp-hub -o wide

3.负载平衡

# All requests go through Service
curl https://mcp.bigtorig.com/sse
# Traffic automatically distributed across pods

有关详细比较，请参阅 KUBERNETES-BENEFITS.md.

💻 用法

Claude桌面配置

增添 claude_desktop_config.json:

{
  "mcpServers": {
    "bigtorig-hub": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.bigtorig.com/sse"
      ]
    }
  }
}

地点：

窗户： %APPDATA%\Claude\claude_desktop_config.json
macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
Linux： ~/.config/Claude/claude_desktop_config.json

添加后， 完全重新启动克劳德桌面.

测试工具

测试1：健康检查

User: "Check if the bigtorig MCP hub is healthy"

Expected: 
{
  "status": "healthy",
  "service": "bigtorig-mcp-hub",
  "version": "0.1.0"
}

测试2：列出服务

User: "What infrastructure services are available in bigtorig?"

Expected: 
3 services listed (Postgres, Qdrant, Neo4j) with endpoints and future tools

手动测试（无Claude）

# Test with mcp-remote directly
npx mcp-remote https://mcp.bigtorig.com/sse

# Should see:
# [PID] Using automatically selected callback port: XXXXX
# [PID] Connecting to remote server: https://mcp.bigtorig.com/sse
# [PID] Connected successfully

🗺️ 发展路线图

✅ 第一阶段：基础（完成）

[x] KIND集群设置（3个节点）
[x] 带有FastMCP的Docker镜像
[x] Kubernetes部署（2个副本）
[x] NodePort服务
[x] 秘密管理
[x] Caddy反向代理
[x] 通过Cloudflare进行HTTPS
[x] 基本工具（健康检查、列表服务）

🔄 第2阶段：数据库集成（进行中）

Postgres工具：

[]连接到Supabase Postgres
[]实施 postgres_query
[]实施 postgres_list_tables
[]实施 postgres_describe_table
[]添加连接池

Qdrant工具：

[]连接到Qdrant矢量数据库
[]实施 qdrant_search
[]实施 qdrant_list_collections
[]实施 qdrant_collection_info

Neo4j工具：

[]连接到Neo4j图形数据库
[]实施 neo4j_query
[]实施 neo4j_list_nodes
[]实施 neo4j_get_relationships

🔮 第3阶段：高级功能（计划中）

可观察性：

[]普罗米修斯指标导出
[]Grafana仪表板
[]结构化日志记录
[]分布式跟踪

扩展和性能：

[]水平吊舱自动缩放器（HPA）
[]垂直吊舱自动缩放器（VPA）
[]资源优化
[]连接池

可靠性：

[]活体探针
[]准备就绪探针
[]断路器
[]速率限制

集成：

[]n8n工作流触发器
[]流动剂相互作用
[]mem0内存API
[]Langfuse可观测性

🔧 故障排除

常见问题

Pod未启动

# Check pod status
kubectl get pods -l app=mcp-hub

# Check pod events
kubectl describe pod -l app=mcp-hub

# Check logs
kubectl logs -l app=mcp-hub --tail=50

常见原因：

图像未加载到KIND中： kind load docker-image bigtorig-mcp-hub:latest --name k8s
缺失的秘密： kubectl get secret mcp-hub-secrets
资源约束：检查节点资源 kubectl top nodes

服务无法访问

# Check service
kubectl get svc mcp-hub-service

# Test from within cluster
kubectl run -it --rm test-curl --image=curlimages/curl --restart=Never \
  -- curl -I http://mcp-hub-service:8000/sse

# Test NodePort
curl -I http://172.23.0.3:30800/sse

球童未布线

# Check Caddy logs
docker logs caddy --tail=50

# Verify Caddy config
docker exec caddy caddy validate --config /etc/caddy/Caddyfile

# Reload Caddy
docker exec caddy caddy reload --config /etc/caddy/Caddyfile

有关详细的故障排除，请参阅故障排除.md.

📊 监控与操作

检查部署状态

# Overview
kubectl get deployments,pods,svc -l app=mcp-hub

# Detailed pod info
kubectl get pods -l app=mcp-hub -o wide

# Resource usage
kubectl top pods -l app=mcp-hub

查看日志

# All pods
kubectl logs -l app=mcp-hub --tail=50

# Follow logs (real-time)
kubectl logs -l app=mcp-hub -f

# Specific pod
kubectl logs mcp-hub-64c475c6b-xxxxx

缩放操作

# Scale up
kubectl scale deployment mcp-hub --replicas=5

# Scale down
kubectl scale deployment mcp-hub --replicas=2

# Auto-scaling (future)
kubectl autoscale deployment mcp-hub --min=2 --max=10 --cpu-percent=80

更新部署

# Rebuild image
docker build -t bigtorig-mcp-hub:latest .

# Load into KIND
kind load docker-image bigtorig-mcp-hub:latest --name k8s

# Rolling update (restarts pods with new image)
kubectl rollout restart deployment/mcp-hub

# Watch rollout
kubectl rollout status deployment/mcp-hub

🔐 安全

当前安全措施

秘密管理
- 存储在Kubernetes Secrets中的凭据
- Base64静态编码
- 作为环境变量注入
网络安全
- 内部服务未公开
- 仅通过Cloudflare+Caddy进行HTTPS
- NodePort仅在集群网络内可访问
资源限制
- 强制执行CPU和内存限制
- 防止资源耗尽
- 公平的资源分配

计划中的安全增强

[]添加身份验证/授权层
[]实施速率限制
[]添加请求验证
[]启用网络策略
[]添加pod安全策略

📚 资源

官方文件

学习资源

🤝 贡献

这是一个展示MCP服务器的Kubernetes部署模式的展示项目。欢迎投稿！

开发工作流程

在本地进行更改
构建并测试Docker镜像
加载到KIND集群
测试部署
提交带有文件更新的PR

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件

🎯 项目结构

02.bigtorig-mcp-hub/
├── README.md                  ← You are here
├── DEPLOYMENT.md              ← Detailed deployment guide
├── KUBERNETES-BENEFITS.md     ← Part I vs Part II comparison
├── TROUBLESHOOTING.md         ← Common issues and solutions
├── Dockerfile                 ← Container build
├── pyproject.toml             ← Python dependencies (UV)
├── .env.example               ← Environment template
├── .gitignore                 ← Git ignore rules
├── src/
│   └── server.py              ← FastMCP server (2 tools)
└── k8s/
    ├── deployment.yaml        ← Kubernetes deployment
    ├── service.yaml           ← NodePort service
    └── secrets-example.yaml   ← Secrets template

📞 支持

问题： 报告问题 GitHub问题

文档： 检查此存储库中的其他.md文件

基础设施文档： ai基础设施

部分思维发展认知基础设施生态系统

🔗 基础设施文档 • 🌐 博客 • ☸️ 第一部分

当前状态： 第一阶段完成✅ | 生产就绪基础架构|提供2个工具