@proofofwork-agency/toolpin 0.2.3

package/docs/how-to/toolpin-curated-registry.md

@@ -0,0 +1,153 @@
+# ToolPin Curated Registry
+
+ToolPin hosts a first-party curated registry without running any custom
+infrastructure. The registry is versioned JSON in this repository, fetched from
+raw GitHub at runtime, and bundled in the npm package as an offline fallback
+snapshot.
+
+Use it for servers ToolPin maintainers are willing to recommend because the
+metadata is installable, reviewable, lockable, and documented. Do not use it as
+a broad directory.
+
+## URLs
+
+Raw GitHub source of truth, no site deploy required:
+
+```text
+https://raw.githubusercontent.com/proofofwork-agency/toolpin/main/registry/v0/servers
+```
+
+GitHub Pages / Docusaurus static mirror:
+
+```text
+https://proofofwork-agency.github.io/toolpin/registry/v0/servers
+```
+
+For custom `official-compatible` registries, ToolPin appends `/servers`
+automatically when configured with a base URL.
+
+## Built-In Source
+
+ToolPin ships this registry as the built-in `toolpin` source: a GitHub-backed
+curated registry with bundled fallback. It is first in the source list, enabled
+by default, and pinned. Users can filter to another source, but `toolpin` cannot be
+disabled through `.toolpin/registries.json`, `toolpin registry disable`, or the
+TUI source selector.
+
+Then:
+
+```sh
+toolpin registry list
+toolpin ingest --source toolpin
+toolpin search github --source toolpin
+```
+
+## Add a Server by PR
+
+Edit both files:
+
+```text
+registry/v0/servers
+website/static/registry/v0/servers
+```
+
+They must stay identical. CI runs:
+
+```sh
+npm run registry:check
+```
+
+Each entry must be installable and include curation metadata:
+
+```json
+{
+  "server": {
+    "name": "io.github.example/server",
+    "title": "Example MCP Server",
+    "description": "What this server does and why it is useful.",
+    "version": "1.0.0",
+    "repository": {
+      "url": "https://github.com/example/server",
+      "source": "github"
+    },
+    "packages": [
+      {
+        "registryType": "npm",
+        "identifier": "@example/server",
+        "version": "1.0.0",
+        "transport": {
+          "type": "stdio"
+        }
+      }
+    ]
+  },
+  "_meta": {
+    "dev.toolpin/curation": {
+      "status": "reviewed",
+      "reviewedAt": "2026-06-25",
+      "reviewedBy": "toolpin-maintainers",
+      "reason": "Why ToolPin recommends this server.",
+      "evidenceTier": "metadata-only",
+      "riskNotes": [],
+      "testedClients": ["claude"],
+      "toolpinEnforcement": {
+        "status": "not-verified",
+        "notes": "Branch protection and ToolPin CI enforcement have not been verified."
+      }
+    },
+    "dev.toolpin/clientSupport": {
+      "default": "unsupported",
+      "clients": {
+        "codex": {
+          "status": "toolpin-installable",
+          "installMode": "mcp-config",
+          "requirements": ["node>=22"],
+          "setupCommands": [],
+          "notes": "ToolPin can write this as a normal Codex MCP server."
+        },
+        "claude": {
+          "status": "toolpin-installable",
+          "installMode": "mcp-config",
+          "requirements": ["node>=22"],
+          "setupCommands": [],
+          "notes": "ToolPin can write this as a project MCP server."
+        }
+      }
+    }
+  }
+}
+```
+
+The container file (`registry/v0/servers`) wraps entries in a `servers` array plus a `metadata` block. If `metadata.count` or `metadata.total` is present, it must equal `servers.length`, or `npm run registry:check` fails. Package targets require `registryType`, `identifier`, and `transport.type`; remote targets require an `https://` URL.
+
+`dev.toolpin/clientSupport` is ToolPin-owned metadata:
+
+- `toolpin-installable`: ToolPin can generate the client MCP config directly.
+- `external-setup`: the client is supported, but setup needs documented steps
+  outside ToolPin, such as plugins, daemons, project initialization, or
+  instruction-file writes.
+- `unsupported`: ToolPin must not offer that client as an install target.
+
+Use `requirements` for runtimes, CLIs, API-key prerequisites, OAuth support, or
+other normal setup constraints. Use `setupCommands` only for documented external
+steps; ToolPin does not run external setup commands from registry metadata.
+
+For ContextRelay specifically, Codex is `toolpin-installable` through a normal
+MCP config that runs package arguments equivalent to `contextrelay codex-mcp
+server`. Claude is `external-setup`: install ContextRelay globally, run
+`ctxrelay init --instructions project`, and use the generated Claude
+plugin/setup. ToolPin must not run `ctxrelay init` until an explicit external
+setup flow exists because it writes project files and plugin state.
+
+Reviewers should reject entries that are hosted-only, source-missing,
+non-installable, stale, duplicate, or not useful enough to recommend. Use
+`evidenceTier` and `toolpinEnforcement.status` honestly: `metadata-only` and
+`not-verified` are valid for seed entries; reserve stronger labels for checks
+ToolPin can actually verify.
+
+Local validation:
+
+```sh
+npm run registry:check
+npm test
+```

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@proofofwork-agency/toolpin",
+  "version": "0.2.3",
+  "description": "Trusted install, lockfile, and governance layer for MCP servers",
+  "license": "Apache-2.0",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "lockfile",
+    "supply-chain",
+    "cli",
+    "github-action"
+  ],
+  "homepage": "https://proofofwork-agency.github.io/toolpin/",
+  "bugs": {
+    "url": "https://github.com/proofofwork-agency/toolpin/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/proofofwork-agency/toolpin.git"
+  },
+  "type": "module",
+  "packageManager": "npm@10.9.2",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "action.yml",
+    "registry",
+    "docs/assets/readme",
+    "docs/how-to/catch-drift-in-ci.md",
+    "docs/how-to/custom-registries.md",
+    "docs/how-to/toolpin-curated-registry.md"
+  ],
+  "bin": {
+    "toolpin": "./dist/cli.js",
+    "tpn": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "postbuild": "node -e \"require('fs').chmodSync('dist/cli.js', 0o755)\"",
+    "docs:build": "docusaurus build website",
+    "docs:clear": "docusaurus clear website",
+    "docs:start": "docusaurus start website",
+    "registry:check": "node scripts/check-curated-registry.mjs",
+    "test": "npm run build && node --test",
+    "docs:check": "node scripts/check-doc-consistency.mjs",
+    "self:ci": "node dist/cli.js ci --file mcp-lock.json --source toolpin --live --verify --skip-live-verification --timeout 15000",
+    "audit:runtime": "npm audit --omit=dev",
+    "release:check": "npm test && npm run self:ci && npm run docs:check && npm run docs:build && npm run registry:check && npm run audit:runtime && node scripts/check-publish-target.mjs && npm pack --dry-run",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run release:check",
+    "start": "node dist/cli.js",
+    "dev": "npm run build && node dist/cli.js",
+    "tui": "npm run build && node dist/cli.js tui",
+    "smoke": "npm run build && node dist/cli.js search github --limit 3 --live"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@docusaurus/core": "^3.10.1",
+    "@docusaurus/preset-classic": "^3.10.1",
+    "@types/node": "^22.10.7",
+    "@types/react": "^19.2.17",
+    "typescript": "^5.7.3"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ink": "^7.1.0",
+    "react": "^19.2.7",
+    "yaml": "^2.9.0"
+  }
+}

package/registry/README.md

@@ -0,0 +1,92 @@
+# ToolPin Curated Registry
+
+This directory is the source of the ToolPin Curated MCP Registry.
+
+It is intentionally GitHub-native:
+
+- entries are reviewed through pull requests;
+- CI validates the registry shape before merge;
+- no database or hosted backend is required;
+- raw GitHub is the runtime source of truth, with GitHub Pages only as a static mirror.
+
+## Endpoints
+
+Canonical source file:
+
+```text
+registry/v0/servers
+```
+
+Raw GitHub URL after merge to `main`:
+
+```text
+https://raw.githubusercontent.com/proofofwork-agency/toolpin/main/registry/v0/servers
+```
+
+GitHub Pages / Docusaurus mirror after the website is deployed:
+
+```text
+https://proofofwork-agency.github.io/toolpin/registry/v0/servers
+```
+
+For custom official-compatible registries, ToolPin appends `/servers`, so
+configure the registry base URL without the trailing `/servers`.
+
+## Built-In CLI Source
+
+Current ToolPin versions expose this registry as the built-in `toolpin` source.
+The CLI fetches the raw GitHub `/servers` file first and uses the packaged
+`registry/v0/servers` file only as an offline fallback snapshot.
+
+Then run:
+
+```sh
+toolpin registry list
+toolpin ingest --source toolpin
+toolpin search github --source toolpin
+```
+
+## Adding Servers
+
+Add entries to `registry/v0/servers` and mirror the same content to
+`website/static/registry/v0/servers`. Run:
+
+```sh
+npm run registry:check
+npm test
+```
+
+Every server entry must be installable: it needs a package or remote target,
+version/source metadata, transport, repository URL when available, declared
+secrets, and ToolPin curation metadata.
+
+Required curation metadata:
+
+```json
+{
+  "_meta": {
+    "dev.toolpin/curation": {
+      "status": "reviewed",
+      "reviewedAt": "2026-06-25",
+      "reviewedBy": "toolpin-maintainers",
+      "reason": "Why this server belongs in the curated registry.",
+      "evidenceTier": "metadata-only",
+      "riskNotes": [],
+      "testedClients": ["claude"],
+      "toolpinEnforcement": {
+        "status": "not-verified",
+        "notes": "Branch protection and ToolPin CI enforcement have not been verified."
+      }
+    }
+  }
+}
+```
+
+Do not add hosted-only, source-missing, stale, duplicate, non-installable, or
+unreviewed entries to this registry. `evidenceTier` must be honest:
+`metadata-only` for reviewed metadata, `digest-pinned` for immutable pins,
+`byte-verified` only when ToolPin recomputed or resolved artifact bytes, and
+`provenance-attested` only when provenance verification is implemented. Use
+`toolpinEnforcement.status: "enforced"` only when the ToolPin check is required
+by branch protection or rulesets and can be validated; otherwise use
+`not-verified` with notes. Use discovery registries for broad search.

package/registry/v0/servers

@@ -0,0 +1,115 @@
+{
+  "servers": [
+    {
+      "server": {
+        "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+        "name": "@proofofwork-agency/contextrelay",
+        "title": "ContextRelay",
+        "description": "Local coordination bridge that connects Codex and Claude Code agents in the same project session.",
+        "repository": {
+          "url": "https://github.com/proofofwork-agency/contextrelay",
+          "source": "github"
+        },
+        "version": "3.9.2",
+        "packages": [
+          {
+            "registryType": "npm",
+            "identifier": "@proofofwork-agency/contextrelay",
+            "version": "3.9.2",
+            "runtimeHint": "bun",
+            "packageArguments": [
+              "codex-mcp",
+              "server"
+            ],
+            "transport": {
+              "type": "stdio"
+            }
+          }
+        ]
+      },
+      "_meta": {
+        "dev.toolpin/curation": {
+          "status": "reviewed",
+          "reviewedAt": "2026-06-27T00:00:00.000Z",
+          "reviewedBy": "toolpin-maintainers",
+          "reason": "First-party ContextRelay bridge for agent collaboration; Codex consumes it as a stdio MCP server, not as a Codex plugin. Claude support requires project/plugin initialization.",
+          "evidenceTier": "byte-verified",
+          "riskNotes": [
+            "Requires Bun to run the npm package through bunx.",
+            "Upstream ContextRelay documents `ctxrelay codex-mcp install` as the canonical global Codex registration; ToolPin direct install writes the equivalent stdio MCP launch command into Codex config.",
+            "Claude setup writes project/plugin state and is documented as external setup until ToolPin has an explicit setup flow."
+          ],
+          "testedClients": [
+            "codex",
+            "claude"
+          ],
+          "toolpinEnforcement": {
+            "status": "not-verified",
+            "notes": "Repository branch protection and ToolPin CI enforcement have not been verified for this entry."
+          }
+        },
+        "dev.toolpin/evidence": [
+          {
+            "code": "npm_integrity_verified",
+            "status": "passed",
+            "message": "npm tarball integrity matched registry dist.integrity for @proofofwork-agency/contextrelay@3.9.2.",
+            "source": "npm-tarball",
+            "claim": "sha512-zUmS+iLWX/uRha5wzO8AdxSHUrOvXy8MOx+JHdMBRDRvMU+wS6jtQn0beWRUjRdMKN2RDZ0WRzxoHlDtEBmQYQ==",
+            "verificationMethod": "npm-packument-sri",
+            "verifiedByToolPin": true,
+            "trustedAnchor": true,
+            "trustAnchor": "registry.npmjs.org",
+            "verifiedAt": "2026-06-27T19:50:00.000Z"
+          }
+        ],
+        "dev.toolpin/clientSupport": {
+          "default": "unsupported",
+          "clients": {
+            "codex": {
+              "status": "toolpin-installable",
+              "installMode": "mcp-config",
+              "requirements": [
+                "bun>=1.0.0"
+              ],
+              "setupCommands": [
+                "ctxrelay codex-mcp install"
+              ],
+              "notes": "ToolPin direct install writes a Codex stdio MCP config for the same server that `ctxrelay codex-mcp install` registers globally. ContextRelay does not currently ship a Codex plugin manifest."
+            },
+            "claude": {
+              "status": "external-setup",
+              "installMode": "claude-plugin",
+              "requirements": [
+                "bun>=1.0.0",
+                "claude-code"
+              ],
+              "setupCommands": [
+                "npm install -g @proofofwork-agency/contextrelay",
+                "ctxrelay init --instructions project"
+              ],
+              "notes": "Claude support exists through the ContextRelay Claude plugin/init flow, not a plain mcpServers entry."
+            }
+          }
+        }
+      }
+    }
+  ],
+  "metadata": {
+    "count": 1,
+    "total": 1,
+    "name": "ToolPin Curated MCP Registry",
+    "description": "A PR-reviewed, GitHub-hosted registry for MCP servers ToolPin can normalize, review, lock, and recommend.",
+    "generatedAt": "2026-06-27T00:00:00.000Z",
+    "source": {
+      "type": "github",
+      "repository": "https://github.com/proofofwork-agency/toolpin",
+      "path": "registry/v0/servers"
+    },
+    "policy": {
+      "installableOnly": true,
+      "reviewRequired": true,
+      "prBasedUpdates": true,
+      "toolpinCiRequired": true
+    }
+  }
+}