@osqi/zsfy

基于 stdio 的 ZSFY MCP 服务，提供查询、预约预检和最终提交挂号的原子接口。流程调度由 Codex 或 Hermes Skill 负责；最终提交必须由用户当次明确确认。

本地开发

复制 .env.example 为 .env 并填入授权官方客户端的当前配置。不要提交 .env。

npm install
npm run build

Linux MCP 配置

无论使用本地包还是已发布的 npm 包，都在 MCP 客户端的 env 中直接提供实际 ZSFY_* 参数。不要配置或复制请求中的 authorization 与 x-timestamp，它们由服务逐请求生成。

{
  "mcpServers": {
    "zsfy": {
      "command": "npx",
      "args": ["--yes", "@osqi/zsfy"],
      "env": {
        "ZSFY_BASE_URL": "https://zsfy.gzsums.net",
        "ZSFY_APP_ID": "<app-id>",
        "ZSFY_APP_SECRET": "<app-secret>",
        "ZSFY_SERIAL": "<current-serial>",
        "ZSFY_HOSPITAL_ID": "1",
        "ZSFY_PRIMARY_USER_ID": "<primary-user-id>",
        "ZSFY_DEVICE_NAME": "wechat",
        "ZSFY_DEVICE_MODEL": "<device-model>",
        "ZSFY_DEVICE_ID": "<device-id>",
        "ZSFY_DEVICE_VERSION": "",
        "ZSFY_OSTYPE": "wx_mini",
        "ZSFY_APP_VERSION": "<current-app-version>",
        "ZSFY_LANGUAGE": "zh_CN",
        "ZSFY_USER_AGENT": "<current-authorized-client-user-agent>"
      }
    }
  }
}

本地开发时，将 args 改为：

["--yes", "--package=file:/absolute/path/to/zsfy", "zsfy-mcp"]

MCP Inspector（Linux）

Inspector 调试时可从项目 .env 导入相同的实际参数：

set -a
. ./.env
set +a
npx --yes @modelcontextprotocol/inspector \
  npx --yes --package=file:/absolute/path/to/zsfy zsfy-mcp

Hermes Agent

在 ~/.hermes/config.yaml 的 mcp_servers 中加入：

mcp_servers:
  zsfy:
    command: "npx"
    # 显式运行包暴露的 bin，避免部分 npx 版本无法从 scoped 包名推断可执行文件。
    args: ["--yes", "--package=@osqi/zsfy", "zsfy-mcp"]
    env:
      ZSFY_BASE_URL: "https://zsfy.gzsums.net"
      ZSFY_APP_ID: "<app-id>"
      ZSFY_APP_SECRET: "<app-secret>"
      ZSFY_SERIAL: "<current-serial>"
      ZSFY_HOSPITAL_ID: "1"
      ZSFY_PRIMARY_USER_ID: "<primary-user-id>"
      ZSFY_DEVICE_NAME: "wechat"
      ZSFY_DEVICE_MODEL: "<device-model>"
      ZSFY_DEVICE_ID: "<device-id>"
      ZSFY_DEVICE_VERSION: ""
      ZSFY_OSTYPE: "wx_mini"
      ZSFY_APP_VERSION: "<current-app-version>"
      ZSFY_LANGUAGE: "zh_CN"
      ZSFY_USER_AGENT: "<current-authorized-client-user-agent>"
    timeout: 120
    connect_timeout: 60
    supports_parallel_tool_calls: false
    tools:
      include:
        - zsfy_list_relatives
        - zsfy_list_departments
        - zsfy_list_department_doctors
        - zsfy_get_doctor
        - zsfy_get_reservation_settings
        - zsfy_get_available_times
        - zsfy_check_reservation

该白名单默认不暴露最终提交工具。需要真实提交时，才手动加入 zsfy_submit_reservation，然后在 Hermes 执行 /reload-mcp。

Hermes 流程 Skill

MCP 只提供原子接口；项目内的 Hermes Skill 负责“就诊人 → 科室 → 医生 → 排班/余号 → 预检 → 明确确认 → 提交”的流程调度。

mkdir -p ~/.hermes/skills/healthcare
cp -r /absolute/path/to/zsfy/hermes-skills/zsfy ~/.hermes/skills/healthcare/

新开 Hermes 会话后使用：

/zsfy 查询内分泌科医生的排班

若不想复制文件，可在 ~/.hermes/config.yaml 中加入：

skills:
  external_dirs:
    - /absolute/path/to/zsfy/hermes-skills

Hermes MCP 配置键和工具过滤规则以其官方配置参考为准。

发布到 npm

当前包名为 @osqi/zsfy。发布包只包含编译产物和两套 Skill；.env、抓包数据、密钥与本地缓存均不会被打包。

npm test
npm pack --dry-run
npm login
npm whoami
npm publish

新版本发布：

npm version patch   # 或 minor / major
npm publish

发布前请补充合适的 LICENSE，确认具备 @osqi scope 的发布权限，并复核发布清单不含敏感信息。

缓存策略

缓存仅存在于 MCP 进程内，退出即清除：就诊人 24 小时、科室 24 小时、科室医生 1 小时、医生详情/排班 1 小时、预约配置 1 小时。余号查询、预约预检和最终提交始终访问上游，不使用缓存。

Hermes 科室目录

Hermes /zsfy 默认使用随 Skill 打包的 hermes-skills/zsfy/references/departments.json，不在普通挂号流程请求远程科室列表。目录保留科室代码、名称和父级入口，因此可区分同名的不同门诊入口；例如默认使用 01003 的内科入口，而非体重管理入口 37006。

只有明确要求“生成最新科室列表”或“更新科室目录”时，Skill 才分页调用科室 MCP 工具，先展示目录变更，获得确认后再替换本地快照。