PromptQL MCP服务器
状态：不稳定，仅适用于PromptQL v1。PromptQL v2的Alpha版本即将发布。
概述
该项目通过模型上下文协议在Hasura的PromptQL数据代理和AI助手之间架起了一座桥梁。通过这种集成，人工智能助手可以使用自然语言直接查询您的企业数据，利用PromptQL强大的数据访问、分析和可视化功能。
特性
- 🔍 自然语言数据查询 -用简单的英语询问有关企业数据的问题
- 📊 表工件支持 -从数据查询中获取格式化的表结果
- 🔐 安全配置 -安全地存储和管理您的PromptQL API凭据
- 🔑 双重身份验证模式 -支持公共和私有DDN部署
- 📈 数据分析 -从您的数据中获得见解和可视化
- 🛠️ 简单集成 -适用于Claude Desktop和其他MCP兼容客户端
身份验证模式
PromptQL MCP服务器支持两种身份验证模式，可用于不同的DDN部署类型：
公共模式（默认）
- 用途
Auth-Token身份验证标头 - 与公共DDN端点兼容
- 与现有配置向后兼容
- 使用时间：您的DDN部署是公开访问的
隐私模式
- 用途
x-hasura-ddn-token身份验证标头 - 与私有DDN端点兼容
- 增强私人部署的安全性
- 使用时间：您的DDN部署是私有/内部的
您可以在配置过程中使用指定身份验证模式 --auth-mode 旗帜或 auth_mode 参数。
安装
先决条件
- Python 3.10或更高版本
- 使用API密钥、游乐场URL和DDN Auth令牌的Hasura PromptQL项目
- Claude Desktop（用于交互式使用）或任何兼容MCP的客户端
从源代码安装
- 克隆存储库：
git clone https://github.com/hasura/promptql-mcp.git
cd promptql-mcp- 设置虚拟环境（推荐）：
# Create a virtual environment
python -m venv venv
# Activate the virtual environment
source venv/bin/activate # On Windows: venv\Scripts\activate- 安装软件包：
pip install -e .快速开始
- 配置您的PromptQL凭据：
# For public DDN deployments (default)
python -m promptql_mcp_server setup --api-key YOUR_PROMPTQL_API_KEY --playground-url YOUR_PLAYGROUND_URL --auth-token YOUR_AUTH_TOKEN --auth-mode public
# For private DDN deployments
python -m promptql_mcp_server setup --api-key YOUR_PROMPTQL_API_KEY --playground-url YOUR_PLAYGROUND_URL --auth-token YOUR_AUTH_TOKEN --auth-mode private备选方案：环境变量
export PROMPTQL_API_KEY="your-api-key"
export PROMPTQL_PLAYGROUND_URL="your-playground-url"
export PROMPTQL_AUTH_TOKEN="your-auth-token"
export PROMPTQL_AUTH_MODE="public" # or "private"- 测试服务器：
python -m promptql_mcp_server- 在新终端中，尝试示例客户端：
python examples/simple_client.py与Claude Desktop一起使用
- 安装 克劳德桌面
- 打开Claude Desktop并转到“设置”>“开发人员”
- 点击“编辑配置”并添加以下内容：
{
"mcpServers": {
"promptql": {
"command": "/full/path/to/python",
"args": ["-m", "promptql_mcp_server"]
}
}
}替换 /full/path/to/python 使用Python可执行文件的实际路径。
如果您正在使用虚拟环境（推荐）：
{
"mcpServers": {
"promptql": {
"command": "/path/to/your/project/venv/bin/python",
"args": ["-m", "promptql_mcp_server"]
}
}
}替代方案：在Claude Desktop中使用环境变量
{
"mcpServers": {
"promptql": {
"command": "/full/path/to/python",
"args": ["-m", "promptql_mcp_server"],
"env": {
"PROMPTQL_API_KEY": "your-api-key",
"PROMPTQL_PLAYGROUND_URL": "your-playground-url",
"PROMPTQL_AUTH_TOKEN": "your-auth-token",
"PROMPTQL_AUTH_MODE": "public"
}
}
}
}要查找Python路径，请运行：
which python # On macOS/Linux
where python # On Windows- 重新启动克劳德桌面
- 与Claude聊天并使用自然语言查询您的数据
克劳德提示示例
- “上个季度我们的总销售额是多少？”
- “按收入计算，我们的前五大客户是谁？”
- “显示过去6个月新用户注册的趋势”
- “哪些产品的利润率最高？”
可用工具和提示
工具
服务器公开了以下MCP工具：
线程管理模式
- start_thread -使用初始消息启动一个新的对话线程并等待完成（返回thread_id、interaction_id和response）
- start_thread_无碰撞 -启动一个新的对话线程，无需等待完成（立即返回thread_id和interaction_id）
- 连续线程 -使用新消息继续现有线程（维护对话上下文）
- get_thread_status -使用GET/threads/v2/{thread_id}检查线程的状态（正在处理/完成）
- cancel_thread -取消线程中最新交互的处理
配置
- setup_config -配置PromptQL API密钥、游乐场URL、DDN Auth Token和身份验证模式（公共/私有）
- check_config -验证当前配置状态，包括身份验证模式
使用示例
多回合对话模式
选项1：从轮询开始（立即得到响应）
# Start a new conversation thread (waits for completion and returns full response)
thread_result = await client.call_tool("start_thread", {
"message": "What tables are available in my database?"
})
# Extract thread_id from result (format: "Thread ID: abc-123\nInteraction ID: def-456\n\n[response content]")
thread_id = thread_result.split("Thread ID: ")[1].split("\n")[0].strip()
# Continue the conversation with context
result = await client.call_tool("continue_thread", {
"thread_id": thread_id,
"message": "Show me the schema of the users table"
})选项2：不轮询启动（单独检查状态）
# Start a new conversation thread (returns immediately with thread_id)
thread_result = await client.call_tool("start_thread_without_polling", {
"message": "What tables are available in my database?"
})
# Extract thread_id from result (format: "Thread ID: abc-123\nInteraction ID: def-456\n\n...")
thread_id = thread_result.split("Thread ID: ")[1].split("\n")[0].strip()
# Check status manually
status_result = await client.call_tool("get_thread_status", {
"thread_id": thread_id
})
# Continue when ready
result = await client.call_tool("continue_thread", {
"thread_id": thread_id,
"message": "Show me the schema of the users table"
})
# Continue further
result = await client.call_tool("continue_thread", {
"thread_id": thread_id,
"message": "How many records are in that table?"
})
# Check thread status
status = await client.call_tool("get_thread_status", {
"thread_id": thread_id
})
# Cancel thread processing (if currently processing)
cancel_result = await client.call_tool("cancel_thread", {
"thread_id": thread_id
})附系统说明
# Start thread with system instructions
result = await client.call_tool("start_thread", {
"message": "Show me the top 10 products by revenue",
"system_instructions": "Format all results as markdown tables"
})配置示例
设置身份验证模式
公共模式配置（默认）
# Using MCP tool
result = await client.call_tool("setup_config", {
"api_key": "your-api-key",
"playground_url": "https://promptql.your-domain.public-ddn.hasura.app/playground",
"auth_token": "your-auth-token",
"auth_mode": "public"
})私人模式配置
# Using MCP tool
result = await client.call_tool("setup_config", {
"api_key": "your-api-key",
"playground_url": "https://promptql.your-domain.private-ddn.hasura.app/playground",
"auth_token": "your-auth-token",
"auth_mode": "private"
})检查当前配置
# Check what authentication mode is currently configured
config_result = await client.call_tool("check_config", {})
# Returns configuration details including auth_mode提示
- 数据分析 -为特定主题的数据分析创建专门的提示
建筑
此集成遵循客户端-服务器架构：
- PromptQL MCP服务器 -通过MCP协议公开PromptQL功能的Python服务器
- MCP客户端 -任何实现MCP协议的客户端（例如Claude Desktop）
- PromptQL API -用于数据访问和分析的Hasura自然语言API
服务器在MCP协议和PromptQL的API之间进行转换，从而实现人工智能助手和企业数据之间的无缝集成。
故障排除
找不到命令：pip或python
在许多系统上，尤其是macOS，您可能需要使用 python3 和 pip3 而不是 python 和 pip.
外部管理环境错误
现代Python安装通常会阻止全局包安装。按照安装部分中的说明使用虚拟环境。
没有名为promptql_mcp_server的模块
确保您已经：
- 安装了以下软件包
pip install -e . - 正在使用正确的Python环境（如果使用虚拟环境，请确保它已激活）
- 已将Claude Desktop配置为使用正确的Python可执行路径
Python版本问题
如果你安装了多个Python版本，请确保你使用的是Python 3.10或更高版本：
python3.10 -m venv venv # Specify the exact version身份验证问题
身份验证模式错误
如果您遇到身份验证错误，请验证您使用的身份验证模式是否正确：
- 公共DDN部署：使用
--auth-mode public（默认） - 私有DDN部署：使用
--auth-mode private
检查您当前的配置：
python -m promptql_mcp_server
# Then use check_config tool to see current auth_mode切换身份验证模式
要在身份验证模式之间切换，只需重新配置：
# Switch to private mode
python -m promptql_mcp_server setup --api-key YOUR_API_KEY --playground-url YOUR_URL --auth-token YOUR_TOKEN --auth-mode private
# Switch back to public mode
python -m promptql_mcp_server setup --api-key YOUR_API_KEY --playground-url YOUR_URL --auth-token YOUR_TOKEN --auth-mode public发展
项目结构
promptql-mcp/
├── promptql_mcp_server/ # Main package
│ ├── __init__.py
│ ├── __main__.py # Entry point
│ ├── server.py # MCP server implementation
│ ├── config.py # Configuration management
│ └── api/ # API clients
│ ├── __init__.py
│ └── promptql_client.py # PromptQL API client
├── examples/ # Example clients
│ └── simple_client.py # Simple MCP client
├── setup.py # Package configuration
└── README.md # Documentation贡献
欢迎投稿！请随时提交拉取请求。
- 克隆该仓库
- 创建功能分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add some amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。
致谢
全部
- 根据mcpserver中continue_thread和start_thread返回的interaction_id正确处理线程响应，目前它只查找最新的interactionid
- 相应地处理交互响应，以找出代码、计划和代码输出
- 确保simple_client.py正确显示cancelation_thread演示，当前状态调用看起来是阻塞的
- 验证工件是否得到了相应的处理