Hi

\"\n});\n```\n\n## Val Town Utility Functions\n\nVal Town provides several utility functions to help with common project tasks.\n\n### Importing Utilities\n\nAlways import utilities with version pins to avoid breaking changes:\n\n```ts\nimport { parseProject, readFile, serveFile } from \"https://esm.town/v/std/utils@85-main/index.ts\";\n```\n\n### Available Utilities\n\n\n#### **serveFile** - Serve project files with proper content types\n\nFor example, in Hono:\n\n```ts\n// serve all files in frontend/ and shared/\napp.get(\"/frontend/*\", c => serveFile(c.req.path, import.meta.url));\napp.get(\"/shared/*\", c => serveFile(c.req.path, import.meta.url));\n```\n\n#### **readFile** - Read files from within the project:\n\n```ts\n// Read a file from the project\nconst fileContent = await readFile(\"/frontend/index.html\", import.meta.url);\n```\n\n#### **listFiles** - List all files in the project\n\n```ts\nconst files = await listFiles(import.meta.url);\n```\n\n#### **parseProject** - Extract information about the current project from import.meta.url\n\nThis is useful for including info for linking back to a val, ie in \"view source\" urls:\n\n```ts\nconst projectVal = parseProject(import.meta.url);\nconsole.log(projectVal.username); // Owner of the project\nconsole.log(projectVal.name); // Project name\nconsole.log(projectVal.version); // Version number\nconsole.log(projectVal.branch); // Branch name\nconsole.log(projectVal.links.self.project); // URL to the project page\n```\n\nHowever, it's *extremely importing* to note that `parseProject` and other Standard Library utilities ONLY RUN ON THE SERVER.\nIf you need access to this data on the client, run it in the server and pass it to the client by splicing it into the HTML page\nor by making an API request for it.\n\n## Val Town Platform Specifics\n\n- **Redirects:** Use `return new Response(null, { status: 302, headers: { Location: \"/place/to/redirect\" }})` instead of `Response.redirect` which is broken\n- **Images:** Avoid external images or base64 images. Use emojis, unicode symbols, or icon fonts/libraries instead\n- **AI Image:** To inline generate an AI image use: `

`\n- **Storage:** DO NOT use the Deno KV module for storage\n- **Browser APIs:** DO NOT use the `alert()`, `prompt()`, or `confirm()` methods\n- **Weather Data:** Use open-meteo for weather data (doesn't require API keys) unless otherwise specified\n- **View Source:** Add a view source link by importing & using `import.meta.url.replace(\"ems.sh\", \"val.town)\"` (or passing this data to the client) and include `target=\"_top\"` attribute\n- **Error Debugging:** Add `` to HTML to capture client-side errors\n- **Error Handling:** Only use try...catch when there's a clear local resolution; Avoid catches that merely log or return 500s. Let errors bubble up with full context\n- **Environment Variables:** Use `Deno.env.get('keyname')` when you need to, but generally prefer APIs that don't require keys\n- **Imports:** Use `https://esm.sh` for npm and Deno dependencies to ensure compatibility on server and browser\n- **Storage Strategy:** Only use backend storage if explicitly required; prefer simple static client-side sites\n- **React Configuration:** When using React libraries, pin versions with `?deps=react@18.2.0,react-dom@18.2.0` and start the file with `/** @jsxImportSource https://esm.sh/react@18.2.0 */`\n- Ensure all React dependencies and sub-dependencies are pinned to the same version\n- **Styling:** Default to using TailwindCSS via `` unless otherwise specified\n\n## Project Structure and Design Patterns\n\n### Recommended Directory Structure\n```\n├── backend/\n│ ├── database/\n│ │ ├── migrations.ts # Schema definitions\n│ │ ├── queries.ts # DB query functions\n│ │ └── README.md\n│ └── routes/ # Route modules\n│ ├── [route].ts\n│ └── static.ts # Static file serving\n│ ├── index.ts # Main entry point\n│ └── README.md\n├── frontend/\n│ ├── components/\n│ │ ├── App.tsx\n│ │ └── [Component].tsx\n│ ├── favicon.svg\n│ ├── index.html # Main HTML template\n│ ├── index.tsx # Frontend JS entry point\n│ ├── README.md\n│ └── style.css\n├── README.md\n└── shared/\n ├── README.md\n └── utils.ts # Shared types and functions\n```\n\n### Backend (Hono) Best Practices\n\n- Hono is the recommended API framework\n- Main entry point should be `backend/index.ts`\n- **Static asset serving:** Use the utility functions to read and serve project files:\n ```ts\n import { readFile, serveFile } from \"https://esm.town/v/std/utils@85-main/index.ts\";\n \n // serve all files in frontend/ and shared/\n app.get(\"/frontend/*\", c => serveFile(c.req.path, import.meta.url));\n app.get(\"/shared/*\", c => serveFile(c.req.path, import.meta.url));\n \n // For index.html, often you'll want to bootstrap with initial data\n app.get(\"/\", async c => {\n let html = await readFile(\"/frontend/index.html\", import.meta.url);\n \n // Inject data to avoid extra round-trips\n const initialData = await fetchInitialData();\n const dataScript = ``;\n \n html = html.replace(\"\", `${dataScript}`);\n return c.html(html);\n });\n ```\n- Create RESTful API routes for CRUD operations\n- Always include this snippet at the top-level Hono app to re-throwing errors to see full stack traces:\n ```ts\n // Unwrap Hono errors to see original error details\n app.onError((err, c) => {\n throw err;\n });\n ```\n\n### Database Patterns\n- Run migrations on startup or comment out for performance\n- Change table names when modifying schemas rather than altering\n- Export clear query functions with proper TypeScript typing\n\n## Common Gotchas and Solutions\n\n1. **Environment Limitations:** \n - Val Town runs on Deno in a serverless context, not Node.js\n - Code in `shared/` must work in both frontend and backend environments\n - Cannot use `Deno` keyword in shared code\n - Use `https://esm.sh` for imports that work in both environments\n\n2. **SQLite Peculiarities:**\n - Limited support for ALTER TABLE operations\n - Create new tables with updated schemas and copy data when needed\n - Always run table creation before querying\n\n3. **React Configuration:**\n - All React dependencies must be pinned to 18.2.0\n - Always include `@jsxImportSource https://esm.sh/react@18.2.0` at the top of React files\n - Rendering issues often come from mismatched React versions\n\n4. **File Handling:**\n - Val Town only supports text files, not binary\n - Use the provided utilities to read files across branches and forks\n - For files in the project, use `readFile` helpers\n\n5. **API Design:**\n - `fetch` handler is the entry point for HTTP vals\n - Run the Hono app with `export default app.fetch // This is the entry point for HTTP vals`\n\n",[],[219],{"_102":227,"_95":228,"_153":229,"_155":-5,"_156":138,"_157":230,"_159":160,"_104":231,"_99":232,"_162":213,"_164":233,"_165":22,"_166":-5,"_167":234,"_98":235},"8dcef2de-a0da-11f0-82df-0224a6c84d84","README.md","f0b498b4-a098-11f0-a8cf-0224a6c84d84",20,["D",1759552099051],3,"# Subregistry API for the Official MCP Registry\n\nI want to create an MCP [Subregistry](https://github.com/modelcontextprotocol/registry/blob/main/docs/guides/consuming/use-rest-api.md#building-a-subregistry) API using the following tech stack:\n\n- [Drizzle](https://docs.val.town/std/sqlite/orms/#drizzle)\n- [Hono](https://hono.dev/)\n- [mcp-registry-spec-sdk](https://www.npmjs.com/package/mcp-registry-spec-sdk)\n- [Open API Spec](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/api/openapi.yaml)\n- [Val.Town Blobs](https://docs.val.town/std/blob/)\n- [Val.Town SQLite](https://docs.val.town/std/sqlite/usage/)\n- [Zod]\n\n### Core Endpoints\n\n- GET /v0/servers — List all servers with pagination\n- GET /v0/servers/{serverName} — Get the latest version of a server (URL-encoded)\n- GET /v0/servers/{serverName}/versions — List all versions of a server\n- GET /v0/servers/{serverName}/versions/{version} — Get a specific version (both parameters URL-encoded)\n\n### Authentication\n\n- Read operations: No authentication required\n- Write operations: Namespace-scoped bearer token issued via official auth exchanges\nContent Typek\n\nAll requests and responses use application/json\n\n### Subregistry Extensions (faith.tools)\n\nThe canonical OpenAPI contract now mirrors the upstream 2025-09-29 MCP registry spec. The faith.tools subregistry layers optional features on top:\n\n- Extended query parameters on `GET /v0/servers`:\n - `search` — simple LIKE-based token search (subregistry only)\n - `updatedSince`, `version` — enable incremental syncs (documented outside the base spec)\n- Auth token exchange endpoints (not part of the upstream spec):\n - POST /v0/auth/github-at\n - POST /v0/auth/github-oidc\n - POST /v0/auth/dns\n - POST /v0/auth/http\n - POST /v0/auth/oidc\n- Observability/admin:\n - GET /metrics — Prometheus metrics endpoint exporting registry counters (publish/update/auth exchange) and uptime\n - GET /v0/health — Enhanced status payload with uptime, metrics summary, and timestamp\n- Marketplace metadata:\n - Publisher-provided `_meta` may include `marketplaceIcon`\n - Registry-managed `_meta.io.modelcontextprotocol.registry/official.marketplaceIcon` stores cached blob references\n\nClients should treat these additions as optional subregistry features.\n\n## Pagination\n\nList endpoints use cursor-based pagination for efficient, stable results.\n\n## Usage\n\n- Initial request: Omit the cursor parameter\n- Subsequent requests: Use the nextCursor value from the previous response\n- End of results: When nextCursor is null or empty, there are no more results\n\nImportant: Always treat cursors as opaque strings. Never manually construct or modify cursor values.\n\n### Database & Storage\n\n- **Val Town compatibility:** We proxy every statement through `sqlite.execute(...)`, matching the [Val Town SQLite migration guidance](https://docs.val.town/std/sqlite/migrations/). Schema bumps create new `_poc_vN` tables instead of running `ALTER TABLE`, and the Drizzle sqlite-proxy adapter is just a typed wrapper around the same helper shown in the [Val Town Drizzle ORM docs](https://docs.val.town/std/sqlite/orms/).\n- **Schema highlights (`server_versions_poc_v2`):** Core fields store canonical server metadata (`server_name`, `version`, timestamps, status), while `search_text` plus supporting indices power LIKE filtering. Optional columns cache blob icon references and MCP capability flags as JSON strings for future expansion. See [`backend/database/migrations.ts`](backend/database/migrations.ts) for the full definition.\n- **Query behavior:** All writes validate against the SDK Zod schemas, recompute `is_latest`, and derive search tokens before persisting. Reads enforce the same schemas, use cursor-based pagination (base64url of `updatedAt`, `serverNameLower`, `version`), and currently treat blob columns as placeholders until the blob ingestion plan lands.\n\n## Plan\n\n- [x] Validate the Open API spec is 100% up to date with upstream 2025-09-29 release\n- [x] Create database tables that meet the Open API spec using Val.Town SQLite/Blobs and the Zod types in `npm:mcp-registry-spec-sdk`\n- [x] Create Hono endpoints (additional integration tests pending)\n- [ ] Wire marketplaceIcon ingestion into publish/update flows\n- [ ] Implement official auth exchanges (GitHub/DNS/HTTP/OIDC) and namespace enforcement\n- [ ] Enforce package ownership, remote URL, registry allowlist, and `_meta` constraints during publish/update\n- [x] Add `/metrics` endpoint and enhanced health checks, then update README/testing guidance\n\n### Manual Test Checklist\n\n- Publish a new server via POST /v0/publish and confirm the response validates against the SDK schema.\n- Publish a server with a remote/data-URL `marketplaceIcon` and verify `blobIconKey/blobIconMime` plus the cached pointer in `_meta`.\n- Fetch GET /v0/servers/{serverName} to verify the latest version flag (`is_latest`) is set correctly.\n- List versions with GET /v0/servers/{serverName}/versions and ensure ordering by `published_at` + `id`.\n- Page through GET /v0/servers with and without `cursor`, confirming `nextCursor` progression.\n- Exercise search by passing tokenized `search` terms and verifying LIKE-based filtering on `search_text`.\n- Update an existing version via PUT /v0/servers/{serverName}/versions/{version} and confirm derived fields recompute, while timestamps behave as expected.\n- Update a version that already has a cached icon and ensure the blob rotates (old key deleted, new key present).\n- Invoke GET /v0/health and confirm uptimeSeconds/timestamp/metrics keys reflect recent activity.\n- Scrape GET /metrics and validate Prometheus exposition format includes publish/update/auth counters and uptime gauge.\n\n### Developer Notes\n\n- Running `deno check main.ts` locally requires allowing remote imports (`deno check --allow-import main.ts`) to satisfy Val Town SDK dependencies.\n\n ## Contact\n\nHey, I'm Cam Pak. [Let me know how I can make this better for you](https://cameronpak.com/contact). \n",[],[228],{"_102":237,"_95":238,"_153":239,"_155":-5,"_156":138,"_157":240,"_159":160,"_104":241,"_99":32,"_162":213,"_164":242,"_165":22,"_166":-5,"_167":243,"_98":244},"262a8096-a0e2-11f0-a7cc-0224a6c84d84","TODO.md","262a8154-a0e2-11f0-a7cc-0224a6c84d84",22,["D",1759555361169],"# TODOs\n\n- [ ] Design DNS/HTTP challenge verification flow (challenge signing, secret storage)\n- [ ] Implement GitHub token/OIDC validation calls with proper error handling\n- [ ] Update OpenAPI spec to document auth and publish endpoints with correct schemas\n- [ ] Adjust error responses to match Problem JSON expectations per spec\n- [ ] Re-test metrics and health outputs after auth refactor",[],[238],{"_102":246,"_95":247,"_153":248,"_155":-5,"_156":138,"_157":249,"_159":160,"_104":250,"_99":251,"_162":213,"_164":252,"_165":22,"_166":-5,"_167":253,"_98":254},"8db9eb8c-a0da-11f0-b260-0224a6c84d84","deno.json","f0a97e2a-a098-11f0-a6a0-0224a6c84d84",16,["D",1759552098946],2,"{\n \"$schema\": \"https://raw.githubusercontent.com/denoland/deno/348900b8b79f4a434cab4c74b3bc8d4d2fa8ee74/cli/schemas/config-file.v1.json\",\n \"lock\": false,\n \"compilerOptions\": {\n \"noImplicitAny\": false,\n \"strict\": true,\n \"types\": [\n \"https://www.val.town/types/valtown.d.ts\"\n ],\n \"lib\": [\n \"dom\",\n \"dom.iterable\",\n \"dom.asynciterable\",\n \"deno.ns\",\n \"deno.unstable\"\n ]\n },\n \"lint\": {\n \"files\": {\n \"indentWidth\": 2,\n \"include\": [\n \"deno:/https/esm.town/**/*\"\n ]\n },\n \"rules\": {\n \"exclude\": [\n \"no-explicit-any\",\n \"no-import-prefix\",\n \"no-unused-vars\"\n ]\n }\n },\n \"node_modules_dir\": false,\n \"experimental\": {\n \"unstable-node-globals\": true,\n \"unstable-temporal\": true,\n \"unstable-worker-options\": true,\n \"unstable-sloppy-imports\": true\n }\n}",[],[247],{"_102":256,"_95":257,"_153":258,"_155":-5,"_156":138,"_157":137,"_159":160,"_104":259,"_99":221,"_162":182,"_164":260,"_165":22,"_166":-5,"_167":261,"_98":262},"263ac500-a0e2-11f0-9cf3-0224a6c84d84","main.ts","51e4ada6-a097-11f0-b09c-0224a6c84d84",["D",1759555361281],"import { Hono } from 'npm:hono@4.9.9';\nimport type { Context } from 'npm:hono@4.9.9';\nimport { HTTPResponseError } from \"npm:hono@4.9.9/types\";\nimport type {\n ErrorModel,\n HealthBody,\n PingBody,\n ServerJSON,\n ServerListResponse,\n ServerResponse,\n} from 'npm:mcp-registry-spec-sdk@0.1.2';\nimport {\n ServerJSONSchema,\n} from 'npm:mcp-registry-spec-sdk@0.1.2';\nimport {\n getLatestServerByName,\n getServerById,\n getServerByNameVersion,\n listServerVersions,\n listServers as listServersQuery,\n publishServerVersion,\n updateServerVersion,\n updateServerStatus,\n} from './backend/database/queries.ts';\n\nconst API_VERSION = '2025-09-29';\nconst START_TIME = Date.now();\nconst metricsState = {\n publishTotal: 0,\n updateTotal: 0,\n authExchanges: new Map(),\n};\n\ntype ServerStatus = 'active' | 'deprecated' | 'deleted';\nconst STATUS_VALUES: readonly ServerStatus[] = ['active', 'deprecated', 'deleted'];\nconst STATUS_SET = new Set(STATUS_VALUES);\n\nfunction isServerStatus(value: string): value is ServerStatus {\n return STATUS_SET.has(value as ServerStatus);\n}\n\ntype RegistryBindings = {\n REGISTRY_AUTH_SECRET?: string;\n GITHUB_AT_SHARED_SECRET?: string;\n GITHUB_OIDC_SHARED_SECRET?: string;\n DNS_SHARED_SECRET?: string;\n HTTP_SHARED_SECRET?: string;\n OIDC_SHARED_SECRET?: string;\n};\n\ntype NormalizedIssue = {\n path: (string | number)[];\n message: string;\n received?: unknown;\n};\n\ntype RegistryTokenClaims = {\n version: 1;\n namespaces: string[];\n methods: string[];\n iat: number;\n exp: number;\n};\n\ntype AuthFieldSpec = {\n names: readonly string[];\n description: string;\n};\n\ntype AuthRequestSpec = {\n required: readonly AuthFieldSpec[];\n extractSecret: (\n body: Record,\n getField: (field: string) => string | undefined,\n ) => string | undefined;\n};\n\nconst TEXT_ENCODER = new TextEncoder();\nconst TEXT_DECODER = new TextDecoder();\nconst HMAC_KEY_CACHE = new Map>();\n\nclass ProblemError extends Error {\n problem: ErrorModel;\n\n constructor(problem: ErrorModel) {\n super(problem.detail ?? problem.title ?? 'Registry error');\n this.problem = problem;\n }\n}\n\nconst app = new Hono<{ Bindings: RegistryBindings }>();\n\napp.onError((err: Error | HTTPResponseError, c: Context) => {\n if (err instanceof ProblemError) {\n return problemResponse(c, (err as ProblemError).problem);\n }\n console.error(err);\n return problemResponse(\n c,\n createProblem(500, 'Internal Server Error', 'An unexpected error occurred.', c),\n );\n});\n\napp.get('/', (c: Context) =>\n c.json({\n message: 'faith.tools MCP Subregistry API',\n documentation: 'https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/api/generic-registry-api.md',\n }),\n);\n\napp.get('/v0/servers', async (c: Context) => {\n const q = c.req.query();\n const cursor = q.cursor ?? undefined;\n const search = q.search ?? undefined;\n const limitRaw = q.limit ?? undefined;\n const limit = limitRaw != null ? Number(limitRaw) : undefined;\n const updatedSinceRaw = q.updated_since ?? q.updatedSince ?? undefined;\n const versionRaw = q.version ?? undefined;\n\n if (limitRaw != null && (Number.isNaN(limit) || limit! <= 0)) {\n throw new ProblemError(\n createProblem(\n 400,\n 'Invalid limit parameter',\n 'limit must be a positive integer.',\n c,\n [\n {\n location: 'query.limit',\n message: 'Expected positive integer',\n value: limitRaw,\n },\n ],\n ),\n );\n }\n\n let updatedSince: string | undefined;\n if (updatedSinceRaw != null) {\n const parsedDate = new Date(updatedSinceRaw);\n if (Number.isNaN(parsedDate.getTime())) {\n throw new ProblemError(\n createProblem(\n 400,\n 'Invalid updated_since parameter',\n 'updated_since must be a valid RFC3339 timestamp.',\n c,\n [\n {\n location: 'query.updated_since',\n message: 'Expected RFC3339 timestamp',\n value: updatedSinceRaw,\n },\n ],\n ),\n );\n }\n updatedSince = parsedDate.toISOString();\n }\n\n const version = typeof versionRaw === 'string' && versionRaw.trim().length > 0\n ? versionRaw.trim()\n : undefined;\n\n const result: ServerListResponse = await listServersQuery({\n cursor,\n limit,\n search,\n updatedSince,\n version,\n });\n\n return c.json(result);\n});\n\napp.get('/v0/servers/:id{[0-9]+}', async (c: Context) => {\n const idParam = c.req.param('id');\n const id = Number(idParam);\n if (!Number.isInteger(id) || id <= 0) {\n throw new ProblemError(\n createProblem(\n 400,\n 'Invalid server id',\n 'id must be a positive integer.',\n c,\n [\n {\n location: 'path.id',\n message: 'Expected positive integer',\n value: idParam,\n },\n ],\n ),\n );\n }\n\n const result = await getServerById(id);\n if (!result) {\n throw new ProblemError(\n createProblem(404, 'Server not found', `No server registered with id ${id}.`, c),\n );\n }\n return c.json(result);\n});\n\napp.get('/v0/servers/:serverName', async (c: Context) => {\n const serverName = decodePathParam(c.req.param('serverName'));\n const result = await getLatestServerByName(serverName);\n if (!result) {\n throw new ProblemError(\n createProblem(404, 'Server not found', `No server registered for ${serverName}.`, c),\n );\n }\n return c.json(result);\n});\n\napp.get('/v0/servers/:serverName/versions', async (c: Context) => {\n const serverName = decodePathParam(c.req.param('serverName'));\n const versions: ServerResponse[] = await listServerVersions(serverName);\n return c.json(versions);\n});\n\napp.get('/v0/servers/:serverName/versions/:version', async (c: Context) => {\n const serverName = decodePathParam(c.req.param('serverName'));\n const version = decodePathParam(c.req.param('version'));\n const result = await getServerByNameVersion(serverName, version);\n if (!result) {\n throw new ProblemError(\n createProblem(\n 404,\n 'Server version not found',\n `No version ${version} found for ${serverName}.`,\n c,\n ),\n );\n }\n return c.json(result);\n});\n\napp.post('/v0/publish', async (c: Context) => {\n const auth = await ensurePublishAuth(c);\n const payload = await readJson(c);\n\n const parsed = await ServerJSONSchema.safeParseAsync(payload);\n if (!parsed.success) {\n const issues = toValidationIssues(parsed.error.issues);\n throw new ProblemError(\n createValidationProblem(\n 422,\n 'Invalid server payload',\n 'Request body failed validation.',\n c,\n issues,\n ),\n );\n }\n\n assertNamespaceAuthorized(auth, parsed.data.name, c);\n validateOfficialPolicies(parsed.data, c);\n\n const result = await publishServerVersion(parsed.data);\n metricsState.publishTotal += 1;\n return c.json(result);\n});\n\napp.put('/v0/servers/:serverName/versions/:version', async (c: Context) => {\n const auth = await ensurePublishAuth(c);\n const serverName = decodePathParam(c.req.param('serverName'));\n const version = decodePathParam(c.req.param('version'));\n const statusParamRaw = c.req.query('status');\n let desiredStatus: ServerStatus | undefined;\n\n if (statusParamRaw != null) {\n const normalized = statusParamRaw.trim().toLowerCase();\n if (!isServerStatus(normalized)) {\n throw new ProblemError(\n createProblem(\n 400,\n 'Invalid status parameter',\n 'status must be one of active, deprecated, or deleted.',\n c,\n [\n {\n location: 'query.status',\n message: 'Expected active, deprecated, or deleted',\n value: statusParamRaw,\n },\n ],\n ),\n );\n }\n desiredStatus = normalized;\n }\n\n const payload = await readJson(c);\n\n const parsed = await ServerJSONSchema.safeParseAsync(payload);\n if (!parsed.success) {\n const issues = toValidationIssues(parsed.error.issues);\n throw new ProblemError(\n createValidationProblem(\n 422,\n 'Invalid server payload',\n 'Request body failed validation.',\n c,\n issues,\n ),\n );\n }\n\n if (parsed.data.name.toLowerCase() !== serverName.toLowerCase()) {\n throw new ProblemError(\n createProblem(\n 409,\n 'Server name mismatch',\n 'Path serverName does not match payload.name.',\n c,\n [\n {\n location: 'body.name',\n message: `Expected ${serverName}`,\n value: parsed.data.name,\n },\n ],\n ),\n );\n }\n\n if (parsed.data.version !== version) {\n throw new ProblemError(\n createProblem(\n 409,\n 'Version mismatch',\n 'Path version does not match payload.version.',\n c,\n [\n {\n location: 'body.version',\n message: `Expected ${version}`,\n value: parsed.data.version,\n },\n ],\n ),\n );\n }\n\n assertNamespaceAuthorized(auth, parsed.data.name, c);\n validateOfficialPolicies(parsed.data, c);\n\n let versionResponse: ServerResponse;\n try {\n versionResponse = await updateServerVersion(serverName, version, parsed.data);\n } catch (err) {\n const error = err as { code?: string; message?: string };\n if (error.code === 'ImmutableVersionConflict') {\n throw new ProblemError(\n createProblem(\n 409,\n 'Immutable server version',\n 'Published server versions are immutable. Publish a new version to change metadata.',\n c,\n ),\n );\n }\n if (error.message === 'Server version not found') {\n throw new ProblemError(\n createProblem(\n 404,\n 'Server version not found',\n `No version ${version} found for ${serverName}.`,\n c,\n ),\n );\n }\n throw err;\n }\n\n const officialMeta = versionResponse._meta?.['io.modelcontextprotocol.registry/official'] as\n | { status?: string }\n | undefined;\n const currentStatus = (officialMeta?.status ?? 'active').toLowerCase() as ServerStatus;\n\n let finalResponse = versionResponse;\n if (desiredStatus && desiredStatus !== currentStatus) {\n try {\n finalResponse = await updateServerStatus(serverName, version, desiredStatus);\n } catch (err) {\n const error = err as { code?: string; message?: string };\n if (error.message === 'Server version not found') {\n throw new ProblemError(\n createProblem(\n 404,\n 'Server version not found',\n `No version ${version} found for ${serverName}.`,\n c,\n ),\n );\n }\n if (error.code === 'StatusTransitionNotAllowed') {\n throw new ProblemError(\n createProblem(\n 409,\n 'Invalid status transition',\n 'Deleted versions cannot transition back to active or deprecated.',\n c,\n [\n {\n location: 'query.status',\n message: 'Cannot transition from deleted to another status',\n value: desiredStatus,\n },\n ],\n ),\n );\n }\n throw err;\n }\n }\n\n metricsState.updateTotal += 1;\n return c.json(finalResponse);\n});\n\napp.get('/v0/health', (c: Context) => {\n const uptimeSeconds = Math.floor((Date.now() - START_TIME) / 1000);\n const payload: HealthBody & {\n uptimeSeconds: number;\n timestamp: string;\n metrics: { publishTotal: number; updateTotal: number; authExchangeTotal: number };\n } = {\n status: 'ok',\n uptimeSeconds,\n timestamp: new Date().toISOString(),\n metrics: {\n publishTotal: metricsState.publishTotal,\n updateTotal: metricsState.updateTotal,\n authExchangeTotal: Array.from(metricsState.authExchanges.values()).reduce(\n (sum, value) => sum + value,\n 0,\n ),\n },\n };\n return c.json(payload);\n});\n\napp.get('/v0/ping', (c: Context) => {\n const payload: PingBody = {\n environment: 'subregistry',\n version: API_VERSION,\n };\n return c.json(payload);\n});\n\napp.post('/v0/auth/github-at', (c: Context) =>\n handleAuthExchange(c, {\n method: 'github-at',\n secretEnvKey: 'GITHUB_AT_SHARED_SECRET',\n namespaceMode: 'github',\n request: {\n required: [\n { names: ['github_access_token'], description: 'GitHub access token' },\n ],\n extractSecret: (_body, getField) => getField('github_access_token'),\n },\n }),\n);\n\napp.post('/v0/auth/github-oidc', (c: Context) =>\n handleAuthExchange(c, {\n method: 'github-oidc',\n secretEnvKey: 'GITHUB_OIDC_SHARED_SECRET',\n namespaceMode: 'github',\n request: {\n required: [\n { names: ['github_oidc_token'], description: 'GitHub OIDC token' },\n ],\n extractSecret: (_body, getField) => getField('github_oidc_token'),\n },\n }),\n);\n\napp.post('/v0/auth/dns', (c: Context) =>\n handleAuthExchange(c, {\n method: 'dns',\n secretEnvKey: 'DNS_SHARED_SECRET',\n namespaceMode: 'domain',\n request: {\n required: [\n { names: ['challenge'], description: 'DNS challenge' },\n { names: ['dns_record', 'dnsRecord'], description: 'DNS record' },\n ],\n extractSecret: (_body, getField) => getField('challenge'),\n },\n }),\n);\n\napp.post('/v0/auth/http', (c: Context) =>\n handleAuthExchange(c, {\n method: 'http',\n secretEnvKey: 'HTTP_SHARED_SECRET',\n namespaceMode: 'domain',\n request: {\n required: [\n { names: ['challenge'], description: 'HTTP challenge' },\n { names: ['signature'], description: 'HTTP challenge signature' },\n ],\n extractSecret: (_body, getField) => getField('signature'),\n },\n }),\n);\n\napp.post('/v0/auth/oidc', (c: Context) =>\n handleAuthExchange(c, {\n method: 'oidc',\n secretEnvKey: 'OIDC_SHARED_SECRET',\n namespaceMode: 'generic',\n request: {\n required: [\n { names: ['oidc_token', 'google_oidc_token'], description: 'OIDC token' },\n ],\n extractSecret: (_body, getField) =>\n getField('oidc_token') ?? getField('google_oidc_token'),\n },\n }),\n);\n\napp.get('/metrics', (c: Context) => {\n const uptimeSeconds = Math.floor((Date.now() - START_TIME) / 1000);\n const lines: string[] = [];\n lines.push('# HELP registry_publish_total Total successful server publish operations.');\n lines.push('# TYPE registry_publish_total counter');\n lines.push(`registry_publish_total ${metricsState.publishTotal}`);\n\n lines.push('# HELP registry_update_total Total successful server update operations.');\n lines.push('# TYPE registry_update_total counter');\n lines.push(`registry_update_total ${metricsState.updateTotal}`);\n\n lines.push('# HELP registry_auth_exchange_total Total auth exchanges by method.');\n lines.push('# TYPE registry_auth_exchange_total counter');\n for (const [method, count] of metricsState.authExchanges.entries()) {\n lines.push(`registry_auth_exchange_total{method=\"${method}\"} ${count}`);\n }\n\n lines.push('# HELP registry_uptime_seconds Process uptime in seconds.');\n lines.push('# TYPE registry_uptime_seconds gauge');\n lines.push(`registry_uptime_seconds ${uptimeSeconds}`);\n\n return new Response(lines.join('\\n') + '\\n', {\n status: 200,\n headers: {\n 'content-type': 'text/plain; version=0.0.4',\n },\n });\n});\n\nexport default app.fetch;\n\nasync function ensurePublishAuth(\n c: Context<{ Bindings: RegistryBindings }>,\n): Promise {\n const secret = c.env?.REGISTRY_AUTH_SECRET;\n if (!secret) {\n throw new ProblemError(\n createProblem(\n 500,\n 'Server configuration error',\n 'REGISTRY_AUTH_SECRET is not configured for this subregistry.',\n c,\n ),\n );\n }\n const header = c.req.header('authorization');\n if (!header?.startsWith('Bearer ')) {\n throw new ProblemError(\n createProblem(401, 'Unauthorized', 'Bearer token is required for this operation.', c),\n );\n }\n const token = header.slice('Bearer '.length).trim();\n const claims = await verifyRegistryToken(token, secret, c);\n if (claims.exp * 1000 <= Date.now()) {\n throw new ProblemError(\n createProblem(401, 'Unauthorized', 'Registry token has expired.', c),\n );\n }\n return claims;\n}\n\nasync function readJson(c: Context<{ Bindings: RegistryBindings }>): Promise {\n try {\n return await c.req.json();\n } catch {\n throw new ProblemError(\n createProblem(400, 'Invalid JSON body', 'Failed to parse request body as JSON.', c),\n );\n }\n}\n\nexport type IssueTokenParams = {\n namespaces: string[];\n method: string;\n secret: string | undefined;\n expiresInSeconds?: number;\n context: Context<{ Bindings: RegistryBindings }>;\n};\n\nexport type AuthMethodConfig = {\n method: string;\n secretEnvKey: keyof RegistryBindings;\n namespaceMode: 'github' | 'domain' | 'generic';\n request: AuthRequestSpec;\n};\n\nasync function handleAuthExchange(\n c: Context<{ Bindings: RegistryBindings }>,\n config: AuthMethodConfig,\n): Promise {\n const sharedSecret = c.env?.[config.secretEnvKey];\n if (!sharedSecret) {\n throw new ProblemError(\n createProblem(\n 501,\n 'Not Implemented',\n `${config.method} auth exchange is not configured on this subregistry.`,\n c,\n ),\n );\n }\n\n const body = await readJson>(c);\n\n const fieldValues = new Map();\n for (const spec of config.request.required) {\n let matchedValue: string | undefined;\n let matchedField: string | undefined;\n for (const fieldName of spec.names) {\n const raw = body[fieldName];\n if (typeof raw === 'string') {\n const trimmed = raw.trim();\n if (trimmed.length > 0) {\n matchedValue = trimmed;\n matchedField = fieldName;\n break;\n }\n }\n }\n if (!matchedValue || !matchedField) {\n const primary = spec.names[0];\n throw new ProblemError(\n createProblem(\n 400,\n 'Invalid request',\n `${spec.description} is required.`,\n c,\n [\n {\n location: `body.${primary}`,\n message: `Expected ${spec.description} as a non-empty string.`,\n },\n ],\n ),\n );\n }\n for (const alias of spec.names) {\n if (!fieldValues.has(alias)) {\n fieldValues.set(alias, matchedValue);\n }\n }\n }\n\n const getField = (field: string): string | undefined => {\n const cached = fieldValues.get(field);\n if (cached) {\n return cached;\n }\n const raw = body[field];\n if (typeof raw === 'string') {\n const trimmed = raw.trim();\n return trimmed.length > 0 ? trimmed : undefined;\n }\n return undefined;\n };\n\n const credential = config.request.extractSecret(body, getField);\n if (!credential) {\n const hint = config.request.required[0]?.names[0] ?? 'credential';\n throw new ProblemError(\n createProblem(\n 400,\n 'Invalid request',\n `Missing credential required for ${config.method} authentication.`,\n c,\n [\n {\n location: `body.${hint}`,\n message: 'Provide a non-empty credential value.',\n },\n ],\n ),\n );\n }\n\n if (credential !== sharedSecret) {\n throw new ProblemError(\n createProblem(401, 'Unauthorized', `Authentication failed for ${config.method}.`, c),\n );\n }\n\n const namespacesRaw = body['namespaces'];\n if (!Array.isArray(namespacesRaw) || namespacesRaw.length === 0) {\n throw new ProblemError(\n createProblem(400, 'Invalid request', 'namespaces must be a non-empty array of strings.', c),\n );\n }\n const namespacesInput: string[] = [];\n for (const ns of namespacesRaw) {\n if (typeof ns !== 'string') {\n throw new ProblemError(\n createProblem(\n 400,\n 'Invalid request',\n 'namespaces must only contain string values.',\n c,\n ),\n );\n }\n namespacesInput.push(ns);\n }\n\n let expiresInSeconds: number | undefined;\n const expiresRaw =\n body['expires_in_seconds'] ??\n body['expiresInSeconds'];\n if (typeof expiresRaw === 'number' && Number.isFinite(expiresRaw)) {\n expiresInSeconds = expiresRaw;\n } else if (typeof expiresRaw === 'string' && expiresRaw.trim()) {\n const parsed = Number(expiresRaw);\n if (!Number.isNaN(parsed) && Number.isFinite(parsed)) {\n expiresInSeconds = parsed;\n }\n }\n\n const normalizedNamespaces = normalizeNamespaceList(namespacesInput);\n validateNamespaceList(normalizedNamespaces, config.namespaceMode, c);\n\n const { token, claims } = await issueRegistryToken({\n namespaces: normalizedNamespaces,\n method: config.method,\n secret: c.env?.REGISTRY_AUTH_SECRET,\n expiresInSeconds,\n context: c,\n });\n recordAuthExchange(config.method);\n\n return c.json({\n token,\n registry_token: token,\n expires_at: new Date(claims.exp * 1000).toISOString(),\n namespaces: claims.namespaces,\n methods: claims.methods,\n });\n}\n\nfunction normalizeNamespaceList(values: string[]): string[] {\n const unique = new Set();\n for (const raw of values) {\n const normalized = raw.trim().toLowerCase();\n if (normalized) {\n unique.add(normalized);\n }\n }\n return Array.from(unique);\n}\n\nfunction validateNamespaceList(\n namespaces: string[],\n mode: 'github' | 'domain' | 'generic',\n c: Context<{ Bindings: RegistryBindings }>,\n): void {\n if (namespaces.length === 0) {\n throw new ProblemError(\n createProblem(400, 'Invalid request', 'At least one namespace must be provided.', c),\n );\n }\n\n const invalid: string[] = [];\n for (const ns of namespaces) {\n if (!isNamespaceFormatValid(ns) || !namespaceModeMatches(ns, mode)) {\n invalid.push(ns);\n }\n }\n\n if (invalid.length > 0) {\n throw new ProblemError(\n createProblem(\n 400,\n 'Invalid namespaces',\n `The following namespaces are invalid for ${mode} auth: ${invalid.join(', ')}`,\n c,\n ),\n );\n }\n}\n\nfunction isNamespaceFormatValid(ns: string): boolean {\n if (!ns) return false;\n const segments = ns.split('.');\n if (segments.length === 0) return false;\n return segments.every((segment) => /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(segment));\n}\n\nfunction namespaceModeMatches(ns: string, mode: 'github' | 'domain' | 'generic'): boolean {\n if (mode === 'github') {\n return ns.startsWith('io.github.') && ns.split('.').length >= 3;\n }\n if (mode === 'domain') {\n const segments = ns.split('.');\n return segments.length >= 2 && segments.every(Boolean);\n }\n return true;\n}\n\nfunction namespaceIsAllowed(allowed: string, actual: string): boolean {\n if (actual === allowed) return true;\n return actual.startsWith(`${allowed}.`);\n}\n\nfunction extractNamespacePrefix(serverName: string): string {\n const trimmed = serverName.trim().toLowerCase();\n if (!trimmed) return '';\n const slashIndex = trimmed.indexOf('/');\n return slashIndex === -1 ? trimmed : trimmed.slice(0, slashIndex);\n}\n\nfunction assertNamespaceAuthorized(\n claims: RegistryTokenClaims,\n serverName: string,\n c: Context<{ Bindings: RegistryBindings }>,\n): void {\n const namespace = extractNamespacePrefix(serverName);\n if (!namespace) {\n throw new ProblemError(\n createProblem(\n 400,\n 'Invalid server name',\n 'Server name must include a namespace prefix (e.g., io.github.user/server).',\n c,\n ),\n );\n }\n\n const authorized = claims.namespaces.some((allowed) => namespaceIsAllowed(allowed, namespace));\n if (!authorized) {\n throw new ProblemError(\n createProblem(\n 403,\n 'Forbidden',\n `Token is not authorized for namespace ${namespace}.`,\n c,\n ),\n );\n }\n}\n\nasync function issueRegistryToken(params: IssueTokenParams): Promise<{\n token: string;\n claims: RegistryTokenClaims;\n}> {\n const { namespaces, method, secret, expiresInSeconds, context } = params;\n if (!secret) {\n throw new ProblemError(\n createProblem(\n 500,\n 'Server configuration error',\n 'REGISTRY_AUTH_SECRET is not configured for this subregistry.',\n context,\n ),\n );\n }\n\n const uniqueNamespaces = Array.from(new Set(namespaces)).sort();\n const issuedAt = Math.floor(Date.now() / 1000);\n const ttl = expiresInSeconds != null && Number.isFinite(expiresInSeconds)\n ? Math.min(Math.max(Math.floor(expiresInSeconds), 60), 86_400)\n : 3_600;\n const claims: RegistryTokenClaims = {\n version: 1,\n namespaces: uniqueNamespaces,\n methods: [method],\n iat: issuedAt,\n exp: issuedAt + ttl,\n };\n\n const token = await signRegistryToken(claims, secret);\n return { token, claims };\n}\n\nasync function signRegistryToken(claims: RegistryTokenClaims, secret: string): Promise {\n const header = { alg: 'HS256', typ: 'JWT' };\n const headerSegment = base64UrlEncodeString(JSON.stringify(header));\n const payloadSegment = base64UrlEncodeString(JSON.stringify(claims));\n const data = `${headerSegment}.${payloadSegment}`;\n const key = await getHmacKey(secret);\n const signatureBuffer = await crypto.subtle.sign('HMAC', key, TEXT_ENCODER.encode(data));\n const signatureSegment = base64UrlEncode(new Uint8Array(signatureBuffer));\n return `${data}.${signatureSegment}`;\n}\n\nasync function verifyRegistryToken(\n token: string,\n secret: string,\n c: Context<{ Bindings: RegistryBindings }>,\n): Promise {\n const parts = token.split('.');\n if (parts.length !== 3) {\n throw new ProblemError(\n createProblem(401, 'Unauthorized', 'Invalid registry token format.', c),\n );\n }\n\n const [headerSegment, payloadSegment, signatureSegment] = parts;\n const data = `${headerSegment}.${payloadSegment}`;\n const key = await getHmacKey(secret);\n const signatureBytes = base64UrlDecode(signatureSegment);\n const signatureCopy = new Uint8Array(signatureBytes);\n const verified = await crypto.subtle.verify(\n 'HMAC',\n key,\n signatureCopy,\n TEXT_ENCODER.encode(data),\n );\n if (!verified) {\n throw new ProblemError(\n createProblem(401, 'Unauthorized', 'Registry token signature is invalid.', c),\n );\n }\n\n try {\n const claimsJson = base64UrlDecodeToString(payloadSegment);\n return normalizeClaims(JSON.parse(claimsJson), c);\n } catch {\n throw new ProblemError(\n createProblem(401, 'Unauthorized', 'Registry token payload could not be parsed.', c),\n );\n }\n}\n\nfunction normalizeClaims(\n raw: unknown,\n c: Context<{ Bindings: RegistryBindings }>,\n): RegistryTokenClaims {\n if (!raw || typeof raw !== 'object') {\n throw new ProblemError(\n createProblem(401, 'Unauthorized', 'Registry token payload is malformed.', c),\n );\n }\n\n const obj = raw as Record;\n if (obj['version'] !== 1) {\n throw new ProblemError(\n createProblem(401, 'Unauthorized', 'Registry token version is unsupported.', c),\n );\n }\n\n const namespacesRaw = obj['namespaces'];\n if (!Array.isArray(namespacesRaw) || namespacesRaw.length === 0) {\n throw new ProblemError(\n createProblem(401, 'Unauthorized', 'Registry token namespaces are missing.', c),\n );\n }\n const namespaceStrings: string[] = [];\n for (const ns of namespacesRaw) {\n if (typeof ns !== 'string') {\n throw new ProblemError(\n createProblem(401, 'Unauthorized', 'Registry token namespaces are invalid.', c),\n );\n }\n namespaceStrings.push(ns);\n }\n const namespaces = normalizeNamespaceList(namespaceStrings);\n validateNamespaceList(namespaces, 'generic', c);\n\n const methodsRaw = Array.isArray(obj['methods']) ? obj['methods'] : [];\n const methods: string[] = [];\n for (const method of methodsRaw) {\n if (typeof method === 'string' && method.trim()) {\n methods.push(method.trim());\n }\n }\n if (methods.length === 0) {\n methods.push('unknown');\n }\n\n const iat = Number(obj['iat']);\n const exp = Number(obj['exp']);\n if (!Number.isFinite(iat) || !Number.isFinite(exp) || exp <= iat) {\n throw new ProblemError(\n createProblem(401, 'Unauthorized', 'Registry token timestamps are invalid.', c),\n );\n }\n\n return {\n version: 1,\n namespaces,\n methods,\n iat: Math.floor(iat),\n exp: Math.floor(exp),\n };\n}\n\nfunction base64UrlEncode(data: Uint8Array): string {\n let binary = '';\n for (const byte of data) {\n binary += String.fromCharCode(byte);\n }\n return btoa(binary).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/g, '');\n}\n\nfunction base64UrlEncodeString(value: string): string {\n return base64UrlEncode(TEXT_ENCODER.encode(value));\n}\n\nfunction base64UrlDecode(value: string): Uint8Array {\n const padLength = (4 - (value.length % 4)) % 4;\n const padded = value.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat(padLength);\n const binary = atob(padded);\n const bytes = new Uint8Array(binary.length);\n for (let i = 0; i < binary.length; i++) {\n bytes[i] = binary.charCodeAt(i);\n }\n return bytes;\n}\n\nfunction base64UrlDecodeToString(value: string): string {\n return TEXT_DECODER.decode(base64UrlDecode(value));\n}\n\nasync function getHmacKey(secret: string): Promise {\n let cached = HMAC_KEY_CACHE.get(secret);\n if (!cached) {\n cached = crypto.subtle.importKey(\n 'raw',\n TEXT_ENCODER.encode(secret),\n { name: 'HMAC', hash: 'SHA-256' },\n false,\n ['sign', 'verify'],\n );\n HMAC_KEY_CACHE.set(secret, cached);\n }\n return cached;\n}\n\nfunction validateOfficialPolicies(\n payload: ServerJSON,\n c: Context<{ Bindings: RegistryBindings }>,\n): void {\n const namespace = extractNamespacePrefix(payload.name ?? '');\n if (!namespace) {\n throw new ProblemError(\n createProblem(\n 400,\n 'Invalid server name',\n 'Server name must include a namespace prefix before the first slash.',\n c,\n ),\n );\n }\n\n validateMetaNamespace(payload as Record, c);\n validatePackagesNamespace(payload as Record, namespace, c);\n validateRemoteNamespace(payload as Record, namespace, c);\n}\n\nfunction validateMetaNamespace(\n payload: Record,\n c: Context<{ Bindings: RegistryBindings }>,\n): void {\n const meta = payload._meta;\n if (meta == null) return;\n if (typeof meta !== 'object' || Array.isArray(meta)) {\n throw new ProblemError(\n createProblem(\n 422,\n 'Invalid `_meta` field',\n '_meta must be an object containing only the `publisher` key.',\n c,\n ),\n );\n }\n\n const metaRecord = meta as Record;\n const invalidKeys = Object.keys(metaRecord).filter((key) => key !== 'publisher');\n if (invalidKeys.length > 0) {\n throw new ProblemError(\n createProblem(\n 422,\n 'Invalid `_meta` field',\n `_meta may only contain the \\`publisher\\` key when publishing to the official registry.`,\n c,\n invalidKeys.map((key) => ({\n location: `_meta.${key}`,\n message: 'Unexpected key present in `_meta`.',\n })),\n ),\n );\n }\n\n try {\n const serialized = JSON.stringify(metaRecord);\n if (serialized.length > 4096) {\n throw new ProblemError(\n createProblem(\n 413,\n '_meta too large',\n '_meta.publisher must be at most 4KB when serialized.',\n c,\n ),\n );\n }\n } catch {\n throw new ProblemError(\n createProblem(\n 422,\n 'Invalid `_meta` field',\n 'Failed to serialize `_meta.publisher` while checking size limits.',\n c,\n ),\n );\n }\n}\n\nconst PACKAGE_REGISTRY_BASE_URLS: Record = {\n npm: 'https://registry.npmjs.org',\n pypi: 'https://pypi.org',\n nuget: 'https://api.nuget.org',\n oci: 'https://docker.io',\n mcpb: null,\n};\n\nfunction validatePackagesNamespace(\n payload: Record,\n namespace: string,\n c: Context<{ Bindings: RegistryBindings }>,\n): void {\n const packages = Array.isArray(payload.packages) ? payload.packages : [];\n for (const [index, pkg] of packages.entries()) {\n if (!pkg || typeof pkg !== 'object') {\n throw new ProblemError(\n createProblem(\n 422,\n 'Invalid package entry',\n `packages[${index}] must be an object describing a package option.`,\n c,\n ),\n );\n }\n const pkgRecord = pkg as Record;\n const registryType = (pkgRecord.registryType ??\n pkgRecord.registry_type) as string | undefined;\n if (!registryType || !(registryType in PACKAGE_REGISTRY_BASE_URLS)) {\n throw new ProblemError(\n createProblem(\n 422,\n 'Unsupported package registry',\n `packages[${index}].registryType must be one of npm, pypi, nuget, oci, or mcpb.`,\n c,\n ),\n );\n }\n\n const identifier = (pkgRecord.identifier ?? pkgRecord.name) as string | undefined;\n if (!identifier || typeof identifier !== 'string') {\n throw new ProblemError(\n createProblem(\n 422,\n 'Missing package identifier',\n `packages[${index}] must include an identifier string.`,\n c,\n ),\n );\n }\n\n const baseUrl = (pkgRecord.registryBaseUrl ??\n pkgRecord.registry_base_url) as string | undefined;\n const allowedBase = PACKAGE_REGISTRY_BASE_URLS[registryType];\n if (allowedBase) {\n if (!baseUrl || baseUrl !== allowedBase) {\n throw new ProblemError(\n createProblem(\n 422,\n 'Disallowed registry base URL',\n `packages[${index}] must use registry_base_url \"${allowedBase}\".`,\n c,\n ),\n );\n }\n }\n\n if (registryType === 'mcpb') {\n const identifierHasMcp = identifier.toLowerCase().includes('mcp');\n if (!identifierHasMcp) {\n throw new ProblemError(\n createProblem(\n 422,\n 'Invalid MCPB identifier',\n `packages[${index}].identifier must contain \"mcp\" when publishing MCPB bundles.`,\n c,\n ),\n );\n }\n\n const sha =\n (pkgRecord.fileSha256 as string | undefined) ??\n (pkgRecord.file_sha256 as string | undefined);\n if (!sha || !/^[a-f0-9]{64}$/i.test(sha)) {\n throw new ProblemError(\n createProblem(\n 422,\n 'Missing MCPB SHA-256',\n `packages[${index}] must include file_sha256 with a 64-character hex digest.`,\n c,\n ),\n );\n }\n\n if (!identifier.startsWith('https://github.com/') && !identifier.startsWith('https://gitlab.com/')) {\n throw new ProblemError(\n createProblem(\n 422,\n 'Unsupported MCPB host',\n `packages[${index}].identifier must point to a GitHub or GitLab release asset.`,\n c,\n ),\n );\n }\n }\n }\n}\n\nfunction validateRemoteNamespace(\n payload: Record,\n namespace: string,\n c: Context<{ Bindings: RegistryBindings }>,\n): void {\n const remotes = Array.isArray(payload.remotes) ? payload.remotes : [];\n if (remotes.length === 0) return;\n\n const domain = namespaceToDomain(namespace);\n for (const [index, remote] of remotes.entries()) {\n if (!remote || typeof remote !== 'object') {\n throw new ProblemError(\n createProblem(\n 422,\n 'Invalid remote entry',\n `remotes[${index}] must be an object describing a remote transport.`,\n c,\n ),\n );\n }\n const remoteRecord = remote as Record;\n const urlRaw = remoteRecord.url as string | undefined;\n if (!urlRaw) {\n throw new ProblemError(\n createProblem(422, 'Missing remote URL', `remotes[${index}] is missing a url.`, c),\n );\n }\n\n let parsed: URL;\n try {\n parsed = new URL(urlRaw);\n } catch {\n throw new ProblemError(\n createProblem(\n 422,\n 'Invalid remote URL',\n `remotes[${index}].url must be a valid absolute URL.`,\n c,\n ),\n );\n }\n\n if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {\n throw new ProblemError(\n createProblem(\n 422,\n 'Unsupported remote protocol',\n `remotes[${index}].url must use http or https.`,\n c,\n ),\n );\n }\n\n if (domain) {\n const host = parsed.hostname.toLowerCase();\n if (host !== domain && !host.endsWith(`.${domain}`)) {\n throw new ProblemError(\n createProblem(\n 422,\n 'Remote URL mismatch',\n `remotes[${index}].url must be hosted on ${domain} or its subdomains for namespace ${namespace}.`,\n c,\n ),\n );\n }\n }\n }\n}\n\nfunction namespaceToDomain(namespace: string): string | null {\n const lower = namespace.toLowerCase();\n if (lower.startsWith('io.github.')) {\n return null;\n }\n const segments = lower.split('.');\n if (segments.length < 2) {\n return null;\n }\n const reversed = [...segments].reverse();\n return reversed.join('.');\n}\n\nfunction decodePathParam(value: string): string {\n try {\n return decodeURIComponent(value);\n } catch {\n return value;\n }\n}\n\nfunction createProblem(\n status: number,\n title: string,\n detail: string,\n c: Context<{ Bindings: RegistryBindings }>,\n errors?: ErrorModel['errors'],\n): ErrorModel {\n return {\n type: 'about:blank',\n title,\n status,\n detail,\n instance: c.req.path,\n errors: errors?.length ? errors : undefined,\n };\n}\n\nfunction createValidationProblem(\n status: number,\n title: string,\n detail: string,\n c: Context<{ Bindings: RegistryBindings }>,\n issues: NormalizedIssue[],\n): ErrorModel {\n const errors = issues.map((issue) => ({\n location: issue.path.length ? issue.path.join('.') : 'body',\n message: issue.message,\n value: issue.received,\n }));\n return createProblem(status, title, detail, c, errors);\n}\n\nfunction problemResponse(\n c: Context<{ Bindings: RegistryBindings }>,\n problem: ErrorModel,\n): Response {\n const status = problem.status ?? 500;\n return new Response(JSON.stringify(problem), {\n status,\n headers: {\n 'content-type': 'application/problem+json',\n },\n });\n}\n\nfunction toValidationIssues(\n issues: ReadonlyArray<{ path: (string | number)[]; message: string }>,\n): NormalizedIssue[] {\n return issues.map((issue) => ({\n path: Array.isArray(issue.path) ? issue.path : [],\n message: issue.message ?? 'Invalid value',\n received: (issue as Record).received,\n }));\n}\n\nfunction recordAuthExchange(method: string): void {\n const current = metricsState.authExchanges.get(method) ?? 0;\n metricsState.authExchanges.set(method, current + 1);\n}\n",[],[257],{"_102":264,"_95":265,"_153":266,"_155":-5,"_156":138,"_157":267,"_159":160,"_104":268,"_99":251,"_162":213,"_164":269,"_165":22,"_166":-5,"_167":270,"_98":271},"8dd57762-a0da-11f0-9c9b-0224a6c84d84","openapi.yaml","f0ba5fba-a098-11f0-826f-0224a6c84d84",21,["D",1759552099110],"openapi: 3.1.0\njsonSchemaDialect: \"https://json-schema.org/draft/2020-12/schema\"\n$id: https://modelcontextprotocol.io/schemas/draft/2025-09-29/server-registry-openapi\ninfo:\n title: MCP Server Registry API\n version: \"2025-09-29\"\n summary: API for discovering and accessing MCP server metadata\n description: |\n Specification for a theoretical REST API that serves metadata about MCP servers.\n license:\n name: MIT\n identifier: MIT\n\npaths:\n /v0/servers:\n get:\n summary: List MCP servers\n description: Returns a list of all registered MCP servers.\n parameters:\n - name: cursor\n in: query\n description: |\n Pagination cursor for retrieving the next set of results.\n\n Cursors are opaque strings returned in the metadata.nextCursor field of paginated responses.\n required: false\n schema:\n type: string\n - name: limit\n in: query\n description: Maximum number of items to return\n required: false\n schema:\n type: integer\n responses:\n '200':\n description: A list of MCP servers\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/ServerList'\n default:\n description: Error payload\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/Problem'\n\n /v0/servers/{serverName}:\n get:\n summary: Get MCP server details\n description: Returns the latest version of a specific MCP server.\n parameters:\n - name: serverName\n in: path\n required: true\n description: URL-encoded server name (e.g., \"com.example%2Fmy-server\")\n schema:\n type: string\n example: \"com.example%2Fmy-server\"\n responses:\n '200':\n description: Detailed server information\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/ServerResponse'\n '404':\n description: Server not found\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/Problem'\n default:\n description: Error payload\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/Problem'\n\n /v0/servers/{serverName}/versions:\n get:\n summary: List all versions of an MCP server\n description: Returns all available versions for the specified MCP server, ordered by publication date (newest first).\n parameters:\n - name: serverName\n in: path\n required: true\n description: URL-encoded server name (e.g., \"com.example%2Fmy-server\")\n schema:\n type: string\n example: \"com.example%2Fmy-server\"\n responses:\n '200':\n description: Versions for the server\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/ServerList'\n '404':\n description: Server not found\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/Problem'\n default:\n description: Error payload\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/Problem'\n\n /v0/servers/{serverName}/versions/{version}:\n get:\n summary: Get specific MCP server version\n description: Returns detailed information about a specific version of an MCP server.\n parameters:\n - name: serverName\n in: path\n required: true\n description: URL-encoded server name (e.g., \"com.example%2Fmy-server\")\n schema:\n type: string\n example: \"com.example%2Fmy-server\"\n - name: version\n in: path\n required: true\n description: URL-encoded version to retrieve (e.g., \"1.0.0\" or \"1.0.0%2Bbuild\")\n schema:\n type: string\n example: \"1.0.0\"\n responses:\n '200':\n description: Detailed server version\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/ServerResponse'\n '404':\n description: Server or version not found\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/Problem'\n default:\n description: Error payload\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/Problem'\n\ncomponents:\n securitySchemes:\n bearerAuth:\n type: http\n scheme: bearer\n bearerFormat: JWT\n description: Registry-specific authentication token. Publishing registries may require a bearer token for write operations.\n\n schemas:\n Problem:\n type: object\n properties:\n type:\n type: string\n title:\n type: string\n status:\n type: integer\n detail:\n type: string\n instance:\n type: string\n additionalProperties: true\n\n Repository:\n type: object\n required:\n - url\n - source\n properties:\n url:\n type: string\n format: uri\n example: \"https://github.com/modelcontextprotocol/servers\"\n source:\n type: string\n example: \"github\"\n id:\n type: string\n example: \"b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9\"\n subfolder:\n type: string\n description: Optional relative path when the server lives inside a monorepo.\n example: \"src/everything\"\n additionalProperties: false\n\n Package:\n type: object\n required:\n - registryType\n - identifier\n - version\n properties:\n registryType:\n type: string\n description: Registry type (npm, pypi, nuget, oci, mcpb, etc.)\n examples: [\"npm\", \"pypi\", \"oci\", \"nuget\", \"mcpb\"]\n registryBaseUrl:\n type: string\n format: uri\n description: Base URL of the package registry.\n examples:\n - \"https://registry.npmjs.org\"\n - \"https://pypi.org\"\n - \"https://docker.io\"\n - \"https://api.nuget.org\"\n - \"https://github.com\"\n identifier:\n type: string\n description: Registry identifier or download URL.\n examples:\n - \"@modelcontextprotocol/server-filesystem\"\n - \"https://github.com/example/releases/download/v1.0.0/package.mcpb\"\n version:\n type: string\n description: Package version.\n example: \"1.0.2\"\n fileSha256:\n type: string\n description: SHA-256 hash for MCPB packages.\n runtimeHint:\n type: string\n description: Hint informing the client which runtime to invoke (e.g., npx, uvx, dnx).\n runtimeArguments:\n type: array\n items:\n $ref: '#/components/schemas/Argument'\n description: Arguments passed to the runtime command.\n packageArguments:\n type: array\n items:\n $ref: '#/components/schemas/Argument'\n description: Arguments passed to the package binary.\n environmentVariables:\n type: array\n items:\n $ref: '#/components/schemas/Argument'\n description: Environment variables required by the package.\n transport:\n type: object\n properties:\n type:\n type: string\n url:\n type: string\n format: uri\n required: [type]\n additionalProperties: false\n additionalProperties: false\n\n InputBase:\n type: object\n properties:\n description:\n type: string\n isRequired:\n type: boolean\n default: false\n format:\n type: string\n description: Supported values include \"string\", \"number\", \"boolean\", \"filepath\".\n default: string\n value:\n type: string\n description: Default or fixed value for the input.\n isSecret:\n type: boolean\n description: Whether the value should be treated as secret.\n default: false\n default:\n type: string\n description: Default value shown to the user.\n choices:\n type: array\n items:\n type: string\n description: Allowed values when the input is constrained.\n additionalProperties: false\n\n InputWithVariables:\n allOf:\n - $ref: '#/components/schemas/InputBase'\n - type: object\n properties:\n variables:\n type: object\n additionalProperties:\n $ref: '#/components/schemas/InputBase'\n additionalProperties: false\n\n PositionalArgument:\n allOf:\n - $ref: '#/components/schemas/InputWithVariables'\n - type: object\n required:\n - type\n properties:\n type:\n type: string\n enum: [positional]\n valueHint:\n type: string\n description: Hint for UI integrations describing the value.\n isRepeated:\n type: boolean\n default: false\n additionalProperties: false\n anyOf:\n - required: [value]\n - required: [valueHint]\n\n NamedArgument:\n allOf:\n - $ref: '#/components/schemas/InputWithVariables'\n - type: object\n required:\n - type\n - name\n properties:\n type:\n type: string\n enum: [named]\n name:\n type: string\n description: Flag name, including leading dashes (e.g., \"--port\").\n isRepeated:\n type: boolean\n default: false\n additionalProperties: false\n\n Argument:\n anyOf:\n - $ref: '#/components/schemas/PositionalArgument'\n - $ref: '#/components/schemas/NamedArgument'\n\n KeyValueInput:\n allOf:\n - $ref: '#/components/schemas/InputWithVariables'\n - type: object\n required:\n - name\n properties:\n name:\n type: string\n description: Name of the header or environment variable.\n additionalProperties: false\n\n Remote:\n type: object\n required:\n - type\n - url\n properties:\n type:\n type: string\n enum: [\"streamable-http\", \"sse\"]\n url:\n type: string\n format: uri\n headers:\n type: array\n items:\n $ref: '#/components/schemas/KeyValueInput'\n additionalProperties: false\n\n ServerDetail:\n type: object\n required:\n - name\n - description\n - version\n properties:\n name:\n type: string\n description: Reverse-DNS server name.\n example: \"io.github.modelcontextprotocol/filesystem\"\n description:\n type: string\n example: \"Filesystem operations server.\"\n version:\n type: string\n description: SHOULD follow semantic versioning.\n repository:\n $ref: '#/components/schemas/Repository'\n websiteUrl:\n type: string\n format: uri\n $schema:\n type: string\n format: uri\n packages:\n type: array\n items:\n $ref: '#/components/schemas/Package'\n remotes:\n type: array\n items:\n $ref: '#/components/schemas/Remote'\n _meta:\n type: object\n properties:\n io.modelcontextprotocol.registry/publisher-provided:\n type: object\n description: Publisher-specific metadata.\n additionalProperties: true\n additionalProperties: true\n additionalProperties: false\n\n OfficialMetadata:\n type: object\n properties:\n status:\n type: string\n enum: [\"active\", \"deprecated\", \"deleted\"]\n publishedAt:\n type: string\n format: date-time\n updatedAt:\n type: string\n format: date-time\n isLatest:\n type: boolean\n serverId:\n type: string\n versionId:\n type: string\n additionalProperties: false\n\n ServerResponse:\n type: object\n required:\n - server\n - _meta\n properties:\n server:\n $ref: '#/components/schemas/ServerDetail'\n _meta:\n type: object\n properties:\n io.modelcontextprotocol.registry/official:\n $ref: '#/components/schemas/OfficialMetadata'\n additionalProperties: true\n additionalProperties: false\n\n Metadata:\n type: object\n properties:\n nextCursor:\n type: string\n count:\n type: integer\n additionalProperties: false\n\n ServerList:\n type: object\n required:\n - servers\n properties:\n servers:\n type: array\n items:\n $ref: '#/components/schemas/ServerResponse'\n metadata:\n $ref: '#/components/schemas/Metadata'\n additionalProperties: false",[],[265],"files",[150,169,176,186,197,207,217,226,236,245,255,263],"counts",{"_276":32,"_277":192,"_278":32,"_279":280},"pulls","branches","forks","envVars",{"_281":32,"_282":32},"count","emptyCount","contents",[285,288,291,294,297,300,303,306],{"_102":151,"_95":152,"_153":154,"_155":-5,"_156":138,"_157":158,"_159":160,"_104":286,"_99":32,"_162":163,"_164":-5,"_165":22,"_166":-5,"_98":287},["D",1759552098645],[152],{"_102":208,"_95":209,"_153":210,"_155":-5,"_156":138,"_157":211,"_159":160,"_104":289,"_99":32,"_162":213,"_164":214,"_165":22,"_166":-5,"_98":290},["D",1759523918235],[209],{"_102":218,"_95":219,"_153":220,"_155":-5,"_156":138,"_157":221,"_159":160,"_104":292,"_99":32,"_162":213,"_164":223,"_165":22,"_166":-5,"_98":293},["D",1759523918233],[219],{"_102":227,"_95":228,"_153":229,"_155":-5,"_156":138,"_157":230,"_159":160,"_104":295,"_99":232,"_162":213,"_164":233,"_165":22,"_166":-5,"_98":296},["D",1759552099051],[228],{"_102":237,"_95":238,"_153":239,"_155":-5,"_156":138,"_157":240,"_159":160,"_104":298,"_99":32,"_162":213,"_164":242,"_165":22,"_166":-5,"_98":299},["D",1759555361169],[238],{"_102":246,"_95":247,"_153":248,"_155":-5,"_156":138,"_157":249,"_159":160,"_104":301,"_99":251,"_162":213,"_164":252,"_165":22,"_166":-5,"_98":302},["D",1759552098946],[247],{"_102":256,"_95":257,"_153":258,"_155":-5,"_156":138,"_157":137,"_159":160,"_104":304,"_99":221,"_162":182,"_164":260,"_165":22,"_166":-5,"_98":305},["D",1759555361281],[257],{"_102":264,"_95":265,"_153":266,"_155":-5,"_156":138,"_157":267,"_159":160,"_104":307,"_99":251,"_162":213,"_164":269,"_165":22,"_166":-5,"_98":308},["D",1759552099110],[265],"upstreamProject","upstreamBranch","emptyEnvVars","isNew","flags",[],"routes/_app.x.$handle.$name.environment-variables",{"_93":94,"_95":96,"_100":317,"_279":322},{"_102":103,"_95":96,"_104":318,"_106":-5,"_107":22,"_108":109,"_110":111,"_112":113,"_14":114,"_115":-5,"_116":22,"_117":-5,"_118":32,"_16":119,"_120":121,"_122":121,"_123":124,"_125":124,"_126":124,"_127":121,"_128":121,"_23":319,"_132":320,"_135":321,"_147":22},["D",1759523222208],{"_93":94,"_130":131},{"_93":94,"_134":131},{"_99":137,"_95":43,"_102":138,"_139":103,"_140":-5,"_141":-5,"_142":-5,"_143":-5,"_144":-5,"_145":96,"_146":94},[],"actionData","errors"]

cameronpak

mcp-registry-subregistry-api

Environment variables