wiki-formant 0.20.0 → 0.22.0

package/dist/well-known.d.ts

@@ -1,3 +1,4 @@
+import type { License } from './license.js';
 export interface RegistryAuthRecord {
     body: string;
     contentType: string;
@@ -48,13 +49,6 @@ export interface SkillSource {
  * capability the server does not have. `search_pages` becomes "Search Pages".
  */
 export declare function skillsFromTools(tools: readonly SkillSource[]): AgentSkill[];
-export interface AgentCardLicense {
-    name: string;
-    url: string;
-    spdx?: string;
-    /** What the licence covers, e.g. `'content'`. */
-    scope?: string;
-}
 export interface AgentCardConfig {
     name: string;
     description: string;
@@ -62,7 +56,10 @@ export interface AgentCardConfig {
     url: string;
     version: string;
     skills: AgentSkill[];
-    license?: AgentCardLicense;
+    /** The grant, as `ccBy40()` builds it. Projected once here, not per repo. */
+    license?: License;
+    /** What the grant covers, e.g. `'content'`, or which half of the site. */
+    licenseScope?: string;
     /** Defaults to `name`. */
     organization?: string;
     /** Defaults to `${url}/llms.txt`. */
@@ -127,3 +124,45 @@ protocolVersions: readonly string[]): Record<string, unknown>;
  * configured" instead of failing verification for a reason nobody sees.
  */
 export declare function registryAuthHandler(publicKey?: string | undefined, keyType?: string | undefined): () => Response;
+/** A tool as `/.well-known/mcp.json` lists it: what tools/list says, no handler. */
+export interface ManifestTool {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema: unknown;
+    annotations?: unknown;
+}
+export interface McpManifestConfig {
+    /** The server's display name. */
+    name: string;
+    /** Its registry name, from server.json. */
+    registryName: string;
+    version: string;
+    description: string;
+    /** Origin, no trailing slash. */
+    url: string;
+    /** Who runs it. Defaults to `name`. */
+    provider?: string;
+    tools: readonly ManifestTool[];
+    /** Auth notes, per-tenant endpoints, payment terms — what this origin has that others do not. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * `/.well-known/mcp.json`: the third path an arriving agent probes, after the
+ * agent card and the OpenAPI spec. All three origins wrote the same envelope,
+ * and one had already dropped the tool titles the other two listed. The
+ * protocol versions and the rate limit come from the transport that answers,
+ * so the manifest cannot advertise a version the server does not speak.
+ */
+export declare function mcpManifest(config: McpManifestConfig): Record<string, unknown>;
+/**
+ * A GET handler serving a descriptor built from code: ETag, 304, freshness.
+ * The agent cards, the manifest and the server card were each a three-line
+ * route around `descriptorResponse`, written out nine times.
+ */
+export declare function descriptorHandler(body: unknown, opts?: {
+    maxAge?: number;
+    extra?: Record<string, string>;
+}): (request: Request) => Response;
+/** The whole `<mcp-url>/server-card` route, projected from server.json. */
+export declare const serverCardHandler: (manifest: ServerManifest) => ((request: Request) => Response);

package/dist/well-known.js

@@ -9,6 +9,9 @@
 // Nothing here touches a framework: these return plain values, and the caller
 // wraps them in whatever its router wants. That keeps this package free of a
 // Next dependency and keeps each app's route a two-liner.
+import { MCP_PROTOCOL_VERSION, MCP_PROTOCOL_VERSIONS } from './mcp.js';
+import { MCP_RATE_LIMIT_TEXT } from './rate-limit.js';
+import { descriptorResponse } from './http.js';
 /**
  * The `v=MCPv1` record the official MCP registry fetches from
  * `/.well-known/mcp-registry-auth` to prove domain ownership. `mcp-publisher
@@ -70,7 +73,7 @@ const A2A_PROTOCOL_VERSION = '0.3.0';
  * means half the callers conclude the origin has no agent at all.
  */
 export function agentCard(config) {
-    const { name, description, url, version, skills, license, organization, documentationUrl, mcpEndpoint, extra } = config;
+    const { name, description, url, version, skills, license, licenseScope, organization, documentationUrl, mcpEndpoint, extra } = config;
     const endpoint = mcpEndpoint === null ? url : (mcpEndpoint ?? `${url}/api/mcp`);
     return {
         protocolVersion: A2A_PROTOCOL_VERSION,
@@ -89,7 +92,14 @@ export function agentCard(config) {
         provider: { organization: organization ?? name, url },
         documentationUrl: documentationUrl ?? `${url}/llms.txt`,
         ...(mcpEndpoint === null ? {} : { mcpEndpoint: endpoint }),
-        ...(license ? { license } : {}),
+        // The same two discovery URLs on every card. The three cards here named the
+        // spec `apiSpecUrl`, `apiSpecUrl` and `openapiUrl`, and one omitted the
+        // server card, so a client reading one card could not read the next.
+        apiSpecUrl: `${url}/.well-known/openapi.json`,
+        ...(mcpEndpoint === null ? {} : { mcpServerCard: `${endpoint}/server-card` }),
+        ...(license
+            ? { license: { name: license.name, spdx: license.spdx, url: license.url, ...(licenseScope ? { scope: licenseScope } : {}) } }
+            : {}),
         ...extra,
         defaultInputModes: ['text/plain', 'application/json'],
         defaultOutputModes: ['text/plain', 'application/json', 'text/markdown'],
@@ -155,3 +165,49 @@ export function registryAuthHandler(publicKey = process.env.MCP_REGISTRY_PUBLIC_
         });
     };
 }
+/**
+ * `/.well-known/mcp.json`: the third path an arriving agent probes, after the
+ * agent card and the OpenAPI spec. All three origins wrote the same envelope,
+ * and one had already dropped the tool titles the other two listed. The
+ * protocol versions and the rate limit come from the transport that answers,
+ * so the manifest cannot advertise a version the server does not speak.
+ */
+export function mcpManifest(config) {
+    const { name, registryName, version, description, url, provider, tools, extra } = config;
+    return {
+        schema_version: '1.0',
+        name,
+        registryName,
+        version,
+        description,
+        url,
+        provider: { name: provider ?? name, url },
+        api: { type: 'openapi', url: `${url}/.well-known/openapi.json` },
+        mcp: {
+            endpoint: `${url}/api/mcp`,
+            transport: 'streamable-http',
+            protocol: 'JSON-RPC 2.0',
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            supportedProtocolVersions: MCP_PROTOCOL_VERSIONS,
+            rateLimit: MCP_RATE_LIMIT_TEXT,
+        },
+        ...extra,
+        tools: tools.map(({ name, title, description, inputSchema, annotations }) => ({
+            name,
+            ...(title ? { title } : {}),
+            description,
+            inputSchema,
+            ...(annotations ? { annotations } : {}),
+        })),
+    };
+}
+/**
+ * A GET handler serving a descriptor built from code: ETag, 304, freshness.
+ * The agent cards, the manifest and the server card were each a three-line
+ * route around `descriptorResponse`, written out nine times.
+ */
+export function descriptorHandler(body, opts = {}) {
+    return request => descriptorResponse(request, body, opts);
+}
+/** The whole `<mcp-url>/server-card` route, projected from server.json. */
+export const serverCardHandler = (manifest) => descriptorHandler(serverCard(manifest, MCP_PROTOCOL_VERSIONS));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, and conditional-GET plumbing.",
   "type": "module",
   "license": "MIT",
@@ -159,6 +159,18 @@
     "./seeded": {
       "types": "./dist/seeded.d.ts",
       "import": "./dist/seeded.js"
+    },
+    "./sanitize": {
+      "types": "./dist/sanitize.d.ts",
+      "import": "./dist/sanitize.js"
+    },
+    "./corpus": {
+      "types": "./dist/corpus.d.ts",
+      "import": "./dist/corpus.js"
+    },
+    "./metadata": {
+      "types": "./dist/metadata.d.ts",
+      "import": "./dist/metadata.js"
     }
   },
   "bin": {
@@ -192,9 +204,11 @@
     "@tiptap/starter-kit": "^2.27.3",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
+    "@types/sanitize-html": "^2.16.1",
     "jose": "^6.2.10",
     "jsdom": "^30.1.0",
     "react": "^19.2.4",
+    "sanitize-html": "^2.17.7",
     "typescript": "^5.9.0"
   },
   "peerDependencies": {
@@ -212,7 +226,9 @@
     "@tiptap/react": ">=2.10",
     "@tiptap/starter-kit": ">=2.10",
     "jose": ">=5",
-    "react": ">=18"
+    "react": ">=18",
+    "sanitize-html": ">=2",
+    "@tiptap/pm": ">=2.10"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -259,6 +275,12 @@
     },
     "@tiptap/extension-placeholder": {
       "optional": true
+    },
+    "sanitize-html": {
+      "optional": true
+    },
+    "@tiptap/pm": {
+      "optional": true
     }
   }
 }