jtcrpa-mcp 0.4.1 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +58 -158
  2. package/package.json +3 -2
package/README.md CHANGED
@@ -1,207 +1,107 @@
1
- # 九头虫 MCP 桥接器 · Jiutouchong MCP Bridge
1
+ # 九头虫 RPA MCP 桥接器 · Jiutouchong RPA MCP Bridge
2
2
 
3
3
  [简体中文](#简体中文) · [English](#english)
4
4
 
5
5
  ## 简体中文
6
6
 
7
- `jtcrpa-mcp` 让 MCP 客户端连接这台 Windows 电脑上的九头虫浏览器扩展。连接后,你可以让 AI 查看指定浏览器的标签页、创建和运行工作流、检查日志,或读取采集到的数据。
7
+ `jtcrpa-mcp` 把外部 AI 客户端接到你浏览器里的**九头虫 Agent**。下面用 Codex 做一次完整采集。你会在聊天里拿到书店首页 4 本书的书名和价格,还能把同一条规则用到下一页。[九头虫 RPA 官网与扩展下载](https://jtcrpa.com/) · [九头虫 Agent 使用手册](https://doc.jtcrpa.com/)
8
8
 
9
- ### 安装并连接第一个浏览器
9
+ ### 首次连接
10
10
 
11
- 1. 准备原生 Windows、Windows PowerShell 5.1、Node.js **20.19.0 或更高版本**,以及装有九头虫扩展的 Chrome 或 Firefox 配置。使用 Codex 的用户还需要能在终端运行 `codex`。在 PowerShell 中安装桥接器并检查版本。
11
+ 1. **浏览器里找到 MCP 入口。** 在 Windows 上将**九头虫 Agent** 添加到 Chrome 或 Firefox。点击浏览器工具栏的九头虫图标打开侧边栏,再点底部的 **设置菜单 ☰ → MCP 连接**。打开页面后应能看到 **开启 MCP 连接** 开关。[设置菜单截图](https://github.com/zhulinjia/jtcrpa-mcp-bridge/blob/main/docs/images/settings-menu-zh.png) · [扩展安装说明](https://doc.jtcrpa.com/guide/install.html)
12
12
 
13
- ```powershell
14
- npm.cmd install --global jtcrpa-mcp
15
- jtcrpa-mcp.cmd --version
16
- ```
17
-
18
- 2. 在要连接的浏览器中打开九头虫的**设置 → MCP 连接**。复制**注册当前浏览器**下的整条命令,在 PowerShell 中运行。页面会填好当前扩展 ID,Chrome 使用 `add --chrome-id`,Firefox 使用 `add --firefox-id`。首次运行会为当前 Windows 用户注册本机宿主。
19
- 3. 在同一页面打开**开启 MCP 连接**,按浏览器提示允许本机通信。状态变为**浏览器与本机程序已连接**后,在**接入外部 AI**中选择客户端。
20
-
21
- | 客户端 | 在哪里使用页面生成的命令或配置 |
22
- | --- | --- |
23
- | Codex | 在 PowerShell 中执行页面给出的 `codex mcp add` 完整命令。它会保存名为 `jtcrpa` 的服务。重新连接 MCP 或重启 Codex。 |
24
- | Claude Code | 在 PowerShell 中执行页面给出的 `config` 命令,将输出的 `mcpServers.jtcrpa` 合并到项目的 `.mcp.json`。重启客户端,在 `/mcp` 查看。 |
25
- | DeepSeek Harness | 在 PowerShell 中执行页面给出的 `config` 命令,把输出的插件条目加入 Harness 的插件列表,然后重启客户端。 |
13
+ 如果菜单里没有这个入口,先确认扩展版本。Chrome 和 Firefox 商店发布的 `2.0.2` 都缺少 MCP。只有商店版时,可向九头虫咨询支持 MCP 的安装包。[联系九头虫](https://jtcrpa.com/contact)
26
14
 
27
- 4. 在客户端发送 **“检查九头虫 MCP 连接,并列出当前浏览器标签页。”** 对照浏览器中打开的标签页即可确认连到了正确的配置。Codex 已在 Chrome 和 Firefox 上完成端到端验收。Claude Code 和 DeepSeek Harness 提供配置生成,尚未完成同等的端到端验收。
15
+ 2. **在 PowerShell 安装桥接器。** 从 Windows 开始菜单打开 PowerShell。需要 Windows PowerShell 5.1 和 Node.js 20.19.0 或更高版本。逐行运行下面的命令,第一行检查 Node.js,最后一行应显示桥接器版本号。[Node.js 下载](https://nodejs.org/en/download)
28
16
 
29
- 安装、注册和客户端接入通常只做一次。保持该浏览器配置的 MCP 开关开启,浏览器会按需启动本机宿主。日常使用时打开目标浏览器即可。
17
+ ```powershell
18
+ node --version
19
+ npm install -g jtcrpa-mcp
20
+ jtcrpa-mcp --version
21
+ ```
30
22
 
31
- ### 使用工作流和数据集
23
+ 3. **把这个浏览器连上。** 回到扩展的 **MCP 连接 → 注册当前浏览器**,点击复制按钮,把整条命令粘贴到刚才的 PowerShell 并按回车。页面已填好当前扩展的 ID。回到扩展打开 **开启 MCP 连接**,浏览器询问时允许本机通信。看到 **浏览器与本机程序已连接** 再继续。
24
+ 4. **把 Codex 连上。** 在同一页的 **接入外部 AI → Codex** 点击 **复制 Codex 接入命令**,在 PowerShell 粘贴并执行。运行 `codex mcp list` 应能看到 `jtcrpa`。打开一个新的 Codex 会话,下面三条消息都发在这个会话里。已安装并登录的 Codex CLI 可以在 PowerShell 输入 `codex` 打开。[安装 Codex CLI](https://developers.openai.com/codex/cli/) · [使用 Claude Code 或 DeepSeek Harness](https://github.com/zhulinjia/jtcrpa-mcp-bridge/blob/main/docs/usage.md#客户端配置)
32
25
 
33
- | 用途 | MCP 工具 | 示例 |
34
- | --- | --- | --- |
35
- | 确认连接、读取页面 | `connection_status`、`connection_ping`、`browser_context`、`page_probe` | “列出当前标签页,查看所选商品列表页能提取哪些字段。” |
36
- | 查找或编排工作流 | `workflow_list`、`workflow_get`、`workflow_contract`、`workflow_save` | “把当前页面的商品名称和价格采集规则保存为工作流。” |
37
- | 执行并检查结果 | `workflow_run`、`run_get`、`run_control` | “在当前列表页运行刚才的工作流,再告诉我状态和最近日志。” |
38
- | 读取采集数据 | `dataset_list`、`dataset_read` | “找到商品数据集,读取前 20 行,只返回商品名称和价格。” |
26
+ ### 第一次用 MCP 采集书名和价格
39
27
 
40
- 保存新工作流或修改已有工作流后,客户端应等你确认再执行。启动返回 `runId`,用 `run_get` 查询完成状态。写操作超时后,先用原 UUID 请求编号查询 `connection_status`,再核对最近运行。暂停可能仍有在途动作,结束运行不会撤销已执行的操作。
28
+ **① 打开网页,确认连到了它。** 用刚才连接的浏览器打开书店首页。如果页面显示英文,点页头的 **简体中文**。然后在 **Codex 聊天框**发送第一条消息。[打开书店练习场](https://doc.jtcrpa.com/practice/index.html)
41
29
 
42
- `dataset_read` 按 `datasetId` 或 `datasetName` 精确读取,两者任选其一。页码从 1 开始,默认每页 50 行、最多 200 行,`fields` 可指定字段。采集仍在进行时,翻页读到的是当时的数据。单次结果上限为 256 KiB,超限时请减小页大小或减少字段。
30
+ > 用九头虫 MCP 检查连接,找到我打开的书店练习场标签页。告诉我页面标题,并从页面上读出第一本书的书名和价格。
43
31
 
44
- ### 管理多个浏览器配置
32
+ 返回结果应能跟页面对上,第一本是《山海之间》,价格 ¥32.00。若找错页,先核对打开练习场的浏览器和配置,再继续。
45
33
 
46
- 直接使用扩展页面生成的接入命令时,客户端绑定该浏览器配置的实例 UUID。需要同时接入多个配置时,为每个实例设置不同的 MCP 服务名。要通过登记编号管理连接,可在 PowerShell 运行以下命令。
34
+ **② 保存一条可复用的规则。** 在同一个聊天里发送第二条消息。
47
35
 
48
- ```powershell
49
- jtcrpa-mcp.cmd list
50
- jtcrpa-mcp.cmd list --json
51
- ```
36
+ > 把书店当前列表页的每本书采成一行,书名列叫 title,价格列叫 price,保留货币符号,只采当前页。先在页面上试采,再把规则保存为工作流「Bookshop demo」,运行时写入数据集 bookshop_demo。告诉我保存的工作流编号,等我确认再运行。
52
37
 
53
- 如果列表显示「待选择实例」,确认目标浏览器已开启 MCP,然后执行列表给出的 `add ... --instance ...` 命令。相同扩展 ID 的多个浏览器配置可以分别选择。选定后,用实际编号替换下面示例中的 `c1`。
38
+ 此时你应拿到 `workflowId`(工作流编号)。也可以在扩展的 **主工作台** 搜索 `Bookshop demo` 查看已保存的规则。
54
39
 
55
- ```powershell
56
- jtcrpa-mcp.cmd config --connection c1 --client codex
57
- ```
40
+ **③ 运行并核对数据。** 收到保存结果后,再单独发第三条消息。
58
41
 
59
- 可选客户端为 `codex`、`claude`、`deepseek`,省略 `--client` 会输出三种配置。生成的启动参数包含登记的绑定 UUID。更换已选实例或扩展时,先添加新连接、更新客户端配置,再运行 `jtcrpa-mcp.cmd remove` 选择旧登记并确认。脚本可用 `jtcrpa-mcp.cmd remove c1` 直接删除指定登记。删除后,即使显示编号被复用,旧配置也会返回 `CONNECTION_REMOVED`。
42
+ > 确认,现在在刚才的书店首页运行 Bookshop demo。等运行结束,告诉我本次写了几行,再从 bookshop_demo 读出 title 和 price,用表格显示。
60
43
 
61
- ### 排查连接问题
44
+ 首次在空数据集中运行,本次应写入 **4 行**。也可以在扩展的 **数据存储** 找到 `bookshop_demo`,点 **预览**,对照同一份结果。
62
45
 
63
- | 现象 | 处理 |
46
+ | title | price |
64
47
  | --- | --- |
65
- | PowerShell 提示禁止运行脚本,或找不到命令 | 使用上面的 `npm.cmd` 和 `jtcrpa-mcp.cmd`。用 `npm.cmd prefix --global` 查看 Windows 全局命令目录,并确认它在当前终端的 `PATH` 中。 |
66
- | npm 镜像提示找不到刚发布的包 | 直接从官方源安装,运行 `npm.cmd install --global jtcrpa-mcp --registry=https://registry.npmjs.org`。 |
67
- | `Access to the specified native messaging host is forbidden` | 从当前扩展的 MCP 页面重新复制注册命令,对照 `list` 的完整扩展 ID,运行命令后重新开启 MCP。开发版扩展换 ID 后也要登记新 ID。 |
68
- | 「本机通信接口尚未就绪」或提示需要权限 | 在浏览器扩展管理页重新加载九头虫,返回 MCP 页面开启连接,按提示允许本机通信。 |
69
- | `BROWSER_OFFLINE` 或标签页属于另一个浏览器 | 打开目标浏览器配置并开启 MCP,核对页面的实例 UUID 与客户端配置。复制浏览器配置造成实例冲突时,使用扩展页面的「生成新实例 ID」并更新该客户端配置。 |
70
- | `CONNECTION_INSTANCE_NOT_SELECTED` 或 `CONNECTION_REMOVED` | 前者按 `list` 的提示选择实例。后者从现有登记重新生成客户端配置。 |
71
-
72
- ### 升级和卸载
48
+ | 山海之间 | ¥32.00 |
49
+ | 城市慢行 | ¥45.00 |
50
+ | 生活的留白 | ¥39.00 |
51
+ | 月光落在书页上 | ¥28.50 |
73
52
 
74
- 在原位置升级时,关闭 MCP 连接,运行 `npm.cmd install --global jtcrpa-mcp@latest`,再开启连接。移动 npm 全局目录或 Node.js 后,重跑当前扩展的注册命令。使用绝对路径的客户端配置也要重新生成。
53
+ **下次复用。** 点击书店的 **下一页**,在聊天中说「找到已保存的 Bookshop demo,在书店第 2 页运行,告诉我这次写入几行」。这次应再写入 4 行,其中有《旅途中的小地图》¥48.00。以后打开同一浏览器配置并保持 MCP 开启即可,浏览器和客户端会按需启动桥接器。
75
54
 
76
- 卸载前先关闭所有浏览器配置的 MCP 开关,再依次运行以下命令。第一条清理本安装的宿主登记和连接,第二条移除 npm 全局包。
55
+ [MCP 工具的实际参数和调用顺序](https://github.com/zhulinjia/jtcrpa-mcp-bridge/blob/main/docs/usage.md#书店示例的工具调用) · [连接或采集遇到问题](https://github.com/zhulinjia/jtcrpa-mcp-bridge/blob/main/docs/usage.md#排查连接问题) · [开发与发布](https://github.com/zhulinjia/jtcrpa-mcp-bridge/blob/main/docs/publishing.md#简体中文)
77
56
 
78
- ```powershell
79
- jtcrpa-mcp.cmd uninstall
80
- npm.cmd uninstall --global jtcrpa-mcp
81
- ```
82
-
83
- ### 开发和验证
84
-
85
- 在独立桥接器仓库的根目录运行以下命令。`npm test` 和 `npm pack` 都会编译 TypeScript,用户安装的是编译后的 JavaScript。与扩展的端到端验收方法见下方的「[维护者参考](#维护者参考)」。
57
+ ## English
86
58
 
87
- ```powershell
88
- npm.cmd ci
89
- npm.cmd run check
90
- npm.cmd test
91
- npm.cmd pack
92
- ```
59
+ `jtcrpa-mcp` connects an external AI client to **Jiutouchong Agent** in your browser. In this walkthrough, you’ll use Codex chat to collect the four titles and prices on a bookshop page, check the saved rows and run the same workflow on the next page. [Jiutouchong RPA website and extension downloads](https://jtcrpa.com/en) · [Jiutouchong Agent user manual](https://doc.jtcrpa.com/en/)
93
60
 
94
- ## English
61
+ ### First-time setup
95
62
 
96
- `jtcrpa-mcp` connects an MCP client to the Jiutouchong browser extension on your Windows computer. Use it to inspect tabs in a chosen browser profile, create and run workflows, check run logs, or read collected data.
63
+ 1. **Find MCP in the browser.** On Windows, add **Jiutouchong Agent** to Chrome or Firefox. Click its toolbar icon to open the sidebar, then choose **Settings ☰ → MCP connection** at the bottom. Look for the **Enable MCP connection** switch. [See the Settings menu](https://github.com/zhulinjia/jtcrpa-mcp-bridge/blob/main/docs/images/settings-menu-en.png) · [Extension installation guide](https://doc.jtcrpa.com/en/guide/install.html)
97
64
 
98
- ### Connect your first browser
65
+ If the menu entry is missing, check the extension build. Version `2.0.2` from both browser stores lacks MCP. If you only have the store release, contact Jiutouchong about an MCP-enabled build. [Contact Jiutouchong](https://jtcrpa.com/en/contact)
99
66
 
100
- 1. Use native Windows with Windows PowerShell 5.1, **Node.js 20.19.0 or later**, and the Jiutouchong extension installed in a Chrome or Firefox profile. For Codex, the `codex` command must also be available in your terminal. Install the bridge and check its version in PowerShell.
67
+ 2. **Install the bridge in PowerShell.** Open PowerShell from the Windows Start menu. You need Windows PowerShell 5.1 and Node.js 20.19.0 or later. Run these lines in order. The first prints your Node.js version and the last should print the bridge version. [Download Node.js](https://nodejs.org/en/download)
101
68
 
102
69
  ```powershell
103
- npm.cmd install --global jtcrpa-mcp
104
- jtcrpa-mcp.cmd --version
70
+ node --version
71
+ npm install -g jtcrpa-mcp
72
+ jtcrpa-mcp --version
105
73
  ```
106
74
 
107
- 2. In the browser profile you want to use, open the extension’s **Settings → MCP connection**. Copy the entire command under **Register this browser** and run it in PowerShell. The extension fills in its own ID. Chrome uses `add --chrome-id` and Firefox uses `add --firefox-id`. The first registration installs the native host for the current Windows user.
108
- 3. Turn on **Enable MCP connection** on that page and grant native messaging permission when prompted. Once the page shows **Browser connected to the local program**, choose your client under **Connect an AI app**.
109
-
110
- | Client | How to use the command or configuration from the extension |
111
- | --- | --- |
112
- | Codex | Run the full `codex mcp add` command in PowerShell. It saves a service named `jtcrpa`. Reconnect the MCP client or restart Codex. |
113
- | Claude Code | Run the generated `config` command in PowerShell. Merge the resulting `mcpServers.jtcrpa` entry into the project’s `.mcp.json`, restart Claude Code and check `/mcp`. |
114
- | DeepSeek Harness | Run the generated `config` command in PowerShell, add the resulting plugin entry to the Harness plugin list and restart the client. |
115
-
116
- 4. Ask your client **“Check the Jiutouchong MCP connection and list the tabs in the connected browser.”** Match the returned tabs to the ones open in your target profile. Codex has been tested end to end with both Chrome and Firefox. Configuration generation is available for Claude Code and DeepSeek Harness. An equivalent end-to-end test for these two clients is pending.
75
+ 3. **Connect this browser.** On the extension’s **MCP connection** page, copy the command under **Register this browser**. Paste it into PowerShell and press Enter. It already contains your extension’s ID. Back in the extension, turn on **Enable MCP connection** and allow native messaging if prompted. Continue when you see **Browser connected to the local program**.
76
+ 4. **Connect Codex.** On the same page, under **Connect an AI app → Codex**, click **Copy Codex setup command** and run it in PowerShell. Run `codex mcp list` and look for `jtcrpa`. Open a new Codex session for the three messages below. If the Codex CLI is installed and you’re signed in, type `codex` in PowerShell to start it. [Install the Codex CLI](https://developers.openai.com/codex/cli/) · [Use Claude Code or DeepSeek Harness](https://github.com/zhulinjia/jtcrpa-mcp-bridge/blob/main/docs/usage.md#client-configuration)
117
77
 
118
- Setup is normally a one-time operation. Leave MCP enabled in the target profile. The browser starts the native host on demand when you open that profile.
78
+ ### Collect your first four books
119
79
 
120
- ### Work with workflows and datasets
80
+ **① Open the page and check the connection.** Open the bookshop homepage in the browser you just connected. If it appears in Chinese, click **English** in the page header. Send this first message in **Codex chat**. [Open the bookshop playground](https://doc.jtcrpa.com/en/practice/index.html)
121
81
 
122
- | Task | MCP tools | Example request |
123
- | --- | --- | --- |
124
- | Check the connection and inspect a page | `connection_status`, `connection_ping`, `browser_context`, `page_probe` | “List the tabs and check which fields can be extracted from the selected product listing.” |
125
- | Find or create a workflow | `workflow_list`, `workflow_get`, `workflow_contract`, `workflow_save` | “Save a workflow that collects product names and prices from this page.” |
126
- | Run a workflow and check the result | `workflow_run`, `run_get`, `run_control` | “Run that saved workflow on this listing and show its status and recent logs.” |
127
- | Read collected data | `dataset_list`, `dataset_read` | “Find the product dataset and show the first 20 rows with just names and prices.” |
82
+ > Use Jiutouchong MCP to check the connection and find my open bookshop playground tab. Tell me the page title and read the first book’s title and price from the page.
128
83
 
129
- After saving a new or edited workflow, the client should wait for your confirmation before running it. Starting a workflow returns a `runId`. Use `run_get` to check whether it finished. If a write times out, query `connection_status` with the original request UUID and check recent runs before retrying. An action already in progress can finish after a pause. Stopping a run does not undo actions it has already taken.
84
+ You should see *Between Mountains and Seas* at ¥32.00. If the result is from a different page, check which browser profile has the bookshop open.
130
85
 
131
- For `dataset_read`, supply exactly one of `datasetId` and `datasetName`. Pages start at 1, with 50 rows by default and a maximum of 200. Use `fields` to select columns. Pages reflect live data if collection is still running. If a result exceeds 256 KiB, request fewer rows or columns.
86
+ **② Save a reusable workflow.** Send this in the same chat.
132
87
 
133
- ### Manage multiple browser profiles
88
+ > Collect one row per book on the current listing page. Name the columns title and price and keep the currency symbol. Preview the extraction on the page, then save a workflow named “Bookshop demo” that writes to the bookshop_demo dataset when run. Give me the saved workflow ID and wait for my confirmation.
134
89
 
135
- The setup command from the extension binds the client to the instance UUID of that browser profile. Give each instance its own MCP service name when connecting several profiles. To manage connections by their registration number, run the following in PowerShell.
90
+ You should receive a `workflowId`. To find the saved rule in the extension, open **Workbench** and search for `Bookshop demo`.
136
91
 
137
- ```powershell
138
- jtcrpa-mcp.cmd list
139
- jtcrpa-mcp.cmd list --json
140
- ```
92
+ **③ Run it and check the saved rows.** Once the client reports that it saved the workflow, send a separate message.
141
93
 
142
- If the list shows `待选择实例` (select an instance), enable MCP in the intended profile and run the `add ... --instance ...` command shown in the list. Profiles with the same extension ID can be selected separately. After selecting a target, substitute its connection number for `c1` in this example.
94
+ > Yes, run Bookshop demo on the bookshop homepage now. Wait for it to finish, tell me how many rows this run saved, then read title and price from bookshop_demo and show them as a table.
143
95
 
144
- ```powershell
145
- jtcrpa-mcp.cmd config --connection c1 --client codex
146
- ```
96
+ On the first run with an empty dataset, expect **four rows**. You can also open **Storage** in the extension, find `bookshop_demo` and click **Preview** to see the same records.
147
97
 
148
- The supported client identifiers are `codex`, `claude` and `deepseek`. Omit `--client` to print all three configurations. The generated startup arguments contain the registration’s binding UUID. To switch to a different extension ID or selected instance, add the new connection, update the client, then run `jtcrpa-mcp.cmd remove` to select and confirm the old registration. In scripts, `jtcrpa-mcp.cmd remove c1` removes the specified entry directly. The old client configuration returns `CONNECTION_REMOVED` even if its display number is later reused.
149
-
150
- ### Troubleshooting
151
-
152
- | Symptom | What to do |
98
+ | title | price |
153
99
  | --- | --- |
154
- | PowerShell reports that scripts are disabled, or cannot find the command | Use `npm.cmd` and `jtcrpa-mcp.cmd` as shown above. Check the Windows global command directory with `npm.cmd prefix --global` and ensure it is on the current terminal’s `PATH`. |
155
- | An npm mirror cannot find a newly published version | Install from the public registry with `npm.cmd install --global jtcrpa-mcp --registry=https://registry.npmjs.org`. |
156
- | `Access to the specified native messaging host is forbidden` | Copy the registration command from the current extension, check its complete ID against `list`, run the command and turn MCP on again. Register the new ID if a development build’s extension ID has changed. |
157
- | The native messaging interface is unavailable, or the browser requests permission | Reload Jiutouchong from the browser’s extensions page, enable the connection again and allow native messaging when prompted. |
158
- | `BROWSER_OFFLINE` or tabs from the wrong browser | Open the target profile, enable MCP and compare its instance UUID with the client configuration. If a copied profile produces an instance conflict, use the extension’s option to generate a new instance ID and update that client. |
159
- | `CONNECTION_INSTANCE_NOT_SELECTED` or `CONNECTION_REMOVED` | For the first error, select a target using the instruction from `list`. For the second, generate a fresh client configuration from an existing registration. |
160
-
161
- ### Upgrade or uninstall
162
-
163
- For an in-place upgrade, turn MCP off, run `npm.cmd install --global jtcrpa-mcp@latest` and reconnect. If Node.js or the npm global directory moves, rerun the registration command from the extension. Regenerate client configurations that refer to the previous absolute paths.
164
-
165
- To uninstall, first disable MCP in all connected browser profiles. The first command below removes this installation’s native host registrations and connections. The second removes the global npm package.
166
-
167
- ```powershell
168
- jtcrpa-mcp.cmd uninstall
169
- npm.cmd uninstall --global jtcrpa-mcp
170
- ```
171
-
172
- ### Development and verification
173
-
174
- Run these commands in the root of the standalone bridge repository. Both `npm test` and `npm pack` compile TypeScript. The npm package ships the compiled JavaScript. For extension integration tests, see the [maintainer reference](#maintainer-reference).
175
-
176
- ```powershell
177
- npm.cmd ci
178
- npm.cmd run check
179
- npm.cmd test
180
- npm.cmd pack
181
- ```
182
-
183
- ## 维护者参考
184
-
185
- - `bin/cli.mjs` 按命令加载 `dist/`。`src/mcp.ts` 装配 `src/tools/` 的连接、编排、执行和数据工具,后者由 `forwarded.ts` 转发到扩展。工具说明为中文,工具名、参数名和状态标识在两种语言中一致。
186
- - 浏览器通过 Native Messaging 启动宿主。MCP 客户端启动单独的 stdio 进程,两者通过当前 Windows 用户的命名管道和每次会话的令牌通信。默认登记目录是 `%LOCALAPPDATA%\Jtcrpa\McpBridge`。`src/install.ts`、`src/connections.ts` 和 `src/registration-lock.ts` 负责登记、绑定和并发更新。浏览器关闭后仍可发现 MCP 工具,并可查询离线状态。
187
- - 原生消息帧最大为 512 KiB,单次业务结果最大为 256 KiB。`page_probe` 支持页面快照、子帧查询、元素/提取探测、点击和滚动。`run_get` 最多列 20 次运行,每次最多读取 50 条日志,默认 10 条。`dataset_list` 默认每页 20 项,最多 50 项。
188
- - 写请求用 UUID 标识。遇到 `OUTCOME_UNKNOWN` 时先查询原请求。扩展最多保留 1,024 条写请求凭据,共 2 MiB。`MCP` 连接断开后,正在运行的工作流由扩展继续管理。
189
- - 扩展仓库与此仓库并列检出时,可在扩展仓库根目录运行下面的命令,对实际分发包进行隔离安装和真实浏览器验收。本例使用 0.4.1。正式发包使用已验收的同一份 `.tgz`。
190
-
191
- ```powershell
192
- node tests/mcp-package/run.mjs ../jtcrpa-mcp-bridge/jtcrpa-mcp-0.4.1.tgz --install-only
193
- node tests/mcp-package/run.mjs ../jtcrpa-mcp-bridge/jtcrpa-mcp-0.4.1.tgz --isolated-host
194
- ```
195
-
196
- ## Maintainer reference
100
+ | Between Mountains and Seas | ¥32.00 |
101
+ | City Strolls | ¥45.00 |
102
+ | Room to Breathe | ¥39.00 |
103
+ | Moonlight on the Page | ¥28.50 |
197
104
 
198
- - `bin/cli.mjs` loads commands from `dist/`. `src/mcp.ts` assembles the connection, authoring, execution and dataset tools in `src/tools/`. `forwarded.ts` relays tool calls to the extension. Tool descriptions are in Chinese. Tool names, argument names and status identifiers are shared by both guides.
199
- - The browser starts the native host through Native Messaging. The MCP client starts a separate stdio process. They communicate through a Windows named pipe restricted to the current user, with a token for each session. Registrations default to `%LOCALAPPDATA%\Jtcrpa\McpBridge`. `src/install.ts`, `src/connections.ts` and `src/registration-lock.ts` manage registrations, bindings and concurrent updates. Tool discovery and offline status queries work while the browser is closed.
200
- - Native frames are limited to 512 KiB, and individual tool results to 256 KiB. `page_probe` supports snapshots, frame queries, element and extraction probes, clicks and scrolling. `run_get` lists at most 20 runs and reads up to 50 log entries, with 10 entries by default. `dataset_list` defaults to 20 items per page and allows up to 50.
201
- - Writes carry a request UUID. Query the original request after `OUTCOME_UNKNOWN`. The extension keeps up to 1,024 write-request records totalling 2 MiB. The extension continues to manage active workflows if the MCP connection drops.
202
- - With the extension and bridge repositories checked out side by side, run the following from the extension repository to test the actual archive in an isolated installation and in real browsers. The example uses version 0.4.1. Publish the same `.tgz` that passed acceptance.
105
+ **Use it again.** Click **Next** in the bookshop, then ask, “Find my saved Bookshop demo workflow, run it on page 2 of the bookshop and tell me how many rows this run saved.” Expect four more rows, including *Little Maps for the Journey* at ¥48.00. For future sessions, open the same browser profile with MCP enabled. The browser and client start the bridge as needed.
203
106
 
204
- ```powershell
205
- node tests/mcp-package/run.mjs ../jtcrpa-mcp-bridge/jtcrpa-mcp-0.4.1.tgz --install-only
206
- node tests/mcp-package/run.mjs ../jtcrpa-mcp-bridge/jtcrpa-mcp-0.4.1.tgz --isolated-host
207
- ```
107
+ [MCP tool calls and their arguments](https://github.com/zhulinjia/jtcrpa-mcp-bridge/blob/main/docs/usage.md#tool-calls-for-the-bookshop-example) · [Connection and collection troubleshooting](https://github.com/zhulinjia/jtcrpa-mcp-bridge/blob/main/docs/usage.md#troubleshooting) · [Development and publishing](https://github.com/zhulinjia/jtcrpa-mcp-bridge/blob/main/docs/publishing.md#english)
package/package.json CHANGED
@@ -1,8 +1,9 @@
1
1
  {
2
2
  "name": "jtcrpa-mcp",
3
- "version": "0.4.1",
3
+ "version": "0.4.2",
4
4
  "type": "module",
5
- "description": "Windows Native Messaging bridge for Jiutouchong / 九头虫浏览器扩展的 Windows MCP 桥接器",
5
+ "description": "在 Windows 上用 Codex 等 AI 客户端连接九头虫 Agent,创建和运行网页采集工作流、读取数据集。Connect AI clients to Jiutouchong Agent on Windows via MCP to create and run web scraping workflows and read datasets.",
6
+ "homepage": "https://jtcrpa.com/",
6
7
  "repository": {
7
8
  "type": "git",
8
9
  "url": "git+https://github.com/zhulinjia/jtcrpa-mcp-bridge.git"