keymaker-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya Acharya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+
+
+
+# Keymaker
+
+**Make your API agent-ready in an afternoon.**
+
+
+
+https://github.com/user-attachments/assets/a8e5b189-dbaa-45dc-81b4-af4f2b72c85b
+
+
+
+Point Keymaker at your OpenAPI spec. It emits everything an AI agent needs to discover, sign up for, and use your product — with zero humans in the loop:
+
+- **`mcp-server.mjs`** — a runnable MCP server exposing every endpoint as a tool (stdio; works with Claude, Cursor, any MCP client)
+- **`llms.txt`** — agent-readable API overview, served the way agents actually browse
+- **`auth.md`** + **`.well-known/auth.md`** — machine-readable signup instructions ([auth.md](https://workos.com/auth-md)-pattern-compatible)
+- **an agent-signup server** — agents `POST /agent-auth` and get a scoped API key back in one round trip; your backend verifies keys and meters usage with one call
+
+Plus a **curation report**: every endpoint or parameter with missing/weak documentation gets flagged — because agents choose tools by documentation quality, and auto-generated tools from an undocumented spec perform measurably worse.
+
+## Quickstart
+
+```bash
+npx keymaker-cli generate https://your.api/openapi.json -o agent-ready
+npx keymaker-cli serve agent-ready       # agent signup + hosted /mcp on :8787
+```
+
+Or from a clone:
+
+```bash
+npm install
+node src/cli.js generate examples/todo-api.yaml -o out/todo
+node src/cli.js serve out/todo          # agent signup on :8787
+node out/todo/mcp-server.mjs            # MCP server (stdio)
+```
+
+An agent signs itself up:
+
+```bash
+curl -s -X POST localhost:8787/agent-auth \
+  -d '{"client_name":"my-agent","scopes":["read","write"]}'
+# → { "api_key": "ak_…", "status": "unclaimed", "expires_at": "<60 min>", "claim_token": "ct_…" }
+```
+
+No attestation → the key is **temporary (60 min)** — enough for the agent to try your API — and becomes permanent when a human claims it (the [Cloudflare Temporary Accounts](https://blog.cloudflare.com/temporary-accounts/) pattern). With a platform attestation (ID-JAG) → issued as `agent_verified`, no expiry. Your backend checks keys and meters usage:
+
+```bash
+curl -s -X POST localhost:8787/agent-auth/verify -d '{"api_key":"ak_…"}'
+# → { "valid": true, "scopes": ["read","write"], "usage": 1 }
+```
+
+## Mount it inside your app (one process, one port)
+
+You don't need a second service. Mount the gateway in your existing app:
+
+```js
+import { keymakerGateway, keymakerAuth } from "keymaker-cli";
+
+const gateway = await keymakerGateway({ dir: "./agent-ready" });
+const auth = keymakerAuth({ dir: "./agent-ready" });
+
+// plain node:http
+createServer(async (req, res) => {
+  if (await gateway(req, res)) return;   // /llms.txt /auth.md /agent-auth* /mcp
+  if (!(await auth(req, res))) return;   // everything else needs an agent key
+  // …your routes, with req.agent populated
+});
+
+// express
+app.use(gateway.express());
+app.use(auth);
+```
+
+`node examples/single-process.mjs` shows the whole thing on one port.
+
+## Agents as paying customers (Stripe)
+
+Add to `signup.config.json` and set `STRIPE_SECRET_KEY`:
+
+```json
+"billing": { "provider": "stripe", "meter_event_name": "keymaker_api_call" }
+```
+
+Registration creates a Stripe customer for the agent (pass `billing_email` at signup — agents have inboxes now); every metered request emits a [Billing Meter event](https://docs.stripe.com/billing/subscriptions/usage-based). Attach a metered price and usage becomes invoices. Billing is optional and off by default — without config, nothing changes.
+
+## One origin, whole loop: hosted `/mcp`
+
+`keymaker serve` doesn't just issue keys — it hosts the tools too. An agent needs exactly one URL:
+
+```
+GET  /llms.txt      → discovers your API
+GET  /auth.md       → learns how to register
+POST /agent-auth    → gets a scoped key
+POST /mcp           → calls your API's tools (Streamable HTTP, Bearer-gated)
+```
+
+No stdio, no local install. Tool visibility is scope-filtered — a `read`-scoped key doesn't even *see* write tools in `tools/list`. Every successful call is metered onto the key. Revoke instantly:
+
+```bash
+curl -X POST localhost:8787/agent-auth/revoke \
+  -H "x-admin-token: <from signup.config.json>" -d '{"key_id":"key_…"}'
+```
+
+(The generated `mcp-server.mjs` still works for stdio/local MCP clients like Claude Desktop.)
+
+## Check any live site: `keymaker doctor`
+
+```bash
+npx keymaker-cli doctor stripe.com yourapi.com
+# stripe.com: 1/3 agent surfaces   llms.txt ✓   auth.md ✗   /mcp ✗
+```
+
+We ran it across 63 top API companies: **71% have llms.txt, 8% have agent signup, exactly one has all three.** Full data: [State of Agent Readiness, July 2026](docs/state-of-agent-readiness-2026-07.md).
+
+## Score your API (Lighthouse, for agents)
+
+```bash
+node src/cli.js score https://petstore3.swagger.io/api/v3/openapi.json
+# Agent-readiness: 84/100  grade B
+#   ██████████  40/40  Operation docs
+#   ░░░░░░░░░░   0/10  Absolute base URL  → servers[0].url should be an absolute https URL
+#   …
+```
+
+Six checks, weighted by what actually drives agent tool-selection: operation docs, parameter docs, API description, absolute base URL, documented auth, tagging. Fun fact: the official Swagger Petstore scores a B — its base URL is relative, so an agent literally can't call it.
+
+## Protect your API (drop-in middleware)
+
+```js
+import { keymakerAuth } from "keymaker-cli";
+
+const auth = keymakerAuth({ dir: "./agent-ready", rateLimitPerMinute: 60 });
+app.use(auth);                    // Express
+// or in plain node:http — if (!(await auth(req, res))) return;
+// req.agent = { key_id, client_name, scopes, status }
+```
+
+Checks the Bearer key, enforces scopes (`read` for GET, `write` for mutations), rate-limits per key, meters usage.
+
+## Real attestation verification
+
+`signup.config.json` (generated next to your artifacts) controls how `agent_verified` keys are issued:
+
+```json
+{
+  "trusted_issuers": [{ "issuer": "https://agents.example.com", "jwks_url": "https://agents.example.com/.well-known/jwks.json" }],
+  "audience": "https://api.yourproduct.com",
+  "registrations_per_minute_per_ip": 10
+}
+```
+
+Attestations are verified as JWTs (RS256/ES256/EdDSA) against the issuer's JWKS — signature, expiry, issuer, and audience checks. The generated default is dev-mode (`dev_accept_any_attestation: true`) so the demo works out of the box; a rejected attestation still issues a 60-minute temporary key, with the rejection reason in the response.
+
+## Why now
+
+- Agents are becoming the first consumer of APIs, and they pick tools by machine-readability. On YC's Lightcone podcast (Feb 2026), Garry Tan described Claude Code choosing the practically-deprecated Whisper V1 over Groq — 200× faster, 10× cheaper — for his transcription pipeline; his co-host pinned the cause: Groq's docs are hard to parse, Whisper's have far more examples.
+- YC's Summer 2026 RFS calls for exactly this: agents need to "discover, sign up for, and instantly start using new tools programmatically, without needing a human in the loop."
+- The signup protocol layer just standardized (WorkOS's auth.md, May 2026 — adopted by Cloudflare, Firecrawl, Resend, Monday.com). But implementing it — endpoints, attestation verification, key issuance, metering — is still work every vendor does by hand. **Keymaker is the retrofit layer: one command from OpenAPI spec to fully agent-ready.**
+
+## Security posture
+
+- **Keys are hashed at rest** (SHA-256) — `keys.json` stores hash + display prefix; the full key is shown exactly once, at registration. Lookups are timing-safe.
+- **Admin token comparison is timing-safe**; key writes are serialized and land atomically (tmp + rename).
+- **Rate limits by default**: 10 registrations/min/IP, 120 verifies/min/key, 60 API requests/min/key — all configurable.
+- Attestations are verified as signed JWTs against the issuer's JWKS (see above); dev-mode acceptance is explicit, config-gated, and off unless you say otherwise.
+
+Scale note: real-world specs are fine — GitHub's 12.6MB / 1,194-operation spec generates in ~0.3s (you'll get a tool-explosion warning telling you to curate with `--include`, because a 1,194-tool MCP server is how you get [the Whisper problem](#why-now)).
+
+## Status & roadmap
+
+v0.1 — working generator, signup server, JWT attestation verification, scope-enforcing middleware, per-key/per-IP rate limits, agent-readiness scoring. 12 passing tests (`npm test`). Roadmap:
+
+- [x] Hosted `/mcp` endpoint — one origin serves discovery, signup, and tools
+- [x] Mountable gateway — run everything inside your existing app, one process
+- [x] Stripe metered billing per key (agents as paying customers)
+- [x] Key revocation API
+- [x] CI gate: `keymaker score --json --min 80`
+- [ ] Managed hosting (`yourapi.keymaker.dev`) — no infra to run
+- [ ] x402 fallback for account-less micropayment access
+- [ ] Registry submission: publish generated MCP servers to agent tool registries
+
+MIT. Built with the [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk).

package/examples/todo-api.yaml

@@ -0,0 +1,69 @@
+openapi: 3.0.3
+info:
+  title: Todozilla API
+  version: 1.0.0
+  description: A simple task-management API used to demo keymaker.
+servers:
+  - url: https://api.todozilla.example.com/v1
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      description: API key issued via /agent-auth (see auth.md)
+paths:
+  /tasks:
+    get:
+      operationId: listTasks
+      tags: [Tasks]
+      summary: List tasks
+      description: Returns tasks, newest first. Supports filtering by status.
+      parameters:
+        - name: status
+          in: query
+          description: Filter by task status
+          schema: { type: string, enum: [open, done] }
+        - name: limit
+          in: query
+          description: Max results (default 20)
+          schema: { type: integer }
+      responses:
+        "200": { description: OK }
+    post:
+      operationId: createTask
+      tags: [Tasks]
+      summary: Create a task
+      description: Creates a new task and returns it.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [title]
+              properties:
+                title: { type: string, description: Task title }
+                due: { type: string, format: date, description: Due date (YYYY-MM-DD) }
+      responses:
+        "201": { description: Created }
+  /tasks/{taskId}:
+    get:
+      operationId: getTask
+      tags: [Tasks]
+      summary: Get one task
+      parameters:
+        - name: taskId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        "200": { description: OK }
+    delete:
+      operationId: deleteTask
+      tags: [Tasks]
+      parameters:
+        - name: taskId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        "204": { description: Deleted }

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "keymaker-cli",
+  "version": "0.1.0",
+  "description": "Make your API agent-ready in an afternoon: OpenAPI spec → curated MCP server + llms.txt + auth.md agent signup",
+  "type": "module",
+  "bin": {
+    "keymaker-cli": "./src/cli.js",
+    "keymaker": "./src/cli.js",
+    "agent-ready": "./src/cli.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "examples/todo-api.yaml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "demo": "node src/cli.js generate examples/todo-api.yaml -o out/todo && node src/cli.js serve out/todo"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adityaaa-IIT-BHU/keymaker.git"
+  },
+  "homepage": "https://github.com/adityaaa-IIT-BHU/keymaker#readme",
+  "bugs": {
+    "url": "https://github.com/adityaaa-IIT-BHU/keymaker/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "openapi",
+    "ai-agents",
+    "llms-txt",
+    "auth-md",
+    "agent-auth",
+    "api"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "Aditya Acharya <aditya.acharya.bme23@itbhu.ac.in>",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "commander": "^12.0.0",
+    "js-yaml": "^4.1.0"
+  }
+}

package/src/attest.js

@@ -0,0 +1,73 @@
+import { createPublicKey, verify as cryptoVerify } from "node:crypto";
+
+function b64urlJson(s) {
+  return JSON.parse(Buffer.from(s, "base64url").toString("utf8"));
+}
+
+/**
+ * Verify an agent-platform attestation (ID-JAG-style JWT).
+ * config.trusted_issuers: [{ issuer, jwks_url }] or [{ issuer, jwks: [<JWK>] }]
+ * config.audience: optional expected aud
+ * config.dev_accept_any_attestation: accept any non-empty token (local testing only)
+ */
+export async function verifyAttestation(token, config = {}) {
+  const issuers = config.trusted_issuers ?? [];
+  if (!issuers.length) {
+    return config.dev_accept_any_attestation
+      ? { verified: true, mode: "dev-accepted", claims: null }
+      : { verified: false, reason: "no trusted_issuers configured (see signup.config.json)" };
+  }
+
+  let header, payload, signature, signingInput;
+  try {
+    const parts = String(token).split(".");
+    if (parts.length !== 3) throw new Error("not a JWT");
+    header = b64urlJson(parts[0]);
+    payload = b64urlJson(parts[1]);
+    signature = Buffer.from(parts[2], "base64url");
+    signingInput = Buffer.from(`${parts[0]}.${parts[1]}`);
+  } catch {
+    return { verified: false, reason: "malformed attestation token" };
+  }
+
+  const issuer = issuers.find((i) => i.issuer === payload.iss);
+  if (!issuer) return { verified: false, reason: `untrusted issuer: ${payload.iss}` };
+  if (payload.exp && payload.exp * 1000 < Date.now()) {
+    return { verified: false, reason: "attestation expired" };
+  }
+  if (config.audience) {
+    const aud = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+    if (!aud.includes(config.audience)) return { verified: false, reason: "audience mismatch" };
+  }
+
+  let jwks = issuer.jwks;
+  if (!jwks && issuer.jwks_url) {
+    try {
+      const res = await fetch(issuer.jwks_url);
+      if (!res.ok) return { verified: false, reason: `JWKS fetch failed: HTTP ${res.status}` };
+      jwks = (await res.json()).keys;
+    } catch (err) {
+      return { verified: false, reason: `JWKS fetch failed: ${err.message}` };
+    }
+  }
+  const jwk = (jwks ?? []).find((k) => !header.kid || k.kid === header.kid);
+  if (!jwk) return { verified: false, reason: "no matching key in JWKS" };
+
+  let key;
+  try {
+    key = createPublicKey({ key: jwk, format: "jwk" });
+  } catch {
+    return { verified: false, reason: "unusable JWK" };
+  }
+
+  let ok = false;
+  if (header.alg === "RS256") ok = cryptoVerify("RSA-SHA256", signingInput, key, signature);
+  else if (header.alg === "ES256")
+    ok = cryptoVerify("SHA256", signingInput, { key, dsaEncoding: "ieee-p1363" }, signature);
+  else if (header.alg === "EdDSA") ok = cryptoVerify(null, signingInput, key, signature);
+  else return { verified: false, reason: `unsupported alg: ${header.alg}` };
+
+  return ok
+    ? { verified: true, mode: "jwt-verified", claims: payload }
+    : { verified: false, reason: "bad signature" };
+}

package/src/billing.js

@@ -0,0 +1,48 @@
+/**
+ * Config-gated billing provider. Enable in signup.config.json:
+ *   "billing": {
+ *     "provider": "stripe",
+ *     "secret_key_env": "STRIPE_SECRET_KEY",
+ *     "meter_event_name": "keymaker_api_call"
+ *   }
+ * On registration the agent becomes a Stripe customer; every metered request
+ * emits a Billing Meter event, so a metered price turns usage into invoices.
+ * Returns null when unconfigured — billing is always optional.
+ */
+export function createBilling(cfg) {
+  if (!cfg || cfg.provider !== "stripe") return null;
+  const key = process.env[cfg.secret_key_env ?? "STRIPE_SECRET_KEY"];
+  if (!key) return null;
+  const base = (cfg.api_base ?? "https://api.stripe.com").replace(/\/$/, "");
+  const eventName = cfg.meter_event_name ?? "keymaker_api_call";
+
+  const call = async (path, params) => {
+    const res = await fetch(`${base}${path}`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${key}`,
+        "content-type": "application/x-www-form-urlencoded",
+      },
+      body: new URLSearchParams(params),
+    });
+    if (!res.ok) throw new Error(`Stripe ${path}: HTTP ${res.status} ${await res.text()}`);
+    return res.json();
+  };
+
+  return {
+    async onRegister(record, body = {}) {
+      const params = { name: record.client_name, "metadata[key_id]": record.key_id };
+      if (body.billing_email) params.email = String(body.billing_email).slice(0, 200);
+      const customer = await call("/v1/customers", params);
+      return { customer_id: customer.id };
+    },
+    async onMeter(record) {
+      if (!record.billing_customer_id) return;
+      await call("/v1/billing/meter_events", {
+        event_name: eventName,
+        "payload[stripe_customer_id]": record.billing_customer_id,
+        "payload[value]": "1",
+      });
+    },
+  };
+}

package/src/cli.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { mkdir, writeFile, access } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { loadSpec } from "./parse.js";
+import { extractOperations } from "./extract.js";
+import { renderMcpServer, toTools } from "./gen-mcp.js";
+import { renderLlmsTxt } from "./gen-llms.js";
+import { renderAuthMd } from "./gen-authmd.js";
+import { startSignupServer } from "./serve.js";
+import { scoreSpec } from "./score.js";
+
+const program = new Command();
+program
+  .name("keymaker")
+  .description("Make your API agent-ready: OpenAPI → curated MCP server + llms.txt + auth.md agent signup")
+  .version("0.1.0");
+
+program
+  .command("generate")
+  .argument("<spec>", "OpenAPI spec path or URL (JSON or YAML)")
+  .option("-o, --out <dir>", "output directory", "agent-ready")
+  .option("--base-url <url>", "override API base URL")
+  .option("--service-url <url>", "public URL where the signup server runs", "http://localhost:8787")
+  .option("--include <names...>", "only operations whose name contains one of these")
+  .option("--exclude <names...>", "skip operations whose name contains one of these")
+  .action(async (specSrc, opts) => {
+    const spec = await loadSpec(specSrc);
+    const baseUrl = (opts.baseUrl ?? spec.servers?.[0]?.url ?? "http://localhost:3000").replace(/\/$/, "");
+    const { ops, warnings } = extractOperations(spec, { include: opts.include, exclude: opts.exclude });
+    if (!ops.length) {
+      console.error("No operations found in spec (check --include/--exclude filters).");
+      process.exit(1);
+    }
+    const title = spec.info?.title ?? "api";
+    await mkdir(join(opts.out, ".well-known"), { recursive: true });
+    const authMd = renderAuthMd({ spec, serviceUrl: opts.serviceUrl });
+    await writeFile(
+      join(opts.out, "mcp-server.mjs"),
+      renderMcpServer({ title, version: spec.info?.version ?? "0.0.0", baseUrl, ops })
+    );
+    await writeFile(join(opts.out, "llms.txt"), renderLlmsTxt({ spec, ops, baseUrl, serviceUrl: opts.serviceUrl }));
+    await writeFile(join(opts.out, "auth.md"), authMd);
+    await writeFile(join(opts.out, ".well-known", "auth.md"), authMd);
+    await writeFile(
+      join(opts.out, "tools.json"),
+      JSON.stringify(
+        { title, version: spec.info?.version ?? "0.0.0", baseUrl, tools: toTools(ops) },
+        null,
+        2
+      )
+    );
+
+    const configPath = join(opts.out, "signup.config.json");
+    try {
+      await access(configPath);
+    } catch {
+      await writeFile(
+        configPath,
+        JSON.stringify(
+          {
+            _note:
+              "dev_accept_any_attestation accepts ANY attestation string — local testing only. For production, set trusted_issuers: [{ issuer, jwks_url }] and remove the dev flag.",
+            dev_accept_any_attestation: true,
+            audience: null,
+            trusted_issuers: [],
+            registrations_per_minute_per_ip: 10,
+            verifies_per_minute_per_key: 120,
+            admin_token: `adm_${randomBytes(16).toString("hex")}`,
+          },
+          null,
+          2
+        )
+      );
+    }
+
+    console.log(`✔ ${title}: ${ops.length} operations → ${opts.out}/`);
+    console.log("  mcp-server.mjs   llms.txt   auth.md   .well-known/auth.md   tools.json   signup.config.json");
+    if (warnings.length) {
+      console.log("\nCuration report — agents choose tools by docs quality; fix these in your spec:");
+      for (const w of warnings.slice(0, 20)) console.log(`  ⚠ ${w}`);
+      if (warnings.length > 20) console.log(`  …and ${warnings.length - 20} more`);
+    }
+    if (ops.length > 40) {
+      console.log(
+        `\n⚠ ${ops.length} tools is tool-explosion territory — agents pick tools better from small, curated sets.` +
+          `\n  Narrow it: keymaker generate <spec> --include <names…>   (or --exclude)`
+      );
+    }
+    const { total, grade } = scoreSpec(spec, ops, warnings);
+    console.log(`\nAgent-readiness score: ${total}/100 (${grade}) — run \`keymaker score\` for the breakdown`);
+    console.log(`\nNext:`);
+    console.log(`  keymaker serve ${opts.out}                # agent-signup endpoint`);
+    console.log(`  node ${join(opts.out, "mcp-server.mjs")}   # MCP server (stdio)`);
+  });
+
+program
+  .command("score")
+  .argument("<spec>", "OpenAPI spec path or URL")
+  .description("Grade how agent-ready an API spec is (like Lighthouse, for agents)")
+  .option("--json", "machine-readable output")
+  .option("--min <score>", "exit non-zero if the score is below this (for CI)")
+  .action(async (specSrc, opts) => {
+    const spec = await loadSpec(specSrc);
+    const { ops, warnings } = extractOperations(spec);
+    const { total, grade, parts } = scoreSpec(spec, ops, warnings);
+    if (opts.json) {
+      console.log(JSON.stringify({ title: spec.info?.title ?? "API", operations: ops.length, total, grade, parts }, null, 2));
+    } else {
+      console.log(`Agent-readiness: ${total}/100  grade ${grade}   (${spec.info?.title ?? "API"}, ${ops.length} operations)\n`);
+      for (const p of parts) {
+        const bar = "█".repeat(Math.round((10 * p.got) / p.max)).padEnd(10, "░");
+        console.log(`  ${bar} ${String(p.got).padStart(3)}/${p.max}  ${p.name}${p.fix ? `  → ${p.fix}` : ""}`);
+      }
+      console.log(`\nAgents choose tools by documentation quality. Fix the arrows, re-run, ship.`);
+    }
+    if (opts.min && total < Number(opts.min)) {
+      console.error(`\n✖ score ${total} is below --min ${opts.min}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("doctor")
+  .argument("<hosts...>", "domain(s) to check, e.g. api.example.com docs.example.com")
+  .description("Check a LIVE site for agent surfaces: llms.txt, auth.md, /mcp")
+  .option("--json", "machine-readable output")
+  .action(async (hosts, opts) => {
+    const { checkSite, formatDoctor } = await import("./doctor.js");
+    const results = [];
+    for (const host of hosts) {
+      const r = await checkSite(host);
+      results.push(r);
+      if (!opts.json) console.log(formatDoctor(r));
+    }
+    if (opts.json) console.log(JSON.stringify(results, null, 2));
+    const invisible = results.filter((r) => !r.llms_txt && !r.auth_md && !r.mcp).length;
+    if (!opts.json && results.length > 1) {
+      console.log(`\n${invisible}/${results.length} hosts have zero agent surfaces. keymaker generate fixes all three.`);
+    }
+  });
+
+program
+  .command("serve")
+  .argument("[dir]", "generated directory", "agent-ready")
+  .option("-p, --port <port>", "port", "8787")
+  .action(async (dir, opts) => {
+    const server = await startSignupServer({ dir, port: Number(opts.port) });
+    const port = server.address().port;
+    console.log(`Agent signup live on http://localhost:${port}`);
+    console.log(`  GET  /auth.md            registration instructions (also /.well-known/auth.md, /llms.txt)`);
+    console.log(`  POST /agent-auth         agent registers, gets a scoped key (temp until claimed, or attested)`);
+    console.log(`  POST /agent-auth/claim   human claims a temporary key`);
+    console.log(`  POST /agent-auth/verify  your backend verifies keys + meters usage`);
+    console.log(`  GET  /agent-auth/keys    issued keys (redacted)`);
+  });
+
+program.parse();

package/src/doctor.js

@@ -0,0 +1,63 @@
+const UA = "keymaker-doctor/0.1 (+https://github.com/adityaaa-IIT-BHU/keymaker)";
+
+async function probe(url, init = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 8000);
+  try {
+    const res = await fetch(url, {
+      ...init,
+      redirect: "follow",
+      signal: controller.signal,
+      headers: { "user-agent": UA, ...(init.headers ?? {}) },
+    });
+    const text = await res.text().catch(() => "");
+    return { status: res.status, type: res.headers.get("content-type") ?? "", body: text.slice(0, 2000) };
+  } catch {
+    return { status: 0, type: "", body: "" };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function looksLikeMarkdownDoc(r) {
+  if (r.status !== 200) return false;
+  const body = r.body.trimStart();
+  // SPA catch-alls return 200 HTML for any path — that's a miss, not a hit
+  if (body.startsWith("<") || r.type.includes("text/html")) return false;
+  return body.startsWith("#") || /\[[^\]]+\]\([^)]+\)/.test(body);
+}
+
+function looksLikeMcp(r) {
+  if (r.status === 0 || r.status === 404) return false;
+  if (r.type.includes("text/html")) return false;
+  // A real MCP endpoint answers POSTs with JSON-RPC (or auth/method errors), not a marketing page
+  return [400, 401, 405, 406].includes(r.status) || r.body.includes("jsonrpc") || r.type.includes("json") || r.type.includes("event-stream");
+}
+
+/** Check a live host for the three agent surfaces. Returns presence + evidence. */
+export async function checkSite(base) {
+  const origin = base.replace(/\/$/, "").replace(/^(?!https?:\/\/)/, "https://");
+  const [llms, llmsFull, authmd, wellKnown, mcp] = await Promise.all([
+    probe(`${origin}/llms.txt`),
+    probe(`${origin}/llms-full.txt`),
+    probe(`${origin}/auth.md`),
+    probe(`${origin}/.well-known/auth.md`),
+    probe(`${origin}/mcp`, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "keymaker-doctor", version: "0.1" } } }),
+    }),
+  ]);
+  return {
+    host: origin.replace(/^https?:\/\//, ""),
+    llms_txt: looksLikeMarkdownDoc(llms) || looksLikeMarkdownDoc(llmsFull),
+    auth_md: looksLikeMarkdownDoc(authmd) || looksLikeMarkdownDoc(wellKnown),
+    mcp: looksLikeMcp(mcp),
+  };
+}
+
+export function formatDoctor(result) {
+  const mark = (b) => (b ? "✓" : "✗");
+  const count = [result.llms_txt, result.auth_md, result.mcp].filter(Boolean).length;
+  return `${result.host}: ${count}/3 agent surfaces   llms.txt ${mark(result.llms_txt)}   auth.md ${mark(result.auth_md)}   /mcp ${mark(result.mcp)}`;
+}