MCP Analytics Server

MCP Analytics Server - 生产级多数据库平台

一个可投入生产的模型上下文协议（MCP）服务器 这使得大型语言模型（如ChatGPT、Claude等）能够通过智能上下文加载、自动化元数据生成和加权人口统计分析等功能，查询多个PostgreSQL数据集。

______________________________________________________________________

🎯 概述

这个平台允许 CMI（消费者与市场洞察）团队 收件人：

1. 添加多个数据集 通过 PostgreSQL 连接字符串从 Microsoft Fabric 获取
2. 自动生成元数据 使用大型语言模型（数据字典、用例、质量检查）
3. 通过自然语言查询数据 通过ChatGPT、Claude或其他MCP客户端
4. 获取加权后的、针对用户角色的深入见解 自动应用
5. 跟踪使用情况 跨越不同的工具和数据集

______________________________________________________________________

✨ 主要特点

第一阶段（✅ 已完成）

• ✅ 基础MCP服务器，配备5种分析工具
• ✅ 支持单一数据集
• ✅ 安全控制（仅选择，行限制）
• ✅ FastMCP协议实现
• ✅ 已在Render.com上部署

第二阶段（🔄 开发中）

• 🔄 支持多数据集注册，连接字符串加密
• 🔄 使用GPT-4o-mini自动生成元数据
• 🔄 用于模式分析的后台工作进程
• 🔄 热加载机制（无需重启即可添加数据集）
• 🔄 逐步加载上下文以提高标记效率

第三阶段（📋 计划中）

• 📋 基于HTMX的UI仪表板
• 📋 数据集导入向导
• 📋 元数据审查/编辑界面
• 📋 查询日志可视化

第四阶段（📋 计划中）

• 📋 并行查询执行（最多支持30个并发查询）
• 📋 每个数据集的连接池
• 📋 高级加权计算
• 📋 性能优化

第五阶段（📋 计划中）

• 📋 全面查询日志记录
• 📋 工具使用分析（ChatGPT vs Claude）
• 📋 性能指标仪表板
• 📋 成本追踪

______________________________________________________________________

📚 文档

• 简化设置指南.md ⭐ 从这里开始 - 无Docker，直接连接字符串
• \GETTING_STARTED.md\ 翻译为中文是：“入门指南.md” 或 “开始使用指南.md” - 开发者入职指南
• 实施计划.md - 详细的实施规范
• ARCHITECTURE.md 翻译为中文是：“架构.md”（其中，.md 通常表示这是一个 Markdown 格式的文件） - 高级系统架构
• 根据上面的信息，执行如下指令： - REST API 和 MCP 端点参考
• \RENDER_DEPLOYMENT.md\ 翻译为中文是：\渲染部署说明.md\ 或 \渲染部署文档.md\（具体翻译可能根据上下文有所调整，但基本意思是指一个关于渲染部署的Markdown文档） - 生产部署指南
• 数据库模式.sql - 完整的数据库模式
• 项目总结.md - 完整的套餐概览

______________________________________________________________________

🚀 快速入门

简单设置（无需Docker - 推荐）

# 1. Clone repository
git clone https://github.com/your-org/mcp-analytics-server.git
cd mcp-analytics-server

# 2. Create virtual environment
python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate   # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Set up environment
cp .env.example .env
# Edit .env and add:
# - METADATA_DATABASE_URL (from your team)
# - OPENAI_API_KEY

# 5. Initialize database (one-time)
psql "$METADATA_DATABASE_URL" -f database_schema.sql

# 6. Run Phase 1
python server.py

# OR run Phase 2+ (when ready)
uvicorn app.main:app --reload --port 8000

高级：Docker 设置（可选）

如果你更喜欢使用 Docker：

docker-compose up -d

见 简化设置指南.md 以获取详细说明。

生产部署（Render.com）

看见 RENDER_DEPLOYMENT.md 翻译为中文是：“渲染部署说明.md” 或 “渲染部署文档.md”。这里，“RENDER”指的是渲染，“DEPLOYMENT”指的是部署，“.md”是Markdown文件格式的后缀 请参阅完整的部署说明。

______________________________________________________________________

🏗️ 建筑学

┌──────────────────────────────────────────────────────┐
│              MCP Analytics Server                    │
├──────────────────────────────────────────────────────┤
│                                                      │
│  ┌─────────────┐  ┌─────────────┐  ┌────────────┐  │
│  │  FastAPI    │  │  FastMCP    │  │   HTMX     │  │
│  │  REST API   │  │  Protocol   │  │  UI        │  │
│  └──────┬──────┘  └──────┬──────┘  └─────┬──────┘  │
│         │                │               │          │
│         └────────────────┴───────────────┘          │
│                          │                          │
│  ┌───────────────────────┴──────────────────┐       │
│  │                                          │       │
│  ▼                                          ▼       │
│  Metadata DB                              Redis     │
│  (Datasets, Logs, Schemas)         (Cache+Pub/Sub)  │
│                                                      │
│  Background Worker (Celery)                          │
│  └─ Schema Profiling                                │
│  └─ LLM Metadata Generation                         │
│                                                      │
└──────────────────────────────────────────────────────┘
           │                       │
           ▼                       ▼
      ChatGPT               Claude Desktop
     (via MCP)               (via MCP)

______________________________________________________________________

🔧 技术栈

• 后端Python 3.11+，FastAPI，FastMCP
• 数据库PostgreSQL 16（通过连接字符串访问元数据+用户数据集）
• 缓存/队列Redis 7（可选，建议用于第二阶段及以后）
• 工人芹菜（第二阶段+）
• LLMOpenAI GPT-4o-mini
• 前端HTMX + Alpine.js + Tailwind CSS
• 部署Render.com（无需Docker）

______________________________________________________________________

第一阶段：部署步骤（当前）

1. 创建渲染账户

首选 render.com（可译为“渲染网”或保持原名，根据上下文决定是否需要意译） 并注册一个免费账户。

2. 创建 PostgreSQL 数据库

1. 点击“新建 +” → “PostgreSQL”
2. 名字： analytics-db
3. 数据库： analytics_db
4. 用户： analytics_user
5. 地区：选择离您最近的
6. 计划： 免费 (1GB存储空间，保留90天)
7. 点击“创建数据库”
8. 复制 外部数据库URL （以……开始 postgres://）

3. 将数据加载到数据库

在您的本地机器上：

# Set the database URL
export DATABASE_URL="postgres://analytics_user:password@host/analytics_db"

# Run the data loading script
python3 load_data_cloud.py

这将把您本地数据库中的所有839,000行数据迁移到云端。

4. 部署Web服务

1. 点击“新建 +”→“Web 服务”
2. 连接您的GitHub仓库（或使用“从Git URL部署”）
3. 姓名： mcp-analytics-server
4. 区域：与数据库相同
5. 分支： main
6. 运行时长： Python 3
7. 构建命令： pip install -r requirements.txt
8. 启动命令： uvicorn server:app --host 0.0.0.0 --port $PORT
9. 计划： 免费 (750小时/月)
10. 环境变量：

- DATABASE_URL粘贴第2步中的外部数据库URL

1. 点击“创建网络服务”

5. 等待部署

渲染将：

• 安装依赖项
• 启动服务器
• 分配一个永久URL（例如。， https://mcp-analytics-server.onrender.com)

备选方案：通过GitHub进行部署

1. 推送到GitHub

cd /home/ubuntu/mcp_analytics_deploy
git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/mcp-analytics-server.git
git push -u origin main

2. 将Render连接到GitHub

1. 在Render仪表板中，点击“新建+”→“Web服务”
2. 点击“连接GitHub”
3. 选择您的存储库
4. 按照上述第3-11步操作

API 端点

一旦部署，您的服务器将拥有以下端点：

• GET / - 服务器信息
• GET /health - 健康检查
• GET /api/schema - 获取表模式
• GET /api/sample?limit=10 - 获取样本数据
• POST /api/query - 执行自定义SQL查询
• GET /api/stats - 获取数据库统计信息
• POST /api/value_counts - 获取频率分布

使用示例

获取模式（或架构）

curl https://your-app.onrender.com/api/schema

获取示例数据

curl https://your-app.onrender.com/api/sample?limit=10

执行查询

curl -X POST https://your-app.onrender.com/api/query \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT type, COUNT(*) FROM digital_insights GROUP BY type"}'

获取统计数据

curl https://your-app.onrender.com/api/stats

MCP客户端的配置

适用于ChatGPT桌面版（OpenAI）

1. 打开ChatGPT设置 → 连接器 → 高级 → 开发者模式
2. 启用开发者模式
3. 使用Streamable HTTP端点添加您已部署的MCP服务器：

配置：

{
  "mcpServers": {
    "analytics": {
      "url": "https://your-app.onrender.com/mcp"
    }
  }
}

注： ChatGPT无法连接到本地主机。您必须将其部署到公共URL（例如，Render、ngrok等）

对于Claude Desktop

1. 打开Claude桌面设置 → 开发者 → 编辑配置
2. 添加以下内容至 claude_desktop_config.json:

对于远程服务器（已部署）：

{
  "mcpServers": {
    "analytics": {
      "transport": {
        "type": "http",
        "url": "https://your-app.onrender.com/mcp"
      }
    }
  }
}

对于本地开发：

{
  "mcpServers": {
    "analytics": {
      "transport": {
        "type": "http",
        "url": "http://localhost:8000/mcp"
      }
    }
  }
}

注： 这个（或“该”） /mcp 端点至关重要——不要忘记！

对于 Claude Code（VS Code 扩展）

使用命令行界面（CLI）命令：

claude mcp add --transport http analytics https://your-app.onrender.com/mcp

或者对于本地（的情况）：

claude mcp add --transport http analytics http://localhost:8000/mcp

免费层级限制

提供免费版 PostgreSQL 渲染服务

• 1 GB 存储空间
• 90天数据保留
• 共享CPU
• 256 MB 内存

免费版Web服务渲染

• 750小时/月
• 共享CPU
• 512 MB 内存
• 在15分钟无活动后停止运转
• 冷启动：约30秒

安全

• 仅允许SELECT查询
• 每次查询最多可获取1000行数据
• 危险关键词被屏蔽
• SQL注入防护
• 基于环境的配置

监测

• 健康终点（或健康指标）： /health
• Render 提供自动健康检查功能
• 在渲染仪表板中查看日志
• 故障时自动重启

缩放

从免费层级升级：

1. 数据库升级到入门版（每月7美元）以享受10GB存储空间
2. 网络服务（或称为“Web服务”）升级到入门版（7美元/月）以享受全天候服务

故障排除

数据库连接失败

检查以下内容：

1. DATABASE_URL 已正确设置
2. 数据库正在运行（请查看渲染仪表板）
3. 数据库URL格式为 postgresql:// 不是 postgres://

服务器无响应

1. 检查渲染日志中的错误
2. 验证服务器是否正在运行（检查渲染仪表板）
3. 在免费层级上，冷启动需等待30秒

数据未加载

1. 验证本地数据库是否包含数据
2. 检查 DATABASE_URL 是否可访问
3. 审查数据加载脚本日志

支持

对于问题：

1. 查看渲染状态页面
2. 在Render仪表板中查看服务器日志
3. 使用 curl 测试端点
4. 检查数据库连接

______________________________________________________________________

📖 开发阶段

看见 IMPLEMENTATION_PLAN.md 翻译为中文是：实施计划.md 以获取详细规格。

______________________________________________________________________

🧪 测试

# Run all tests
pytest

# With coverage
pytest --cov=app --cov-report=html

# Specific tests
pytest tests/test_dataset_service.py -v

______________________________________________________________________

🤝 贡献

开发工作流程

1. 创建特性分支： git checkout -b feature/my-feature
2. 进行更改并在本地测试
3. 运行代码检查： black app/ && ruff check app/
4. 运行测试： pytest
5. 提交： git commit -m "Add feature"
6. 推送并创建拉取请求（Pull Request）

代码质量

# Format code
black app/
isort app/

# Lint
ruff check app/

# Type checking
mypy app/

______________________________________________________________________

📊 关键概念

加权方法论

所有数据均代表一个 样本群体 其中每个用户都有一个 重量：

• 用户权重0.456 = 表示在其所在的人口统计单元中有456人
• 单元格 = 年龄/性别/NCCS（可能指某种分类或编码系统）/城镇类别/州
• 始终衡量用户，而非事件
• 报告于 加权级别 除非另有说明

渐进式上下文加载

优化代币使用：

• 0级仅全球规则（约500个标记）
• 一级数据集摘要（约2000个标记）
• 第二级表模式（~5000个标记）
• 第三级完整模式 + 示例（约10000个标记）

热重载机制

当新数据集获得批准时：

1. 状态变为 approved
2. Redis 发布/订阅通知已发送
3. MCP 服务器重新加载（无需重启！）
4. 大型语言模型（LLM）客户端立即看到新数据集

______________________________________________________________________

🔐 安全

• 静态时加密的连接字符串（使用Fernet）
• SQL注入防护（查询验证）
• 强制执行只读查询
• 行限制（原始数据为5行，聚合数据为1000行）
• 基于环境的密钥管理

______________________________________________________________________

📈 扩展/规模化

免费层（当前）

• 成本每月0美元
• 局限性冷启动，1GB存储空间，90天数据保留
• 最适合用于5-10名用户，用于开发/测试

入门级（推荐用于生产环境）

• 成本28美元/月
• 好处；益处始终在线，10GB存储空间，无限保留期
• 最适合于10-100名用户

企业（未来）

• 成本自定义
• 好处专用资源、自动扩展、服务级别协议（SLA）
• 最适合于100+用户，关键任务系统
• 迁移只需更新.env文件中的连接字符串（无需更改代码）

看见 \RENDER_DEPLOYMENT.md\ 翻译为中文是：“渲染部署说明文件” 或 “渲染部署指南文件”。这里，\RENDER\ 通常指的是“渲染”，\DEPLOYMENT\ 指的是“部署”，而 \.md\ 是 Markdown 文件格式的扩展名，常用于编写技术文档。因此，整个文件名可以理解为一个关于如何进行渲染部署的说明或指南文件 用于缩放指南。

______________________________________________________________________

📞 支持

• 文档见 文档 文件夹
• 问题GitHub Issues（GitHub问题）
• API 文档： https://your-app.onrender.com/docs

______________________________________________________________________

📝 许可证

专有 - 仅限内部使用

______________________________________________________________________

🎉 致谢

构建于：

• FastAPI
• FastMCP
• 模型上下文协议
• OpenAI（开放人工智能研究所）

______________________________________________________________________

下一步

对于开发者

1. 阅读 《GETTING_STARTED.md》翻译为中文是《入门指南.md》或《开始使用指南.md》（具体翻译可能根据上下文调整，但基本传达了原文的意思）
2. 设置本地环境
3. 评论 IMPLEMENTATION_PLAN.md 翻译为中文是：实施计划.md
4. 开始实施第二阶段

对于产品经理

1. 评论 ARCHITECTURE.md 翻译为中文是：“架构.md”（注：这里的“.md”通常表示Markdown文件格式，但在中文语境下，我们通常保留原文件扩展名，不直接翻译，所以“ARCHITECTURE.md”直接翻译为“架构.md”即可，理解为这是一个关于架构的Markdown文档）
2. 检查实施时间表
3. 准备测试数据集
4. 定义成功指标

针对DevOps（开发运维一体化）

1. 评论 \RENDER_DEPLOYMENT.md\ 翻译为中文是：“渲染部署说明文件” 或 “渲染部署指南”
2. 从数据团队获取PostgreSQL连接字符串
3. 建立CI/CD流水线
4. 配置监控