🔌 bigtorig-mcp-hub

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

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

![MCP](https://modelcontextprotocol.io) ![FastMCP](https://github.com/jlowin/fastmcp) ![Kubernetes](https://kind.sigs.k8s.io/)

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

______________________________________________________________________

______________________________________________________________________

🌍 概述

什么是bigtorig mcp中心？

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

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

MCP服务器之旅的第二部分

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

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

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

______________________________________________________________________

🏗️ 建筑

基础结构拓扑

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

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](./DEPLOYMENT.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](./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](./TROUBLESHOOTING.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


______________________________________________________________________

## 🔐 安全

### 当前安全措施

1. **秘密管理**

   - 存储在Kubernetes Secrets中的凭据
   - Base64静态编码
   - 作为环境变量注入

1. **网络安全**

   - 内部服务未公开
   - 仅通过Cloudflare+Caddy进行HTTPS
   - NodePort仅在集群网络内可访问

1. **资源限制**

   - 强制执行CPU和内存限制
   - 防止资源耗尽
   - 公平的资源分配

### 计划中的安全增强

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

______________________________________________________________________

## 📚 资源

### 官方文件

- [模型上下文协议（MCP）](https://modelcontextprotocol.io)
- [FastMCP框架](https://github.com/jlowin/fastmcp)
- [Kubernetes文档](https://kubernetes.io/docs/)
- [KIND文档](https://kind.sigs.k8s.io/)
- [球童文件](https://caddyserver.com/docs/)

### 相关项目

- [ai基础设施](https://github.com/mindset-dev/ai-infra-hostinger) -基础设施文件
- [01.mcp服务器](../01.mcp-server/) -第一部分：基于Docker的MCP服务器

### 学习资源

- [Kubernetes示例](https://kubernetesbyexample.com/)
- [Kubernetes模式](https://k8spatterns.io/)
- [MCP规范](https://spec.modelcontextprotocol.io/)

______________________________________________________________________

## 🤝 贡献

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

### 开发工作流程

1. 在本地进行更改
1. 构建并测试Docker镜像
1. 加载到KIND集群
1. 测试部署
1. 提交带有文件更新的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


______________________________________________________________________

## 📞 支持

**问题：** 报告问题 

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

**基础设施文档：** [ai基础设施](https://github.com/mindset-dev/ai-infra-hostinger)

______________________________________________________________________

**部分 [思维发展](https://github.com/mindset-dev) 认知基础设施生态系统**

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

Bigtorig MCP Hub

快速接入

详细介绍

🔌 bigtorig-mcp-hub

📋 目录

🌍 概述

什么是bigtorig mcp中心？

MCP服务器之旅的第二部分

🏗️ 建筑

基础结构拓扑

部署堆栈

Kubernetes资源

📊 当前状态

第一阶段：基础✅ 完成

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

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

🧰 可用工具

基础工具（2）

1.健康检查

2.列表_服务

Postgres工具（5）

3.postgres_list_databases

4.postgres_create_database

5.postgres_query

6.postgres_list_tables

7.postgres_descripte_table

MySQL工具（3）

8.mysql_query

9.mysql_list_tables

10.mysql_describe_table

Qdrant工具（3）

11.qdrant_search

12.qdrant_list_collections

13.qdrant_collection_info

Neo4j工具（3）

14.neo4j_query

15.新4j_list_nodes

16.neo4j_get关系

1. Navigate to project directory

2. Build Docker image

3. Load into KIND cluster

4. Create Kubernetes secrets

(Edit secrets-example.yaml with real credentials first)

5. Deploy to Kubernetes

6. Verify deployment

7. Configure Caddy (add to Caddyfile)

mcp.bigtorig.com {

reverse_proxy http://172.23.0.3:30800

}

8. Reload Caddy

9. Test external access

Delete a pod

Watch automatic recreation

New pod created in 3 seconds! Service never went down.

Scale to 3 replicas

Instant: 3 pods running across cluster

All requests go through Service

Traffic automatically distributed across pods

Test with mcp-remote directly

Should see:

[PID] Using automatically selected callback port: XXXXX

[PID] Connecting to remote server: https://mcp.bigtorig.com/sse

[PID] Connected successfully

Check pod status

Check pod events

Check logs

Check service

Test from within cluster

Test NodePort

Check Caddy logs

Verify Caddy config

Reload Caddy

Overview

Detailed pod info

Resource usage

All pods

Follow logs (real-time)

Specific pod

Scale up

Scale down