STARWARCLOUD STARWAR.AI
返回市场
量子MCP

量子MCP

作者：gabiteodoru5 星标更新：2025-10-07
安装使用来源：spider==github.com

项目介绍

qmcp 服务器

qmcp 是一个用于 q/kdb+ 集成的 Model Context Protocol (MCP) 服务器。

MCP 是由 Anthropic 创建的一个开放协议，使 AI 系统能够与外部工具和数据源进行交互。目前支持 Claude（桌面版和命令行版），但该开放标准允许其他 LLM 在未来采用它。

开源概念验证

此仓库包含一个开源概念验证，展示了核心 qmcp 方法。Qython 翻译工具（可在 github.com/gabiteodoru/qython 获取）覆盖了大约 5% 的 q 语言，并提供评估和实验使用。

生产结果： 完整的 Qython 实现对 HumanEval 基准测试的失败率为 0.6%，比原生 q 开发提高了 10 倍的可靠性。详见完整评估：0.6% 失败率：解决 q/kdb+ 的 LLM 代码生成问题

商业许可： 如需访问完整的 Qython 实现并获得全面的语言覆盖，请联系 gabiteodoru@gmail.com

特性

  • 连接到 q/kdb+ 服务器
  • 执行 q 查询和命令
  • 持久连接管理
  • 具有可配置超时的智能异步查询处理
  • 程序化查询取消（相当于 Ctrl+C）
  • 平稳处理长时间运行的查询
  • 新功能： Qython 语言翻译器（实验性 Alpha 版）

Windows 用户：推荐使用 WSL

⚠️ 重要提示：对于 Windows 用户：为了实现最佳功能，强烈建议在 WSL（Windows Subsystem for Linux）中运行 MCP 服务器和您的 q 会话。这确保了服务器可以中断无限循环和意外生成的长时间运行查询。

在 Windows 上运行 MCP 服务器（不通过 WSL）会禁用基于 SIGINT 的查询中断功能，这对于在 AI 辅助开发会话期间逃离有问题的查询至关重要。

架构及设计理念

设计目标

qmcp 被设计为向 AI 编码助手提供对 q/kdb+ 数据库的受控访问，以支持开发和调试工作流程：

  1. 面向开发：优化用于与调试/开发 q 服务器一起工作的编码工具
  2. 查询控制：AI 可以中断长时间运行的查询（类似于开发者按 Ctrl+C）
  3. 可预测行为：顺序执行防止开发过程中的资源冲突
  4. 可配置超时：针对不同开发场景定制的超时设置

设计逻辑

服务器架构为 AI 辅助开发工作流程做出了明确的选择：

单一连接模型

  • 为什么：简化开发调试 - 单一连接，清晰状态
  • 好处：匹配典型开发者的单个 q 会话工作流
  • 实现：每个 MCP 会话一个持久连接

顺序查询执行

  • 为什么：开发环境不需要并发查询支持
  • 好处：可预测的资源使用，易于调试，防止查询干扰
  • 实现：当另一个查询正在运行时拒绝新的查询

智能异步切换与可配置超时

快速查询（< 异步切换超时） → 立即返回结果
慢速查询（> 异步切换超时） → 切换到异步模式
                             → 自动中断（如果配置了中断超时）
  • 为什么：保持 AI 编码会话响应，同时允许复杂的开发查询
  • 好处：快速查询即时反馈，分析进度跟踪
  • 定制：所有超时均可通过 MCP 工具配置

AI 控制的查询中断

  • 为什么：AI 编码工具需要能够取消失控查询（类似于开发者按 Ctrl+C）
  • 如何：MCP 服务器通过端口定位 q 进程，在配置的超时后发送 SIGINT
  • 好处：防止开发会话因有问题的查询而挂起
  • 限制：当以下情况发生时，SIGINT 功能被禁用：
    • MCP 服务器在 Windows（不通过 WSL）上运行
    • MCP 服务器和 q 会话分别位于 WSL 和 Windows 两侧

面向开发的过程管理

  • 为什么：编码工具与用户管理的开发 q 服务器一起工作
  • 好处：开发者控制 q 服务器生命周期，AI 控制查询执行
  • 设计：MCP 服务器提供查询中断能力而不管理服务器生命周期

为什么这种设计对编码工具有意义

  1. 开发工作流程：符合开发者与 q 的交互方式 - 单一会话，迭代查询
  2. AI 安全性：防止 AI 用并发请求淹没开发环境
  3. 调试友好：顺序执行使得问题追踪更容易
  4. 响应性：异步处理防止 AI 编码会话阻塞
  5. 可配置性：超时可以根据不同的开发场景调整

这种架构为 AI 编码助手提供了有效的 q/kdb+ 访问，同时保持了开发工作流程所需的可预测和受控环境。

要求

  • Python 3.8+
  • 访问 q/kdb+ 服务器
  • uv（轻量级安装）或 pip（完整安装）

快速开始

对于初次使用者，最快的方式是：

  1. 启动 q 服务器： 
    q -p 5001
  2. 将 qmcp 添加到 Claude CLI： 
    claude mcp add qmcp "uv run qmcp/server.py"
  3. 使用 Claude CLI： 
    claude
    然后与 qmcp 互动： 
    > 连接到端口 5001 并计算 2+2

● qmcp:connect_to_q (MCP)(host: "5001")
  ⎿  true

● qmcp:query_q (MCP)(command: "2+2")
  ⎿  4

安装

轻量级安装（仅限 Claude CLI）

直接使用 uv 运行（无需 pip 安装，启动可能较慢；适合初次尝试）：

claude mcp add qmcp "uv run qmcp/server.py"

完整安装

选项 1：pip（推荐全局使用）

pip install qmcp

注意：考虑使用虚拟环境以避免依赖冲突：

python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate
pip install qmcp

选项 2：uv（项目特定使用）

# 一次性执行（每次下载依赖项）
uv run qmcp

# 或频繁使用时，先同步依赖项
uv sync
uv run qmcp
添加到 Claude CLI

完成完整安装后，将服务器添加到 Claude CLI：

claude mcp add qmcp qmcp
添加到 Claude Desktop

添加到您的 Claude Desktop 配置文件：

{
  "mcpServers": {
    "qmcp": {
      "command": "qmcp"
    }
  }
}

对于基于 uv 的安装：

{
  "mcpServers": {
    "qmcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/绝对路径/qm_安装目录",
        "run",
        "qmcp"
      ]
    }
  }
}

使用

启动 MCP 服务器

完成完整安装后：

qmcp

轻量级安装时： 服务器会在 Claude CLI 使用时自动启动（无需手动启动）。

环境变量

  • Q_DEFAULT_HOST - 默认连接信息格式：主机名、主机名:端口 或 主机名:端口:用户名:密码

连接回退逻辑

connect_to_q(host) 工具使用灵活的回退逻辑：

  1. 完整的连接字符串（包含冒号）：直接使用，忽略 Q_DEFAULT_HOST
    • connect_to_q("myhost:5001:user:pass")
  2. 仅端口号：与 Q_DEFAULT_HOST 结合使用或使用 localhost
    • connect_to_q(5001) → 使用 Q_DEFAULT_HOST 设置，端口为 5001
  3. 无参数：直接使用 Q_DEFAULT_HOST
    • connect_to_q() → 直接使用 Q_DEFAULT_HOST
  4. 仅主机名：作为主机名使用，结合 Q_DEFAULT_HOST 的端口/认证或默认端口
    • connect_to_q("myhost") → 结合 Q_DEFAULT_HOST 设置

工具稳定性状态

生产就绪工具：

  • connect_to_q - 具有回退逻辑的稳定连接管理
  • query_q - 执行具有智能异步超时控制的查询
  • set_timeout_switch_to_async - 配置查询何时切换到异步模式
  • set_timeout_interrupt_q - 配置何时发送 SIGINT 中断查询
  • set_timeout_connection - 配置连接超时
  • get_timeout_settings - 查看当前超时配置
  • get_current_task_status - 检查正在运行的异步查询状态
  • get_current_task_result - 获取已完成异步查询的结果
  • interrupt_current_query - 发送 SIGINT 中断正在运行的查询

实验性工具（Alpha）：

  • translate_qython_to_q - ⚠️ 实验性：Python 类似语法到 q 的翻译器
    • Qython 支持：do n times:、converge()、partial()、reduce()、arange()
    • 假设导入：from functools import partial、from numpy import arange
    • 鼓励使用向量化、numpy 风格的操作而非基本的 Python 循环
    • 词汇有限，可能会产生错误代码
    • 请在使用前验证所有输出
  • translate_q_to_qython - ⚠️ 实验性：Q 代码到 Python 类似的翻译器，带有 AI 解析
    • 使用 ParseQ 将 q 表达式转换为可读且文档良好的 Python 类似代码
    • 解析 q AST，展平嵌套调用，并使用 AI 解析重载操作符
    • 需要先连接 q - 在使用前运行 connect_to_q 工具（使用 q 的解析器）
    • 命名空间影响：在您的 q 会话的 .parseq 命名空间中创建变量和函数
    • 硬连线到 Claude Code CLI - 与其他适用于任何 MCP 兼容 LLM 的工具不同，此工具专门调用 Claude Code CLI 进行 AI 解析
    • 可能会产生错误翻译，尤其是对于复杂表达式
    • 请在使用前验证所有输出
    • 报告错误：GitHub Issues

已知限制

使用 MCP 服务器时请注意以下限制：

查询中断（SIGINT）限制

  • Windows 平台：当 MCP 服务器在 Windows（不通过 WSL）上运行时，查询中断被禁用
  • 跨平台设置：当 MCP 服务器和 q 会话分别位于 WSL 和 Windows 两侧时，查询中断被禁用
  • 影响：在这种配置下，LLM 无法自动逃离无限循环或取消失控查询

数据转换限制

  • 键表：如 1!table 的操作在 pandas 转换过程中可能会失败
  • 字符串与符号的区别：q 字符串和符号在输出中可能看起来相同
  • 类型模糊：当精度很重要时，使用 q 的 meta 和 type 命令来确定实际数据类型
  • pandas 转换：某些 q 特定的数据结构可能不会正确转换为 pandas DataFrame

对于类型检查，使用：

meta table           / 检查表列类型和结构
type variable        / 检查变量类型

WSL2 端口通信（Windows 用户）

如果您不是 Windows 用户，请跳过此部分。

由于在 Windows 上 Claude CLI 仅限于 WSL，但您可能希望使用 Windows IDE 或工具连接到您的 q 服务器，因此需要在 WSL2 和 Windows 之间进行适当的端口通信。

WSL2 配置以实现端口通信

.wslconfig 文件设置

位置：C:\Users\{您的用户名}\.wslconfig

添加镜像网络配置：

# 镜像网络模式以实现无缝端口通信
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

重启 WSL2

从 Windows PowerShell/CMD（而不是从 WSL 内部）运行：

wsl --shutdown
# 等待几秒钟，然后重新启动 WSL

验证配置

检查镜像网络是否激活：

ip addr show
cat /etc/resolv.conf

测试端口通信

测试 WSL2 → Windows（localhost）：

# 在 WSL2 中启动服务器
python3 -m http.server 8000

# 在 Windows 浏览器或 PowerShell 中
curl http://localhost:8000

测试 Windows → WSL2（localhost）：

# 在 Windows PowerShell 中
python -m http.server 8001

# 在 WSL2 中
curl http://localhost:8001

镜像网络提供的内容

  • ✅ 双向直接 localhost 通信
  • ✅ 不需要手动端口转发
  • ✅ 更好的 VPN 兼容性
  • ✅ 简化的网络（Windows 和 WSL2 共享网络接口）
  • ✅ 自动处理防火墙规则

⚠️ 端口 5000 的特殊情况

问题：由于 Windows 服务绑定，端口 5000 的镜像网络支持有限。

根本原因：

  • Windows svchost 服务绑定到 127.0.0.1:5000（仅限 localhost）
  • 仅限 localhost 的绑定在 Windows 和 WSL2 之间没有完全镜像
  • 这导致了一般镜像网络功能的例外情况

端口 5000 通信矩阵：

  • ✅ Windows ↔ Windows：正常工作（相同的 localhost）
  • ❌ WSL2 ↔ Windows：失败（不同的 localhost 解释）
  • ✅ WSL2 ↔ WSL2：正常工作（相同的环境）

端口 5000 的解决方案：

  1. 使用其他端口：5001、5002 等（推荐）
  2. 停止 Windows 服务：如果不需要
  3. 传统的端口转发：针对特定使用案例

可能具有仅限 localhost 绑定的常见服务

  • Flask 开发服务器（默认 127.0.0.1:5000）
  • UPnP 设备主机服务
  • Windows Media Player 网络共享
  • 各种开发工具

镜像网络的已知限制

  1. 仅限 localhost 的服务：未完全镜像（如确认的端口 5000）
  2. mDNS 在镜像模式下不起作用
  3. 某些 Docker 配置可能存在问题
  4. 需要 Windows 11 22H2+（构建 22621+）