qMCP (Gabiteodoru)

QMCP服务器

用于q/kdb+集成的模型上下文协议（MCP）服务器。

MCP是由Anthropic创建的一种开放协议，它使人工智能系统能够与外部工具和数据源进行交互。虽然目前该协议已得到Claude（桌面版和命令行界面版）的支持，但这一开放标准未来允许其他大型语言模型（LLM）采用。

开源概念验证（或原型）

这个存储库包含一个 开源概念验证 展示量子蒙特卡洛方法（QMC）的核心思路。Qython翻译工具（可访问于 ) 覆盖了q语言的大约5%，仅供评估和实验使用。

生产成果： 完整的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 Subsystem for Linux）

⚠️ 对Windows用户很重要为了获得最佳功能，强烈建议在Windows Subsystem for Linux（WSL）中同时运行MCP服务器和您的q会话。这样可以确保服务器能够中断大型语言模型（LLMs）可能意外生成的无限循环和失控查询。

在Windows系统上运行MCP服务器（不在WSL环境中）会禁用基于SIGINT的查询中断功能，而这一功能在AI辅助开发会话中对于终止问题查询至关重要。

建筑与设计理念

预期目标

qmcp 可以翻译为“量子蒙特卡洛方法”（Quantum Monte Carlo Method），这是一种在物理学、化学和材料科学等领域中用于模拟和计算量子系统性质的数值方法 旨在为AI编码助手提供 受控访问 用于开发和调试工作流的q/kdb+数据库：

1. 以发展为重点针对与调试/开发队列服务器配合使用的编码工具进行了优化
2. 查询控制AI可以中断长时间运行的查询（相当于开发者按下Ctrl+C）
3. 可预测的行为顺序执行可防止开发过程中的资源冲突
4. 可配置的超时时间针对不同开发场景的可定制时间安排

设计逻辑

服务器架构在人工智能辅助开发工作流程方面做出了精心设计的选择：

单一连接模型

• 为什么简化开发调试——一次连接，状态清晰
• 好处；利益与典型的开发者工作流程相匹配，使用单一q会话
• 实施每个MCP会话保持一个持久连接

顺序查询执行

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

智能异步切换，支持可配置超时设置

Fast Query ( async switch timeout)  →  Switch to async mode
                                     →  Auto-interrupt after interrupt timeout (if configured)

• 为什么在保持AI编码会话响应性的同时，支持复杂的开发查询
• 益处；好处即时反馈以快速查询，进度跟踪以进行分析
• 定制化所有超时设置均可通过MCP工具进行配置

AI控制的查询中断

• 为什么AI编码工具需要具备取消失控查询的能力（类似于开发者按Ctrl+C）
• 如何MCP服务器通过端口定位q进程，并在可配置的超时时间后发送SIGINT信号
• 好处；利益防止开发会话因问题查询而挂起
• 局限性当以下情况发生时，SIGINT功能将被禁用：

- MCP服务器在Windows上运行（不在WSL中） - MCP服务器和q会话运行在WSL/Windows分界线的两侧

面向发展的过程管理

• 为什么编码工具与用户管理的开发队列服务器协同工作
• 利益；好处开发者控制q服务器的生命周期，AI控制查询执行
• 设计MCP服务器提供查询中断功能，且无需服务器生命周期管理

为何这种设计对编码工具而言是合理的

1. 开发工作流程符合开发者与q的交互方式——单会话、迭代查询
2. 人工智能安全防止人工智能通过并发请求淹没开发环境
3. 便于调试顺序执行使得问题追踪更加容易
4. 响应式的异步处理避免了AI编码会话的阻塞
5. 可配置的可以根据不同的开发场景调整超时设置

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

要求

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

快速入门

对于首次使用的用户，最快上手的方法是：

1. 启动一个q服务器：

   q -p 5001

1. 将qmcp添加到Claude CLI中：

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

1. 开始使用Claude CLI：

   claude

然后与qmcp进行交互：

   > connect to port 5001 and compute 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  # On Windows: venv\Scripts\activate
pip install qmcp

选项2：uv（用于项目特定用途）

# One-time execution (downloads dependencies each time)
uv run qmcp

# Or for frequent use, sync dependencies first
uv sync
uv run qmcp

为Claude CLI添加功能

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

claude mcp add qmcp qmcp

添加到Claude桌面版

在您的Claude桌面配置文件中添加：

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

对于基于紫外线的安装：

{
  "mcpServers": {
    "qmcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/qmcp",
        "run",
        "qmcp"
      ]
    }
  }
}

使用方法

启动MCP服务器

安装完成后：

qmcp

安装简便轻便： 当 Claude CLI 使用时，服务器会自动启动（无需手动启动）。

环境变量

• Q_DEFAULT_HOST - 默认连接信息格式为： host， host:port，或者 host:port:user:passwd

连接回退逻辑

这个（或“该”） connect_to_q(host) 该工具采用灵活的回退逻辑：

1. 完整的连接字符串 （含有冒号）：直接使用，忽略 Q_DEFAULT_HOST

- connect_to_q("myhost:5001:user:pass")

1. 仅端口号与……结合 Q_DEFAULT_HOST 或者使用 localhost

- connect_to_q(5001) → 用途 Q_DEFAULT_HOST 设置端口为5001

1. 无参数使用 Q_DEFAULT_HOST 直接

- connect_to_q() → 用途 Q_DEFAULT_HOST 按现状处理/不加改动

1. 仅主机名用作主机名与 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），展平嵌套调用，并使用人工智能来消除重载运算符的歧义 - 首先需要建立q连接 - 跑 connect_to_q 使用前请安装工具（使用q自带的解析器） - 命名空间影响在（某处）创建变量和函数 .parseq 您的q会话的命名空间 - 硬连接到Claude代码CLI - 与其他可与任何MCP兼容的大型语言模型（LLM）配合使用的工具不同，此工具特别调用Claude Code CLI进行人工智能歧义消除 - 可能会产生错误的翻译，尤其是对于复杂的表达 - 请在使用前验证所有输出内容 - 在（此处填写网址或平台）报告错误

已知的限制

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

查询中断（SIGINT）的限制

• Windows平台当MCP服务器在Windows（非WSL环境）上运行时，查询中断功能被禁用
• 跨平台设置当MCP服务器和q会话运行在WSL/Windows分隔线的两侧时，查询中断功能被禁用
• 影响在这些配置中，LLM无法自动跳出无限循环或取消失控的查询

数据转换的局限性

• 带键表像这样的操作 1!table 在Pandas转换过程中可能会失败
• 字符串与符号的区别在输出中，q 字符串和符号可能看起来相同
• 类型歧义使用q键 meta 和 type 在精度至关重要的情况下，用于确定实际数据类型的命令
• 熊猫转换某些特定于q的数据结构可能无法正确转换为pandas的DataFrame

用于类型检查，请使用：

meta table           / Check table column types and structure
type variable        / Check variable type

WSL2 端口通信（Windows 用户）

*如果你不是在使用Windows系统，请跳过此部分。*

由于Claude CLI在Windows上仅支持WSL（Windows Subsystem for Linux），但你可能希望使用Windows的集成开发环境（IDE）或工具来连接到你的q服务器，因此你需要在WSL2和Windows之间建立适当的端口通信。

WSL2端口通信配置

.wslconfig 文件设置

位置： C:\Users\{YourUsername}\.wslconfig

添加镜像网络配置：

# Mirrored networking mode for seamless port communication
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

重启 WSL2

从 Windows PowerShell/CMD 运行（不要在 WSL 内运行）：

wsl --shutdown
# Wait a few seconds, then start WSL again

验证配置

检查是否启用了镜像网络：

ip addr show
cat /etc/resolv.conf

测试端口通信

测试 WSL2 → Windows（本地主机）：

# In WSL2, start a server
python3 -m http.server 8000

# In Windows browser or PowerShell
curl http://localhost:8000

测试 Windows → WSL2（本地主机）：

# In Windows PowerShell
python -m http.server 8001

# In WSL2
curl http://localhost:8001

镜像网络提供的功能

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

⚠️ 端口5000特殊情况

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

根本原因：

• Windows svchost 服务绑定到 127.0.0.1:5000 （仅限本地主机）
• Windows 和 WSL2 之间仅 localhost 的绑定设置并未完全同步
• 这为通用的镜像网络功能创建了一个例外情况

端口5000通信矩阵：

• ✅ Windows ↔ Windows：可工作（同一本地主机）
• ❌ WSL2 ↔ Windows：失败（本地主机解释不同）
• ✅ WSL2 ↔ WSL2：正常工作（相同环境）

端口5000的解决方案：

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

可能仅绑定到本地主机的常见服务

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

镜像网络的已知限制

1. 仅限本地主机的服务未完全镜像（已通过端口5000确认）
2. mDNS无法工作 在镜像模式下
3. 一些Docker配置 可能存在一些问题
4. 需要Windows 11 22H2或更高版本 （版本22621+）