@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, get_corpus, 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                 # the index
npx -y @bounded-systems/site-mcp get_conformance accessibility   # one area
npx -y @bounded-systems/site-mcp get_conformance --full          # every criterion
npx -y @bounded-systems/site-mcp get_corpus                      # the index
npx -y @bounded-systems/site-mcp get_corpus topics               # one full list
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 four verbs, on both surfaces:

One verb per subject, not one per drill-down

A client loads every tool's name, description and input schema into its context before any call is made — a cost paid on every session whether or not the tool is used — and choosing among the tools is itself a fan-out. So the tool list is a fold: F is the list, a call is one step of the generator rule, and a terminal response is where expansion stops.

Which makes a verb per drill-down the wrong shape: it grows the part paid always in order to shrink the part paid sometimes. get_conformance_index + get_conformance_area + get_corpus_index + get_corpus_list would take this server from three tools to eight.

Instead there is one verb per subject, and the parameter is the generator rule: no argument returns the index, an argument unfolds one branch of it, and --full still reaches the unfolded document at its own path. Nothing was removed from the API — site://conformance and site://corpus still serve the complete documents, and site://conformance/index and site://corpus/index are new entry points alongside them.

Changed default. get_conformance with no arguments used to return the whole 19.7 KB report; it now returns the 3.2 KB index. Pass --full (CLI) or {"full": true} (MCP) for the previous behaviour.

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).

[!IMPORTANT] Versions must stay in sync. The release version lives in four places that must all match: package.json, deno.json, server.json, and the v<version> git tag. The workflow's verify job hard-fails the whole release on any mismatch, so npm and JSR can never drift apart. The MCP Registry also requires package.json to carry "mcpName": "io.github.bounded-systems/site-mcp" (it reads that field off the published npm package to prove ownership).