使用说明
🎯 Tableau MCP AI代理
一个使用自然语言查询和分析Tableau数据的人工智能平台。使用FastAPI、Streamlit、LangGraph和PostgreSQL构建。
✨ 特性
- 自然语言查询：用简明英语询问有关Tableau数据的问题
- AI驱动的分析：从GPT-4获取自动化见解和建议
- 活动追踪：查询、反馈和使用情况的完整审计跟踪
- 喜欢/不喜欢反馈：评价回应以改进系统
- 分析仪表盘：使用统计和性能指标
- 多数据源支持：跨多个Tableau数据源查询
🏗️ 建筑
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Streamlit │────▶│ FastAPI │────▶│ Tableau MCP │
│ Frontend │ │ Backend │ │ Server │
│ (Port 8501) │ │ (Port 8000) │ │ (Port 3927) │
└─────────────────┘ └────────┬────────┘ └─────────────────┘
│
┌────────▼────────┐
│ PostgreSQL │
│ Database │
└─────────────────┘
📁 项目结构
tableau-mcp-agent/
├── backend/ # FastAPI Backend
│ ├── src/
│ │ ├── agent/ # LangGraph AI Agent
│ │ ├── api/routes/ # REST API endpoints
│ │ ├── core/ # Config, logging, exceptions
│ │ ├── db/ # SQLAlchemy models & sessions
│ │ ├── mcp/ # MCP client
│ │ ├── services/ # Business logic services
│ │ └── main.py # FastAPI application
│ ├── tests/ # Pytest tests
│ ├── Dockerfile
│ └── pyproject.toml # UV dependencies
├── frontend/ # Streamlit Frontend
│ ├── app.py # Main application
│ ├── pages/ # Multi-page app
│ ├── Dockerfile
│ └── pyproject.toml # UV dependencies
├── k8s/ # Kubernetes manifests
├── docker-compose.yml # Development setup
├── docker-compose.prod.yml # Production setup
└── Makefile
🚀 快速开始
先决条件
- Python 3.11+
- Docker&Docker编写
- OpenAI API密钥
- 使用个人访问令牌（PAT）访问Tableau云/服务器
1.克隆和配置
cd tableau-mcp-agent
# Copy environment files
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
# Edit backend/.env with your credentials:
# - OPENAI_API_KEY
# - TABLEAU_SERVER, TABLEAU_SITE_NAME
# - TABLEAU_PAT_NAME, TABLEAU_PAT_VALUE
# - POSTGRES_PASSWORD
2.从Docker开始
# Start all services
docker-compose up --build
# Access the applications:
# - Streamlit UI: http://localhost:8501
# - API Docs: http://localhost:8000/docs
3.地方发展（可选）
# Install UV if not installed
pip install uv
# Backend
cd backend
uv sync
uv run uvicorn src.main:app --reload --port 8000
# Frontend (in another terminal)
cd frontend
uv sync
uv run streamlit run app.py
📊 API终点
| 端点 | 方法 | 描述 |
|---|---|---|
/api/v1/query |
POST | 提交自然语言查询 |
/api/v1/query/history |
GET | 获取查询历史记录 |
/api/v1/query/{id} |
GET | 获取特定查询详细信息 |
/api/v1/datasources |
GET | 列出可用数据源 |
/api/v1/feedback |
POST | 提交喜欢/不喜欢的反馈 |
/api/v1/feedback/stats |
GET | 获取反馈统计信息 |
/api/v1/analytics/dashboard |
GET | 获取使用情况仪表板 |
/api/v1/analytics/report |
GET | 生成使用情况报告 |
/api/v1/health |
GET | 健康检查 |
🗄️ 数据库模式
| 表 | 说明 |
|---|---|
users |
用户帐户 |
sessions |
用户会话 |
queries |
查询历史记录和结果 |
query_feedback |
喜欢/不喜欢反馈 |
activity_logs |
完整的审计跟踪 |
usage_statistics |
每日汇总统计数据 |
🔧 配置
环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
OPENAI_API_KEY |
OpenAI API密钥 | 必需 |
OPENAI_MODEL |
要使用的模型 | gpt-4-turbo预览 |
TABLEAU_SERVER |
Tableau服务器URL | 必填 |
TABLEAU_PAT_NAME |
PAT名称 | 必填 |
TABLEAU_PAT_VALUE |
PAT值 | 必填 |
POSTGRES_HOST |
数据库主机 | localhost |
POSTGRES_PASSWORD |
数据库密码 | 必填 |
MCP_SERVER_URL |
MCP服务器URL | http://mcp:3927 |
🧪 测试
cd backend
# Run tests
uv run pytest tests/ -v
# With coverage
uv run pytest tests/ --cov=src --cov-report=html
🐳 Docker命令
# Build all images
make docker-build
# Start services
make docker-up
# View logs
make docker-logs
# Stop services
make docker-down
# Clean up
make docker-clean
☸️ Kubernetes部署
# Deploy to Kubernetes
make k8s-deploy
# Check status
make k8s-status
# View logs
make k8s-logs
# Delete deployment
make k8s-delete
📈 活动追踪
平台跟踪：
- ✅ 每个带有时间戳的查询
- ✅ 查询执行次数和行数
- ✅ 喜欢/不喜欢评分反馈
- ✅ 书面意见和建议
- ✅ 用户活动历史
- ✅ 汇总使用统计数据
🔒 安全
- 非根Docker容器
- 通过环境变量管理的秘密
- 前端CORS配置
- 在所有端点上进行输入验证
📝 许可证
MIT许可证-有关详细信息，请参阅许可证文件。
🤝 贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 运行测试
- 提交拉取请求
