@bounded-systems/site-mcp

A local, read-only MCP server (and a matching CLI) over robertdelanghe.dev's signed static API.

It exposes the site's identity data — profile, writing, the GitHub corpus, the résumé credential, the OpenAPI doc — to any MCP client (Claude Desktop, Claude Code, etc.), and verifies every response byte-for-byte against the site's Sigstore-signed sha256 manifest before handing it back. If the bytes a client would receive don't match the signed manifest, it refuses to return them.

It runs locally over stdio — the client spawns it as a subprocess. There is no hosted server and no network listener, which preserves the site's static / no-attack-surface posture.

A thin implementation of a generic core

This package is now thin. All of the reusable machinery — the verifying fetch client, the sha256 manifest + Sigstore checks, and the VerbSpec → MCP (tools + resources) / VerbSpec → CLI projection — lives in @bounded-systems/static-mcp. site-mcp supplies only:

• the verbs (src/verbs.ts) — list_posts, get_post, get_conformance, each authored once as a @bounded-systems/verbspec VerbSpec;
• the resource catalog (src/catalog.ts) — the site://… resources;
• the config values (src/config.ts) — the origin and expected signer identity; and
• the entry (src/index.ts) — which picks a surface and hands the spec to the core.

src/verbs.ts ─┐
src/catalog.ts ├─▶ buildSiteSpec(config) ─▶ @bounded-systems/static-mcp
src/config.ts ─┘        serveVerifiedStaticMcp(spec, config)   (MCP, stdio)
                        runStaticCli(spec, config, argv)        (CLI)

Two surfaces, one definition. verbspec projects each verb to both an MCP tool and a CLI subcommand. The exact same verb set backs site-mcp's MCP tools and its CLI commands — no second definition, no drift.

Install / run

Requires Node ≥ 18.17. site-mcp's verbspec dependency is published to JSR, so installs resolve it through JSR's npm bridge — the included .npmrc sets @jsr:registry=https://npm.jsr.io. (Consuming from a fresh environment, add that one line to your npm config.)

# MCP server over stdio (what an MCP client launches):
npx -y @bounded-systems/site-mcp

# CLI — the SAME verbs, printing the verified JSON:
npx -y @bounded-systems/site-mcp list_posts
npx -y @bounded-systems/site-mcp get_conformance
npx -y @bounded-systems/site-mcp get_post agent-authored-code-drift

The MCP server logs a readiness line to stderr (stdout is the MCP channel):

site-mcp ready (stdio) → https://robertdelanghe.dev; signature mode=off

MCP client configuration

{
  "mcpServers": {
    "robertdelanghe": {
      "command": "npx",
      "args": ["-y", "@bounded-systems/site-mcp"],
      "env": { "SITE_MCP_SIGNATURE_MODE": "warn" }
    }
  }
}

Resources

Tools / CLI commands (read-only)

The same three verbs, on both surfaces:

Resource reads and tool results carry a _meta.verification block (the manifest-relative path, source URL, the verified sha256, and the manifest signature status). The CLI prints the verified JSON; a verification failure exits non-zero with nothing on stdout.

Verification / trust model

The site publishes a single signed manifest, https://robertdelanghe.dev/site.sha256 (sha256sum format), and a Sigstore bundle over it, site.sha256.sigstore.json. The core enforces:

1. Per-file hash check (always on). Fetch the manifest once per process; for every resource, fetch it, SHA-256 the received bytes, and require that digest to equal the manifest entry. A tampered file, a stale CDN edge, or a MITM → mismatch → VerificationError instead of a response. A path absent from the manifest is likewise refused.
2. Manifest signature check (optional). SITE_MCP_SIGNATURE_MODE=warn|require verifies the Sigstore bundle against the deploy workflow identity (…/bdelanghe/site/.github/workflows/deploy.yml@refs/heads/main).

Sigstore backend / @bounded-systems/verify. The optional manifest-signature step is intended to delegate to @bounded-systems/verify, the canonical in-process bundle verifier. As of verify@0.1.0 that package ships as a self-executing CLI with no exported function (importing it runs and exits the process), so the core keeps a minimal, behaviorally-identical copy of the check and the gap is filed upstream. See static-mcp's README.

Configuration

Development

npm install         # resolves @bounded-systems/static-mcp (npm) + verbspec (JSR bridge)
npm run build       # tsc → dist/
npm test            # node --test via tsx (server + CLI; no network)
npm run typecheck

Publishing

One tag publishes the same version to three registries, mirrored. Pushing a v* tag runs publish.yml, which fans out to:

There are no long-lived secrets — every registry authenticates with the job's short-lived GitHub Actions OIDC token (id-token: write). npm needs npm ≥ 11.5 (the workflow upgrades npm to guarantee this).

The MCP Registry job runs after the npm job, because the registry verifies ownership by reading mcpName from the freshly-published npm package.

One-time setup (maintainer) — do these BEFORE the first tag

These three registry-side authorizations only need to happen once. Two of the three (JSR, MCP Registry) are pure repo-link / OIDC — no tokens are minted.

(a) npm — Trusted Publisher (on npmjs.com)

1. Sign in as an owner of the @bounded-systems scope.
2. Open the package page for @bounded-systems/site-mcp → Settings → Trusted Publisher. For a brand-new package you may need to publish 0.1.0 once manually (or create the package), then switch to trusted publishing.
3. Choose GitHub Actions and enter:
   • Organization / user: bounded-systems
   • Repository: site-mcp
   • Workflow filename: publish.yml ← (was publish-npm.yml)
   • Environment: (leave blank)
4. Save. No token is generated or stored anywhere. Ensure the package's publishing-access policy allows automation/OIDC (trusted publishers satisfy 2FA).

(b) JSR — create + link the package (on jsr.io)

1. Sign in to jsr.io with GitHub and create the package @bounded-systems/site-mcp under the @bounded-systems scope.
2. Open the package's Settings tab → under GitHub Repository enter bounded-systems/site-mcp and click Link. Linking the repo is what enables tokenless OIDC publishing from this workflow (same idea as npm's trusted publisher). No token is created.

(c) MCP Registry — nothing to pre-authorize

The io.github.bounded-systems/* namespace is auto-authorized via GitHub OIDC: because this repo lives under github.com/bounded-systems, mcp-publisher login github-oidc proves ownership of the namespace from the Actions run itself. There is no registry-side claim/consent/linking step to do in advance — the first publish.yml run authenticates and registers the server on its own. (Package-ownership of the npm entry is proven separately by the mcpName field; see the note above.)

Cut a release (the single command)

# 1. Bump the version in ALL of: package.json, deno.json, server.json
#    (and the package entry in server.json). Commit.
# 2. Tag with the SAME version and push — this is the only command:
git tag v0.1.0 && git push origin v0.1.0

That one v* tag triggers publish.yml → npm + JSR + MCP Registry, all at the same version. You can also run it from the Actions tab via workflow_dispatch (which reuses the package.json version in place of a tag).

Local dry-runs (verify without publishing)

npm pack --dry-run                                   # npm tarball contents
npx --yes jsr publish --dry-run --allow-slow-types   # JSR (or: deno publish --dry-run --allow-slow-types)
mcp-publisher validate ./server.json                 # MCP Registry schema check

site-mcp depends on @bounded-systems/static-mcp; publish the core first (its own v* tag → JSR + npm), then cut site-mcp's tag.

License

MIT — see LICENSE. The site data itself is published under CC BY 4.0.