@se-studio/site-mcp 0.2.2 → 0.3.1

package/CHANGELOG.md

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

package/README.md

@@ -23,6 +23,8 @@ pnpm add @se-studio/site-mcp
 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). In middleware, call `apiPathNeedingTrailingSlash` from `@se-studio/core-ui` and `NextResponse.rewrite` so bare `/api/*` hits the handler without a client-visible 308 (Streamable HTTP POST cannot rely on redirects).
+
 Use `endpointPath` only on **`buildMcpServerCard`** so the well-known card advertises the same URL agents should call:
 
 | Site shape | Example `endpointPath` (server card) |

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.2";
+export declare const SITE_MCP_VERSION = "0.3.1";
 //# 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.2";
+export const SITE_MCP_VERSION = "0.3.1";
 //# sourceMappingURL=version.js.map

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/docs/llms.md

@@ -58,6 +58,29 @@ buildMcpServerCard({
 ## Paths
 
 - Mount via Next route (e.g. `/api/mcp`)
-- Card `endpointPath` must match mount
+- Card `endpointPath` must match mount (**no** trailing slash)
+- Sites with `trailingSlash: true`: middleware rewrite bare `/api/*` via `apiPathNeedingTrailingSlash` from `@se-studio/core-ui` (avoids 308 on MCP POST)
 - 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.2",
+  "version": "0.3.1",
   "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.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.5",