PromptQL MCP Server

PromptQL MCP 服务

状态：不稳定，仅适用于 PromptQL v1。PromptQL v2 的 Alpha 版本即将发布。

概述

此项目通过模型上下文协议，为 Hasura 的 PromptQL 数据 Agent 与 AI 助手搭建桥梁。借助此集成，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 或更高版本
• Hasura PromptQL 项目，以及 API 密钥、playground URL 和 DDN Auth Token
• Claude Desktop（用于交互使用）或任何兼容 MCP 的客户端

从源代码安装

1. 克隆代码库：

git clone https://github.com/hasura/promptql-mcp.git
cd promptql-mcp

2. 创建虚拟环境（推荐）：

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. 安装软件包：

pip install -e .

快速入门

1. 配置 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"

2. 测试服务：

python -m promptql_mcp_server

3. 在新的终端中，尝试示例客户端：

python examples/simple_client.py

与 Claude Desktop 配合使用

1. 安装 Claude Desktop
2. 打开 Claude Desktop，并前往 Settings > Developer
3. 点击“Edit Config”并添加以下内容：

{
  "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

4. 重启 Claude Desktop
5. 与 Claude 聊天，并使用自然语言查询数据

Claude 提示词示例

• “上个季度的总销售额是多少？”
• “按收入排名，前五位客户是谁？”
• “展示过去 6 个月新用户注册量的趋势”
• “哪些产品的利润率最高？”

可用工具和提示词

工具

该服务提供以下 MCP 工具：

线程管理模式

• start_thread - 使用初始消息启动新的对话线程，并等待完成（返回 thread_id、interaction_id 和响应）
• start_thread_without_polling - 启动新的对话线程，但不等待完成（立即返回 thread_id 和 interaction_id）
• continue_thread - 使用新消息继续现有线程（保留对话上下文）
• get_thread_status - 使用 GET /threads/v2/{thread_id} 检查线程状态（处理中/已完成）
• cancel_thread - 取消线程中最新交互的处理

配置

• setup_config - 配置 PromptQL API 密钥、playground 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

提示词

• data_analysis - 为特定主题的数据分析创建专用提示词

架构

此集成采用客户端-服务端架构：

1. PromptQL MCP 服务 - 通过 MCP 协议提供 PromptQL 功能的 Python 服务
2. MCP 客户端 - 实现 MCP 协议的任意客户端（例如 Claude Desktop）
3. PromptQL API - Hasura 用于数据访问和分析的自然语言 API

该服务在 MCP 协议和 PromptQL API 之间进行转换，从而实现 AI 助手与企业数据的无缝集成。

故障排除

找不到命令：pip 或 python

在许多系统上，尤其是 macOS，可能需要使用 python3 和 pip3，而不是 python 和 pip。

externally-managed-environment 错误

现代 Python 安装通常会阻止全局安装软件包。请按照安装部分的说明使用虚拟环境。

No module named promptql_mcp_server

请确保已：

1. 使用 pip install -e . 安装软件包
2. 使用正确的 Python 环境（如果使用虚拟环境，请确保已激活）
3. 将 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

贡献

欢迎贡献！欢迎提交 Pull Request。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 将分支推送到远程仓库（git push origin feature/amazing-feature）
5. 创建 Pull Request

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

• 感谢 Hasura 创建 PromptQL
• 感谢 Anthropic 开发 Model Context Protocol

待办事项

• 根据 mcp_server 中 continue_thread 和 start_thread 返回的 interaction_id 正确处理线程响应；目前只会查找最新的 interaction_id
• 相应地处理 interaction_response，以确定代码、计划和 code_output
• 确保 simple_client.py 正确展示 cancellation_thread 演示；当前的状态调用似乎会阻塞
• 验证工件是否得到正确处理