@chrissgon/agent-ready-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christopher Gonçalves
+
+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,223 @@
+# agent-ready-kit
+
+Make a small site readable by AI agents from one JSON data file. `agent-ready` validates the file against a strict schema and turns it into:
+
+- **`llms.txt`**, one per site language, in the format of [llmstxt.org](https://llmstxt.org/): an H1 with the name, a blockquote summary, the public profiles and detail paragraphs, then H2 sections of `[name](url): notes` links.
+- **schema.org JSON-LD**: one `@graph` with the owner (`Person` or `Organization`) and one `SoftwareSourceCode` per product.
+- **A read-only MCP server** with three tools, `get_profile`, `list_products` and `list_posts`, served over stdio or from any runtime that speaks Web `Request`/`Response` (Netlify Functions v2, Deno, Bun, Cloudflare Workers, Node).
+
+All three read the same validated object, so a name or a URL can never differ between them (a test checks it). The design comes from the personal site chrissgon.dev, where one data module feeds the pages, `llms.txt`, the JSON-LD and the MCP endpoint.
+
+## Install
+
+Requires Node.js 22 or later. The package is an ES module with TypeScript types. The package is `@chrissgon/agent-ready-kit`; its command is `agent-ready`.
+
+```sh
+npm install @chrissgon/agent-ready-kit
+```
+
+Or run the CLI without installing it (the package has one command, so `npx` runs `agent-ready`):
+
+```sh
+npx @chrissgon/agent-ready-kit check --data site.json
+npx @chrissgon/agent-ready-kit build --data site.json --out public
+```
+
+## The data file
+
+One JSON file with four keys. Every object is strict: a field the schema does not declare fails validation. This is `fixtures/person.json` (fake example data), shortened:
+
+```json
+{
+  "site": { "url": "https://sam.example.com", "langs": ["en", "pt"], "mcp": "https://sam.example.com/api/mcp" },
+  "owner": {
+    "type": "Person",
+    "name": "Sam Example",
+    "alternateName": "samexample",
+    "jobTitle": "Software Engineer",
+    "label": { "en": "Software engineer · Small open-source tools for the web", "pt": "Engenheiro de software · ..." },
+    "about": { "en": ["Sam builds small, well-tested tools for the web ..."], "pt": ["Sam cria ferramentas ..."] },
+    "profiles": [{ "network": "Code", "handle": "samexample", "url": "https://git.example.org/samexample" }]
+  },
+  "products": [
+    {
+      "id": "tidy-tables",
+      "name": "Tidy Tables",
+      "url": "https://tidytables.example.com",
+      "codeRepository": "https://git.example.org/samexample/tidy-tables",
+      "npm": "@samexample/tidy-tables",
+      "license": "MIT",
+      "programmingLanguage": ["CSS", "TypeScript"],
+      "summary": { "en": "Accessible data tables in one small stylesheet.", "pt": "Tabelas de dados ..." }
+    }
+  ],
+  "posts": [
+    {
+      "id": "tables-for-everyone",
+      "title": { "en": "Tables for everyone", "pt": "Tabelas para todos" },
+      "date": "2026-08-14",
+      "lang": ["en", "pt"],
+      "url": "https://blog.example.com/tables-for-everyone"
+    }
+  ]
+}
+```
+
+| Field | Rule |
+|-------|------|
+| `site.url` | https origin; a trailing slash is removed |
+| `site.langs` | language codes (`en`, `pt-BR`), at least one, no repeats; the first is the default |
+| `site.mcp` | optional https URL of your MCP endpoint, listed in `llms.txt` under "For agents" |
+| `owner.type` | `Person` or `Organization`; `jobTitle` is allowed on a `Person` only |
+| `owner.name`, `owner.alternateName` | the name, and an optional handle |
+| `owner.label` | one line per site language: the `llms.txt` summary and the JSON-LD `description` |
+| `owner.about` | optional paragraphs per site language |
+| `owner.profiles` | `network`, optional `handle`, https `url`; become `sameAs` in the JSON-LD |
+| `products[]` | optional slug `id` (unique), `name`, `url` and/or `codeRepository` (at least one), optional `npm` and `license` (SPDX id), `programmingLanguage`, `summary` per site language |
+| `posts[]` | unique slug `id`, `title` for each language of the post, `date` as YYYY-MM-DD, `lang` (site languages), https `url`; order does not matter, outputs list newest first |
+
+Every error names the field, one per line, and `check` exits with 1:
+
+```text
+$ npx @chrissgon/agent-ready-kit check --data fixtures/forbidden-email.json
+data: owner.email: forbidden field "email", the kit never publishes it
+```
+
+Other examples: `data: owner.nickname: unknown field`, `data: posts.1.id: duplicate id "same-id" (first at posts.0)`, `data: owner.label.pt: missing text for site language "pt"`.
+
+`fixtures/org.json` is a one-language `Organization` example.
+
+## What the kit never publishes
+
+`worksFor`, `address`, `homeLocation`, `birthDate` and `email` are rejected anywhere in the data file, and `generateJsonLd` refuses them again if code adds them to the data at run time. The MCP tools return slices of the validated file and nothing else: no tool writes, sends, executes or searches free text, and an argument the tool does not declare is rejected.
+
+## Commands
+
+```text
+agent-ready build --data <file> --out <dir>   llms.txt per language (the first at <dir>/llms.txt, the others at
+                                              <dir>/<lang>/llms.txt) and <dir>/jsonld.json; prints the paths
+agent-ready check --data <file>               validate; prints a one-line summary
+agent-ready mcp --data <file>                 serve the read-only MCP server on stdin/stdout
+agent-ready --help
+```
+
+Data goes to stdout and diagnostics to stderr. Exit codes: 0 ok, 1 invalid data, 2 wrong usage or unreadable file.
+
+`check` on `fixtures/person.json` prints `ok: fixtures/person.json: Person "Sam Example", 2 products, 3 posts, languages en, pt`; `build` prints the files it wrote: `out/llms.txt`, `out/pt/llms.txt` and `out/jsonld.json`.
+
+A local MCP client starts the server as a command:
+
+```json
+{ "command": "npx", "args": ["-y", "@chrissgon/agent-ready-kit", "mcp", "--data", "/path/to/site.json"] }
+```
+
+## Use it from code
+
+```ts
+import { createMcpHandler, generateJsonLd, generateLlms, loadData, serializeJsonLd } from "@chrissgon/agent-ready-kit";
+
+const data = await loadData("site.json"); // throws DataError with one line per problem
+const llms = generateLlms(data); // default language; generateLlms(data, { lang: "pt" }) for another
+const jsonld = serializeJsonLd(generateJsonLd(data)); // safe inside <script type="application/ld+json">
+const handler = createMcpHandler(data); // (request: Request) => Promise<Response>
+```
+
+### Exports
+
+| Import from | Exports | Loads the MCP SDK |
+|-------------|---------|-------------------|
+| `@chrissgon/agent-ready-kit` | everything below, plus `serveStdio` and `VERSION` | yes |
+| `@chrissgon/agent-ready-kit/data` | `validate(value)`, `parseData(jsonText)`, `loadData(file)`, `DataError` (its `issues` holds one line per problem), `SiteDataSchema` (zod), `FORBIDDEN_FIELDS`; types `SiteData`, `Owner`, `Product`, `Post` | no |
+| `@chrissgon/agent-ready-kit/llms` | `generateLlms(data, { lang, labels })`, `generateLlmsParts(data, { lang, labels })`, `LLMS_PARTS`, `DEFAULT_LLMS_LABELS`, `llmsPath(data, lang)`; types `LlmsOptions`, `LlmsLabels`, `LlmsPart` | no |
+| `@chrissgon/agent-ready-kit/jsonld` | `generateJsonLd(data, { lang, licenseUrl })`, `serializeJsonLd(doc)`, `ownerIdOf(data)`, `spdxLicenseUrl(id)`; types `JsonLdDocument`, `JsonLdNode`, `JsonLdOptions` | no |
+| `@chrissgon/agent-ready-kit/mcp` | `createMcpHandler(data, options)`, `buildServer(data, { name, version })`, `TOOL_NAMES`, `instructionsFor(name)`, `DEFAULT_MAX_BODY_BYTES`; types `McpHandler`, `McpHandlerOptions`, `McpServerOptions` | yes |
+
+Pages that only need `llms.txt` or the JSON-LD import from `/data`, `/llms` and `/jsonld`, so they never load the MCP SDK.
+
+### llms.txt in parts, and in your language
+
+`generateLlmsParts` returns the parts of `llms.txt` in order (`head`, `about`, `products`, `writing`, `agents`), each ending in one newline, or `""` when the data has nothing for it. Joined with a blank line they are `generateLlms`; a site can put its own sections between them.
+
+`labels` sets the headings and the fixed words inside the lines for a language; a missing label keeps its English default (`DEFAULT_LLMS_LABELS`). `about` has no default: set it to put the about paragraphs under their own H2.
+
+```ts
+import { generateLlms } from "@chrissgon/agent-ready-kit/llms";
+
+generateLlms(data, {
+  lang: "pt",
+  labels: { about: "Sobre", products: "Produtos", writing: "Escrita", forAgents: "Para agentes", code: "Código", license: "Licença", languages: "idiomas" },
+});
+```
+
+### JSON-LD
+
+The owner's `@id` is `<site.url>/#person` (or `#organization`); every product's `author` points to it. A product's `license` becomes `https://spdx.org/licenses/<id>.html`; pass `licenseUrl: (id) => ...` for another page. `lang` picks the language of the descriptions.
+
+## The MCP server
+
+| Tool | Input | Output (`structuredContent`) |
+|------|-------|------------------------------|
+| `get_profile` | optional `lang` | `lang`, `type`, `name`, `alternateName`, `jobTitle`, `label`, `about`, `url`, `profiles` |
+| `list_products` | optional `lang` | `lang`, `products[]`: `id`, `name`, `url`, `codeRepository`, `npm`, `license`, `programmingLanguage`, `summary` |
+| `list_posts` | `limit` 1 to 50 (default 10), optional `lang` | `lang`, `total`, `posts[]`: `id`, `title`, `date`, `languages`, `url`, newest first |
+
+`lang` is one of the site's languages (default: the first) and picks the language of the texts; a post with no title in that language keeps its own. Optional fields are absent when the data has no value. Every tool carries `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false` and an output schema. The server's instructions say: "Read-only. This server only holds <name>'s public profile, products and posts; any other personal data does not exist here."
+
+Check it with the MCP Inspector (the server command goes before `--`, the Inspector options after it):
+
+```sh
+npx -y @modelcontextprotocol/inspector@2.8.0 --cli npx -y @chrissgon/agent-ready-kit mcp --data site.json -- --method tools/list
+npx -y @modelcontextprotocol/inspector@2.8.0 --cli npx -y @chrissgon/agent-ready-kit mcp --data site.json -- --method tools/call --tool-name list_posts --tool-arg limit=2
+```
+
+### In a Netlify Function (v2)
+
+The handler is stateless: each POST gets a new server and transport, responses are JSON (no SSE stream), any method other than POST gets 405 with `Allow: POST`, a body over `maxBodyBytes` (default 64 KiB) gets 413 before it is parsed, and every response carries `Cache-Control: no-store` and `X-Content-Type-Options: nosniff`. That is the pattern proven in the chrissgon.dev spike on Netlify Functions v2.
+
+```ts
+// netlify/functions/mcp.mts
+import type { Config } from "@netlify/functions";
+import { validate } from "@chrissgon/agent-ready-kit/data";
+import { createMcpHandler } from "@chrissgon/agent-ready-kit/mcp";
+import site from "../../site.json" with { type: "json" };
+
+export default createMcpHandler(validate(site), { name: "example.com", version: "1.0.0" });
+
+export const config: Config = { path: "/api/mcp" };
+```
+
+`name` and `version` are what the server reports to clients (default `agent-ready` and this package's version). A public endpoint costs something on every call; Netlify can rate-limit a function from its `config` (`rateLimit: { windowLimit, windowSize, aggregateBy: ["ip", "domain"] }`, see https://docs.netlify.com/manage/security/secure-access-to-sites/rate-limiting/).
+
+### In a static site
+
+Run `build` before the site generator and publish its output at the site root, so `llms.txt` is served at `/llms.txt` and each other language at `/<lang>/llms.txt`:
+
+```sh
+npx @chrissgon/agent-ready-kit build --data site.json --out public
+```
+
+Put the JSON-LD in the page head, from `public/jsonld.json` or from code with `serializeJsonLd(generateJsonLd(data))`:
+
+```html
+<script type="application/ld+json">{"@context":"https://schema.org","@graph":[ ... ]}</script>
+```
+
+## Development
+
+| Task | Command |
+|------|---------|
+| Install | `npm ci` |
+| Type-check | `npm run typecheck` |
+| Test | `npm test` (vitest; includes the MCP Inspector CLI over stdio) |
+| Build | `npm run build` (writes `dist/`) |
+| Packed tarball smoke test | `npm run test:pack` (packs, runs the CLI with `npx`, installs the tarball in a scratch project, imports every entry point and type-checks against the shipped types; needs the registry) |
+
+From a clone, `node dist/cli.js <command>` runs the CLI after `npm run build`.
+
+## Releasing
+
+Releases are published by `.github/workflows/publish.yml` with npm trusted publishing (no token) and provenance. The owner bumps `version` in `package.json` and `src/version.ts` through a pull request, then pushes the tag `v<version>` on the merged commit. The workflow checks that the tag matches `package.json` and is on `main`, runs the secret scan, types, tests, build and the packed-tarball smoke test, and publishes with `--access public`; a prerelease version (`0.2.0-beta.1`) goes to the `next` dist-tag.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+export declare const HELP = "Usage: agent-ready <command> --data <file> [--out <dir>]\n\nMake a small site readable by AI agents from one JSON data file.\n\nCommands:\n  build --data <file> --out <dir>   Write llms.txt (one per site language; the first at <dir>/llms.txt,\n                                    the others at <dir>/<lang>/llms.txt) and <dir>/jsonld.json.\n                                    Prints the written paths.\n  check --data <file>               Validate the data file. Prints a one-line summary.\n  mcp --data <file>                 Serve the read-only MCP server (get_profile, list_products,\n                                    list_posts) on stdin and stdout.\n\nOptions:\n  --data <file>   The JSON data file.\n  --out <dir>     Output folder (build only).\n  -h, --help      Show this help.\n\nExit codes: 0 ok, 1 invalid data, 2 wrong usage or unreadable file.\n";
+export interface Io {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+}
+/** Run the CLI with `argv` (without the node and script paths). Resolves to the exit code. */
+export declare function run(argv: string[], io?: Io): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// agent-ready: build llms.txt and JSON-LD, check a data file, or serve the read-only MCP server on stdio.
+// Data goes to stdout, diagnostics to stderr. Exit 0 ok, 1 invalid data, 2 wrong usage.
+import { realpathSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { generateJsonLd } from "./jsonld.js";
+import { generateLlms, llmsPath } from "./llms.js";
+import { DataError, loadData } from "./load.js";
+import { serveStdio } from "./stdio.js";
+export const HELP = `Usage: agent-ready <command> --data <file> [--out <dir>]
+
+Make a small site readable by AI agents from one JSON data file.
+
+Commands:
+  build --data <file> --out <dir>   Write llms.txt (one per site language; the first at <dir>/llms.txt,
+                                    the others at <dir>/<lang>/llms.txt) and <dir>/jsonld.json.
+                                    Prints the written paths.
+  check --data <file>               Validate the data file. Prints a one-line summary.
+  mcp --data <file>                 Serve the read-only MCP server (get_profile, list_products,
+                                    list_posts) on stdin and stdout.
+
+Options:
+  --data <file>   The JSON data file.
+  --out <dir>     Output folder (build only).
+  -h, --help      Show this help.
+
+Exit codes: 0 ok, 1 invalid data, 2 wrong usage or unreadable file.
+`;
+const processIo = {
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+};
+class UsageError extends Error {
+}
+async function readData(file) {
+    try {
+        return await loadData(file);
+    }
+    catch (err) {
+        if (err instanceof DataError)
+            throw err;
+        throw new UsageError(`cannot read ${file}: ${err.message}`);
+    }
+}
+async function build(data, out, io) {
+    const files = data.site.langs.map((lang) => [join(out, llmsPath(data, lang)), generateLlms(data, { lang })]);
+    files.push([join(out, "jsonld.json"), `${JSON.stringify(generateJsonLd(data), null, 2)}\n`]);
+    for (const [path, content] of files) {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, content, "utf8");
+        io.stdout(`${path}\n`);
+    }
+}
+/** Run the CLI with `argv` (without the node and script paths). Resolves to the exit code. */
+export async function run(argv, io = processIo) {
+    try {
+        const { values, positionals } = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            strict: true,
+            options: {
+                data: { type: "string" },
+                out: { type: "string" },
+                help: { type: "boolean", short: "h" },
+            },
+        });
+        if (values.help) {
+            io.stdout(HELP);
+            return 0;
+        }
+        const [command, ...extra] = positionals;
+        if (!command)
+            throw new UsageError("missing command");
+        if (!["build", "check", "mcp"].includes(command))
+            throw new UsageError(`unknown command "${command}"`);
+        if (extra.length)
+            throw new UsageError(`unexpected argument "${extra[0]}"`);
+        if (!values.data)
+            throw new UsageError(`${command} needs --data <file>`);
+        if (command === "build" && !values.out)
+            throw new UsageError("build needs --out <dir>");
+        if (command !== "build" && values.out)
+            throw new UsageError(`--out only applies to build`);
+        const data = await readData(values.data);
+        if (command === "check") {
+            const { owner, products, posts, site } = data;
+            io.stdout(`ok: ${values.data}: ${owner.type} "${owner.name}", ${products.length} products, ${posts.length} posts, languages ${site.langs.join(", ")}\n`);
+        }
+        else if (command === "build") {
+            await build(data, values.out, io);
+        }
+        else {
+            await serveStdio(data);
+            io.stderr(`agent-ready: read-only MCP server for "${data.owner.name}" on stdio\n`);
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof DataError) {
+            io.stderr(`${err.message}\n`);
+            return 1;
+        }
+        const message = err.message;
+        // parseArgs throws TypeError with a code for unknown or malformed options.
+        if (err instanceof UsageError || err.code?.startsWith("ERR_PARSE_ARGS")) {
+            io.stderr(`agent-ready: ${message}\nRun "agent-ready --help" for usage.\n`);
+            return 2;
+        }
+        io.stderr(`agent-ready: ${message}\n`);
+        return 1;
+    }
+}
+/** True when this file is the process entry point, also through the npm bin symlink. */
+function isEntry() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntry()) {
+    // Never call process.exit: the mcp command keeps the process alive on stdin.
+    process.exitCode = await run(process.argv.slice(2));
+}

package/dist/data.d.ts

@@ -0,0 +1,2 @@
+export { FORBIDDEN_FIELDS, SiteDataSchema, type Owner, type Post, type Product, type SiteData } from "./schema.js";
+export { DataError, loadData, parseData, validate } from "./load.js";

package/dist/data.js

@@ -0,0 +1,3 @@
+// Entry point `@chrissgon/agent-ready-kit/data`: the data file contract and its validation, without the MCP SDK.
+export { FORBIDDEN_FIELDS, SiteDataSchema } from "./schema.js";
+export { DataError, loadData, parseData, validate } from "./load.js";

package/dist/handler.d.ts

@@ -0,0 +1,11 @@
+import { type McpServerOptions } from "./mcp.js";
+import type { SiteData } from "./schema.js";
+export type McpHandler = (request: Request) => Promise<Response>;
+/** Default largest request body, in bytes. A JSON-RPC call to these tools is a few hundred bytes. */
+export declare const DEFAULT_MAX_BODY_BYTES: number;
+export interface McpHandlerOptions extends McpServerOptions {
+    /** Largest request body accepted, in bytes; a larger one gets 413 before it is parsed. Default 64 KiB. */
+    maxBodyBytes?: number;
+}
+/** A handler that serves the read-only MCP server over `data`. */
+export declare function createMcpHandler(data: SiteData, options?: McpHandlerOptions): McpHandler;

package/dist/handler.js

@@ -0,0 +1,56 @@
+// A Web Request handler for the MCP server, for any runtime with the Fetch API (Netlify Functions v2,
+// Deno, Bun, Cloudflare Workers, Node 22+). Stateless Streamable HTTP, as proven in the chrissgon.dev
+// spike: a new server and transport per request, no session id, JSON responses instead of SSE, so a
+// buffered serverless response is enough; anything but POST gets 405, a body over the limit gets 413,
+// and every response says it must not be cached.
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { buildServer } from "./mcp.js";
+/** Default largest request body, in bytes. A JSON-RPC call to these tools is a few hundred bytes. */
+export const DEFAULT_MAX_BODY_BYTES = 64 * 1024;
+/** Set on every response: tool answers are per request, and the body is JSON, never sniffed as anything else. */
+const NO_STORE = { "cache-control": "no-store", "x-content-type-options": "nosniff" };
+function jsonRpcError(status, message, headers = {}) {
+    return new Response(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message }, id: null }), {
+        status,
+        headers: { "content-type": "application/json", ...NO_STORE, ...headers },
+    });
+}
+/** A handler that serves the read-only MCP server over `data`. */
+export function createMcpHandler(data, options = {}) {
+    const { maxBodyBytes = DEFAULT_MAX_BODY_BYTES, ...serverOptions } = options;
+    const tooLarge = () => jsonRpcError(413, `Request body too large (limit ${maxBodyBytes} bytes).`);
+    return async (request) => {
+        // Stateless: no server-initiated SSE stream (GET) and no session to end (DELETE).
+        if (request.method !== "POST") {
+            return jsonRpcError(405, "Method not allowed. This stateless MCP endpoint accepts POST only.", { allow: "POST" });
+        }
+        const declared = Number(request.headers.get("content-length") ?? "0");
+        if (Number.isFinite(declared) && declared > maxBodyBytes)
+            return tooLarge();
+        // The declared length can be missing or wrong, so the body that was read is measured too.
+        const body = await request.arrayBuffer();
+        if (body.byteLength > maxBodyBytes)
+            return tooLarge();
+        const server = buildServer(data, serverOptions);
+        const transport = new WebStandardStreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true,
+        });
+        try {
+            await server.connect(transport);
+            const response = await transport.handleRequest(new Request(request.url, { method: "POST", headers: request.headers, body }));
+            for (const [key, value] of Object.entries(NO_STORE))
+                response.headers.set(key, value);
+            return response;
+        }
+        catch (err) {
+            console.error("agent-ready: mcp handler error", err);
+            return jsonRpcError(500, "Internal server error");
+        }
+        finally {
+            // With JSON responses the body is complete before handleRequest resolves, so closing here is safe.
+            await transport.close();
+            await server.close();
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { FORBIDDEN_FIELDS, SiteDataSchema, type Owner, type Post, type Product, type SiteData } from "./schema.js";
+export { DataError, loadData, parseData, validate } from "./load.js";
+export { DEFAULT_LLMS_LABELS, generateLlms, generateLlmsParts, LLMS_PARTS, llmsPath, type LlmsLabels, type LlmsOptions, type LlmsPart, } from "./llms.js";
+export { generateJsonLd, ownerIdOf, serializeJsonLd, spdxLicenseUrl, type JsonLdDocument, type JsonLdNode, type JsonLdOptions, } from "./jsonld.js";
+export { buildServer, instructionsFor, TOOL_NAMES, type McpServerOptions } from "./mcp.js";
+export { createMcpHandler, DEFAULT_MAX_BODY_BYTES, type McpHandler, type McpHandlerOptions } from "./handler.js";
+export { serveStdio } from "./stdio.js";
+export { VERSION } from "./version.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+// Public API of @chrissgon/agent-ready-kit. The subpaths `/data`, `/llms`, `/jsonld` and `/mcp` export parts
+// of it; all but `/mcp` load without the MCP SDK.
+export { FORBIDDEN_FIELDS, SiteDataSchema } from "./schema.js";
+export { DataError, loadData, parseData, validate } from "./load.js";
+export { DEFAULT_LLMS_LABELS, generateLlms, generateLlmsParts, LLMS_PARTS, llmsPath, } from "./llms.js";
+export { generateJsonLd, ownerIdOf, serializeJsonLd, spdxLicenseUrl, } from "./jsonld.js";
+export { buildServer, instructionsFor, TOOL_NAMES } from "./mcp.js";
+export { createMcpHandler, DEFAULT_MAX_BODY_BYTES } from "./handler.js";
+export { serveStdio } from "./stdio.js";
+export { VERSION } from "./version.js";

package/dist/jsonld.d.ts

@@ -0,0 +1,23 @@
+import { type SiteData } from "./schema.js";
+export interface JsonLdOptions {
+    /** Language of the descriptions, one of `site.langs`; defaults to the first. */
+    lang?: string;
+    /** The URL of a product's license from its SPDX id. Default: the SPDX page, https://spdx.org/licenses/<id>.html. */
+    licenseUrl?: (spdxId: string) => string;
+}
+/** The SPDX page of a license, e.g. https://spdx.org/licenses/MIT.html. */
+export declare const spdxLicenseUrl: (spdxId: string) => string;
+export interface JsonLdNode {
+    "@type": string;
+    "@id"?: string;
+    [property: string]: unknown;
+}
+export interface JsonLdDocument {
+    "@context": "https://schema.org";
+    "@graph": JsonLdNode[];
+}
+/** The owner node's `@id`: the site URL with `#person` or `#organization`. Products point to it as `author`. */
+export declare const ownerIdOf: (data: SiteData) => string;
+export declare function generateJsonLd(data: SiteData, { lang, licenseUrl }?: JsonLdOptions): JsonLdDocument;
+/** JSON for a `<script type="application/ld+json">`, with "<" escaped so no tag can close the script. */
+export declare const serializeJsonLd: (doc: JsonLdDocument) => string;

package/dist/jsonld.js

@@ -0,0 +1,49 @@
+// schema.org JSON-LD from the data file: one @graph with the owner (Person or Organization) and one
+// SoftwareSourceCode per product, each pointing to the owner's @id (<site>/#person or #organization). Properties used are defined on
+// https://schema.org/SoftwareSourceCode and its parents CreativeWork and Thing (read 2026-09-30).
+import { forbiddenPaths } from "./schema.js";
+import { assertLang, defaultLang } from "./select.js";
+/** The SPDX page of a license, e.g. https://spdx.org/licenses/MIT.html. */
+export const spdxLicenseUrl = (spdxId) => `https://spdx.org/licenses/${spdxId}.html`;
+/** Throw `jsonld: forbidden field <path>` for every forbidden field found in `value`. */
+function refuseForbidden(value) {
+    const found = forbiddenPaths(value).map((p) => `jsonld: forbidden field ${p.map(String).join(".")}`);
+    if (found.length)
+        throw new Error(found.join("\n"));
+}
+/** The owner node's `@id`: the site URL with `#person` or `#organization`. Products point to it as `author`. */
+export const ownerIdOf = (data) => `${data.site.url}/#${data.owner.type.toLowerCase()}`;
+export function generateJsonLd(data, { lang = defaultLang(data), licenseUrl = spdxLicenseUrl } = {}) {
+    // The data is typed, but code can still add a field at run time; refuse it before and after building.
+    refuseForbidden(data);
+    assertLang(data, lang, "jsonld");
+    const { owner, site } = data;
+    const ownerId = ownerIdOf(data);
+    const ownerNode = { "@type": owner.type, "@id": ownerId, name: owner.name };
+    if (owner.alternateName)
+        ownerNode.alternateName = owner.alternateName;
+    if (owner.type === "Person" && owner.jobTitle)
+        ownerNode.jobTitle = owner.jobTitle;
+    ownerNode.description = owner.label[lang];
+    ownerNode.url = `${site.url}/`;
+    if (owner.profiles.length)
+        ownerNode.sameAs = owner.profiles.map((p) => p.url);
+    const productNodes = data.products.map((p) => {
+        const node = { "@type": "SoftwareSourceCode", name: p.name, description: p.summary[lang] };
+        if (p.url)
+            node.url = p.url;
+        if (p.codeRepository)
+            node.codeRepository = p.codeRepository;
+        if (p.programmingLanguage.length)
+            node.programmingLanguage = p.programmingLanguage;
+        if (p.license)
+            node.license = licenseUrl(p.license);
+        node.author = { "@id": ownerId };
+        return node;
+    });
+    const doc = { "@context": "https://schema.org", "@graph": [ownerNode, ...productNodes] };
+    refuseForbidden(doc);
+    return doc;
+}
+/** JSON for a `<script type="application/ld+json">`, with "<" escaped so no tag can close the script. */
+export const serializeJsonLd = (doc) => JSON.stringify(doc).replace(/</g, "\\u003c");

package/dist/llms.d.ts

@@ -0,0 +1,45 @@
+import type { SiteData } from "./schema.js";
+/** Headings and the fixed words inside the lines. Every one has an English default. */
+export interface LlmsLabels {
+    /** H2 above the about paragraphs. Default: none, so the paragraphs are free text before the H2 sections. */
+    about?: string;
+    /** H2 of the products. Default "Products". */
+    products: string;
+    /** H2 of the posts. Default "Writing". */
+    writing: string;
+    /** H2 of the MCP endpoint and the other languages' files. Default "For agents". */
+    forAgents: string;
+    /** Before a product's code repository. Default "Code". */
+    code: string;
+    /** Before a product's license. Default "License". */
+    license: string;
+    /** Before a product's programming languages. Default "Programming languages". */
+    programmingLanguages: string;
+    /** Before a post's languages. Default "languages". */
+    languages: string;
+    /** The MCP endpoint's link text. Default "MCP server". */
+    mcpServer: string;
+    /** The MCP endpoint's notes, before the tool names. Default "read-only, Streamable HTTP (POST); tools". */
+    mcpNotes: string;
+    /** The notes of a link to another language's file, before the language code. Default "this file in". */
+    thisFileIn: string;
+}
+export declare const DEFAULT_LLMS_LABELS: Readonly<LlmsLabels>;
+export interface LlmsOptions {
+    /** One of `site.langs`; defaults to the first. */
+    lang?: string;
+    /** Headings and words for this language; missing ones keep their English default. */
+    labels?: Partial<LlmsLabels>;
+}
+/** The parts of llms.txt, in order. Joined, they are `generateLlms`; a site can place its own parts between them. */
+export declare const LLMS_PARTS: readonly ["head", "about", "products", "writing", "agents"];
+export type LlmsPart = (typeof LLMS_PARTS)[number];
+/** Where the llms.txt of `lang` lives, relative to the site root: the default language at the root. */
+export declare function llmsPath(data: SiteData, lang: string): string;
+/**
+ * Each part of llms.txt as text ending in one newline, or "" when the data has nothing for it (no about,
+ * no products, no posts, no MCP endpoint and one language). `generateLlms` joins the non-empty parts
+ * with a blank line between them.
+ */
+export declare function generateLlmsParts(data: SiteData, { lang, labels }?: LlmsOptions): Record<LlmsPart, string>;
+export declare function generateLlms(data: SiteData, options?: LlmsOptions): string;

package/dist/llms.js

@@ -0,0 +1,69 @@
+import { TOOL_NAMES } from "./tools.js";
+import { assertLang, defaultLang, postsNewestFirst, postTitle, productLink } from "./select.js";
+export const DEFAULT_LLMS_LABELS = {
+    products: "Products",
+    writing: "Writing",
+    forAgents: "For agents",
+    code: "Code",
+    license: "License",
+    programmingLanguages: "Programming languages",
+    languages: "languages",
+    mcpServer: "MCP server",
+    mcpNotes: "read-only, Streamable HTTP (POST); tools",
+    thisFileIn: "this file in",
+};
+/** The parts of llms.txt, in order. Joined, they are `generateLlms`; a site can place its own parts between them. */
+export const LLMS_PARTS = ["head", "about", "products", "writing", "agents"];
+/** Where the llms.txt of `lang` lives, relative to the site root: the default language at the root. */
+export function llmsPath(data, lang) {
+    return lang === defaultLang(data) ? "llms.txt" : `${lang}/llms.txt`;
+}
+/**
+ * Each part of llms.txt as text ending in one newline, or "" when the data has nothing for it (no about,
+ * no products, no posts, no MCP endpoint and one language). `generateLlms` joins the non-empty parts
+ * with a blank line between them.
+ */
+export function generateLlmsParts(data, { lang = defaultLang(data), labels = {} } = {}) {
+    assertLang(data, lang, "llms");
+    const w = { ...DEFAULT_LLMS_LABELS, ...labels };
+    const { owner, site } = data;
+    const block = (lines) => (lines.length ? `${lines.join("\n")}\n` : "");
+    const section = (title, items) => items.length ? block([...(title ? [`## ${title}`, ""] : []), ...items]) : "";
+    const head = [`# ${owner.name}`, "", `> ${owner.label[lang]}`];
+    if (owner.profiles.length) {
+        head.push("", ...owner.profiles.map((p) => `- [${p.network}](${p.url})${p.handle ? `: ${p.handle}` : ""}`));
+    }
+    const about = (owner.about?.[lang] ?? []).flatMap((paragraph, i) => (i ? ["", paragraph] : [paragraph]));
+    const products = data.products.map((p) => {
+        const notes = [p.summary[lang]];
+        if (p.url && p.codeRepository)
+            notes.push(`${w.code}: ${p.codeRepository}.`);
+        if (p.npm)
+            notes.push(`npm: ${p.npm}.`);
+        if (p.license)
+            notes.push(`${w.license}: ${p.license}.`);
+        if (p.programmingLanguage.length)
+            notes.push(`${w.programmingLanguages}: ${p.programmingLanguage.join(", ")}.`);
+        return `- [${p.name}](${productLink(p)}): ${notes.join(" ")}`;
+    });
+    const writing = postsNewestFirst(data).map((p) => `- [${postTitle(p, lang)}](${p.url}): ${p.date}; ${w.languages}: ${p.lang.join(", ")}`);
+    const agents = [];
+    if (site.mcp)
+        agents.push(`- [${w.mcpServer}](${site.mcp}): ${w.mcpNotes} ${TOOL_NAMES.join(", ")}`);
+    for (const other of site.langs.filter((l) => l !== lang)) {
+        agents.push(`- [llms.txt (${other})](${site.url}/${llmsPath(data, other)}): ${w.thisFileIn} ${other}`);
+    }
+    return {
+        head: block(head),
+        about: section(w.about, about),
+        products: section(w.products, products),
+        writing: section(w.writing, writing),
+        agents: section(w.forAgents, agents),
+    };
+}
+export function generateLlms(data, options = {}) {
+    const parts = generateLlmsParts(data, options);
+    return LLMS_PARTS.map((name) => parts[name])
+        .filter(Boolean)
+        .join("\n");
+}

package/dist/load.d.ts

@@ -0,0 +1,12 @@
+import { type SiteData } from "./schema.js";
+/** The data file is not valid. `issues` holds one `data: <field path>: <message>` line per problem. */
+export declare class DataError extends Error {
+    readonly issues: string[];
+    constructor(issues: string[]);
+}
+/** Validate a parsed data file. Throws DataError when it is not valid. */
+export declare function validate(value: unknown): SiteData;
+/** Parse and validate the text of a data file. */
+export declare function parseData(json: string): SiteData;
+/** Read, parse and validate a data file. A file that cannot be read throws the file system error. */
+export declare function loadData(file: string): Promise<SiteData>;

package/dist/load.js

@@ -0,0 +1,49 @@
+// Read and validate a data file. Every problem becomes one line `data: <field path>: <message>`.
+import { readFile } from "node:fs/promises";
+import { FORBIDDEN_FIELDS, forbiddenPaths, SiteDataSchema } from "./schema.js";
+/** The data file is not valid. `issues` holds one `data: <field path>: <message>` line per problem. */
+export class DataError extends Error {
+    issues;
+    constructor(issues) {
+        super(issues.join("\n"));
+        this.name = "DataError";
+        this.issues = issues;
+    }
+}
+const FORBIDDEN = new Set(FORBIDDEN_FIELDS);
+const line = (path, message) => `data: ${path.length ? path.map(String).join(".") : "(root)"}: ${message}`;
+function zodLines(issues) {
+    return issues.flatMap((issue) => {
+        if (issue.code === "unrecognized_keys") {
+            // Forbidden keys are reported on their own, with a clearer message.
+            return issue.keys.filter((k) => !FORBIDDEN.has(k)).map((k) => line([...issue.path, k], "unknown field"));
+        }
+        return [line(issue.path, issue.message)];
+    });
+}
+/** Validate a parsed data file. Throws DataError when it is not valid. */
+export function validate(value) {
+    const forbidden = forbiddenPaths(value).map((p) => line(p, `forbidden field "${String(p.at(-1))}", the kit never publishes it`));
+    const result = SiteDataSchema.safeParse(value, {
+        error: (iss) => (iss.input === undefined && iss.code === "invalid_type" ? "required" : undefined),
+    });
+    const issues = [...forbidden, ...(result.success ? [] : zodLines(result.error.issues))];
+    if (issues.length || !result.success)
+        throw new DataError(issues.length ? issues : [line([], "invalid data")]);
+    return result.data;
+}
+/** Parse and validate the text of a data file. */
+export function parseData(json) {
+    let value;
+    try {
+        value = JSON.parse(json);
+    }
+    catch (err) {
+        throw new DataError([line([], `invalid JSON: ${err.message}`)]);
+    }
+    return validate(value);
+}
+/** Read, parse and validate a data file. A file that cannot be read throws the file system error. */
+export async function loadData(file) {
+    return parseData(await readFile(file, "utf8"));
+}

package/dist/mcp.d.ts

@@ -0,0 +1,13 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SiteData } from "./schema.js";
+export { TOOL_NAMES } from "./tools.js";
+export interface McpServerOptions {
+    /** The server name reported to clients in `initialize`. Default "agent-ready". */
+    name?: string;
+    /** The server version reported to clients. Default: this package's version. */
+    version?: string;
+}
+/** The server's instructions for `owner`: read-only, and nothing but the public profile, products and posts. */
+export declare const instructionsFor: (ownerName: string) => string;
+/** A new server over `data`. Stateless: build one per connection or per HTTP request. */
+export declare function buildServer(data: SiteData, { name, version }?: McpServerOptions): McpServer;

package/dist/mcp.js

@@ -0,0 +1,125 @@
+// The read-only MCP server: three tools that return slices of the validated data file and nothing else.
+// No tool writes, sends, executes or searches free text; inputs are strict, so an extra argument is
+// rejected by validation (the tool contract of chrissgon.dev's ADR-0004).
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { defaultLang, postsNewestFirst, postTitle } from "./select.js";
+import { VERSION } from "./version.js";
+export { TOOL_NAMES } from "./tools.js";
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const ProfileOutput = z.object({
+    lang: z.string(),
+    type: z.enum(["Person", "Organization"]),
+    name: z.string(),
+    alternateName: z.string().optional(),
+    jobTitle: z.string().optional(),
+    label: z.string(),
+    about: z.array(z.string()),
+    url: z.string(),
+    profiles: z.array(z.object({ network: z.string(), handle: z.string().optional(), url: z.string() })),
+});
+const ProductsOutput = z.object({
+    lang: z.string(),
+    products: z.array(z.object({
+        id: z.string().optional(),
+        name: z.string(),
+        url: z.string().optional(),
+        codeRepository: z.string().optional(),
+        npm: z.string().optional(),
+        license: z.string().optional(),
+        programmingLanguage: z.array(z.string()),
+        summary: z.string(),
+    })),
+});
+const PostsOutput = z.object({
+    lang: z.string(),
+    total: z.int(),
+    posts: z.array(z.object({ id: z.string(), title: z.string(), date: z.string(), languages: z.array(z.string()), url: z.string() })),
+});
+/** A tool result whose text is the JSON of its structured content. */
+const result = (structuredContent) => ({
+    content: [{ type: "text", text: JSON.stringify(structuredContent) }],
+    structuredContent,
+});
+/** Drop keys whose value is undefined, so optional fields are absent rather than null. */
+const compact = (value) => Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+/**
+ * MCP lets a client omit `arguments` in tools/call. SDK 1.31.0 validates the missing value against the
+ * tool's object schema and fails with "expected object, received undefined", so a call without
+ * arguments is passed on as `{}`. Must run before the first registerTool, which installs the handler.
+ */
+function treatMissingArgumentsAsEmpty(server) {
+    const inner = server.server;
+    const install = inner.setRequestHandler.bind(inner);
+    // The SDK's generic handler types do not survive a wrapper; the request shape is checked at run time.
+    inner.setRequestHandler = ((schema, handler) => install(schema, (request, extra) => handler(request.method === "tools/call" && request.params?.arguments === undefined
+        ? { ...request, params: { ...request.params, arguments: {} } }
+        : request, extra)));
+}
+/** The server's instructions for `owner`: read-only, and nothing but the public profile, products and posts. */
+export const instructionsFor = (ownerName) => `Read-only. This server only holds ${ownerName}'s public profile, products and posts; any other personal data does not exist here.`;
+/** A new server over `data`. Stateless: build one per connection or per HTTP request. */
+export function buildServer(data, { name = "agent-ready", version = VERSION } = {}) {
+    const { owner, site } = data;
+    const langs = site.langs;
+    const server = new McpServer({ name, version }, { instructions: instructionsFor(owner.name) });
+    treatMissingArgumentsAsEmpty(server);
+    /** Every tool takes `lang`, the language of the texts it returns; the site's first language by default. */
+    const lang = z
+        .enum(langs)
+        .default(defaultLang(data))
+        .describe(`Language of the texts: ${langs.map((l) => `"${l}"`).join(" or ")} (default "${defaultLang(data)}").`);
+    server.registerTool("get_profile", {
+        title: "Get profile",
+        description: `Return ${owner.name}'s public profile: name, label, about, site URL and public profiles. Read-only.`,
+        inputSchema: z.strictObject({ lang }),
+        outputSchema: ProfileOutput,
+        annotations: READ_ONLY,
+    }, async ({ lang: l }) => result(compact({
+        lang: l,
+        type: owner.type,
+        name: owner.name,
+        alternateName: owner.alternateName,
+        jobTitle: owner.type === "Person" ? owner.jobTitle : undefined,
+        label: owner.label[l],
+        about: owner.about?.[l] ?? [],
+        url: `${site.url}/`,
+        profiles: owner.profiles.map((p) => compact({ network: p.network, handle: p.handle, url: p.url })),
+    })));
+    server.registerTool("list_products", {
+        title: "List products",
+        description: `List ${owner.name}'s products with their URL, code repository, npm package, license, programming languages and summary. Read-only.`,
+        inputSchema: z.strictObject({ lang }),
+        outputSchema: ProductsOutput,
+        annotations: READ_ONLY,
+    }, async ({ lang: l }) => result({
+        lang: l,
+        products: data.products.map((p) => compact({
+            id: p.id,
+            name: p.name,
+            url: p.url,
+            codeRepository: p.codeRepository,
+            npm: p.npm,
+            license: p.license,
+            programmingLanguage: p.programmingLanguage,
+            summary: p.summary[l],
+        })),
+    }));
+    server.registerTool("list_posts", {
+        title: "List posts",
+        description: `List ${owner.name}'s posts, newest first: title, date, languages and link. Read-only.`,
+        inputSchema: z.strictObject({
+            limit: z.int().min(1).max(50).default(10).describe("How many posts, newest first: 1 to 50 (default 10)."),
+            lang,
+        }),
+        outputSchema: PostsOutput,
+        annotations: READ_ONLY,
+    }, async ({ limit, lang: l }) => result({
+        lang: l,
+        total: data.posts.length,
+        posts: postsNewestFirst(data)
+            .slice(0, limit)
+            .map((p) => ({ id: p.id, title: postTitle(p, l), date: p.date, languages: p.lang, url: p.url })),
+    }));
+    return server;
+}

package/dist/schema.d.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+/** Fields the kit never publishes, wherever they appear in the data file. */
+export declare const FORBIDDEN_FIELDS: readonly ["worksFor", "address", "homeLocation", "birthDate", "email"];
+/** Paths of every forbidden key anywhere in a value, e.g. [["owner", "email"]]. */
+export declare function forbiddenPaths(value: unknown, path?: PropertyKey[]): PropertyKey[][];
+export declare const SiteDataSchema: z.ZodObject<{
+    site: z.ZodObject<{
+        url: z.ZodPipe<z.ZodURL, z.ZodTransform<string, string>>;
+        langs: z.ZodArray<z.ZodString>;
+        mcp: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strict>;
+    owner: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        name: z.ZodString;
+        alternateName: z.ZodOptional<z.ZodString>;
+        label: z.ZodRecord<z.ZodString, z.ZodString>;
+        about: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+        profiles: z.ZodArray<z.ZodObject<{
+            network: z.ZodString;
+            handle: z.ZodOptional<z.ZodString>;
+            url: z.ZodURL;
+        }, z.core.$strict>>;
+        type: z.ZodLiteral<"Person">;
+        jobTitle: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        name: z.ZodString;
+        alternateName: z.ZodOptional<z.ZodString>;
+        label: z.ZodRecord<z.ZodString, z.ZodString>;
+        about: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+        profiles: z.ZodArray<z.ZodObject<{
+            network: z.ZodString;
+            handle: z.ZodOptional<z.ZodString>;
+            url: z.ZodURL;
+        }, z.core.$strict>>;
+        type: z.ZodLiteral<"Organization">;
+    }, z.core.$strict>], "type">;
+    products: z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodURL>;
+        codeRepository: z.ZodOptional<z.ZodURL>;
+        npm: z.ZodOptional<z.ZodString>;
+        license: z.ZodOptional<z.ZodString>;
+        programmingLanguage: z.ZodArray<z.ZodString>;
+        summary: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>>;
+    posts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodRecord<z.ZodString, z.ZodString>;
+        date: z.ZodISODate;
+        lang: z.ZodArray<z.ZodString>;
+        url: z.ZodURL;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** A validated data file. */
+export type SiteData = z.output<typeof SiteDataSchema>;
+export type Owner = SiteData["owner"];
+export type Product = SiteData["products"][number];
+export type Post = SiteData["posts"][number];

package/dist/schema.js

@@ -0,0 +1,143 @@
+// The data file contract. Every object is strict: a field that is not declared here fails validation,
+// so nothing reaches llms.txt, the JSON-LD or the MCP server unless this schema names it.
+import { z } from "zod";
+/** Fields the kit never publishes, wherever they appear in the data file. */
+export const FORBIDDEN_FIELDS = ["worksFor", "address", "homeLocation", "birthDate", "email"];
+const FORBIDDEN = new Set(FORBIDDEN_FIELDS);
+/** Paths of every forbidden key anywhere in a value, e.g. [["owner", "email"]]. */
+export function forbiddenPaths(value, path = []) {
+    if (Array.isArray(value))
+        return value.flatMap((v, i) => forbiddenPaths(v, [...path, i]));
+    if (value === null || typeof value !== "object")
+        return [];
+    return Object.entries(value).flatMap(([key, v]) => FORBIDDEN.has(key) ? [[...path, key]] : forbiddenPaths(v, [...path, key]));
+}
+const LANG = /^[a-z]{2,3}(-[A-Z]{2})?$/;
+const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const NPM_NAME = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+const SPDX_ID = /^[A-Za-z0-9.+-]+$/;
+const text = z.string().trim().min(1, { error: "must not be empty" });
+const https = z.url({ protocol: /^https$/, error: "must be an https URL" });
+const lang = z.string().regex(LANG, { error: "must be a language code such as en or pt-BR" });
+/** A text per language code; which languages are required is checked against `site.langs`. */
+const localized = z.record(z.string(), text);
+const Profile = z.strictObject({
+    /** The network or site name shown to readers, e.g. "GitHub". */
+    network: text,
+    handle: text.optional(),
+    url: https,
+});
+const ownerFields = {
+    name: text,
+    /** A handle or short name. */
+    alternateName: text.optional(),
+    /** One line that says who the owner is; the llms.txt summary. */
+    label: localized,
+    /** Paragraphs about the owner, per language. */
+    about: z.record(z.string(), z.array(text).min(1)).optional(),
+    profiles: z.array(Profile),
+};
+const Person = z.strictObject({ type: z.literal("Person"), ...ownerFields, jobTitle: text.optional() });
+const Organization = z.strictObject({ type: z.literal("Organization"), ...ownerFields });
+const Product = z
+    .strictObject({
+    /** Optional stable slug, unique among products; the MCP server returns it so an agent can refer to a product. */
+    id: z.string().regex(SLUG, { error: "must be a lowercase slug such as my-product" }).optional(),
+    name: text,
+    url: https.optional(),
+    codeRepository: https.optional(),
+    /** npm package name. */
+    npm: z.string().regex(NPM_NAME, { error: "must be an npm package name" }).optional(),
+    /** SPDX license identifier, e.g. MIT. */
+    license: z.string().regex(SPDX_ID, { error: "must be an SPDX license identifier such as MIT" }).optional(),
+    programmingLanguage: z.array(text),
+    summary: localized,
+})
+    .refine((p) => p.url !== undefined || p.codeRepository !== undefined, {
+    error: "needs a url or a codeRepository",
+});
+const Post = z.strictObject({
+    id: z.string().regex(SLUG, { error: "must be a lowercase slug such as my-first-post" }),
+    /** The title per language of the post. */
+    title: localized,
+    date: z.iso.date({ error: "must be a date YYYY-MM-DD" }),
+    lang: z.array(lang).min(1),
+    url: https,
+});
+const Site = z.strictObject({
+    /** The site's origin, https, without a trailing slash (one is removed). */
+    url: https.transform((u) => u.replace(/\/+$/, "")),
+    /** Languages of the site; the first is the default. */
+    langs: z.array(lang).min(1),
+    /** Public URL of the site's MCP endpoint, when it serves one. */
+    mcp: https.optional(),
+});
+export const SiteDataSchema = z
+    .strictObject({
+    site: Site,
+    owner: z.discriminatedUnion("type", [Person, Organization]),
+    products: z.array(Product),
+    posts: z.array(Post),
+})
+    .superRefine((data, ctx) => {
+    const langs = data.site.langs;
+    const known = new Set(langs);
+    const list = langs.join(", ");
+    const seenLang = new Set();
+    langs.forEach((l, i) => {
+        if (seenLang.has(l))
+            ctx.addIssue({ code: "custom", path: ["site", "langs", i], message: `duplicate language "${l}"` });
+        seenLang.add(l);
+    });
+    /** Every site language has a text, and no key is a language the site does not declare. */
+    const checkLocalized = (value, path) => {
+        if (!value)
+            return;
+        for (const l of langs) {
+            if (!(l in value))
+                ctx.addIssue({ code: "custom", path: [...path, l], message: `missing text for site language "${l}"` });
+        }
+        for (const key of Object.keys(value)) {
+            if (!known.has(key))
+                ctx.addIssue({ code: "custom", path: [...path, key], message: `"${key}" is not a site language (${list})` });
+        }
+    };
+    checkLocalized(data.owner.label, ["owner", "label"]);
+    checkLocalized(data.owner.about, ["owner", "about"]);
+    data.products.forEach((p, i) => checkLocalized(p.summary, ["products", i, "summary"]));
+    const productIndex = new Map();
+    data.products.forEach((p, i) => {
+        if (p.id === undefined)
+            return;
+        const first = productIndex.get(p.id);
+        if (first !== undefined) {
+            ctx.addIssue({ code: "custom", path: ["products", i, "id"], message: `duplicate id "${p.id}" (first at products.${first})` });
+        }
+        else {
+            productIndex.set(p.id, i);
+        }
+    });
+    const firstIndex = new Map();
+    data.posts.forEach((post, i) => {
+        const first = firstIndex.get(post.id);
+        if (first !== undefined) {
+            ctx.addIssue({ code: "custom", path: ["posts", i, "id"], message: `duplicate id "${post.id}" (first at posts.${first})` });
+        }
+        else {
+            firstIndex.set(post.id, i);
+        }
+        post.lang.forEach((l, j) => {
+            if (!known.has(l))
+                ctx.addIssue({ code: "custom", path: ["posts", i, "lang", j], message: `"${l}" is not a site language (${list})` });
+        });
+        for (const key of Object.keys(post.title)) {
+            if (!known.has(key))
+                ctx.addIssue({ code: "custom", path: ["posts", i, "title", key], message: `"${key}" is not a site language (${list})` });
+        }
+        for (const l of post.lang) {
+            if (known.has(l) && !(l in post.title)) {
+                ctx.addIssue({ code: "custom", path: ["posts", i, "title", l], message: `missing text for post language "${l}"` });
+            }
+        }
+    });
+});

package/dist/select.d.ts

@@ -0,0 +1,11 @@
+import type { Post, SiteData } from "./schema.js";
+/** The site's default language: the first of `site.langs`. */
+export declare const defaultLang: (data: SiteData) => string;
+/** Throw `<prefix>: "<lang>" is not a site language (...)` unless the site declares `lang`. */
+export declare function assertLang(data: SiteData, lang: string, prefix: string): void;
+/** Posts sorted newest first; posts with the same date keep the file's order. */
+export declare const postsNewestFirst: (data: SiteData) => Post[];
+/** A post's title in `lang`, else in the post's first language. */
+export declare const postTitle: (post: Post, lang: string) => string;
+/** The public link of a product: its URL, else its code repository. */
+export declare const productLink: (p: SiteData["products"][number]) => string;

package/dist/select.js

@@ -0,0 +1,14 @@
+/** The site's default language: the first of `site.langs`. */
+export const defaultLang = (data) => data.site.langs[0];
+/** Throw `<prefix>: "<lang>" is not a site language (...)` unless the site declares `lang`. */
+export function assertLang(data, lang, prefix) {
+    if (!data.site.langs.includes(lang)) {
+        throw new Error(`${prefix}: "${lang}" is not a site language (${data.site.langs.join(", ")})`);
+    }
+}
+/** Posts sorted newest first; posts with the same date keep the file's order. */
+export const postsNewestFirst = (data) => [...data.posts].sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0));
+/** A post's title in `lang`, else in the post's first language. */
+export const postTitle = (post, lang) => post.title[lang] ?? post.title[post.lang[0]];
+/** The public link of a product: its URL, else its code repository. */
+export const productLink = (p) => (p.url ?? p.codeRepository);

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+export { buildServer, instructionsFor, TOOL_NAMES, type McpServerOptions } from "./mcp.js";
+export { createMcpHandler, DEFAULT_MAX_BODY_BYTES, type McpHandler, type McpHandlerOptions } from "./handler.js";

package/dist/server.js

@@ -0,0 +1,3 @@
+// Entry point `@chrissgon/agent-ready-kit/mcp`: the read-only MCP server and its Web Request handler.
+export { buildServer, instructionsFor, TOOL_NAMES } from "./mcp.js";
+export { createMcpHandler, DEFAULT_MAX_BODY_BYTES } from "./handler.js";

package/dist/stdio.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SiteData } from "./schema.js";
+/** Serve the read-only MCP server over `data` on stdin and stdout. Nothing else may write to stdout. */
+export declare function serveStdio(data: SiteData): Promise<McpServer>;

package/dist/stdio.js

@@ -0,0 +1,9 @@
+// The MCP server over stdio, for local clients that start it as a command.
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildServer } from "./mcp.js";
+/** Serve the read-only MCP server over `data` on stdin and stdout. Nothing else may write to stdout. */
+export async function serveStdio(data) {
+    const server = buildServer(data);
+    await server.connect(new StdioServerTransport());
+    return server;
+}

package/dist/tools.d.ts

@@ -0,0 +1,2 @@
+/** The MCP tools, in the order the server registers them. Kept apart from mcp.ts so llms.txt can name them without loading the MCP SDK. */
+export declare const TOOL_NAMES: readonly ["get_profile", "list_products", "list_posts"];

package/dist/tools.js

@@ -0,0 +1,2 @@
+/** The MCP tools, in the order the server registers them. Kept apart from mcp.ts so llms.txt can name them without loading the MCP SDK. */
+export const TOOL_NAMES = ["get_profile", "list_products", "list_posts"];

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** The package version, reported as the MCP server version. A test keeps it equal to package.json. */
+export declare const VERSION = "0.1.0";

package/dist/version.js

@@ -0,0 +1,2 @@
+/** The package version, reported as the MCP server version. A test keeps it equal to package.json. */
+export const VERSION = "0.1.0";

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@chrissgon/agent-ready-kit",
+  "version": "0.1.0",
+  "description": "Make a small site readable by AI agents from one data file: llms.txt, schema.org JSON-LD and a read-only MCP server.",
+  "keywords": [
+    "llms.txt",
+    "json-ld",
+    "schema.org",
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "seo",
+    "static-site"
+  ],
+  "homepage": "https://github.com/chrissgon/agent-ready-kit#readme",
+  "bugs": {
+    "url": "https://github.com/chrissgon/agent-ready-kit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrissgon/agent-ready-kit.git"
+  },
+  "license": "MIT",
+  "author": "Christopher Gonçalves (https://chrissgon.dev)",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "agent-ready": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./data": {
+      "types": "./dist/data.d.ts",
+      "default": "./dist/data.js"
+    },
+    "./llms": {
+      "types": "./dist/llms.d.ts",
+      "default": "./dist/llms.js"
+    },
+    "./jsonld": {
+      "types": "./dist/jsonld.d.ts",
+      "default": "./dist/jsonld.js"
+    },
+    "./mcp": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:pack": "bash scripts/pack-smoke.sh",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.31.0",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/inspector": "2.8.0",
+    "@types/node": "26.6.3",
+    "tsx": "4.23.15",
+    "typescript": "7.0.2",
+    "vitest": "5.0.2"
+  }
+}