@mrscraper/opencode 0.1.0 → 0.3.0

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.
package/CHANGELOG.md CHANGED
@@ -3,6 +3,28 @@
3
3
  All notable changes to the MrScraper OpenCode plugin are documented here. The
4
4
  project follows [Semantic Versioning](https://semver.org/).
5
5
 
6
+ ## 0.3.0 - 2026-10-14
7
+
8
+ - Updated the skills for the hosted MCP server's new tools: `scraperAPI`
9
+ (pages as HTML, Markdown, or screenshots), `webSearch` (Google), and `status`
10
+ (account usage). The `fetch`, `scrape`, `serp`, `rerun`, `results`, and
11
+ `result` tools no longer exist.
12
+ - Removed the `mrscraper-scrape` skill. Skills are identical to the MrScraper
13
+ Claude plugin 0.2.0.
14
+
15
+ ## 0.2.0 - 2026-10-12
16
+
17
+ - Added OpenCode 2 support. OpenCode 2 does not run OpenCode 1 plugins; the
18
+ package now default-exports one object with an OpenCode 2 `setup()`, which
19
+ registers the `mrscraper` MCP server and the four skills through MCP and
20
+ skill transforms, and an OpenCode 1 `server()`, which keeps the existing
21
+ config hook.
22
+ - OpenCode 1 now needs 1.18.29 or later (the first release that loads the
23
+ object form). On older releases, pin `@mrscraper/opencode@0.1.0`.
24
+ - The `MrScraperPlugin` named export was removed; use the default export.
25
+ - Documented OpenCode 2 install, sign-in, API-key configuration
26
+ (`mcp.servers`), and update commands.
27
+
6
28
  ## 0.1.0 - 2026-10-05
7
29
 
8
30
  - Added the initial `@mrscraper/opencode` plugin: registers the hosted
package/README.md CHANGED
@@ -1,10 +1,11 @@
1
1
  # MrScraper for OpenCode
2
2
 
3
3
  MrScraper connects [OpenCode](https://opencode.ai) to a hosted MCP server for
4
- fetching public web pages, managed structured extraction, Google discovery,
5
- saved scraper reruns, stored results, and account usage. The plugin also
6
- includes four focused skills that help OpenCode choose the right workflow and
7
- preserve raw page content.
4
+ retrieving public web pages as HTML, Markdown, or screenshots, Google
5
+ discovery, and account usage. The plugin also includes three focused skills
6
+ that help OpenCode choose the right workflow and preserve raw page content.
7
+
8
+ The same package works in OpenCode 2 and OpenCode 1.
8
9
 
9
10
  ## What this plugin adds
10
11
 
@@ -12,22 +13,42 @@ preserve raw page content.
12
13
  endpoint `https://mcp.mrscraper.com/mcp`.
13
14
  - OAuth 2.1 sign-in handled by OpenCode; no credential is stored in this
14
15
  package.
15
- - The `mrscraper`, `mrscraper-fetch`, `mrscraper-scrape`, and `mrscraper-serp`
16
- skills, loaded on demand through OpenCode's `skill` tool.
17
- - A fetch-first workflow that keeps raw page responses available for analysis,
18
- verification, and follow-up transformations.
16
+ - The `mrscraper`, `mrscraper-fetch`, and `mrscraper-serp` skills.
17
+ - A retrieve-first workflow that keeps raw page responses available for
18
+ analysis, verification, and follow-up transformations.
19
19
 
20
- If your configuration already defines `mcp.mrscraper`, the plugin keeps your
21
- entry and only adds the skills.
20
+ If your configuration already defines a `mrscraper` MCP server, the plugin
21
+ keeps your entry and only adds the skills. It also leaves any skill with the
22
+ same name that you already have in place.
22
23
 
23
24
  ## Requirements
24
25
 
25
- - [OpenCode](https://opencode.ai/docs/) (verified with 1.18.34).
26
+ - OpenCode 2 (verified with 2.0.26), or OpenCode 1.18.29 or later (verified
27
+ with 1.18.29 and 1.19.0). On older OpenCode 1 releases, pin
28
+ `@mrscraper/opencode@0.1.0`.
26
29
  - A [MrScraper](https://app.mrscraper.com) account.
27
30
  - Permission to access and process the target content.
28
31
 
29
32
  ## Install
30
33
 
34
+ ### OpenCode 2
35
+
36
+ ```bash
37
+ opencode plugin add @mrscraper/opencode
38
+ ```
39
+
40
+ This adds the package to `plugins` in your global configuration. To enable it
41
+ for one project instead, add it to that project's `opencode.jsonc`:
42
+
43
+ ```jsonc
44
+ {
45
+ "$schema": "https://opencode.ai/config.json",
46
+ "plugins": ["@mrscraper/opencode"]
47
+ }
48
+ ```
49
+
50
+ ### OpenCode 1
51
+
31
52
  ```bash
32
53
  opencode plugin @mrscraper/opencode --global
33
54
  ```
@@ -42,8 +63,7 @@ Or add the package to the `plugin` list in `~/.config/opencode/opencode.json`
42
63
  }
43
64
  ```
44
65
 
45
- OpenCode installs npm plugins when it starts and caches them under
46
- `~/.cache/opencode/packages/`.
66
+ OpenCode installs npm plugins when it starts and caches them.
47
67
 
48
68
  ## Sign in
49
69
 
@@ -51,16 +71,10 @@ OpenCode installs npm plugins when it starts and caches them under
51
71
  opencode mcp auth mrscraper
52
72
  ```
53
73
 
54
- OpenCode opens the MrScraper consent page and waits up to five minutes for the
55
- browser to return to `http://127.0.0.1:19876/mcp/oauth/callback`. It requests
56
- the `scrape:read`, `scrape:write`, and `account:read` scopes advertised by the
57
- server, plus `offline_access` for token refresh, and stores the tokens in
58
- `~/.local/share/opencode/mcp-auth.json`. Never paste OAuth tokens or API keys
59
- into chat.
60
-
61
- On a remote machine, open the printed URL in a local browser after forwarding
62
- the callback port, for example `ssh -L 19876:127.0.0.1:19876 <host>`, or use
63
- an API key instead.
74
+ In OpenCode 2 you can also run `/mcps` in a session, select `mrscraper`, and
75
+ sign in there. OpenCode opens the MrScraper consent page in your browser,
76
+ registers its own OAuth client, and stores the tokens outside your project
77
+ configuration. Never paste OAuth tokens or API keys into chat.
64
78
 
65
79
  Check the connection:
66
80
 
@@ -71,11 +85,37 @@ opencode mcp list
71
85
  `mrscraper` shows `needs authentication` before sign-in and `connected`
72
86
  afterwards.
73
87
 
88
+ On a machine without a local browser, use an API key instead (next section).
89
+ OpenCode 1 waits for the browser on `http://127.0.0.1:19876/mcp/oauth/callback`,
90
+ so you can also forward that port, for example
91
+ `ssh -L 19876:127.0.0.1:19876 <host>`.
92
+
74
93
  ## Use an API key instead of OAuth
75
94
 
76
95
  Create a key at [app.mrscraper.com/api-tokens](https://app.mrscraper.com/api-tokens),
77
96
  export it as `MRSCRAPER_API_KEY` in the environment that starts OpenCode, and
78
- define the server yourself:
97
+ define the server yourself.
98
+
99
+ OpenCode 2 (`opencode.jsonc`):
100
+
101
+ ```jsonc
102
+ {
103
+ "$schema": "https://opencode.ai/config.json",
104
+ "plugins": ["@mrscraper/opencode"],
105
+ "mcp": {
106
+ "servers": {
107
+ "mrscraper": {
108
+ "type": "remote",
109
+ "url": "https://mcp.mrscraper.com/mcp",
110
+ "oauth": false,
111
+ "headers": { "Authorization": "Bearer {env:MRSCRAPER_API_KEY}" }
112
+ }
113
+ }
114
+ }
115
+ }
116
+ ```
117
+
118
+ OpenCode 1 (`opencode.json`):
79
119
 
80
120
  ```json
81
121
  {
@@ -95,8 +135,10 @@ define the server yourself:
95
135
  ```
96
136
 
97
137
  OpenCode substitutes `{env:MRSCRAPER_API_KEY}` when it loads the configuration,
98
- so the key stays out of the file. An API key carries your full account
99
- authority; OAuth scopes do not apply to it.
138
+ so the key stays out of the file. In OpenCode 2 the substitution happens in the
139
+ background service, so the variable must be set where the service starts; after
140
+ setting it, run `opencode service restart` from that shell. An API key carries
141
+ your full account authority; OAuth scopes do not apply to it.
100
142
 
101
143
  ## Try it
102
144
 
@@ -104,44 +146,33 @@ authority; OAuth scopes do not apply to it.
104
146
  Fetch https://www.scrapethissite.com/pages/simple/ and summarize the page.
105
147
  ```
106
148
 
107
- OpenCode prefixes MCP tools with the server name:
149
+ The server provides these tools. OpenCode 1 shows them as `mrscraper_<tool>`;
150
+ OpenCode 2 reaches MCP tools through Code Mode by default.
108
151
 
109
152
  | Tool | Purpose |
110
153
  | --- | --- |
111
- | `mrscraper_fetch` | Retrieve and preserve a known page's raw response. |
112
- | `mrscraper_scrape` | Run managed structured extraction or bounded site mapping. |
113
- | `mrscraper_serp` | Discover public pages through Google. |
114
- | `mrscraper_rerun` | Reuse a saved AI or manual scraper configuration. |
115
- | `mrscraper_results` | Browse and filter stored result records. |
116
- | `mrscraper_result` | Retrieve one stored result or poll an asynchronous run. |
117
- | `mrscraper_status` | Inspect subscription usage and request outcomes. |
118
-
119
- To keep the tools out of every session, add `"tools": { "mrscraper_*": false }`
120
- to your configuration and enable them per agent; see
121
- [MCP servers](https://opencode.ai/docs/mcp-servers/#manage).
122
-
123
- ## Fetch-first routing
124
-
125
- When a public URL is already known, the skills direct OpenCode to fetch it
126
- first and treat the raw response as the source of truth. The agent can read,
127
- summarize, compare, or derive structured output locally without losing details
128
- to an early extraction prompt.
129
-
130
- For roughly 100 known pages with a shared layout, the agent can fetch pages
131
- concurrently, retain every raw response, and apply one reusable local extractor
132
- instead of requesting 100 separate backend-LLM extractions. Use `scrape` when
133
- managed extraction is explicitly requested or has a clear benefit after the page
134
- structure and desired schema are understood.
154
+ | `scraperAPI` | Retrieve a known page as HTML, Markdown, a screenshot, or a combination. |
155
+ | `webSearch` | Discover public pages through Google. |
156
+ | `status` | Inspect subscription status, token usage, and remaining tokens. |
157
+
158
+ ## Retrieve-first routing
159
+
160
+ When a public URL is already known, the skills direct OpenCode to retrieve it
161
+ with `scraperAPI` first and treat the raw response as the source of truth. The
162
+ agent can read, summarize, compare, or derive structured output locally without
163
+ losing details.
164
+
165
+ For roughly 100 known pages with a shared layout, the agent can retrieve pages
166
+ concurrently, retain every raw response, and apply one reusable local
167
+ extractor.
135
168
 
136
169
  ## Data and permissions
137
170
 
138
- The plugin sends MCP tool inputs, including target URLs and extraction
139
- instructions, to MrScraper's hosted service. Page responses and tool results are
140
- then available to OpenCode and its model provider for the requested task.
141
- Managed general and listing extraction sends page content and the extraction
142
- prompt to a backend language model and saves a reusable scraper configuration;
143
- reruns create new stored results. Use it only with public or otherwise
144
- authorized content, and follow the target site's requirements.
171
+ The plugin sends MCP tool inputs, including target URLs and search queries, to
172
+ MrScraper's hosted service. Page responses and tool results are then available
173
+ to OpenCode and its model provider for the requested task. Use it only with
174
+ public or otherwise authorized content, and follow the target site's
175
+ requirements.
145
176
 
146
177
  Review MrScraper's [MCP documentation](https://docs.mrscraper.com/docs/getting-started/mcp-server),
147
178
  [Privacy Policy](https://mrscraper.com/privacy-policy),
@@ -150,17 +181,25 @@ Review MrScraper's [MCP documentation](https://docs.mrscraper.com/docs/getting-s
150
181
 
151
182
  ## Update or remove
152
183
 
153
- An unpinned entry stays on the version OpenCode first cached. To control
154
- updates, pin a version and change it when you upgrade:
184
+ OpenCode 2 checks unpinned npm plugins for updates without installing them.
185
+ Update or remove the plugin with:
186
+
187
+ ```bash
188
+ opencode plugin update @mrscraper/opencode
189
+ opencode plugin remove @mrscraper/opencode
190
+ ```
191
+
192
+ In OpenCode 1, an unpinned entry stays on the version OpenCode first cached.
193
+ To control updates, pin a version and change it when you upgrade:
155
194
 
156
195
  ```json
157
196
  {
158
- "plugin": ["@mrscraper/opencode@0.1.0"]
197
+ "plugin": ["@mrscraper/opencode@0.3.0"]
159
198
  }
160
199
  ```
161
200
 
162
- To remove MrScraper, delete the entry from `plugin`, then remove the stored
163
- OAuth tokens:
201
+ To remove it from OpenCode 1, delete the entry from `plugin`. In either
202
+ version, remove the stored OAuth tokens afterwards:
164
203
 
165
204
  ```bash
166
205
  opencode mcp logout mrscraper
@@ -179,7 +218,8 @@ account.
179
218
  ## Development
180
219
 
181
220
  ```text
182
- index.ts registers the MCP server and the skills directory
221
+ index.ts default export with an OpenCode 2 `setup()` and an OpenCode 1
222
+ `server()`; both register the MCP server and the skills
183
223
  skills/ MCP-oriented skills, copied verbatim from
184
224
  mrscraper-com/mrscraper-claude-plugin (plugins/mrscraper/skills)
185
225
  ```
@@ -190,10 +230,12 @@ npm run check
190
230
  npm pack --dry-run
191
231
  ```
192
232
 
193
- Test a local checkout by adding its absolute path to `plugin` in an OpenCode
194
- configuration, then run `opencode mcp list` and `opencode debug skill`. Record
195
- user-visible changes in [CHANGELOG.md](CHANGELOG.md) and follow
196
- [PUBLISHING.md](PUBLISHING.md) for releases.
233
+ Test a local checkout in both majors before a release. In OpenCode 2, add the
234
+ checkout's absolute path to `plugins`, then run `opencode mcp list` and
235
+ `opencode api skill.list`. In OpenCode 1, add it to `plugin`, then run
236
+ `opencode mcp list` and `opencode debug skill`. Record user-visible changes in
237
+ [CHANGELOG.md](CHANGELOG.md) and follow [PUBLISHING.md](PUBLISHING.md) for
238
+ releases.
197
239
 
198
240
  ## License
199
241
 
package/index.ts CHANGED
@@ -1,19 +1,23 @@
1
- import type { Plugin } from "@opencode-ai/plugin"
1
+ import type { Plugin as OpenCode1Plugin } from "@opencode-ai/plugin"
2
+ import type { Plugin as OpenCode2, Skill } from "@opencode/plugin"
3
+ import { readdir, readFile } from "node:fs/promises"
2
4
  import { dirname, join } from "node:path"
3
5
  import { fileURLToPath } from "node:url"
4
6
 
7
+ const SERVER_NAME = "mrscraper"
5
8
  const MCP_URL = "https://mcp.mrscraper.com/mcp"
6
9
  const SKILLS_DIR = join(dirname(fileURLToPath(import.meta.url)), "skills")
7
10
 
8
- // OpenCode reads `skills.paths` (see https://opencode.ai/config.json), but the
11
+ // OpenCode 1 reads `skills.paths` (see https://opencode.ai/config.json), but the
9
12
  // plugin SDK's Config type does not declare it yet.
10
13
  type SkillsConfig = { skills?: { paths?: string[]; urls?: string[] } }
11
14
 
12
- export const MrScraperPlugin: Plugin = async () => ({
15
+ // OpenCode 1: add the server and the skills directory through the config hook.
16
+ const server: OpenCode1Plugin = async () => ({
13
17
  async config(input) {
14
18
  input.mcp ??= {}
15
19
  // Keep a user-defined entry, such as the API-key fallback or `enabled: false`.
16
- input.mcp.mrscraper ??= { type: "remote", url: MCP_URL }
20
+ input.mcp[SERVER_NAME] ??= { type: "remote", url: MCP_URL }
17
21
 
18
22
  const config = input as typeof input & SkillsConfig
19
23
  config.skills ??= {}
@@ -22,4 +26,68 @@ export const MrScraperPlugin: Plugin = async () => ({
22
26
  },
23
27
  })
24
28
 
25
- export default MrScraperPlugin
29
+ // OpenCode 2: register the same server and skills through domain transforms.
30
+ const definition = {
31
+ id: "mrscraper",
32
+ async setup(ctx) {
33
+ const skills = await readSkills()
34
+ await ctx.mcp.transform((editor) => {
35
+ // Keep a user-defined `mcp.servers.mrscraper`, such as the API-key fallback.
36
+ if (!editor.get(SERVER_NAME)) editor.set(SERVER_NAME, { type: "remote", url: MCP_URL })
37
+ })
38
+ await ctx.skill.transform((editor) => {
39
+ for (const skill of skills) if (!editor.get(skill.id)) editor.add(skill)
40
+ })
41
+ },
42
+ } satisfies OpenCode2.Plugin
43
+
44
+ // Mirrors OpenCode 2's own SKILL.md loading: the folder name is the ID, the
45
+ // frontmatter supplies `name` and `description`, and the body is the content.
46
+ async function readSkills(): Promise<Skill.Info[]> {
47
+ const skills: Skill.Info[] = []
48
+ const folders = await readdir(SKILLS_DIR, { withFileTypes: true }).catch(() => [])
49
+ for (const folder of folders) {
50
+ if (!folder.isDirectory()) continue
51
+ const path = join(SKILLS_DIR, folder.name, "SKILL.md")
52
+ const text = await readFile(path, "utf8").catch(() => undefined)
53
+ const markdown = text === undefined ? undefined : parseMarkdown(text)
54
+ if (!markdown) continue
55
+ const { name, description } = markdown.frontmatter
56
+ skills.push({
57
+ id: folder.name as Skill.Info["id"],
58
+ name: (name || folder.name) as Skill.Info["name"],
59
+ ...(description ? { description } : {}),
60
+ path: path as Skill.Info["path"],
61
+ content: markdown.content,
62
+ })
63
+ }
64
+ return skills
65
+ }
66
+
67
+ // Reads the flat frontmatter these skills use: plain or quoted scalars and
68
+ // `|` or `>` block scalars. Nested keys are ignored.
69
+ function parseMarkdown(text: string) {
70
+ const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/.exec(text)
71
+ if (!match) return undefined
72
+ const frontmatter: Record<string, string> = {}
73
+ const lines = match[1].split(/\r?\n/)
74
+ for (let i = 0; i < lines.length; i++) {
75
+ const field = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(lines[i])
76
+ if (!field) continue
77
+ const [, key, value] = field
78
+ if (!/^[|>][-+]?$/.test(value)) {
79
+ frontmatter[key] = value.replace(/^(["'])(.*)\1$/, "$2").trim()
80
+ continue
81
+ }
82
+ const block: string[] = []
83
+ while (i + 1 < lines.length && (lines[i + 1].trim() === "" || /^\s/.test(lines[i + 1]))) block.push(lines[++i])
84
+ const indent = Math.min(...block.filter((line) => line.trim()).map((line) => line.length - line.trimStart().length))
85
+ const literal = block.map((line) => line.slice(indent)).join("\n")
86
+ frontmatter[key] = (value.startsWith(">") ? literal.replace(/([^\n])\n(?=[^\n])/g, "$1 ") : literal).trim()
87
+ }
88
+ return { frontmatter, content: match[2] }
89
+ }
90
+
91
+ // One default export serves both majors: OpenCode 1 (1.18.29 or later) calls
92
+ // `server()`, and OpenCode 2 reads `id` and `setup()` and ignores `server()`.
93
+ export default { ...definition, server }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrscraper/opencode",
3
- "version": "0.1.0",
3
+ "version": "0.3.0",
4
4
  "description": "MrScraper for OpenCode: the hosted MrScraper MCP server plus fetch-first skills for web scraping, structured data extraction, and Google search.",
5
5
  "type": "module",
6
6
  "main": "index.ts",
@@ -42,7 +42,8 @@
42
42
  "check": "tsc --noEmit"
43
43
  },
44
44
  "devDependencies": {
45
- "@opencode-ai/plugin": "1.18.34",
45
+ "@opencode-ai/plugin": "1.19.0",
46
+ "@opencode/plugin": "2.0.26",
46
47
  "@types/node": "^22.20.5",
47
48
  "typescript": "^5.9.3"
48
49
  },