<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>

用你自己的 [氚云](https://www.h3yun.com) 账号登录，把网页工作台里的应用、表单、记录做成 [FastMCP](https://gofastmcp.com/) 工具。

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

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

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

## 接线（Agent 先读这里）

给人类和 Agent 的同一套步骤。先装 [uv](https://docs.astral.sh/uv/)（Python 3.12+）。建议用权限收窄的只读氚云账号。

1. 克隆并安装：

```bash
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 设置：

```json
{
  "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 贴进对话：

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

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

```json
{
  "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。

```bash
uv run pytest
```

## 许可

MIT。欢迎看 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [SECURITY.md](SECURITY.md)。