Tianyan MCP Server

当前版本以本文“受控实验提交”章节为准：Server 公开三个 Tool，其中两个查询 Tool 只读； submit_quantum_experiment 会创建远程实验任务，受下述安全开关与 Host 确认约束。

只读查询并受控提交实验的 Streamable HTTP MCP Server。

当前 MVP 提供三个 Tool：

• list_available_quantum_backends：查询当前运行中的量子计算机和量子仿真机；

• get_quantum_backend：按 id 或 code 精确查询资源详情。

• submit_quantum_experiment：在受控条件下提交一条 QCIS 实验线路。

前置条件

• Python 3.11 或更高版本；

• uv；

• 天衍云列表接口的网络访问能力；

• 提交实验还需要天衍云 SDK API 的网络访问能力，以及由 Server 端配置的 SDK 凭证。

Related MCP server: luogu-mcp-server

安装

uv sync

依赖只安装到项目 .venv，无需全局安装 Python 包。

启动 Streamable HTTP

只在当前 PowerShell 进程设置 API Key，不要写入代码、README 或提交到 Git：

$env:TIANYAN_MCP_API_KEY = 'replace-with-at-least-32-characters'
uv run tianyan-mcp-http

默认 MCP Endpoint：

http://127.0.0.1:8000/mcp

Client 必须发送：

Authorization: Bearer <api-key>

默认只监听 loopback。应用自身不终止 TLS，也不提供公网部署能力。

环境变量

TIANYAN_MCP_ALLOWED_ORIGINS 不支持 *。浏览器请求携带 Origin 时，必须与白名单完全匹配；非浏览器 MCP Client 未携带 Origin 时可继续认证。

健康检查

/healthz 不要求 Bearer API Key，且不会调用天衍云：

Invoke-WebRequest -UseBasicParsing -Uri 'http://127.0.0.1:8000/healthz'

本地 stdio 调试

stdio 模式不要求 TIANYAN_MCP_API_KEY，仅用于本地进程集成：

uv run tianyan-mcp-stdio

测试

默认测试不访问网络：

uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest --cov=tianyan_mcp --cov-report=term-missing --cov-fail-under=90

只有在明确需要验证天衍云真实只读接口时，才在当前 PowerShell 进程显式启用：

$env:TIANYAN_LIVE_TEST = '1'
uv run pytest tests/test_live.py -q

真实测试只执行列表查询和按返回资源 id 查询详情，不调用写接口。

HTTPS 边界

应用只提供 HTTP。正式环境必须在 Nginx、云负载均衡或 API 网关终止 TLS，并显式配置允许的 Host 与 Origin。当前项目不负责域名、证书或公网部署。

能力边界

• 仅支持量子计算机和量子仿真机；

• 列表只返回 status=0 的运行中资源；

• 详情查询可以返回校准中或升级中的已知资源；

• 不包含 HPC、天衍-P2000、任务取消和资源修改；受控的单线路 QCIS 实验提交是唯一写入操作。

• 不转发 MCP 调用方的 Authorization、Cookie 或其他凭证到天衍云。

受控实验提交

除已有的只读 Tool list_available_quantum_backends 与 get_quantum_backend 外，Server 还提供 submit_quantum_experiment。该 Tool 仅提交一条 QCIS 线路，并且创建远程任务、可能消耗天衍云资源； 它不是幂等操作，调用失败后不能把重试当作安全行为。

Server 进程配置与认证边界

在启动 Server 的进程中设置 SDK 凭证和硬件总开关。下面的占位符不是可用密钥，禁止将真实值写入 README、代码、测试、日志或 Git：

# 通过受控 Secret 注入 TIANYAN_SDK_OPEN_ID；不要在文档或命令历史中赋值。
$env:TIANYAN_ALLOW_HARDWARE_SUBMISSION = 'false'

TIANYAN_MCP_API_KEY authenticates Agent -> MCP Server.
TIANYAN_SDK_OPEN_ID authenticates MCP Server -> Tianyan SDK API.
The Agent must never receive TIANYAN_SDK_OPEN_ID or the returned SDK Token.

TIANYAN_ALLOW_HARDWARE_SUBMISSION 仅接受严格的小写 true 或 false，默认 false。SDK 密钥缺失 不会阻止 HTTP 或 stdio Server 启动，但调用提交 Tool 会安全失败。SDK 登录属于 Server 内部实现， 不注册为 Agent 可调用的 Tool；也不会转发 Agent 的 Authorization、Cookie 或其他凭证给天衍云。

Tool 合同

submit_quantum_experiment 的六个输入为：

• computer_code：目标后端代码；只允许下方九个白名单后端及硬件别名。

• circuit：一条 QCIS 线路；只允许单条线路，不能为空、不含 U+0000，最大 20,000 个字符。

• name：实验名称，去除首尾空白后长度为 1–100。

• lab_name：实验集合名称，去除首尾空白后长度为 1–100。

• shots：采样次数，必须为整数且 1 <= shots <= 1000。

• allow_hardware：是否显式确认真实硬件提交，默认 false。

白名单包含四个量子计算机：tianyan176、tianyan176-2、tianyan24、tianyan504；以及五个 模拟器：tianyan_sw、tianyan_s、tianyan_tn、tianyan_sa、tianyan_swn。硬件还可使用 tianyan-176、tianyan-176-2、tianyan-24、tianyan-504 作为提交别名。

上游请求字段被固定为 QCIS（language=qcis）、普通优先级（priority=0）和校验开启 （is_verify=true）；调用方不能覆盖这些字段。上游 lab_id 固定为空字符串，其实际平台语义为 “待实测”。

模拟器提交不需要硬件开关。真实硬件提交必须同时满足：Server 的 TIANYAN_ALLOW_HARDWARE_SUBMISSION=true、Tool 的 allow_hardware=true，以及 Host 在调用前向用户展示 后端、线路名称、实验集合名称与 shots 并取得确认。默认配置禁止真实硬件写入。

提交 POST 不自动重试。网络超时、连接错误、5xx 或无法解析的成功响应都会报告“结果未知”：天衍云 可能已经接收了实验，应先在平台核查，不能直接重复提交。

测试与真实调用边界

默认测试不访问天衍云，也不会提交实验。TIANYAN_LIVE_TEST=1 仍然只执行只读 smoke test：仅列表查询 和按返回的资源 ID 查询详情，不调用 SDK 登录或提交接口。正常 quick-start 路径不包含任何可执行的真实 写入命令；真实写入测试需要独立开关、逐次用户批准，并不属于本项目的默认流程。

多租户生产部署（单主机）

共享部署必须显式设置 TIANYAN_IDENTITY_MODE=multi_tenant。此模式仅用于 Streamable HTTP：每位用户 使用自己的 MCP API Key，并且各自绑定的 SDK Open ID 只会在服务端加密保存。TIANYAN_MCP_API_KEY 和 TIANYAN_SDK_OPEN_ID 是单用户模式变量；它们在 multi_tenant 模式中不得存在。

多租户服务需要一条绝对路径的 SQLite 数据库，以及两份彼此独立的服务器密钥材料：

在受控密钥管理系统中生成独立的高熵 Pepper 和 32 字节加密密钥，再由 systemd credentials、容器 Secret 或等价的进程级 Secret 注入方式交给服务。不要在终端、Shell 历史、README、工单、日志或 Git 中打印或 粘贴这些值。数据库备份不能替代这两份密钥材料的独立备份。

应用仅监听 loopback；Nginx 负责 HTTPS 终止和公网入口。部署前复制并按本机证书、域名和代理策略审查 docs/deployment/nginx-multi-tenant.conf.example。公网仅 应暴露 /mcp、/account/sdk-credential 和 /healthz，再代理到 127.0.0.1:8000。 Nginx 将上游 Host 固定为 127.0.0.1，使其符合服务默认的 TIANYAN_MCP_ALLOWED_HOSTS；不要把未经验证的公网 Host 透传给应用。

管理员与用户流程

管理员只在服务器本机运行 tianyan-mcp-admin。使用 create-user 创建租户时，CLI 只显示一次新 MCP API Key；通过受控渠道交给该用户，随后不应再记录或请求该明文。list-users 不显示 Key、SDK Open ID、 密文或 Token。

用户在自己的受信任客户端运行 tianyan-mcp-client configure，按交互提示输入 HTTPS 服务地址、自己的 MCP API Key 和 SDK Open ID；SDK Open ID 使用隐藏输入，不会被 CLI 持久化或回显。随后将 MCP API Key 配置到 用户自己的 MCP 客户端。tianyan-mcp-client status 只显示是否已绑定，remove 只移除当前用户自己的绑定。

发生泄露、人员变更或凭据替换时，管理员在服务器本机使用 tianyan-mcp-admin rotate-key 或 revoke-key， 并确认目标租户和操作。轮换会立即废止旧 Key 并只显示一次替换 Key；撤销不会删除审计历史。禁用用户用于 临时或长期停止访问，重新启用前应完成权限核验。

在线备份、恢复验证与迁移

tianyan-mcp-admin backup 使用 SQLite 在线备份生成一致性快照，并要求管理员显式确认目标文件。备份文件 包含加密凭据但不包含用于解密的服务器密钥；将 SQLite 快照、凭据加密密钥和 API Key Pepper 以不同访问控制 和不同介质保存。

恢复前先在隔离环境中复制快照并验证 SQLite 完整性、迁移版本和抽样凭据可否用对应密钥解密；确认租户、 已撤销 Key 和审计记录都符合预期后，才安排维护窗口切换服务数据库。不要通过删除凭据、降级为明文或跳过 迁移来强行启动。升级服务版本前先完成在线备份；应用启动时只会执行版本化 SQLite 迁移，失败时应保持服务 停止并从备份与日志诊断问题。