feat: package Websets as a self-contained Claude Code plugin

[glassBead-tc]

Summary

Convert this repo from a Docker-first HTTP MCP server (with a thin external channel) into a self-contained Claude Code plugin that bundles both the MCP server and a realtime channel as stdio subprocesses.

When the plugin is enabled, two MCP servers spawn as stdio subprocesses:

• websets — code-mode tools (search, execute, status), 110 ops across 12 domains, 12 background workflows, SQLite shadow store, and an in-process Express webhook receiver.
• websets-channel — declares claude/channel, subscribes to the local SSE stream, pushes notifications/claude/channel so Webset events show up in your session as <channel source="websets-channel">…</channel>.

Three Websets-specific skills install with the plugin and become invocable as /websets:deep-research-item, /websets:verify-item, /websets:workflow-config.

What changed

New plugin entrypoint

• src/stdio.ts — speaks MCP over stdio + starts the webhook listener in-process on WEBSETS_HTTP_PORT (default 7860). Logs to stderr; stdout reserved for the transport.

Refactor src/server.ts

• Extracted createMcpServer() and startWebhookListener() alongside the existing HTTP createServer(). Both transports share tool registration via buildMcpServer().

Channel polish (src/channel.ts)

• Removed hardcoded /workspaces/schwartz13/data/workflow-configs.json path — now uses ${CLAUDE_PLUGIN_DATA}/workflow-configs.json.
• Updated header docblock to describe the plugin spawn path.

Plugin scaffolding

• .claude-plugin/plugin.json — full manifest with mcpServers (websets + websets-channel), channels array, and userConfig prompts for EXA_API_KEY (sensitive/keychain), EXA_WEBHOOK_SECRET (sensitive), port, db path, compat mode.
• .claude-plugin/marketplace.json — single-entry marketplace pointing at this plugin.

Strip non-Websets infrastructure (per scope decision)

• Deleted servers/ (github-channel, linear-channel, agentmail-mcp-codemode, google-workspace-mcp, effect-airtable-mcp, thoughtbox-gateway).
• Deleted src/channel-dedalus.ts and the dedalus npm dep.
• docker-compose.yml: dropped companion services, renamed schwartz13 → websets.
• .mcp.json.template: only websets entries remain.

Plugin asset moves

• git mv .claude/skills/{deep-research-item,verify-item,workflow-config} → skills/ at repo root, so they're plugin-namespaced.

Docs

• README rewritten plugin-install-first; HTTP/Docker documented as a secondary path.
• CLAUDE.md updated for the plugin-first architecture.

Verification done

• npm ci && npm run build — clean compile.
• Smoke-tested dist/stdio.js startup: stdio MCP connects, webhook listener binds on configured port, /health and /webhooks/status return 200.
• dist/server.js exports the expected three functions: createMcpServer, createServer, startWebhookListener.

Test plan

• npm run test (unit)
• npm run test:integration
• npm run test:e2e
• Local plugin install: /plugin marketplace add /path/to/repo → /plugin install websets@websets-mcp-codemode
• During channels research preview: claude --dangerously-load-development-channels plugin:websets@websets-mcp-codemode --channels plugin:websets@websets-mcp-codemode
• Verify /websets:deep-research-item autocompletes
• Send a signed webhook to localhost:7860/webhooks/exa and verify <channel source="websets-channel" …> appears in the session

Known follow-ups

• package-lock.json still references the dropped dedalus dep (the bash policy blocks npm install so the lockfile sync didn't happen). Next clean npm install will resolve.
• The channels field uses array form per the docs; the prior scaffold and the deleted sibling plugins used the object form. If install fails with "channels must be an object" we'll revert.
• HTTP/Docker path keeps DAuth OAuth; stdio path skips it (transport-bound).

https://claude.ai/code/session_01HusbT4R3ov5SwBXjzEKqQG

---

Generated by Claude Code

[glassBead-tc]

@claude Identify any P0/P1 issues in this PR and 2-3 viable means of addressing each, along with your reasoning for why each was chosen. Pay attention to the concept of making illegal states unrepresentable in your review, and give a confidence score to each recommendation.

[glassBead-tc]

Self-review of this PR through the "make illegal states unrepresentable" lens.

I've ranked these against an empty plugin install on a clean machine. Where the docs are silent I marked the assumption explicitly. Confidence is my estimate that the named fix actually resolves the issue — not that the issue exists.

---

P0 — must fix before merge

P0-1: ${CLAUDE_PLUGIN_DATA} substitution inside userConfig.default is unverified

Where: .claude-plugin/plugin.json — userConfig.websets_db_path.default = "${CLAUDE_PLUGIN_DATA}/websets.db"

The plugins-reference page lists ${CLAUDE_PLUGIN_DATA} substitution for MCP/LSP configs, hook commands, and monitor commands. userConfig.default is not on that list. If the harness takes the default literally, the user accepts a default that resolves to a directory called ${CLAUDE_PLUGIN_DATA} under whatever the plugin process's cwd happens to be — different per session, untracked, untested.

Illegal-state framing: The schema currently lets a default reference a runtime-only token; the type "default value" is too loose. The only valid encodings are (a) literal absolute paths, or (b) tokens the harness guarantees to substitute in this position.

Fix	Reasoning	Confidence
A: Drop the default from userConfig. Resolve at runtime in stdio.ts: path.join(process.env.CLAUDE_PLUGIN_DATA ?? path.resolve("data"), "websets.db").	The runtime env var is the contract the docs do commit to. Substitution happens in code, not in a JSON field whose semantics aren't specified.	High (90%)
B: Hardcode an absolute literal default like ~/.claude/plugins/data/websets/websets.db.	Predictable but circumvents the harness data-dir abstraction; brittle if Claude Code moves the data root.	Medium (60%)
C: Verify experimentally that defaults DO substitute, leave as-is if so.	Burns a test cycle on a docs question whose answer can change.	Low (30%)

Recommend A.

---

P0-2: Empty EXA_API_KEY is a representable success state

Where: src/server.ts createMcpServer does new Exa(config.exaApiKey || 'dummy-key-for-testing'). src/stdio.ts:44 passes process.env.EXA_API_KEY ?? "" unconditionally.

Result: a plugin user who skips/blanks the API-key prompt gets a fully-spawned MCP server that returns Exa errors lazily on every tool call. The required: true flag in userConfig enforces this at install, but anyone running npm run stdio directly hits the dummy-key fallback.

Illegal-state framing: ServerConfig.exaApiKey: string permits the empty string; the || fallback hides "no key" inside "yes key, just a dummy one". The type cannot distinguish authenticated vs. unauthenticated startup.

Fix	Reasoning	Confidence
A: Fail-fast in stdio.ts if EXA_API_KEY is empty — non-zero exit, single stderr line. Mirrors the install-layer required: true.	Smallest delta. The dummy-key path is for unit tests only; the runtime should refuse to start.	High (90%)
B: Type ServerConfig.exaApiKey as a branded NonEmptyString. Strip the || 'dummy-key-for-testing' fallback.	Encodes the constraint at the type boundary — illegal state literally unrepresentable. Cost: tests that build servers without a key need to be updated.	High (85%)
C: Keep silent fallback, emit a notification on each tool call when dummy key is in use.	Doesn't prevent the illegal state, just narrates it.	Low (40%)

Recommend A now, B as the proper fix.

---

P0-3: dist/ is gitignored — /plugin install ships with no compiled code

.gitignore:2 excludes dist/. The manifest references ${CLAUDE_PLUGIN_ROOT}/dist/stdio.js and ${CLAUDE_PLUGIN_ROOT}/dist/channel.js. After claude plugin install websets@…, the cache directory contains TypeScript source but no JS. First spawn → MODULE_NOT_FOUND. README documents a manual npm install && npm run build step but plugin users won't run it.

Illegal-state framing: The manifest references files that the install pipeline doesn't deliver. The current state is "install succeeds but plugin is non-functional" — that combination should not be representable.

Fix	Reasoning	Confidence
A: Spawn via npm, not node. command: "npm", args: ["--prefix", "${CLAUDE_PLUGIN_ROOT}", "run", "stdio:plugin"] where stdio:plugin runs npm install --omit=dev && npm run build && node dist/stdio.js. First spawn slow, subsequent fast. Mirrors what the prior channel-only scaffold already did.	Smallest behavioral delta. Trades startup time for install correctness. Native dep better-sqlite3 still rebuilds.	Medium-high (75%)
B: Bundle with esbuild --bundle --platform=node --external:better-sqlite3 and commit dist/stdio.js + dist/channel.js (only the entrypoints, not the whole tree). Keep better-sqlite3 as a runtime dep.	Clean install, fast spawn, no npm install needed if Node + native deps are present. Cost: dist diffs in PRs.	High (80%)
C: Add a SessionStart plugin hook that runs npm install && npm run build if dist/ is missing.	Hooks fire before tool calls but ordering vs. MCP server spawn is not documented.	Medium (60%)

Recommend A for the smallest delta, B for production polish.

---

P0-4: Port collision causes silent webhook cross-talk between sessions

Where: src/stdio.ts:31 — startWebhookListener({ port: 7860 }). Two Claude Code sessions running this plugin: the second session's app.listen(7860) fires EADDRINUSE. My current code logs the error to stderr but does not exit. The MCP transport still attaches successfully. Session B's channel then connects to http://localhost:7860/webhooks/events — which is session A's webhook port — and forwards session A's events into session B's chat.

Illegal-state framing: The system represents "two valid websets processes running" but the webhook intake is a global resource. Two MCP server processes can both report success; only one of them owns the port that the channel reads.

Fix	Reasoning	Confidence
A: port: 0 (OS-assigned) by default. After listen, write actual port to ${CLAUDE_PLUGIN_DATA}/websets-${pid}.port. Channel reads its sibling's port via PID handshake (Claude Code spawns siblings as children of the same parent — the channel can match the websets PID via its sibling env).	Per-process isolation; multiple sessions coexist. Cost: handshake logic; the PID-matching is fragile.	Medium (70%)
B: On EADDRINUSE, exit non-zero. Forces a single-active-session model unless user sets websets_http_port per-session.	Eliminates cross-talk loudly. Cheapest correct fix. Multi-session users have to configure manually.	High (85%)
C: Unix domain socket per-PID at ${CLAUDE_PLUGIN_DATA}/websets-${pid}.sock. Channel connects via UDS.	Clean isolation, no port-coordination surface. Cost: SSE-over-UDS needs custom HTTP server config; Exa webhooks still need a TCP port externally.	Medium (55%)

Recommend B as the immediate fix, A as the proper plugin-friendly answer once tested.

---

P1 — should fix soon

P1-5: Server/channel startup race; events can drop in the first ~5s

src/channel.ts has a 5s reconnect loop. If the channel spawns first (Claude Code doesn't document spawn order between two MCP servers in the same plugin), or if the websets process takes >0s to bind 7860, any webhook arriving during the gap is lost — eventBus is in-memory, late SSE subscribers don't get history.

Fix	Reasoning	Confidence
A: Channel polls /health 200 before subscribing, with 250ms→1s exponential backoff during initial connect.	Small change; closes the typical 100–500ms race window.	High (80%)
B: Replay buffer in eventBus — new SSE subscribers get last N seconds of events.	Robust but adds eventBus complexity and persistence semantics.	Medium (60%)
C: Fold channel into the websets process; in-memory pubsub instead of HTTP/SSE.	Breaks the plugin model (one MCP server per process).	Low (40%)

Recommend A.

---

P1-6: channels field shape — array vs object — empirically untested

I wrote channels: [{ server: "websets-channel" }] per the docs. The prior .claude-plugin/plugin.json in this repo, plus all five sibling plugins under the now-deleted servers/, used the object form: channels: { "websets-channel": { "server": "..." } }. Both shapes appear in the wild; the docs only document the array form.

Fix	Reasoning	Confidence
A: claude --plugin-dir . against this branch in a scratch session, observe whether the manifest loads. Commit whichever shape works.	Empirical, no guessing.	High (90%)
B: File a docs/schema clarification issue with anthropics/claude-code.	Slow; doesn't unblock this PR.	Low (30%)
C: Try array first; ship it; revert to object form on first user report.	Defers the unknown into prod.	Medium (60%)

Recommend A — needs to happen before this PR merges.

---

P1-7: No Node ≥ 20 enforcement at the plugin layer

package.json engines field requires Node 20+ (better-sqlite3 v11 demands it). The plugin manifest doesn't surface this. A user on Node 18 hits an opaque native-binding error.

Fix	Reasoning	Confidence
A: First lines of stdio.ts and channel.ts: assert parseInt(process.versions.node) >= 20, exit non-zero with a clear message if not.	Three-line change; converts opaque binding error into a one-line install hint.	High (85%)
B: Rely on README docs.	Ignored until it breaks.	Low (50%)
C: Migrate to node:sqlite (Node 22+ built-in) — drops the native dep entirely.	Bigger migration; raises the floor to Node 22.	Low (35%)

Recommend A.

---

Suggested merge gate

Before merging: P0-1, P0-2, P0-4 (fix B), and P1-6 (empirical test). P0-3 can ship as-is if README is the contract; ideally fix A before public install. Everything else is post-merge.

Happy to take any of these on if you confirm the priorities.

---

Generated by Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ebab0ef314

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Keep bundled skills aligned with renamed MCP server IDs

This manifest now exposes only websets/websets-channel, but the shipped skills still whitelist old tool names like mcp__schwartz13-local__execute and mcp__schwartz13-local__search (see skills/deep-research-item/SKILL.md:6 and skills/verify-item/SKILL.md:6). In plugin mode those tools are unavailable, so invoking /websets:verify-item or /websets:deep-research-item cannot call the Websets execute/search tools and the skill flow breaks.

Useful? React with 👍 / 👎.

[glassBead-tc]

Fixed in efcb1f5.

allowed-tools in the three bundled skills updated to mcp__websets__{execute,search} to match the renamed MCP server. Also dropped the unavailable mcp__airtable__execute from deep-research-item (the Airtable MCP was removed with the rest of servers/), and replaced the hardcoded /workspaces/schwartz13/data/workflow-configs.json path in workflow-config with ${CLAUDE_PLUGIN_DATA}/workflow-configs.json so the skill aligns with where the channel now expects the config.

Drive-by: also fixed two remaining schwartz13-mcp User-Agent strings in src/handlers/github.ts and src/workflows/verifyEnrichments.ts, and rewrote the EXAMPLES.md header for the new identity.

---

Generated by Claude Code

[chatgpt-codex-connector]

Regenerate lockfile after dependency set changes

The dependency block was updated here, but package-lock.json was left stale (it still has root package name schwartz13 and a root dedalus dependency). That lock drift means local/CI installs are no longer deterministic for this commit and will force lockfile rewrites on the next install; the lockfile should be updated in the same change as dependency edits.

Useful? React with 👍 / 👎.

[glassBead-tc]

Acknowledged — the lockfile drift is real (it still pins name: schwartz13 and a dedalus@0.0.1 entry under node_modules/).

I tried to address this in the same commit but two harness hooks block both paths:

• npm install --package-lock-only → blocked by the bash policy hook (which forces npm ci for installs).
• Direct edit of package-lock.json → blocked by the file-protect hook with pattern ^(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|poetry\.lock)$.

Both are intentional guardrails I can't override from this session. Flagging this for the human reviewer to run npm install --package-lock-only && git commit package-lock.json in a follow-up commit on this branch (or to grant a one-time hook bypass for this PR). The drift doesn't affect the build of the dropped dedalus dep — it's only used by the deleted src/channel-dedalus.ts, so npm ci will still install it harmlessly until the lockfile is regenerated.

---

Generated by Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: efcb1f540f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Bind webhook listener to localhost in plugin mode

The new stdio path starts startWebhookListener() with app.listen(port) and no host, which binds on all interfaces instead of loopback. In this commit the webhook secret is optional, and createWebhookRouter accepts unsigned POSTs when no secret is set, so any host that can reach the machine can inject fake webhook events that are forwarded into the active Claude channel session. For plugin mode this should default to 127.0.0.1 (or require an explicit opt-in host) to avoid remote event injection.

Useful? React with 👍 / 👎.

[glassBead-tc]

Fixed in e564c56.

Changed startWebhookListener to take an optional host parameter, defaulting to 127.0.0.1. The stdio entrypoint (src/stdio.ts) reads a new WEBSETS_HTTP_HOST env var so users running the plugin behind a reverse proxy or in a container can opt into a non-loopback bind explicitly; the default install is loopback-only.

Verified locally: stdio startup now logs webhook listener on http://127.0.0.1:<port>/webhooks/*.

The HTTP/Docker entrypoint (src/index.ts → dist/index.js) is unchanged — it still uses Express's default 0.0.0.0 because port-mapping the container needs it, and that path also gates /mcp behind DAuth. The webhook endpoint there has always been intentionally reachable; any non-localhost deployment of the HTTP path should pair it with EXA_WEBHOOK_SECRET.

---

Generated by Claude Code

[chatgpt-codex-connector]

Keep GitHub token env in Docker compose service

This change removes GITHUB_TOKEN from the container environment, so Docker users can no longer pass a token through the default compose flow. The code still uses process.env.GITHUB_TOKEN in src/handlers/github.ts and verifyEnrichmentsWorkflow for authenticated GitHub API calls; without it, requests are subject to low unauthenticated limits and will start failing with 403/rate-limit errors during normal verification workloads. Keep GITHUB_TOKEN alongside the new webhook secret variable.

Useful? React with 👍 / 👎.

[glassBead-tc]

Fixed in e564c56. Added GITHUB_TOKEN=${GITHUB_TOKEN:-} back to the websets service env in docker-compose.yml.

Note for the plugin/stdio path: the same process.env.GITHUB_TOKEN is read by src/handlers/github.ts and verifyEnrichmentsWorkflow regardless of transport. Plugin users currently have no way to feed a GitHub token in via userConfig, so they hit the same unauth rate-limit issue if they exercise github.* ops or the verifyEnrichments workflow. Want me to add an optional github_token (sensitive) entry to .claude-plugin/plugin.json's userConfig and wire it through the websets server's env block? It's a clean parallel to exa_api_key / exa_webhook_secret.

---

Generated by Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e564c56ca4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Align channel URL host with webhook bind address

websets-channel is configured to read events from http://localhost:${user_config.websets_http_port}, but the new stdio entrypoint binds the webhook listener to 127.0.0.1 by default (src/stdio.ts). On hosts where localhost resolves to ::1 first, the channel can get stuck reconnecting to /webhooks/events and never emit notifications/claude/channel, even though the MCP server itself is up. Use the same loopback form on both sides (for example 127.0.0.1 in WEBSETS_SERVER_URL) to avoid address-family mismatches.

Useful? React with 👍 / 👎.

[glassBead-tc]

Fixed in 7612e47. Changed WEBSETS_SERVER_URL from http://localhost:... to http://127.0.0.1:... so both sides use the same IPv4 loopback form. Avoids the IPv6-first resolution gap where the channel would silently retry against [::1]:port.

---

Generated by Claude Code