@se-studio/site-mcp 0.0.0-next16-20260822103555

package/CHANGELOG.md

@@ -0,0 +1,200 @@
+# @se-studio/site-mcp
+
+## 0.0.0-next16-20260822103555
+
+### Patch Changes
+
+- Updated dependencies [eeed547]
+  - @se-studio/core-ui@0.0.0-next16-20260822103555
+
+## 0.3.23
+
+### Patch Changes
+
+- Updated dependencies [f8a2ec2]
+  - @se-studio/core-ui@1.24.7
+
+## 0.3.22
+
+### Patch Changes
+
+- Updated dependencies [b6434f7]
+  - @se-studio/core-ui@1.24.6
+
+## 0.3.21
+
+### Patch Changes
+
+- Updated dependencies [dbfb662]
+  - @se-studio/core-ui@1.24.5
+
+## 0.3.20
+
+### Patch Changes
+
+- Updated dependencies [2c479e7]
+  - @se-studio/core-ui@1.24.4
+
+## 0.3.19
+
+### Patch Changes
+
+- @se-studio/core-ui@1.24.3
+
+## 0.3.18
+
+### Patch Changes
+
+- Updated dependencies
+  - @se-studio/core-ui@1.24.2
+
+## 0.3.17
+
+### Patch Changes
+
+- Updated dependencies
+  - @se-studio/core-ui@1.24.1
+
+## 0.3.16
+
+### Patch Changes
+
+- Updated dependencies [50d02a0]
+  - @se-studio/core-ui@1.24.0
+
+## 0.3.15
+
+### Patch Changes
+
+- @se-studio/core-ui@1.23.2
+
+## 0.3.14
+
+### Patch Changes
+
+- Updated dependencies
+  - @se-studio/core-ui@1.23.1
+
+## 0.3.13
+
+### Patch Changes
+
+- Updated dependencies
+  - @se-studio/core-ui@1.23.0
+
+## 0.3.12
+
+### Patch Changes
+
+- Updated dependencies [5b69ac6]
+  - @se-studio/core-ui@1.22.1
+
+## 0.3.11
+
+### Patch Changes
+
+- Updated dependencies [760c9c4]
+  - @se-studio/core-ui@1.22.0
+
+## 0.3.10
+
+### Patch Changes
+
+- Updated dependencies
+  - @se-studio/core-ui@1.21.0
+
+## 0.3.9
+
+### Patch Changes
+
+- Updated dependencies [928562f]
+  - @se-studio/core-ui@1.20.0
+
+## 0.3.8
+
+### Patch Changes
+
+- Updated dependencies
+  - @se-studio/core-ui@1.19.10
+
+## 0.3.7
+
+### Patch Changes
+
+- Updated dependencies
+  - @se-studio/core-ui@1.19.9
+
+## 0.3.6
+
+### Patch Changes
+
+- @se-studio/core-ui@1.19.8
+
+## 0.3.5
+
+### Patch Changes
+
+- @se-studio/core-ui@1.19.7
+
+## 0.3.4
+
+### Patch Changes
+
+- @se-studio/core-ui@1.19.6
+
+## 0.3.3
+
+### Patch Changes
+
+- @se-studio/core-ui@1.19.5
+
+## 0.3.2
+
+### Patch Changes
+
+- @se-studio/core-ui@1.19.4
+
+## 0.3.1
+
+### Patch Changes
+
+- Add `apiPathNeedingTrailingSlash` for middleware: rewrite bare `/api/*` under Next `trailingSlash: true` so Streamable HTTP MCP POST is not 308’d. Document the pattern in site-mcp.
+- Updated dependencies
+  - @se-studio/core-ui@1.19.3
+
+## 0.3.0
+
+### Minor Changes
+
+- 14aeb6d: Agent discovery helpers: API catalog, A2A agent card, skills index builders; Link header options for api-catalog, agent-card, and agent-skills.
+
+### Patch Changes
+
+- Updated dependencies [14aeb6d]
+  - @se-studio/core-ui@1.19.2
+
+## 0.2.2
+
+### Patch Changes
+
+- 6573a6b: Rate-limit public Upstash search (default 10/min per IP) on `/api/search` and MCP `search_site` via optional `checkRateLimit` inject.
+
+## 0.2.1
+
+### Patch Changes
+
+- Updated dependencies [d9ddfa0]
+  - @se-studio/core-ui@1.19.1
+
+## 0.2.0
+
+### Minor Changes
+
+- e716d0e: Public site MCP (Band B): new `@se-studio/site-mcp` for stateless read-only agent tools (`get_markdown`, `get_site_info`, `search_site`). Server-card `endpointPath` is configurable (default `/api/mcp`); the App Router mount is the routing source of truth.
+
+  `@se-studio/core-ui`: opt-in MCP server-card Link headers (`mcpServerCard`), robots `allowExtra`, hardened `htmlPathToMarkdownPath` (encoded traversal + length), and `./agent-ready` subpath export for pure helpers shared with site-mcp.
+
+### Patch Changes
+
+- Updated dependencies [e716d0e]
+  - @se-studio/core-ui@1.19.0

package/README.md

@@ -0,0 +1,117 @@
+# @se-studio/site-mcp
+
+Public, **read-only**, **stateless** MCP for SE Studio marketing sites.
+
+Agents use tools instead of scraping HTML:
+
+| Tool | Purpose |
+|------|---------|
+| `search_site` | Hybrid search (injected; typically `@se-studio/search`) |
+| `get_markdown` | Fetch `/{path}.md` export |
+| `get_site_info` | Fetch `/site-info.md` |
+
+This is **not** cms-edit. No OAuth, no draft writes. Runs on the marketing origin.
+
+## Install
+
+```bash
+pnpm add @se-studio/site-mcp
+```
+
+## Endpoint path
+
+The **Next.js route file path** is the mount point (e.g. `app/api/mcp/route.ts` → `/api/mcp`).  
+`createSiteMcpHandler` does **not** take a path — routing is owned by App Router.
+
+**Trailing slash:** SE Studio sites use `trailingSlash: true`. Advertise **`/api/mcp` without a trailing slash** (server card, catalog, agent card). Also set **`skipTrailingSlashRedirect: true`** — Next’s built-in slash 308 runs before middleware and ignores rewrites. Then in middleware call `apiPathNeedingTrailingSlash` + `NextResponse.rewrite` for bare `/api/*`, and 308 HTML paths to the slashed form yourself if you still want page trailing slashes.
+
+Use `endpointPath` only on **`buildMcpServerCard`** so the well-known card advertises the same URL agents should call:
+
+| Site shape | Example `endpointPath` (server card) |
+|------------|--------------------------------------|
+| Standard SE Studio | `/api/mcp` |
+| Top-level | `/mcp` |
+| Point.me-style API prefix | `/marketing-api/mcp` |
+
+When under `/api/`, update robots with `allowExtra` from `@se-studio/core-ui`:
+
+```ts
+createRobotsTxtResponse({
+  isProduction,
+  baseUrl,
+  allowExtra: ['/api/mcp', '/api/search'],
+});
+```
+
+Some crawlers treat `Allow` loosely; discovery is primarily via `Link: rel="mcp-server-card"` and the well-known card.
+
+## Usage
+
+```ts
+// app/api/mcp/route.ts
+import { createSiteMcpHandler } from '@se-studio/site-mcp';
+import { baseUrl } from '@/lib/server-config';
+
+const handler = createSiteMcpHandler({
+  identity: {
+    name: 'se-studio',
+    title: 'Something Else',
+    websiteUrl: baseUrl,
+  },
+  tools: {
+    getMarkdown: {},
+    getSiteInfo: {},
+    // search: { search: async ({ query, limit, type }) => { … } },
+  },
+});
+
+export const GET = handler;
+export const POST = handler;
+export const DELETE = handler;
+```
+
+### Server card
+
+```ts
+// app/.well-known/mcp/server-card.json/route.ts
+import { buildMcpServerCard } from '@se-studio/site-mcp';
+import { baseUrl } from '@/lib/server-config';
+
+export function GET() {
+  const card = buildMcpServerCard({
+    identity: {
+      name: 'se-studio',
+      title: 'Something Else',
+      websiteUrl: baseUrl,
+    },
+    endpointPath: '/api/mcp', // must match the App Router mount
+    tools: { getMarkdown: {}, getSiteInfo: {} },
+  });
+  return Response.json(card, {
+    headers: {
+      'Cache-Control': 'public, s-maxage=3600, stale-while-revalidate',
+    },
+  });
+}
+```
+
+### Discovery Link header
+
+```ts
+appendAgentDiscoveryLinkHeaders(response.headers, pathname, { mcpServerCard: true });
+```
+
+## Path mapping
+
+Markdown paths use **`@se-studio/core-ui/agent-ready`** (`htmlPathToMarkdownPath`) — the same Band A helper as middleware content negotiation — so rules do not drift.
+
+## Safety defaults
+
+- Fetch timeout: 10s (override `fetchTimeoutMs`)
+- Max body: 512 KiB (override `maxBodyBytes`)
+- Encoded path traversal rejected
+- Tool failures set MCP `isError: true`
+
+## LLM reference
+
+See [docs/llms.md](./docs/llms.md).

package/dist/create-server.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { SiteMcpHandlerConfig } from './types.js';
+/**
+ * Create an MCP server instance with tools based on config.
+ * Fresh per request (stateless serverless).
+ */
+export declare function createSiteMcpServer(config: SiteMcpHandlerConfig): McpServer;
+//# sourceMappingURL=create-server.d.ts.map

package/dist/create-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-server.d.ts","sourceRoot":"","sources":["../src/create-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAgBvD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,CA+H3E"}

package/dist/create-server.js

@@ -0,0 +1,121 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { fetchTextLimited } from './fetch-text.js';
+import { joinUrl, resolveMarkdownRequestPath } from './path.js';
+import { listEnabledToolNames } from './server-card.js';
+import { SITE_MCP_VERSION } from './version.js';
+function toolText(text) {
+    return {
+        content: [{ type: 'text', text }],
+    };
+}
+function toolError(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}
+/**
+ * Create an MCP server instance with tools based on config.
+ * Fresh per request (stateless serverless).
+ */
+export function createSiteMcpServer(config) {
+    const version = config.identity.version ?? SITE_MCP_VERSION;
+    const websiteUrl = config.identity.websiteUrl.replace(/\/+$/, '');
+    const fetchImpl = config.fetch ?? fetch;
+    const tools = config.tools ?? {};
+    const fetchTimeoutMs = config.fetchTimeoutMs;
+    const maxBodyBytes = config.maxBodyBytes;
+    const server = new McpServer({
+        name: config.identity.name,
+        version,
+    });
+    const enabled = listEnabledToolNames(tools);
+    if (enabled.includes('get_markdown')) {
+        server.tool('get_markdown', `Fetch a page or article from ${config.identity.title} as clean Markdown (frontmatter + body). ` +
+            'Use public paths like "/", "/about", or article paths (not .md suffix). Prefer this over scraping HTML.', {
+            path: z.string().describe('Public page path, e.g. "/", "/about", "/work/case-study"'),
+        }, async ({ path }) => {
+            const mdPath = resolveMarkdownRequestPath(path);
+            if (!mdPath) {
+                return toolError(`Invalid or disallowed path: ${path}`);
+            }
+            const url = joinUrl(websiteUrl, mdPath);
+            const result = await fetchTextLimited(url, {
+                fetchImpl,
+                timeoutMs: fetchTimeoutMs,
+                maxBytes: maxBodyBytes,
+                headers: { Accept: 'text/markdown, text/plain, */*' },
+            });
+            if (!result.ok) {
+                return toolError(`${result.error} (${url})`);
+            }
+            // Raw markdown on success — agents can use it directly
+            return toolText(result.text);
+        });
+    }
+    if (enabled.includes('get_site_info')) {
+        server.tool('get_site_info', `Fetch the factual site-info document for ${config.identity.title} (counts, lists, summary for assistants).`, {}, async () => {
+            const url = joinUrl(websiteUrl, '/site-info.md');
+            const result = await fetchTextLimited(url, {
+                fetchImpl,
+                timeoutMs: fetchTimeoutMs,
+                maxBytes: maxBodyBytes,
+                headers: { Accept: 'text/markdown, text/plain, */*' },
+            });
+            if (!result.ok) {
+                return toolError(`${result.error} (${url})`);
+            }
+            return toolText(result.text);
+        });
+    }
+    if (enabled.includes('search_site') && tools.search) {
+        const searchFn = tools.search.search;
+        const checkRateLimit = tools.search.checkRateLimit;
+        const request = config.request;
+        server.tool('search_site', `Search published content on ${config.identity.title}. Returns titles, hrefs, and short snippets. ` +
+            'Use get_markdown on a result href/path for full page content.', {
+            query: z.string().min(1).describe('Search query'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .optional()
+                .describe('Max results (1–20, default 10)'),
+            type: z
+                .string()
+                .optional()
+                .describe('Optional content type filter, e.g. page, article, person'),
+        }, async ({ query, limit, type }) => {
+            const capped = Math.min(limit ?? 10, 20);
+            try {
+                if (checkRateLimit && request) {
+                    const rate = await checkRateLimit(request);
+                    if (!rate.allowed) {
+                        const retry = rate.retryAfterSeconds != null && rate.retryAfterSeconds > 0
+                            ? ` Try again in ${rate.retryAfterSeconds} seconds.`
+                            : '';
+                        return toolError(rate.message ?? `Rate limited: too many search requests.${retry}`);
+                    }
+                }
+                const result = await searchFn({
+                    query: query.trim(),
+                    limit: capped,
+                    type,
+                });
+                return toolText(JSON.stringify({
+                    query: result.query,
+                    totalCount: result.totalCount,
+                    results: result.results,
+                }));
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return toolError(`Search failed: ${message}`);
+            }
+        });
+    }
+    return server;
+}
+//# sourceMappingURL=create-server.js.map

package/dist/create-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-server.js","sourceRoot":"","sources":["../src/create-server.ts"],"names":[],"mappings":"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"}

package/dist/discovery.d.ts

@@ -0,0 +1,96 @@
+/**
+ * One API advertised in RFC 9727-style api-catalog linkset.
+ * Omit disabled/future endpoints (e.g. /api/ask) until they return 200.
+ */
+export interface ApiCatalogEntry {
+    /** Absolute or site-relative path of the API (e.g. `/api/mcp`). */
+    path: string;
+    /** Optional human docs URL (absolute or site-relative). */
+    serviceDoc?: string;
+    /** Optional schema.org type URL(s), e.g. SearchAction. */
+    type?: string | string[];
+}
+export interface BuildApiCatalogOptions {
+    baseUrl: string;
+    apis: ApiCatalogEntry[];
+}
+/**
+ * Build `application/linkset+json` body for `/.well-known/api-catalog`.
+ * Shape matches what isitagentready validates (Joost-compatible).
+ */
+export declare function buildApiCatalog(options: BuildApiCatalogOptions): {
+    linkset: Array<{
+        anchor: string;
+        'service-doc'?: Array<{
+            href: string;
+        }>;
+        type?: Array<{
+            href: string;
+        }>;
+    }>;
+};
+/** Skill advertised on an A2A agent card (maps to MCP tools today; ask later). */
+export interface A2AAgentSkill {
+    id: string;
+    name: string;
+    description: string;
+    inputModes?: string[];
+    outputModes?: string[];
+    examples?: string[];
+}
+export interface A2ASupportedInterface {
+    url: string;
+    transport: string;
+    protocol: string;
+}
+export interface BuildA2AAgentCardOptions {
+    name: string;
+    version?: string;
+    description: string;
+    /** Organization / site URL (provider). */
+    websiteUrl: string;
+    organization?: string;
+    /** Primary agent URL (usually the MCP endpoint). */
+    url: string;
+    supportedInterfaces?: A2ASupportedInterface[];
+    skills: A2AAgentSkill[];
+    capabilities?: {
+        streaming?: boolean;
+        pushNotifications?: boolean;
+    };
+}
+/**
+ * Build A2A Agent Card JSON for `/.well-known/agent-card.json`.
+ * v1 should describe live MCP tools only; add ask skill + /api/ask interface when Ask ships.
+ */
+export declare function buildA2AAgentCard(options: BuildA2AAgentCardOptions): Record<string, unknown>;
+export interface AgentSkillsIndexEntry {
+    name: string;
+    type?: string;
+    description: string;
+    /** Absolute or site-relative URL to SKILL.md */
+    url: string;
+    digest?: string;
+}
+export interface BuildAgentSkillsIndexOptions {
+    baseUrl: string;
+    skills: AgentSkillsIndexEntry[];
+    schema?: string;
+}
+/**
+ * Build Agent Skills discovery index for `/.well-known/agent-skills/index.json`.
+ * Only list real skills — do not pad empty entries for score.
+ */
+export declare function buildAgentSkillsIndex(options: BuildAgentSkillsIndexOptions): {
+    $schema: string;
+    skills: Array<{
+        name: string;
+        type: string;
+        description: string;
+        url: string;
+        digest?: string;
+    }>;
+};
+/** JSON response helpers for well-known routes. */
+export declare function jsonDiscoveryResponse(body: unknown, contentType?: string): Response;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,eAAe,EAAE,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG;IAChE,OAAO,EAAE,KAAK,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACxC,IAAI,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAChC,CAAC,CAAC;CACJ,CA0BA;AAED,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,mBAAmB,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAC9C,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,YAAY,CAAC,EAAE;QACb,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;KAC7B,CAAC;CACH;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuC5F;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ,CAYA;AAED,mDAAmD;AACnD,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,OAAO,EACb,WAAW,SAAoC,GAC9C,QAAQ,CASV"}

package/dist/discovery.js

@@ -0,0 +1,94 @@
+import { joinUrl } from './path.js';
+/**
+ * Build `application/linkset+json` body for `/.well-known/api-catalog`.
+ * Shape matches what isitagentready validates (Joost-compatible).
+ */
+export function buildApiCatalog(options) {
+    const base = options.baseUrl.replace(/\/+$/, '');
+    const linkset = options.apis.map((api) => {
+        const anchor = api.path.startsWith('http') ? api.path : joinUrl(base, api.path);
+        const entry = { anchor };
+        if (api.serviceDoc) {
+            const doc = api.serviceDoc.startsWith('http')
+                ? api.serviceDoc
+                : joinUrl(base, api.serviceDoc);
+            entry['service-doc'] = [{ href: doc }];
+        }
+        if (api.type) {
+            const types = Array.isArray(api.type) ? api.type : [api.type];
+            entry.type = types.map((href) => ({ href }));
+        }
+        return entry;
+    });
+    return { linkset };
+}
+/**
+ * Build A2A Agent Card JSON for `/.well-known/agent-card.json`.
+ * v1 should describe live MCP tools only; add ask skill + /api/ask interface when Ask ships.
+ */
+export function buildA2AAgentCard(options) {
+    const websiteUrl = options.websiteUrl.replace(/\/+$/, '');
+    const primaryUrl = options.url.startsWith('http')
+        ? options.url
+        : joinUrl(websiteUrl, options.url);
+    const interfaces = options.supportedInterfaces ??
+        [
+            {
+                url: primaryUrl,
+                transport: 'http',
+                protocol: 'MCP/2025-11-25',
+            },
+        ];
+    return {
+        name: options.name,
+        version: options.version ?? '1.0.0',
+        description: options.description,
+        url: primaryUrl,
+        provider: {
+            organization: options.organization ?? options.name,
+            url: websiteUrl,
+        },
+        supportedInterfaces: interfaces,
+        capabilities: {
+            streaming: options.capabilities?.streaming ?? true,
+            pushNotifications: options.capabilities?.pushNotifications ?? false,
+        },
+        skills: options.skills.map((s) => ({
+            id: s.id,
+            name: s.name,
+            description: s.description,
+            inputModes: s.inputModes ?? ['text'],
+            outputModes: s.outputModes ?? ['text'],
+            ...(s.examples?.length ? { examples: s.examples } : {}),
+        })),
+    };
+}
+/**
+ * Build Agent Skills discovery index for `/.well-known/agent-skills/index.json`.
+ * Only list real skills — do not pad empty entries for score.
+ */
+export function buildAgentSkillsIndex(options) {
+    const base = options.baseUrl.replace(/\/+$/, '');
+    return {
+        $schema: options.schema ?? 'https://agentskills.io/schema/index.json',
+        skills: options.skills.map((s) => ({
+            name: s.name,
+            type: s.type ?? 'skill-md',
+            description: s.description,
+            url: s.url.startsWith('http') ? s.url : joinUrl(base, s.url),
+            ...(s.digest ? { digest: s.digest } : {}),
+        })),
+    };
+}
+/** JSON response helpers for well-known routes. */
+export function jsonDiscoveryResponse(body, contentType = 'application/json; charset=utf-8') {
+    return new Response(JSON.stringify(body, null, 2), {
+        status: 200,
+        headers: {
+            'Content-Type': contentType,
+            'Cache-Control': 'public, s-maxage=3600, stale-while-revalidate=86400',
+            'Access-Control-Allow-Origin': '*',
+        },
+    });
+}
+//# sourceMappingURL=discovery.js.map

package/dist/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoBpC;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAA+B;IAO7D,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACvC,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QAChF,MAAM,KAAK,GAIP,EAAE,MAAM,EAAE,CAAC;QAEf,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;YACnB,MAAM,GAAG,GAAG,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC;gBAC3C,CAAC,CAAC,GAAG,CAAC,UAAU;gBAChB,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;YAClC,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;QACzC,CAAC;QAED,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;YACb,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC9D,KAAK,CAAC,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAC/C,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;IAEH,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC;AAmCD;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAiC;IACjE,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC1D,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC;QAC/C,CAAC,CAAC,OAAO,CAAC,GAAG;QACb,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IAErC,MAAM,UAAU,GACd,OAAO,CAAC,mBAAmB;QAC1B;YACC;gBACE,GAAG,EAAE,UAAU;gBACf,SAAS,EAAE,MAAM;gBACjB,QAAQ,EAAE,gBAAgB;aAC3B;SACiC,CAAC;IAEvC,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,OAAO;QACnC,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,GAAG,EAAE,UAAU;QACf,QAAQ,EAAE;YACR,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,IAAI;YAClD,GAAG,EAAE,UAAU;SAChB;QACD,mBAAmB,EAAE,UAAU;QAC/B,YAAY,EAAE;YACZ,SAAS,EAAE,OAAO,CAAC,YAAY,EAAE,SAAS,IAAI,IAAI;YAClD,iBAAiB,EAAE,OAAO,CAAC,YAAY,EAAE,iBAAiB,IAAI,KAAK;SACpE;QACD,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACjC,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,CAAC,MAAM,CAAC;YACpC,WAAW,EAAE,CAAC,CAAC,WAAW,IAAI,CAAC,MAAM,CAAC;YACtC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxD,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAiBD;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAqC;IAUzE,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACjD,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,MAAM,IAAI,0CAA0C;QACrE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACjC,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,UAAU;YAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC;YAC5D,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1C,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,qBAAqB,CACnC,IAAa,EACb,WAAW,GAAG,iCAAiC;IAE/C,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;QACjD,MAAM,EAAE,GAAG;QACX,OAAO,EAAE;YACP,cAAc,EAAE,WAAW;YAC3B,eAAe,EAAE,qDAAqD;YACtE,6BAA6B,EAAE,GAAG;SACnC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/fetch-text.d.ts

@@ -0,0 +1,23 @@
+/** Default timeout for origin fetches (markdown / site-info). */
+export declare const DEFAULT_FETCH_TIMEOUT_MS = 10000;
+/** Default max body size (~512 KiB) for public tool responses. */
+export declare const DEFAULT_MAX_BODY_BYTES: number;
+export type FetchTextResult = {
+    ok: true;
+    text: string;
+    status: number;
+} | {
+    ok: false;
+    error: string;
+    status?: number;
+};
+/**
+ * Fetch a URL as text with timeout and max body size.
+ */
+export declare function fetchTextLimited(url: string, options?: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    maxBytes?: number;
+    headers?: Record<string, string>;
+}): Promise<FetchTextResult>;
+//# sourceMappingURL=fetch-text.d.ts.map