# 聚水潭个人连接器

为支持本地 MCP 的 AI 和业务系统提供聚水潭登录、页面探索和查询能力。组件运行在使用者自己的 Windows 电脑或 Linux 环境，使用本人的聚水潭账号及权限。

统一入口：[GitHub 仓库](https://github.com/ditingchenming-sys/jst-personal-connector)；安装包入口：[最新 Release](https://github.com/ditingchenming-sys/jst-personal-connector/releases/latest)。

把本仓库链接交给 AI，并告诉它：

> 请读取 https://github.com/ditingchenming-sys/jst-personal-connector 中的《AI接入说明.md》，在当前环境安装聚水潭个人连接器并配置 MCP，保留我的其他配置，再引导我本人登录。

AI 需要能够读取仓库、安装本地组件，并支持 MCP stdio。只接收远程 MCP 地址的客户端目前不能直接使用；仓库链接是接入说明和版本入口。

## 当前能力

当前版本 **0.2.0**，提供 **15 个 MCP 工具**。

| 能力 | 说明 |
|---|---|
| 本人登录 | 连接器登录页内填账号密码；只在聚水潭要求时由本人收取、填写短信验证码 |
| 登录恢复 | 本机加密保存登录态；不同 AI 调用端独立登录，主动退出账号清除对应资料 |
| 基础查询 | 预置查询目录，具体可用状态和参数通过 `search_capabilities` 获取 |
| 按需对接 | AI 查看页面、观察请求、核对只读用途、试查并保存查询模板；预置接口不是功能上限 |
| 条件调整 | 保存模板后，可更换模板明确声明的业务条件并复用 |
| 系统嵌入 | 提供 SDK、签名任务及员工本地执行通道；目标业务系统仍需独立配对和联调 |
| 业务写入 | **当前关闭**；预览、确认与执行工具的存在不表示已开放制单、修改、审核或付款 |

通用探索当前支持可核验的 JSON 查询协议。老式回调、复杂隐藏页面状态和未适配风控可能需要新增适配。查询失败不能解释为空数据，分页和完整性必须根据返回信息核实。

登录页只负责本人登录授权、验证码、连接状态和退出，完成后即可关闭。后续查询和条件交互在 AI 或业务系统中完成。

## 安装与使用

- [AI 接入说明](AI接入说明.md)：给 AI 的安装、配置和使用流程。
- [安装说明](INSTALL.md)：Windows、Linux、MCP 配置及更新。
- [通用探索与接口复用](docs/通用探索与接口复用.md)：未预置页面与查询的对接方式。

本项目是独立实现，不代表聚水潭官方认证或平台上架。GitHub 仅分发代码、说明和安装包，不接收使用者的密码、Cookie、业务数据或加密运行目录。

## 维护与更新

更新仓库说明后，AI 再次读取链接即可获取新说明。**本地已安装的程序不会随仓库修改自动升级**；发布新版本后按 [安装说明](INSTALL.md) 更新并重启相关 MCP。保留本机运行目录和原有密钥，更新不需要把登录资料交给维护者。

开发环境：Python 3.11+。使用 `uv sync --extra dev` 安装依赖，`uv run pytest -q` 执行离线和受控回环测试，`uv build --wheel` 构建 wheel。测试不使用真实 ERP 账号。

本项目采用 [MIT 许可证](LICENSE)。源码、wheel 和完整分发包均附许可证全文；复制或分发时请保留版权及许可声明。