Promptql MCP

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的客户端

从源代码安装

1. 克隆存储库：

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

1. 设置虚拟环境（推荐）：

# Create a virtual environment
python -m venv venv

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

1. 安装软件包：

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"

1. 测试服务器：

python -m promptql_mcp_server

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

python examples/simple_client.py

与Claude Desktop一起使用

1. 安装 克劳德桌面
2. 打开Claude Desktop并转到“设置”>“开发人员”
3. 点击“编辑配置”并添加以下内容：

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

1. 重新启动克劳德桌面
2. 与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

提示

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

建筑

此集成遵循客户端-服务器架构：

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

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

故障排除

找不到命令：pip或python

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

外部管理环境错误

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

没有名为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

贡献

欢迎投稿！请随时提交拉取请求。

1. 克隆该仓库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

致谢

• 哈苏拉 用于创建PromptQL
• Anthropic 用于开发模型上下文协议

全部

• 根据mcpserver中continue_thread和start_thread返回的interaction_id正确处理线程响应，目前它只查找最新的interactionid
• 相应地处理交互响应，以找出代码、计划和代码输出
• 确保simple_client.py正确显示cancelation_thread演示，当前状态调用看起来是阻塞的
• 验证工件是否得到了相应的处理