Tianyan MCP Server

只读查询天衍云公开量子计算机和量子仿真机的 Streamable HTTP MCP Server。

当前 MVP 提供两个 Tool：

• list_available_quantum_backends：查询当前运行中的量子计算机和量子仿真机；
• get_quantum_backend：按 id 或 code 精确查询资源详情。

前置条件

• Python 3.11 或更高版本；
• uv；
• 天衍云列表接口的网络访问能力。

安装

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_API_KEY	无	HTTP 模式必填，去除首尾空白后至少 32 字符
TIANYAN_MCP_ALLOWED_ORIGINS	空	逗号分隔的精确 Origin；空值拒绝所有带 Origin 的请求
TIANYAN_MCP_ALLOWED_HOSTS	127.0.0.1,localhost,::1	逗号分隔的主机名，不包含端口
TIANYAN_HTTP_TIMEOUT_SECONDS	10	天衍云请求超时，范围 (0, 60] 秒
TIANYAN_MCP_HOST	127.0.0.1	ASGI 监听地址
TIANYAN_MCP_PORT	8000	ASGI 监听端口
TIANYAN_LIVE_TEST	0	只有值为 1 时才启用真实只读 Smoke Test

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、任务提交、任务取消和资源修改；
• 不转发 MCP 调用方的 Authorization、Cookie 或其他凭证到天衍云。