isingq-mcp

<h1 align="center">IsingQ Toolkit</h1>

让 Agent 帮助你完成 QUBO 建模、校验并调用 IsingQ 求解

简体中文 · <a href="README.en.md">English</a> · <a href="#快速开始">快速开始</a> · <a href="https://console.isingq.com/">获取 API Key</a>

IsingQ Toolkit 是北京伊辛智能科技有限公司公开维护的本地 Agent 工具。

你可以直接描述排程、路径规划、投资组合或图优化问题，由 Agent 协助构建 QUBO，并使用你自己的 IsingQ API Key 发起求解。

• 建模引导、QUBO 校验和结果记录在用户电脑上完成。
• 只有调用求解工具时，矩阵才会通过 HTTPS 提交给 IsingQ。
• API Key 保存在本机私有文件中，不进入 Agent 对话或 MCP 配置。
• 支持标准 MCP、Codex Plugin 和 DeepSeek Harness 原生 Plugin。

快速开始

不熟悉终端或 MCP 配置时，把下面这段话发送给当前 Agent：

请从 https://github.com/ising-tech/isingq-toolkit 读取
skills/install-isingq-mcp/SKILL.zh-CN.md，严格遵循该 Skill，
帮我安装 IsingQ MCP，并且只接入当前 Agent。
不要在对话中索要或显示我的 API Key；需要 Key 时使用系统安全输入框。
安装完成后先重连 isingq MCP；如果当前 Agent 不支持动态重载，
再等我重启 Agent，然后验证是否加载出 7 个 MCP 工具。

安装 Skill 会根据当前 Agent 和操作系统选择一种接入方式，不会自动修改电脑上的其他 Agent。Host 不支持自动注册时，Skill 会输出可手工导入的 stdio JSON。

完成接入后应能在标准 MCP Host 中看到 7 个 isingq_* 工具。DSH 原生 Plugin 提供 9 个工具。

安装演示

第一次求解

知识查询、建模引导和 QUBO 校验不需要 API Key。只有提交真实求解任务时才需要个人 IsingQ API Key。

1. 登录或注册玉盘·伊辛云。
2. 进入 设置 → API → 创建API，创建便于识别的个人 API Key。
3. 让 Agent 调用 isingq_api_key_setup，在系统安全输入框中填写 Key。
4. 直接向 Agent 描述需要建模的问题。

不要把 API Key 发到 Agent 对话、命令参数、MCP JSON、Issue 或日志中。如果 Key 意外泄露，请在云平台删除对应记录并重新创建。

可以从这个示例开始：

请把下面的问题建成 QUBO。先解释变量、目标函数、约束和 Penalty，展示矩阵摘要，等我确认后再调用 IsingQ 求解：

任务 A、B 只能选择一个；选择 A 的收益为 8，选择 B 的收益为 5。

Agent 应先展示变量映射、目标函数、约束、Penalty、矩阵摘要和 SHA-256。你确认后，Agent 才应调用 isingq_solve_start。

该工具被 Host 放行后会立即创建远端任务。MCP 不再弹出额外的操作系统求解确认框；Host 是否再次确认取决于它自身的工具权限设置。

还能做什么

除了求解，Toolkit 还包含本地公开知识和 QUBO 建模指导。例如：

玉盘·伊辛云目前提供什么能力？请给出知识版本、来源和表述边界。

请先检查这个 QUBO 的维度、对称性、系数范围和矩阵摘要，不要提交求解。

云平台 API 当前支持最高 2048 个 QUBO 二进制变量。具体任务是否适合当前规模，仍取决于建模方式和约束展开结果。

支持范围

接入方式	适用范围	是否需要 Node.js
标准 MCP	WorkBuddy、Claude Code、Cursor、VS Code 等 MCP Host	npx 方式需要 Node.js 18+；Release 不需要
Codex Plugin	Codex 内置 Plugin 接入	否
DSH 原生 Plugin	DeepSeek Harness	由 DSH 管理

标准 MCP 的 Release 程序支持 macOS arm64/x64、Linux arm64/x64 和 Windows x64。同一台电脑只需要一份运行程序，不同 Agent 可以分别注册它。

其他安装方式

快速开始中的 Agent Skill 是普通用户的推荐入口。下面的命令适合需要手动管理安装或配置的用户。

npm / npx

需要 Node.js 18 或更高版本：

npx @ising-tech/isingq-mcp setup
npx @ising-tech/isingq-mcp configure-host --name generic --npx

将 generic 替换为实际支持的 Host 名称。需要手工注册的 Host 保持使用 generic，并在其 MCP 设置中导入输出的 stdio JSON。

GitHub Release

不希望安装 Node.js 时，从 GitHub Releases 下载对应系统的固定版本程序，并使用随 Release 提供的 SHA256SUMS 校验文件。

DeepSeek Harness

DSH 使用原生 Plugin，不需要 MCP Bridge。安装前可以查看 npm 包与完整使用说明：

dsh plugin --profile <profile> add @ising-tech/isingq-dsh-plugin

最低兼容基线为 DeepSeek Harness 0.1.0-rc.7，当前开发验证版本为 0.1.0-rc.8。@deepseek-ai/dsh-tools 支持范围为 >=0.1.0-rc.7 <0.2.0-0。

不要在同一个 DSH Profile 中同时启用 IsingQ 原生 Plugin 和旧 MCP Bridge。详细说明见 DSH Plugin README。

源码开发

从源码运行、架构说明、包边界和 Release 流程统一放在开发者文档，不建议普通用户通过源码安装。

工具能力

…