@se-studio/site-mcp 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @se-studio/site-mcp
 
+## 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

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

@@ -1 +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,CAkH3E"}
+{"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

@@ -71,6 +71,8 @@ export function createSiteMcpServer(config) {
     }
     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'),
@@ -88,6 +90,15 @@ export function createSiteMcpServer(config) {
         }, 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,

package/dist/create-server.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-server.js","sourceRoot":"","sources":["../src/create-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,CAAC;KAC3C,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,OAAe;IAChC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QACnD,OAAO,EAAE,IAAa;KACvB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAA4B;IAC9D,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,IAAI,gBAAgB,CAAC;IAC5D,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAClE,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,IAAI,KAAK,CAAC;IACxC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;IACjC,MAAM,cAAc,GAAG,MAAM,CAAC,cAAc,CAAC;IAC7C,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IAEzC,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI;QAC1B,OAAO;KACR,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAE5C,IAAI,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QACrC,MAAM,CAAC,IAAI,CACT,cAAc,EACd,gCAAgC,MAAM,CAAC,QAAQ,CAAC,KAAK,2CAA2C;YAC9F,yGAAyG,EAC3G;YACE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0DAA0D,CAAC;SACtF,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;YACjB,MAAM,MAAM,GAAG,0BAA0B,CAAC,IAAI,CAAC,CAAC;YAChD,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,OAAO,SAAS,CAAC,+BAA+B,IAAI,EAAE,CAAC,CAAC;YAC1D,CAAC;YAED,MAAM,GAAG,GAAG,OAAO,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;YACxC,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE;gBACzC,SAAS;gBACT,SAAS,EAAE,cAAc;gBACzB,QAAQ,EAAE,YAAY;gBACtB,OAAO,EAAE,EAAE,MAAM,EAAE,gCAAgC,EAAE;aACtD,CAAC,CAAC;YAEH,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;gBACf,OAAO,SAAS,CAAC,GAAG,MAAM,CAAC,KAAK,KAAK,GAAG,GAAG,CAAC,CAAC;YAC/C,CAAC;YAED,uDAAuD;YACvD,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC,CACF,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QACtC,MAAM,CAAC,IAAI,CACT,eAAe,EACf,4CAA4C,MAAM,CAAC,QAAQ,CAAC,KAAK,2CAA2C,EAC5G,EAAE,EACF,KAAK,IAAI,EAAE;YACT,MAAM,GAAG,GAAG,OAAO,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC;YACjD,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE;gBACzC,SAAS;gBACT,SAAS,EAAE,cAAc;gBACzB,QAAQ,EAAE,YAAY;gBACtB,OAAO,EAAE,EAAE,MAAM,EAAE,gCAAgC,EAAE;aACtD,CAAC,CAAC;YAEH,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;gBACf,OAAO,SAAS,CAAC,GAAG,MAAM,CAAC,KAAK,KAAK,GAAG,GAAG,CAAC,CAAC;YAC/C,CAAC;YAED,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC,CACF,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACpD,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;QACrC,MAAM,CAAC,IAAI,CACT,aAAa,EACb,+BAA+B,MAAM,CAAC,QAAQ,CAAC,KAAK,+CAA+C;YACjG,+DAA+D,EACjE;YACE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,cAAc,CAAC;YACjD,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,GAAG,EAAE;iBACL,GAAG,CAAC,CAAC,CAAC;iBACN,GAAG,CAAC,EAAE,CAAC;iBACP,QAAQ,EAAE;iBACV,QAAQ,CAAC,gCAAgC,CAAC;YAC7C,IAAI,EAAE,CAAC;iBACJ,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,0DAA0D,CAAC;SACxE,EACD,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE;YAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;YACzC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC;oBAC5B,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE;oBACnB,KAAK,EAAE,MAAM;oBACb,IAAI;iBACL,CAAC,CAAC;gBACH,OAAO,QAAQ,CACb,IAAI,CAAC,SAAS,CAAC;oBACb,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,UAAU,EAAE,MAAM,CAAC,UAAU;oBAC7B,OAAO,EAAE,MAAM,CAAC,OAAO;iBACxB,CAAC,CACH,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACjE,OAAO,SAAS,CAAC,kBAAkB,OAAO,EAAE,CAAC,CAAC;YAChD,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"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":"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"}

package/dist/generated/version.d.ts

@@ -1,3 +1,3 @@
 export declare const SITE_MCP_PACKAGE_NAME = "@se-studio/site-mcp";
-export declare const SITE_MCP_VERSION = "0.2.1";
+export declare const SITE_MCP_VERSION = "0.3.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/generated/version.js

@@ -1,4 +1,4 @@
 // Generated by scripts/generate-version.mjs — do not edit manually.
 export const SITE_MCP_PACKAGE_NAME = "@se-studio/site-mcp";
-export const SITE_MCP_VERSION = "0.2.1";
+export const SITE_MCP_VERSION = "0.3.0";
 //# sourceMappingURL=version.js.map

package/dist/handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAsBvD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,oBAAoB,GAC3B,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAqBzC"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAsBvD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,oBAAoB,GAC3B,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAsBzC"}

package/dist/handler.js

@@ -40,7 +40,8 @@ export function createSiteMcpHandler(config) {
             return new Response(null, { status: 204, headers: CORS_HEADERS });
         }
         try {
-            const server = createSiteMcpServer(config);
+            // Per-request server so search rate limiting can use this HTTP request.
+            const server = createSiteMcpServer({ ...config, request });
             const transport = new WebStandardStreamableHTTPServerTransport({
                 sessionIdGenerator: undefined,
                 enableJsonResponse: true,

package/dist/handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"handler.js","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wCAAwC,EAAE,MAAM,+DAA+D,CAAC;AACzH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAGzD,MAAM,YAAY,GAA2B;IAC3C,6BAA6B,EAAE,GAAG;IAClC,8BAA8B,EAAE,4BAA4B;IAC5D,8BAA8B,EAC5B,iGAAiG;IACnG,+BAA+B,EAAE,sCAAsC;CACxE,CAAC;AAEF,SAAS,QAAQ,CAAC,QAAkB;IAClC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC9C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QACxD,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE;QACjC,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,UAAU,EAAE,QAAQ,CAAC,UAAU;QAC/B,OAAO;KACR,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAA4B;IAE5B,OAAO,KAAK,UAAU,cAAc,CAAC,OAAgB;QACnD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACjC,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC;QACpE,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;YAC3C,MAAM,SAAS,GAAG,IAAI,wCAAwC,CAAC;gBAC7D,kBAAkB,EAAE,SAAS;gBAC7B,kBAAkB,EAAE,IAAI;aACzB,CAAC,CAAC;YAEH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAChC,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;YACxD,OAAO,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,OAAO,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;QAC5F,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wCAAwC,EAAE,MAAM,+DAA+D,CAAC;AACzH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAGzD,MAAM,YAAY,GAA2B;IAC3C,6BAA6B,EAAE,GAAG;IAClC,8BAA8B,EAAE,4BAA4B;IAC5D,8BAA8B,EAC5B,iGAAiG;IACnG,+BAA+B,EAAE,sCAAsC;CACxE,CAAC;AAEF,SAAS,QAAQ,CAAC,QAAkB;IAClC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC9C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QACxD,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE;QACjC,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,UAAU,EAAE,QAAQ,CAAC,UAAU;QAC/B,OAAO;KACR,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAA4B;IAE5B,OAAO,KAAK,UAAU,cAAc,CAAC,OAAgB;QACnD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACjC,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC;QACpE,CAAC;QAED,IAAI,CAAC;YACH,wEAAwE;YACxE,MAAM,MAAM,GAAG,mBAAmB,CAAC,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;YAC3D,MAAM,SAAS,GAAG,IAAI,wCAAwC,CAAC;gBAC7D,kBAAkB,EAAE,SAAS;gBAC7B,kBAAkB,EAAE,IAAI;aACzB,CAAC,CAAC;YAEH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAChC,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;YACxD,OAAO,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,OAAO,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;QAC5F,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { createSiteMcpServer } from './create-server.js';
+export type { A2AAgentSkill, A2ASupportedInterface, AgentSkillsIndexEntry, ApiCatalogEntry, BuildA2AAgentCardOptions, BuildAgentSkillsIndexOptions, BuildApiCatalogOptions, } from './discovery.js';
+export { buildA2AAgentCard, buildAgentSkillsIndex, buildApiCatalog, jsonDiscoveryResponse, } from './discovery.js';
 export type { FetchTextResult } from './fetch-text.js';
 export { DEFAULT_FETCH_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES, fetchTextLimited, } from './fetch-text.js';
 export { createSiteMcpHandler } from './handler.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EACL,sBAAsB,EACtB,OAAO,EACP,uBAAuB,EACvB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC5E,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,YAAY,EACV,aAAa,EACb,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,wBAAwB,EACxB,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EACL,sBAAsB,EACtB,OAAO,EACP,uBAAuB,EACvB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC5E,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -1,4 +1,5 @@
 export { createSiteMcpServer } from './create-server.js';
+export { buildA2AAgentCard, buildAgentSkillsIndex, buildApiCatalog, jsonDiscoveryResponse, } from './discovery.js';
 export { DEFAULT_FETCH_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES, fetchTextLimited, } from './fetch-text.js';
 export { createSiteMcpHandler } from './handler.js';
 export { htmlPathToMarkdownPath, joinUrl, MAX_MARKDOWN_PATH_INPUT, normalizeEndpointPath, resolveMarkdownRequestPath, } from './path.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EACL,sBAAsB,EACtB,OAAO,EACP,uBAAuB,EACvB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAU5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAUzD,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EACL,sBAAsB,EACtB,OAAO,EACP,uBAAuB,EACvB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAU5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/dist/types.d.ts

@@ -45,6 +45,16 @@ export interface SiteMcpToolsConfig {
     /** Enable search_site via injected function (no hard dep on @se-studio/search). */
     search?: {
         search: SiteMcpSearchFn;
+        /**
+         * Optional billable-query rate limit (e.g. Upstash). Called with the HTTP
+         * request before `search`. Deny → tool error, no Upstash call.
+         * Wire from `@se-studio/search/rate-limit` `checkSearchRateLimit`.
+         */
+        checkRateLimit?: (request: Request) => Promise<{
+            allowed: boolean;
+            retryAfterSeconds?: number;
+            message?: string;
+        }>;
     };
 }
 /**
@@ -62,6 +72,11 @@ export interface SiteMcpHandlerConfig {
     fetchTimeoutMs?: number;
     /** Max markdown/site-info body bytes (default 512 KiB). */
     maxBodyBytes?: number;
+    /**
+     * Incoming HTTP request for this invocation (set by {@link createSiteMcpHandler}).
+     * Used for search rate limiting; apps normally do not set this.
+     */
+    request?: Request;
 }
 export interface McpServerCard {
     name: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,iBAAiB,KAAK,OAAO,CAAC;IACjE,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CAAC;AAEH,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,WAAW,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACpC,uDAAuD;IACvD,WAAW,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACpC,mFAAmF;IACnF,MAAM,CAAC,EAAE;QACP,MAAM,EAAE,eAAe,CAAC;KACzB,CAAC;CACH;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,gDAAgD;IAChD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,qBAAqB,aAAa,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,iBAAiB,KAAK,OAAO,CAAC;IACjE,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CAAC;AAEH,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,WAAW,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACpC,uDAAuD;IACvD,WAAW,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACpC,mFAAmF;IACnF,MAAM,CAAC,EAAE;QACP,MAAM,EAAE,eAAe,CAAC;QACxB;;;;WAIG;QACH,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;YAC7C,OAAO,EAAE,OAAO,CAAC;YACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;YAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;SAClB,CAAC,CAAC;KACJ,CAAC;CACH;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,gDAAgD;IAChD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,qBAAqB,aAAa,CAAC"}

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAgFA,MAAM,CAAC,MAAM,qBAAqB,GAAG,UAAU,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA+FA,MAAM,CAAC,MAAM,qBAAqB,GAAG,UAAU,CAAC"}

package/docs/llms.md

@@ -23,13 +23,24 @@ createSiteMcpHandler({
   tools?: {
     getMarkdown?: { enabled?: boolean },
     getSiteInfo?: { enabled?: boolean },
-    search?: { search: (args) => Promise<{ results, query, totalCount }> },
+    search?: {
+      search: (args) => Promise<{ results, query, totalCount }>,
+      // Optional: gate Upstash cost before search() runs (pass HTTP request from handler)
+      checkRateLimit?: (request: Request) => Promise<{
+        allowed: boolean;
+        retryAfterSeconds?: number;
+        message?: string;
+      }>,
+    },
   },
   fetch?: typeof fetch,
   fetchTimeoutMs?: number,  // default 10000
   maxBodyBytes?: number,    // default 512KiB
 });
 
+// Typical wire-up with @se-studio/search:
+// checkRateLimit: (req) => checkSearchRateLimit({ request: req, namespace: 'mcp' })
+
 // Server card — advertise the same path as the route file
 buildMcpServerCard({
   identity,
@@ -50,3 +61,25 @@ buildMcpServerCard({
 - Card `endpointPath` must match mount
 - Markdown mapping: `@se-studio/core-ui/agent-ready` (shared with Band A middleware)
 - Robots: `allowExtra: ['/api/mcp', '/api/search']` when under `Disallow: /api/`
+
+## Discovery builders (well-known)
+
+```ts
+import {
+  buildApiCatalog,
+  buildA2AAgentCard,
+  buildAgentSkillsIndex,
+  jsonDiscoveryResponse,
+} from '@se-studio/site-mcp';
+
+// GET /.well-known/api-catalog
+jsonDiscoveryResponse(buildApiCatalog({ baseUrl, apis: [{ path: '/api/mcp' }, { path: '/api/search', type: 'https://schema.org/SearchAction' }] }), 'application/linkset+json')
+
+// GET /.well-known/agent-card.json — MCP skills now; add ask skill when /api/ask exists
+buildA2AAgentCard({ name, description, websiteUrl: baseUrl, url: '/api/mcp', skills: [...] })
+
+// GET /.well-known/agent-skills/index.json — only real skills
+buildAgentSkillsIndex({ baseUrl, skills: [{ name, description, url: '/.well-known/agent-skills/.../SKILL.md' }] })
+```
+
+Link headers (core-ui): `appendAgentDiscoveryLinkHeaders(headers, pathname, { mcpServerCard, apiCatalog, agentCard, agentSkills })`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/site-mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Public, read-only, stateless MCP for SE Studio marketing sites (search, markdown, site-info)",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3",
-    "@se-studio/core-ui": "1.19.1"
+    "@se-studio/core-ui": "1.19.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.5",