serpkin 0.2.0 → 0.2.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 (5) hide show
  1. package/README.md +47 -5
  2. package/lib/agents.mjs +1 -1
  3. package/package.json +3 -3
  4. package/plugin/serpkin/.claude-plugin/plugin.json +2 -2
  5. package/templates/github-action.yml +1 -1
package/README.md CHANGED
@@ -1,12 +1,34 @@
1
1
  # serpkin
2
2
 
3
- The SEO teammate for your coding agent. One command connects your repository, your agent and Serpkin.
3
+ **The SEO teammate for Claude Code, Codex and Cursor.** Serpkin reads your site and your real search data, picks the one SEO fix worth doing next, and hands it to your coding agent with the files to change. After you ship, it checks the preview and measures whether the change helped.
4
4
 
5
5
  ```sh
6
6
  npx serpkin
7
7
  ```
8
8
 
9
- Requires Node 22 or newer. No dependencies.
9
+ [Website](https://serpkin.com) · [Guides](https://serpkin.com/guides) · [Free SEO checker](https://serpkin.com/tools/seo-check) · [Claude Code](https://serpkin.com/integrations/claude-code) · [Cursor](https://serpkin.com/integrations/cursor) · [Codex](https://serpkin.com/integrations/codex)
10
+
11
+ ## Quick start
12
+
13
+ 1. In your website's repository, run `npx serpkin`. It signs you in, connects your agent and registers the site (about a minute).
14
+ 2. Ask your agent: _"What should I do for SEO?"_
15
+ 3. Your agent implements the mission. Before you merge, run `npx serpkin check <preview-url>` to catch SEO regressions.
16
+
17
+ Requires Node 22 or newer. No dependencies. There is a free plan (one site); see [pricing](https://serpkin.com/#pricing).
18
+
19
+ ## What you get
20
+
21
+ - **One mission at a time**, chosen from a crawl of your site and, once connected, your Google Search Console data. Not a list of 200 warnings.
22
+ - **Patch-ready instructions**: the files to edit (from your route map), code snippets for metadata, sitemaps, redirects and structured data, and a definition of done.
23
+ - **A preview check** that fails on regressions such as a new `noindex`, a removed title or canonical, or a broken sitemap.
24
+ - **Results**: Serpkin verifies the fix on production and reports what changed in search afterwards.
25
+
26
+ | Agent | How it connects |
27
+ | ----------- | -------------------------------------------------------------------- |
28
+ | Claude Code | Plugin with a skill, slash commands and hooks, or a plain MCP server |
29
+ | Cursor | `.cursor/mcp.json` plus a project rule |
30
+ | Codex | `~/.codex/config.toml` plus a section in `AGENTS.md` |
31
+ | Others | Any MCP client: `https://serpkin.com/api/mcp` with your agent key |
10
32
 
11
33
  ## What `npx serpkin` does
12
34
 
@@ -26,10 +48,10 @@ Then ask your agent: _"What should I do for SEO?"_
26
48
  ## Claude Code plugin
27
49
 
28
50
  ```sh
29
- claude plugin marketplace add apwn/serpkin-plugin && claude plugin install serpkin@serpkin
51
+ claude plugin marketplace add apwn/serpkin && claude plugin install serpkin@serpkin
30
52
  ```
31
53
 
32
- Inside a session you can run `/plugin marketplace add apwn/serpkin-plugin`, then `/plugin install serpkin@serpkin`. The plugin lives in [`plugin/serpkin`](plugin/serpkin) and includes:
54
+ Inside a session you can run `/plugin marketplace add apwn/serpkin`, then `/plugin install serpkin@serpkin`. The plugin lives in [`plugins/serpkin`](https://github.com/apwn/serpkin/tree/main/plugins/serpkin) and includes:
33
55
 
34
56
  - the **`serpkin-seo` skill**, which runs the loop: next mission → implement → run checks → check the preview → submit → verify the preview → verify production after you deploy. It treats page text and search data as untrusted and never deploys.
35
57
  - **commands**: `/serpkin:next` gets the next mission and implements it. `/serpkin:ship <preview-url>` submits it, checks the preview and verifies. `/serpkin:check <preview-url>` runs `npx serpkin check`. `/serpkin:status` shows the site status.
@@ -94,4 +116,24 @@ Preview hosts must be the site's own domain or subdomains, or `*.vercel.app`, `*
94
116
 
95
117
  ### GitHub Action
96
118
 
97
- Copy [`templates/github-action.yml`](templates/github-action.yml) to `.github/workflows/serpkin.yml` then add a repository secret `SERPKIN_API_KEY` (create a key with `npx serpkin` or in Settings → Agent setup) and a repository variable `SERPKIN_SITE_ID` (the `site_id` from `.serpkin.json`). The workflow doesn't check out the pull request, so code or config from a PR never runs while the key is available, and it pins the CLI version. It runs on `deployment_status` events, which Vercel sends when a preview finishes deploying. It checks the deployment's `target_url` and fails the job when the preview introduces a regression. If your previews use Vercel Deployment Protection, Serpkin's requests get HTTP 401. Allow them through, or the check reports the preview as unreachable.
119
+ The GitHub Action template ships in the package at `templates/github-action.yml` (`node_modules/serpkin/templates/github-action.yml`). Copy it to `.github/workflows/serpkin.yml`, then add a repository secret `SERPKIN_API_KEY` (create a key with `npx serpkin` or in Settings → Agent setup) and a repository variable `SERPKIN_SITE_ID` (the `site_id` from `.serpkin.json`). The workflow doesn't check out the pull request, so code or config from a PR never runs while the key is available, and it pins the CLI version. It runs on `deployment_status` events, which Vercel sends when a preview finishes deploying. It checks the deployment's `target_url` and fails the job when the preview introduces a regression. If your previews use Vercel Deployment Protection, Serpkin's requests get HTTP 401. Allow them through, or the check reports the preview as unreachable.
120
+
121
+ ## What leaves your machine
122
+
123
+ - **Sent to Serpkin:** your site URL, the answers you give during setup (the site description defaults to the one in `package.json`), the route map (URL paths and the source file names that serve them, up to 2,000 routes), and your computer's hostname at sign-in, used to name your agent key. Your agent sends what it asks Serpkin for through MCP.
124
+ - **Never sent:** your source code, environment files or the contents of your repository. To detect the framework and build the route map, the CLI reads `package.json` and the file names in your routes folder, not their contents. It also updates your agent's config files (`.mcp.json`, `.cursor/`, `AGENTS.md`, `~/.codex/config.toml`) as described above.
125
+ - **Stored locally:** your agent key in `~/.config/serpkin/credentials.json` (mode 600), never in the repository.
126
+
127
+ Details: [privacy policy](https://serpkin.com/legal/privacy).
128
+
129
+ ## Troubleshooting
130
+
131
+ - **Serpkin can't reach your site**: Serpkin needs a public URL. Use a preview deploy with `--url`, not `localhost`.
132
+ - **Preview check returns 401**: your preview is behind deployment protection. Allow Serpkin's requests or check a public preview.
133
+ - **The agent doesn't see Serpkin**: make sure `SERPKIN_API_KEY` is exported in the shell your agent starts from, then restart the agent.
134
+ - **Start over**: re-run `npx serpkin`. It reuses the stored key and site and refreshes only its own blocks.
135
+
136
+ ## Support and license
137
+
138
+ Questions or bugs: [serpkin.com](https://serpkin.com) or the [plugin repository](https://github.com/apwn/serpkin/issues). MIT licensed (this CLI and the Claude Code plugin).
139
+
package/lib/agents.mjs CHANGED
@@ -149,7 +149,7 @@ export const PLUGIN_ID = "serpkin@serpkin";
149
149
  * name lives: the --help text and every printed install command read it from here. The repository
150
150
  * is generated by cli/scripts/export-plugin-repo.mjs. Override for forks or local testing.
151
151
  */
152
- export const PLUGIN_MARKETPLACE_REPO = "apwn/serpkin-plugin";
152
+ export const PLUGIN_MARKETPLACE_REPO = "apwn/serpkin";
153
153
  export const pluginMarketplace = (env = process.env) =>
154
154
  env.SERPKIN_PLUGIN_MARKETPLACE || PLUGIN_MARKETPLACE_REPO;
155
155
  export const pluginInstallCommand = (env = process.env) =>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "serpkin",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "description": "Connect your coding agent to Serpkin: sign in, register your site, upload its route map, and check pull-request previews for SEO regressions.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -35,12 +35,12 @@
35
35
  ],
36
36
  "homepage": "https://serpkin.com",
37
37
  "bugs": {
38
- "url": "https://github.com/apwn/serpkin-plugin/issues",
38
+ "url": "https://github.com/apwn/serpkin/issues",
39
39
  "email": "support@serpkin.com"
40
40
  },
41
41
  "repository": {
42
42
  "type": "git",
43
- "url": "git+https://github.com/apwn/serpkin-plugin.git"
43
+ "url": "git+https://github.com/apwn/serpkin.git"
44
44
  },
45
45
  "author": "Serpkin (https://serpkin.com)",
46
46
  "license": "MIT",
package/plugin/serpkin/.claude-plugin/plugin.json CHANGED
@@ -1,14 +1,14 @@
1
1
  {
2
2
  "name": "serpkin",
3
3
  "displayName": "Serpkin",
4
- "version": "0.2.0",
4
+ "version": "0.2.2",
5
5
  "description": "The SEO brain for your coding agent: ranked SEO missions with patch-ready plans, preview checks and verification.",
6
6
  "author": {
7
7
  "name": "Serpkin",
8
8
  "url": "https://serpkin.com"
9
9
  },
10
10
  "homepage": "https://serpkin.com",
11
- "repository": "https://github.com/apwn/serpkin-plugin",
11
+ "repository": "https://github.com/apwn/serpkin",
12
12
  "license": "MIT",
13
13
  "keywords": ["seo", "nextjs", "mcp", "search-console"]
14
14
  }
package/templates/github-action.yml CHANGED
@@ -36,4 +36,4 @@ jobs:
36
36
  # Passed through env, not interpolated into the script, so the URL can't inject shell.
37
37
  PREVIEW_URL: ${{ github.event.deployment_status.target_url }}
38
38
  # Pinned version and registry; update the version deliberately.
39
- run: npx --yes --registry=https://registry.npmjs.org serpkin@0.2.0 check "$PREVIEW_URL" --site "$SERPKIN_SITE_ID"
39
+ run: npx --yes --registry=https://registry.npmjs.org serpkin@0.2.2 check "$PREVIEW_URL" --site "$SERPKIN_SITE_ID"