fast-h3yun

<p align="center"> <img src="./assets/readme/hero.svg" width="100%" alt="fast-h3yun：用氚云手机号和密码登录，只读检索应用、表单和业务记录，并接到 MCP"> </p>

<p align="center"> <img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12+-4C8DFF?style=flat-square"> <img alt="MIT License" src="https://img.shields.io/badge/license-MIT-8BA0B5?style=flat-square"> <img alt="FastMCP" src="https://img.shields.io/badge/MCP-FastMCP-3DDC97?style=flat-square"> <img alt="Read-only" src="https://img.shields.io/badge/scope-read--only-1A3348?style=flat-square"> </p>

用你自己的 氚云 账号登录，把网页工作台里的应用、表单、记录做成 FastMCP 工具。给 Cursor、OPC Feed 或其他 MCP 客户端查询用。

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

<p align="center"> <img src="./assets/readme/workflow.svg" width="100%" alt="流程：账号密码登录，建立工作台会话，只读检索应用表单记录，再接到 Cursor 或 OPC Feed"> </p>

能做什么

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

第一版只读：不会创建、修改、删除或审批。

启动

需要 Python 3.12+ 和 uv。建议用权限收窄的只读氚云账号。

git clone https://github.com/ironfrancis/fast-h3yun.git
cd fast-h3yun
cp .env.example .env
uv sync --extra dev
uv run fast-h3yun

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

.env 里可以预填 H3YUN_MOBILE / H3YUN_PASSWORD。不填也能启动，连上后先调用 h3yun_login。

接到 MCP 客户端

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

OPC Feed 走 mcp_connection_parse → probe → propose。Cursor 把同一 URL 配进 MCP 设置即可。账号密码留在本服务，不要写进客户端仓库。

环境变量

变量	说明
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	默认 127.0.0.1 / 8765

限制

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

uv run pytest

许可

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