IsingQ Toolkit

English | 简体中文

IsingQ Toolkit is a local Agent tool publicly maintained by Beijing Ising Intelligent Technology Co., Ltd. It helps Agents express scheduling, path planning, portfolio optimization, graph optimization, and other problems as QUBO, and after user confirmation, calls the Yupan·Ising Cloud solver using the user's own IsingQ API Key.

• Modeling guidance, QUBO generation, validation, and result recording are done on the user's computer.

• Only the solving matrix confirmed by the user is sent to IsingQ over HTTPS.

• Supports WorkBuddy, Codex, Claude Code, Cursor, VS Code, Trae, and DeepSeek Harness.

• The standard MCP provides 7 tools and 13 local Resources; the DSH native Plugin provides 9 tools.

• The cloud platform API currently supports up to 2048 QUBO binary variables.

Before You Start: Get an IsingQ API Key

Real solving requires a personal IsingQ API Key. Knowledge queries, modeling guidance, and QUBO validation do not require an API Key.

1. Open Yupan·Ising Cloud and register or log in to your personal account.

2. In the platform, go to Settings → API.

3. Click Create API, enter a recognizable API name, and complete the creation.

4. Save the API Key through the operating system's secure input box during installation.

The platform's creation path is also documented in the "Settings" service description in the Yupan·Ising Cloud website privacy policy.

Do not send the API Key to Agent conversations, command arguments, MCP JSON, Issues, or logs. If the Key is accidentally leaked, go back to Settings → API in the cloud platform, delete the corresponding record, and create a new one.

Recommended Installation: Let the Agent Read the Skill

Send the following text to the current Agent:

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

Installing the Skill selects the current operating system and the current Agent; it will not configure everything just because other Agents are installed on the computer. Trae requires importing the stdio JSON output by the Skill into the MCP settings page.

A successful installation should satisfy:

• The program is installed and passes hash verification.

• A valid API Key already exists on this machine.

• The current Agent has registered MCP.

• After restart, the standard MCP loads 7 tools, or the DSH native Plugin loads 9 tools.

Installing from GitHub Source

The current public repository can be tested directly. Requires Node.js 18 or higher:

git clone https://github.com/ising-tech/isingq-toolkit.git
cd isingq-toolkit
npm ci
npm install -g .
isingq-mcp setup
isingq-mcp self-check --json

isingq-mcp setup receives the API Key without echo. Then only configure the Agent actually in use:

isingq-mcp configure-host --name workbuddy

--name supports workbuddy, codex, claude-code, cursor, vscode, and generic. For Trae or other Hosts, you can obtain the standard configuration and import it manually:

isingq-mcp config --json

The generic stdio configuration is as follows:

{
  "mcpServers": {
    "isingq": {
      "command": "isingq-mcp",
      "args": ["serve"]
    }
  }
}

After configuration, fully exit and restart the Agent.

npm, Release, and DSH

With Node.js 18 or higher, install and configure directly via npm/npx:

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

Replace generic with the actual workbuddy, codex, claude-code, cursor, or vscode in use; for Trae, keep using generic and import the output stdio JSON.

Users who do not wish to install Node.js can download the pinned version for their system from GitHub Releases and verify it with SHA256SUMS. Supports macOS arm64/x64, Linux arm64/x64, and Windows x64.

DeepSeek Harness uses the native Plugin and does not require the MCP Bridge:

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

Do not enable both the IsingQ native Plugin and the old MCP Bridge in the same DSH Profile.

How to Use

After installation and restart, simply describe the problem to the Agent; there is no need to memorize tool names:

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

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

The Agent should first complete modeling and validation, showing the variable mapping, objective function, constraints, Penalty, matrix summary, and SHA-256. Solving is submitted only after you explicitly confirm and pass the operating system confirmation dialog.

You can also query local public knowledge:

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

Tool Capabilities

Solve results are retained in both forms:

• IsingQ provider energy: E(s) = -1/2 · Σ_i Σ_j J_ij s_i s_j - Σ_i h_i s_i.

• MCP objective recomputed from QUBO: f(x) = offset + Σ_i Q_ii x_i + Σ_{i<j} Q_ij x_i x_j.

The two may differ due to variable transformation, constant terms, or coefficient conventions. The lowest energy also does not automatically represent business feasibility, global optimality, or specific hardware performance.

Data and Security

• The API Key is stored only in a local private file and never enters tool arguments or conversations.

• Modeling guidance, QUBO validation, and public knowledge queries are done locally.

• Only isingq_solve_start sends the solving matrix after user confirmation.

• API requests use HTTPS; matrix uploads use short-term signatures and do not carry the personal API Key.

• Local records store the model, task ID, and results, but not the API Key.

See Security Policy for more boundaries.

Upgrades and Multiple Agents

• To upgrade, simply re-run the installation Skill or reinstall npm/Release.

• Existing API Keys and local solve records are preserved.

• Only one copy of the program needs to be installed per computer; different Agents can each register the same local program.

• After updating the configuration, you must fully restart the corresponding Agent.

Troubleshooting

• No API Key: Go to Settings → API → Create API on Yupan·Ising Cloud.

• Tools not appearing in the Agent: After confirming the configuration, fully restart the Agent and approve its MCP trust prompt.

• Agent sandbox blocks writes: Only authorize the explicit installation directory and user configuration directory; do not put the API Key in the project directory.

• Trae cannot connect automatically: Run isingq-mcp config --json and import it through the Trae MCP settings page.

• Only an NDJSON response is tested: This only shows the process is accessible; you must see the 7 native tools in the Agent for the integration to be complete.

Developer Documentation

Architecture, package boundaries, QUBO data contract, build, and Release process are documented in docs/DEVELOPMENT.md.

This project is licensed under the Apache License 2.0. This license does not grant any trademark rights related to IsingQ or Ising Intelligent.