IsingQ Toolkit

English | 한국어

IsingQ Toolkit은 北京伊辛智能科技有限公司이 공개적으로 유지관리하는 로컬 Agent 도구입니다. Agent가 스케줄링, 경로 계획, 포트폴리오, 그래프 최적화 등의 문제를 QUBO로 표현하도록 돕고, 사용자 확인 후 사용자 자신의 IsingQ API Key로 玉盘·伊辛云에 풀이를 요청합니다.

• 모델링 안내, QUBO 생성, 검증, 결과 기록은 사용자 컴퓨터에서 완료됩니다.

• 사용자가 확인한 풀이 행렬만 HTTPS를 통해 IsingQ로 전송됩니다.

• WorkBuddy, Codex, Claude Code, Cursor, VS Code, Trae 및 DeepSeek Harness를 지원합니다.

• 표준 MCP는 7개 도구와 13개 로컬 Resources를 제공하고, DSH 네이티브 Plugin은 9개 도구를 제공합니다.

• 클라우드 플랫폼 API는 현재 최대 2048개의 QUBO 이진 변수를 지원합니다.

시작하기 전: IsingQ API Key 받기

실제 풀이에는 개인 IsingQ API Key가 반드시 필요합니다. 지식 조회, 모델링 안내, QUBO 검증에는 API Key가 필요 없습니다.

1. 玉盘·伊辛云을 열고 개인 계정으로 등록하거나 로그인합니다.

2. 플랫폼에서 설정 → API로 이동합니다.

3. API 생성을 클릭하고 식별하기 쉬운 API 이름을 입력한 후 생성을 완료합니다.

4. 설치 시 운영체제 보안 입력 창을 통해 API Key를 저장합니다.

플랫폼의 생성 경로는 玉盘·伊辛云 웹사이트 개인정보 처리방침의 "설정" 서비스 설명에도 기록되어 있습니다.

API Key를 Agent 대화, 명령 인자, MCP JSON, Issue 또는 로그에 보내지 마세요. Key가 실수로 유출된 경우 클라우드 플랫폼의 설정 → API로 돌아가 해당 기록을 삭제하고 다시 생성하세요.

권장 설치: Agent가 Skill을 읽도록 하기

아래 문단을 현재 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 工具。

Skill 설치는 현재 운영체제와 현재 Agent를 대상으로 하므로, 컴퓨터에 다른 Agent가 설치되어 있어도 모두 구성하지 않습니다. Trae는 Skill이 출력한 stdio JSON을 MCP 설정 페이지에 가져와야 합니다.

설치 성공 조건:

• 프로그램이 설치되고 해시 검증을 통과했습니다.

• 로컬에 유효한 API Key가 있습니다.

• 현재 Agent가 MCP에 등록되었습니다.

• 재시작 후 표준 MCP가 7개 도구를 로드하거나, DSH 네이티브 Plugin이 9개 도구를 로드합니다.

GitHub 소스에서 설치

현재 공개 저장소는 바로 테스트할 수 있습니다. Node.js 18 이상이 필요합니다:

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은 입력 내용을 표시하지 않고 API Key를 입력받습니다. 그런 다음 실제 사용하는 Agent만 구성합니다:

isingq-mcp configure-host --name workbuddy

--name은 workbuddy, codex, claude-code, cursor, vscode, generic을 지원합니다. Trae 또는 다른 Host는 표준 구성을 얻은 후 수동으로 가져올 수 있습니다:

isingq-mcp config --json

일반 stdio 구성은 다음과 같습니다:

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

구성 후 Agent를 완전히 종료하고 다시 시작하세요.

npm, Release 및 DSH

Node.js 18 이상이 있으면 npm/npx로 직접 설치하고 구성합니다:

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

generic을 실제 사용하는 workbuddy, codex, claude-code, cursor 또는 vscode로 바꾸세요. Trae는 generic을 그대로 사용하고 출력된 stdio JSON을 가져옵니다.

Node.js를 설치하고 싶지 않은 사용자는 GitHub Releases에서 해당 시스템용 고정 버전 프로그램을 다운로드하고 SHA256SUMS로 검증할 수 있습니다. macOS arm64/x64, Linux arm64/x64, Windows x64를 지원합니다.

DeepSeek Harness는 네이티브 Plugin을 사용하며 MCP Bridge가 필요 없습니다:

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

같은 DSH Profile에서 IsingQ 네이티브 Plugin과 기존 MCP Bridge를 동시에 활성화하지 마세요.

사용 방법

설치 후 재시작하면 도구 이름을 외울 필요 없이 Agent에게 문제를 직접 설명하세요:

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

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

Agent는 먼저 모델링과 검증을 완료하고 변수 매핑, 목적 함수, 제약 조건, Penalty, 행렬 요약, SHA-256을 표시해야 합니다. 사용자가 명시적으로 확인하고 운영체제 확인 창을 거친 후에만 풀이를 제출합니다.

로컬 공개 지식도 조회할 수 있습니다:

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

도구 기능

풀이 결과는 다음을 함께 보존합니다:

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

• MCP가 QUBO로 다시 계산한 objective: f(x) = offset + Σ_i Q_ii x_i + Σ_{i<j} Q_ij x_i x_j.

둘은 변수 변환, 상수항 또는 계수 기준이 달라 같지 않을 수 있습니다. 최저 energy도 자동으로 비즈니스 타당성, 전역 최적성 또는 특정 하드웨어 성능을 의미하지 않습니다.

데이터 및 보안

• API Key는 로컬 개인 파일에만 저장되며 도구 인자나 대화에 들어가지 않습니다.

• 모델링 안내, QUBO 검증, 공개 지식 조회는 로컬에서 완료됩니다.

• isingq_solve_start만 사용자 확인 후 풀이 행렬을 전송합니다.

• API 요청은 HTTPS를 사용하며, 행렬 업로드는 단기 서명을 사용하고 개인 API Key를 포함하지 않습니다.

• 로컬 기록에는 모델, 작업 ID, 결과가 저장되며 API Key는 저장되지 않습니다.

더 자세한 경계 사항은 Security Policy를 참조하세요.

업그레이드 및 다중 Agent

• 업그레이드할 때 설치 Skill을 다시 실행하거나 npm/Release를 다시 설치하면 됩니다.

• 기존 API Key와 로컬 풀이 기록은 유지됩니다.

• 컴퓨터당 프로그램 하나만 설치하면 됩니다. 서로 다른 Agent가 같은 로컬 프로그램을 각각 등록하면 됩니다.

• 구성을 업데이트한 후 반드시 해당 Agent를 완전히 재시작해야 합니다.

문제 발생 시

• API Key가 없음: 玉盘·伊辛云의 설정 → API → API 생성으로 이동하세요.

• Agent에 도구가 표시되지 않음: 구성을 확인한 후 Agent를 완전히 재시작하고 MCP 신뢰 프롬프트를 승인하세요.

• Agent 샌드박스가 쓰기를 금지함: 명시된 설치 디렉터리와 사용자 구성 디렉터리만 승인하고 API Key를 프로젝트 디렉터리에 넣지 마세요.

• Trae 자동 연동 불가: isingq-mcp config --json을 실행하고 Trae MCP 설정 페이지에서 가져오세요.

• NDJSON 응답만 확인됨: 이는 프로세스에 접근할 수 있다는 뜻일 뿐입니다. Agent에서 7개 네이티브 도구가 보여야 연동이 완료된 것입니다.

개발자 문서

아키텍처, 패키지 경계, QUBO 데이터 계약, 빌드 및 Release 프로세스는 docs/DEVELOPMENT.md를 참조하세요.

이 프로젝트는 Apache License 2.0을 사용합니다. 이 라이선스는 IsingQ 또는 伊辛智能 관련 상표권을 부여하지 않습니다.