Fast H3yun

用你自己的 氚云 账号登录，把网页工作台里的应用、表单、记录做成 FastMCP 工具。

默认是 STDIO MCP：由 Cursor、Claude Desktop 等客户端拉起进程，不占端口。OPC Feed 目前走 URL，用 --http。

这不是氚云官方产品，也不是官方 OpenAPI。会话来自网页登录：手机号 + 密码 → JWT + EngineCode。能看到什么，取决于这个登录用户的权限。

接线（Agent 先读这里）

给人类和 Agent 的同一套步骤。先装 uv（Python 3.12+）。建议用权限收窄的只读氚云账号。

1. 克隆并安装：

git clone https://github.com/ironfrancis/fast-h3yun.git
cd fast-h3yun
uv sync

2. 选一种客户端配置（下面两段 JSON 复制即用，把路径和账号换成当前机器）。
3. 没把手机号密码写进 env 时，连上后先调用 h3yun_login。
4. 不要把密码写进 git，也不要提交 .env。

Cursor / Claude Desktop（推荐，STDIO）

客户端自己执行 command，用 stdin/stdout 通信。不要先手动起服务。

把仓库的绝对路径和氚云账号填进去，写入 Cursor 的 ~/.cursor/mcp.json（或项目 .cursor/mcp.json）、Claude 的 MCP 设置：

{
  "mcpServers": {
    "h3yun": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/ABS/PATH/fast-h3yun",
        "fast-h3yun"
      ],
      "env": {
        "H3YUN_MOBILE": "YOUR_MOBILE",
        "H3YUN_PASSWORD": "YOUR_PASSWORD"
      }
    }
  }
}

env 也可以留空，连上后用工具 h3yun_login 输入手机号和密码。

OPC Feed（HTTP URL）

OPC 的 mcp_connection_parse → probe → propose 吃的是 URL，不是 STDIO。在本机先起 HTTP，再把 JSON 贴进对话：

cd /ABS/PATH/fast-h3yun
uv sync
uv run fast-h3yun --http

默认地址：http://127.0.0.1:8765/mcp

{
  "mcpServers": {
    "h3yun": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

Agent：把上面这段交给 mcp_connection_parse，然后 mcp_connection_probe，再 mcp_connection_propose。氚云账号放在本服务的环境变量或 h3yun_login，不要写进 OPC 仓库。

能做什么

工具	作用
h3yun_login	手机号和密码登录。mobile / password 必填
h3yun_session_info	当前用户和引擎
h3yun_list_apps	应用列表
h3yun_list_forms	某个应用下的表单
h3yun_search_forms	按名称搜表单
h3yun_query_records	分页查记录
h3yun_get_record	按 ObjectId 取一条

第一版只读：不会创建、修改、删除或审批。典型顺序：h3yun_login → h3yun_session_info → h3yun_list_apps → h3yun_search_forms 或 h3yun_list_forms → h3yun_query_records。

环境变量

变量	说明
H3YUN_MOBILE	登录手机号。不填则必须调用 h3yun_login
H3YUN_PASSWORD	登录密码。不填则必须调用 h3yun_login
H3YUN_ENGINE_CODE	多引擎账号时指定引擎
H3YUN_TOKEN	验证码挡住密码登录时的兜底 JWT
H3YUN_BASE_URL	默认 https://www.h3yun.com
H3YUN_HOST / H3YUN_PORT	仅 --http：默认 127.0.0.1 / 8765

也可以 cp .env.example .env 后填写。STDIO 模式下更常见的是写在客户端 JSON 的 env 里。

限制

• 网页 /v1 没有官方稳定性承诺，氚云发版可能改字段。
• 密码错误次数过多会被锁；本服务会缓存 token，并限制登录频率。
• 线上密码登录可能弹出阿里云验证码。无人值守可改用浏览器里已登录的 H3YUN_TOKEN + H3YUN_ENGINE_CODE。
• --http 不对调用方鉴权。默认只监听本机，不要把端口暴露到公网。
• 不要提交 .env、token 或 EngineSecret。工具返回值会剥离 password / token。

uv run pytest

许可

MIT。欢迎看 CONTRIBUTING.md 和 SECURITY.md。