@se-studio/site-mcp 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# @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.
+
+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,CAkH3E"}

package/dist/create-server.js

@@ -0,0 +1,110 @@
+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;
+        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 {
+                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/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

package/dist/fetch-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-text.d.ts","sourceRoot":"","sources":["../src/fetch-text.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,kEAAkE;AAClE,eAAO,MAAM,sBAAsB,QAAa,CAAC;AAEjD,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B,GACL,OAAO,CAAC,eAAe,CAAC,CAmD1B"}

package/dist/fetch-text.js

@@ -0,0 +1,56 @@
+/** Default timeout for origin fetches (markdown / site-info). */
+export const DEFAULT_FETCH_TIMEOUT_MS = 10_000;
+/** Default max body size (~512 KiB) for public tool responses. */
+export const DEFAULT_MAX_BODY_BYTES = 512 * 1024;
+/**
+ * Fetch a URL as text with timeout and max body size.
+ */
+export async function fetchTextLimited(url, options = {}) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BODY_BYTES;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, {
+            headers: options.headers,
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            return { ok: false, error: `HTTP ${res.status}`, status: res.status };
+        }
+        const contentLength = res.headers.get('content-length');
+        if (contentLength) {
+            const len = Number(contentLength);
+            if (Number.isFinite(len) && len > maxBytes) {
+                return {
+                    ok: false,
+                    error: `Content too large (${len} bytes; max ${maxBytes})`,
+                    status: res.status,
+                };
+            }
+        }
+        // Prefer arrayBuffer so we can enforce a hard cap without loading unbounded strings
+        const buffer = await res.arrayBuffer();
+        if (buffer.byteLength > maxBytes) {
+            return {
+                ok: false,
+                error: `Content too large (${buffer.byteLength} bytes; max ${maxBytes})`,
+                status: res.status,
+            };
+        }
+        const text = new TextDecoder('utf-8').decode(buffer);
+        return { ok: true, text, status: res.status };
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+            return { ok: false, error: `Request timed out after ${timeoutMs}ms` };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: message };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=fetch-text.js.map

package/dist/fetch-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-text.js","sourceRoot":"","sources":["../src/fetch-text.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAE/C,kEAAkE;AAClE,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,GAAG,IAAI,CAAC;AAMjD;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAAW,EACX,UAKI,EAAE;IAEN,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;IAC7C,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,wBAAwB,CAAC;IAChE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,sBAAsB,CAAC;IAE5D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAE9D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE;YAC/B,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QAEH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,GAAG,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;QACxE,CAAC;QAED,MAAM,aAAa,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QACxD,IAAI,aAAa,EAAE,CAAC;YAClB,MAAM,GAAG,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;YAClC,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,QAAQ,EAAE,CAAC;gBAC3C,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,KAAK,EAAE,sBAAsB,GAAG,eAAe,QAAQ,GAAG;oBAC1D,MAAM,EAAE,GAAG,CAAC,MAAM;iBACnB,CAAC;YACJ,CAAC;QACH,CAAC;QAED,oFAAoF;QACpF,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,WAAW,EAAE,CAAC;QACvC,IAAI,MAAM,CAAC,UAAU,GAAG,QAAQ,EAAE,CAAC;YACjC,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,sBAAsB,MAAM,CAAC,UAAU,eAAe,QAAQ,GAAG;gBACxE,MAAM,EAAE,GAAG,CAAC,MAAM;aACnB,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACrD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;IAChD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YACtD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,2BAA2B,SAAS,IAAI,EAAE,CAAC;QACxE,CAAC;QACD,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IACvC,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

package/dist/generated/version.d.ts

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

package/dist/generated/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/generated/version.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,qBAAqB,wBAAwB,CAAC;AAC3D,eAAO,MAAM,gBAAgB,UAAU,CAAC"}

package/dist/generated/version.js

@@ -0,0 +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.1.0";
+//# sourceMappingURL=version.js.map

package/dist/generated/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/generated/version.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,MAAM,CAAC,MAAM,qBAAqB,GAAG,qBAAqB,CAAC;AAC3D,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC"}

package/dist/handler.d.ts

@@ -0,0 +1,20 @@
+import type { SiteMcpHandlerConfig } from './types.js';
+/**
+ * Create a Next.js-compatible route handler for public site MCP (stateless Streamable HTTP).
+ *
+ * Mount at the route that matches your public path (e.g. `app/api/mcp/route.ts` → `/api/mcp`).
+ * The handler does not take `endpointPath` — that value is only for {@link buildMcpServerCard}
+ * so the well-known card advertises the same URL agents should call.
+ *
+ * @example
+ * ```ts
+ * // app/api/mcp/route.ts
+ * import { createSiteMcpHandler } from '@se-studio/site-mcp';
+ * const handler = createSiteMcpHandler({ identity: {…}, tools: {…} });
+ * export const GET = handler;
+ * export const POST = handler;
+ * export const DELETE = handler;
+ * ```
+ */
+export declare function createSiteMcpHandler(config: SiteMcpHandlerConfig): (request: Request) => Promise<Response>;
+//# sourceMappingURL=handler.d.ts.map

package/dist/handler.d.ts.map

@@ -0,0 +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"}

package/dist/handler.js

@@ -0,0 +1,58 @@
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { createSiteMcpServer } from './create-server.js';
+const CORS_HEADERS = {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Accept, Authorization, Mcp-Session-Id, Mcp-Protocol-Version, Mcp-Method, Mcp-Name',
+    'Access-Control-Expose-Headers': 'Mcp-Session-Id, Mcp-Protocol-Version',
+};
+function withCors(response) {
+    const headers = new Headers(response.headers);
+    for (const [key, value] of Object.entries(CORS_HEADERS)) {
+        headers.set(key, value);
+    }
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
+/**
+ * Create a Next.js-compatible route handler for public site MCP (stateless Streamable HTTP).
+ *
+ * Mount at the route that matches your public path (e.g. `app/api/mcp/route.ts` → `/api/mcp`).
+ * The handler does not take `endpointPath` — that value is only for {@link buildMcpServerCard}
+ * so the well-known card advertises the same URL agents should call.
+ *
+ * @example
+ * ```ts
+ * // app/api/mcp/route.ts
+ * import { createSiteMcpHandler } from '@se-studio/site-mcp';
+ * const handler = createSiteMcpHandler({ identity: {…}, tools: {…} });
+ * export const GET = handler;
+ * export const POST = handler;
+ * export const DELETE = handler;
+ * ```
+ */
+export function createSiteMcpHandler(config) {
+    return async function siteMcpHandler(request) {
+        if (request.method === 'OPTIONS') {
+            return new Response(null, { status: 204, headers: CORS_HEADERS });
+        }
+        try {
+            const server = createSiteMcpServer(config);
+            const transport = new WebStandardStreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                enableJsonResponse: true,
+            });
+            await server.connect(transport);
+            const response = await transport.handleRequest(request);
+            return withCors(response);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return withCors(Response.json({ error: 'MCP handler failed', message }, { status: 500 }));
+        }
+    };
+}
+//# sourceMappingURL=handler.js.map

package/dist/handler.js.map

@@ -0,0 +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"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { createSiteMcpServer } from './create-server.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';
+export { htmlPathToMarkdownPath, joinUrl, MAX_MARKDOWN_PATH_INPUT, normalizeEndpointPath, resolveMarkdownRequestPath, } from './path.js';
+export { buildMcpServerCard, listEnabledToolNames } from './server-card.js';
+export type { McpServerCard, SiteMcpHandlerConfig, SiteMcpIdentity, SiteMcpSearchArgs, SiteMcpSearchFn, SiteMcpSearchHit, SiteMcpToolsConfig, } from './types.js';
+export { DEFAULT_ENDPOINT_PATH } from './types.js';
+export { SITE_MCP_PACKAGE_NAME, SITE_MCP_VERSION } from './version.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export { createSiteMcpServer } from './create-server.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';
+export { buildMcpServerCard, listEnabledToolNames } from './server-card.js';
+export { DEFAULT_ENDPOINT_PATH } from './types.js';
+export { SITE_MCP_PACKAGE_NAME, SITE_MCP_VERSION } from './version.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/path.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Site-mcp path helpers.
+ *
+ * HTML → markdown mapping lives in `@se-studio/core-ui/agent-ready` (Band A) so
+ * middleware negotiation and this package stay in sync. This module only adds
+ * agent-input normalization and URL joining.
+ */
+import { htmlPathToMarkdownPath } from '@se-studio/core-ui/agent-ready';
+export { htmlPathToMarkdownPath };
+/** Cap agent-provided path strings before mapping. */
+export declare const MAX_MARKDOWN_PATH_INPUT = 512;
+/**
+ * Normalize endpoint path: leading slash, no trailing slash (except root).
+ * Used by the server card so agents know the transport URL; the Next.js route
+ * path is the mount point (they must match).
+ */
+export declare function normalizeEndpointPath(path: string | undefined): string;
+/**
+ * Normalize agent-provided path input for get_markdown.
+ */
+export declare function resolveMarkdownRequestPath(input: string): string | null;
+/**
+ * Join origin + path without double slashes.
+ */
+export declare function joinUrl(origin: string, path: string): string;
+//# sourceMappingURL=path.d.ts.map

package/dist/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAExE,OAAO,EAAE,sBAAsB,EAAE,CAAC;AAElC,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAOtE;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOvE;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI5D"}

package/dist/path.js

@@ -0,0 +1,44 @@
+/**
+ * Site-mcp path helpers.
+ *
+ * HTML → markdown mapping lives in `@se-studio/core-ui/agent-ready` (Band A) so
+ * middleware negotiation and this package stay in sync. This module only adds
+ * agent-input normalization and URL joining.
+ */
+import { htmlPathToMarkdownPath } from '@se-studio/core-ui/agent-ready';
+export { htmlPathToMarkdownPath };
+/** Cap agent-provided path strings before mapping. */
+export const MAX_MARKDOWN_PATH_INPUT = 512;
+/**
+ * Normalize endpoint path: leading slash, no trailing slash (except root).
+ * Used by the server card so agents know the transport URL; the Next.js route
+ * path is the mount point (they must match).
+ */
+export function normalizeEndpointPath(path) {
+    const raw = (path ?? '/api/mcp').trim() || '/api/mcp';
+    let p = raw.startsWith('/') ? raw : `/${raw}`;
+    if (p.length > 1 && p.endsWith('/')) {
+        p = p.slice(0, -1);
+    }
+    return p;
+}
+/**
+ * Normalize agent-provided path input for get_markdown.
+ */
+export function resolveMarkdownRequestPath(input) {
+    const trimmed = input.trim();
+    if (!trimmed || trimmed.length > MAX_MARKDOWN_PATH_INPUT) {
+        return null;
+    }
+    const withSlash = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+    return htmlPathToMarkdownPath(withSlash);
+}
+/**
+ * Join origin + path without double slashes.
+ */
+export function joinUrl(origin, path) {
+    const base = origin.replace(/\/+$/, '');
+    const p = path.startsWith('/') ? path : `/${path}`;
+    return `${base}${p}`;
+}
+//# sourceMappingURL=path.js.map

package/dist/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAExE,OAAO,EAAE,sBAAsB,EAAE,CAAC;AAElC,sDAAsD;AACtD,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAE3C;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAwB;IAC5D,MAAM,GAAG,GAAG,CAAC,IAAI,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,UAAU,CAAC;IACtD,IAAI,CAAC,GAAG,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC;IAC9C,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACpC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAAa;IACtD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,uBAAuB,EAAE,CAAC;QACzD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;IACpE,OAAO,sBAAsB,CAAC,SAAS,CAAC,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,OAAO,CAAC,MAAc,EAAE,IAAY;IAClD,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACxC,MAAM,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;IACnD,OAAO,GAAG,IAAI,GAAG,CAAC,EAAE,CAAC;AACvB,CAAC"}

package/dist/server-card.d.ts

@@ -0,0 +1,15 @@
+import { type McpServerCard, type SiteMcpIdentity, type SiteMcpToolsConfig } from './types.js';
+export declare function listEnabledToolNames(tools?: SiteMcpToolsConfig): string[];
+/**
+ * Build a static-ish MCP server card for `/.well-known/mcp/server-card.json`.
+ *
+ * `endpointPath` is advertisement-only: set it to the same path as your Next.js
+ * route (e.g. `/api/mcp` for `app/api/mcp/route.ts`). The HTTP handler does not
+ * read this value — the App Router mount is the source of truth for routing.
+ */
+export declare function buildMcpServerCard(options: {
+    identity: SiteMcpIdentity;
+    endpointPath?: string;
+    tools?: SiteMcpToolsConfig | string[];
+}): McpServerCard;
+//# sourceMappingURL=server-card.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server-card.d.ts","sourceRoot":"","sources":["../src/server-card.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAC;AAGpB,wBAAgB,oBAAoB,CAAC,KAAK,CAAC,EAAE,kBAAkB,GAAG,MAAM,EAAE,CAYzE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC1C,QAAQ,EAAE,eAAe,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,kBAAkB,GAAG,MAAM,EAAE,CAAC;CACvC,GAAG,aAAa,CAkBhB"}

package/dist/server-card.js

@@ -0,0 +1,42 @@
+import { joinUrl, normalizeEndpointPath } from './path.js';
+import { DEFAULT_ENDPOINT_PATH, } from './types.js';
+import { SITE_MCP_VERSION } from './version.js';
+export function listEnabledToolNames(tools) {
+    const names = [];
+    if (tools?.getMarkdown?.enabled !== false && tools?.getMarkdown) {
+        names.push('get_markdown');
+    }
+    if (tools?.getSiteInfo?.enabled !== false && tools?.getSiteInfo) {
+        names.push('get_site_info');
+    }
+    if (tools?.search) {
+        names.push('search_site');
+    }
+    return names;
+}
+/**
+ * Build a static-ish MCP server card for `/.well-known/mcp/server-card.json`.
+ *
+ * `endpointPath` is advertisement-only: set it to the same path as your Next.js
+ * route (e.g. `/api/mcp` for `app/api/mcp/route.ts`). The HTTP handler does not
+ * read this value — the App Router mount is the source of truth for routing.
+ */
+export function buildMcpServerCard(options) {
+    const endpointPath = normalizeEndpointPath(options.endpointPath ?? DEFAULT_ENDPOINT_PATH);
+    const websiteUrl = options.identity.websiteUrl.replace(/\/+$/, '');
+    const toolNames = Array.isArray(options.tools)
+        ? options.tools
+        : listEnabledToolNames(options.tools);
+    return {
+        name: options.identity.name,
+        title: options.identity.title,
+        version: options.identity.version ?? SITE_MCP_VERSION,
+        websiteUrl,
+        endpointPath,
+        endpoint: joinUrl(websiteUrl, endpointPath),
+        transport: 'streamable-http',
+        tools: toolNames,
+        description: `Public read-only MCP for ${options.identity.title}: query site content without scraping HTML.`,
+    };
+}
+//# sourceMappingURL=server-card.js.map

package/dist/server-card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-card.js","sourceRoot":"","sources":["../src/server-card.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EACL,qBAAqB,GAItB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,MAAM,UAAU,oBAAoB,CAAC,KAA0B;IAC7D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,KAAK,EAAE,WAAW,EAAE,OAAO,KAAK,KAAK,IAAI,KAAK,EAAE,WAAW,EAAE,CAAC;QAChE,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC7B,CAAC;IACD,IAAI,KAAK,EAAE,WAAW,EAAE,OAAO,KAAK,KAAK,IAAI,KAAK,EAAE,WAAW,EAAE,CAAC;QAChE,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAC9B,CAAC;IACD,IAAI,KAAK,EAAE,MAAM,EAAE,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAIlC;IACC,MAAM,YAAY,GAAG,qBAAqB,CAAC,OAAO,CAAC,YAAY,IAAI,qBAAqB,CAAC,CAAC;IAC1F,MAAM,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACnE,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC;QAC5C,CAAC,CAAC,OAAO,CAAC,KAAK;QACf,CAAC,CAAC,oBAAoB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAExC,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI;QAC3B,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK;QAC7B,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,OAAO,IAAI,gBAAgB;QACrD,UAAU;QACV,YAAY;QACZ,QAAQ,EAAE,OAAO,CAAC,UAAU,EAAE,YAAY,CAAC;QAC3C,SAAS,EAAE,iBAAiB;QAC5B,KAAK,EAAE,SAAS;QAChB,WAAW,EAAE,4BAA4B,OAAO,CAAC,QAAQ,CAAC,KAAK,6CAA6C;KAC7G,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Identity for the public site MCP server and server-card.
+ */
+export interface SiteMcpIdentity {
+    /** Stable MCP server name (e.g. `se-studio`). */
+    name: string;
+    /** Human title (e.g. `Something Else`). */
+    title: string;
+    /** Absolute origin, e.g. `https://www.se.studio` (no trailing slash preferred). */
+    websiteUrl: string;
+    /** Optional override; defaults to package version from package.json. */
+    version?: string;
+}
+/**
+ * Compact search hit returned by the injected search function.
+ */
+export interface SiteMcpSearchHit {
+    title: string;
+    description?: string;
+    href: string;
+    type?: string;
+    score?: number;
+    /** Short body snippet (keep small for agent context). */
+    snippet?: string;
+}
+export interface SiteMcpSearchArgs {
+    query: string;
+    limit: number;
+    type?: string;
+}
+export type SiteMcpSearchFn = (args: SiteMcpSearchArgs) => Promise<{
+    results: SiteMcpSearchHit[];
+    query: string;
+    totalCount: number;
+}>;
+export interface SiteMcpToolsConfig {
+    /** Enable get_markdown (self-fetch of .md exports). Present object enables the tool. */
+    getMarkdown?: {
+        enabled?: boolean;
+    };
+    /** Enable get_site_info (self-fetch /site-info.md). */
+    getSiteInfo?: {
+        enabled?: boolean;
+    };
+    /** Enable search_site via injected function (no hard dep on @se-studio/search). */
+    search?: {
+        search: SiteMcpSearchFn;
+    };
+}
+/**
+ * Config for the HTTP MCP handler (mounted at whatever Next.js route path you choose).
+ *
+ * `endpointPath` is **not** needed here — the App Router file path is the mount point.
+ * Pass the same path to {@link buildMcpServerCard} so the server-card advertises it.
+ */
+export interface SiteMcpHandlerConfig {
+    identity: SiteMcpIdentity;
+    tools?: SiteMcpToolsConfig;
+    /** Optional fetch implementation (tests). Defaults to global fetch. */
+    fetch?: typeof fetch;
+    /** Origin fetch timeout in ms (default 10s). */
+    fetchTimeoutMs?: number;
+    /** Max markdown/site-info body bytes (default 512 KiB). */
+    maxBodyBytes?: number;
+}
+export interface McpServerCard {
+    name: string;
+    title: string;
+    version: string;
+    websiteUrl: string;
+    /** Absolute MCP endpoint URL. */
+    endpoint: string;
+    endpointPath: string;
+    transport: 'streamable-http';
+    tools: string[];
+    description: string;
+}
+export declare const DEFAULT_ENDPOINT_PATH = "/api/mcp";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export const DEFAULT_ENDPOINT_PATH = '/api/mcp';
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export { SITE_MCP_PACKAGE_NAME, SITE_MCP_VERSION } from './generated/version.js';
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/version.js

@@ -0,0 +1,2 @@
+export { SITE_MCP_PACKAGE_NAME, SITE_MCP_VERSION } from './generated/version.js';
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}

package/docs/llms.md

@@ -0,0 +1,52 @@
+# @se-studio/site-mcp — LLM reference
+
+Public read-only MCP for marketing sites. Stateless Streamable HTTP. Not cms-edit.
+
+## Exports
+
+| Export | Purpose |
+|--------|---------|
+| `createSiteMcpHandler(config)` | Next route handler (GET/POST/DELETE/OPTIONS) |
+| `createSiteMcpServer(config)` | In-process `McpServer` (tests) |
+| `buildMcpServerCard(options)` | JSON for `/.well-known/mcp/server-card.json` (`endpointPath` here) |
+| `listEnabledToolNames(tools)` | Tool names from config |
+| `normalizeEndpointPath` / `resolveMarkdownRequestPath` / `htmlPathToMarkdownPath` | Path helpers |
+| `fetchTextLimited` | Timeout + size-capped fetch |
+| `SITE_MCP_VERSION` | From `package.json` via generate-version |
+
+## Config
+
+```ts
+// Handler — no endpointPath (App Router owns the mount)
+createSiteMcpHandler({
+  identity: { name, title, websiteUrl, version? },
+  tools?: {
+    getMarkdown?: { enabled?: boolean },
+    getSiteInfo?: { enabled?: boolean },
+    search?: { search: (args) => Promise<{ results, query, totalCount }> },
+  },
+  fetch?: typeof fetch,
+  fetchTimeoutMs?: number,  // default 10000
+  maxBodyBytes?: number,    // default 512KiB
+});
+
+// Server card — advertise the same path as the route file
+buildMcpServerCard({
+  identity,
+  endpointPath: '/api/mcp',  // default
+  tools,
+});
+```
+
+## Tools
+
+- **get_markdown** `{ path }` → raw markdown text on success; `isError` on failure
+- **get_site_info** → raw `/site-info.md` text
+- **search_site** `{ query, limit?, type? }` → JSON hits; omit config to hide tool
+
+## Paths
+
+- Mount via Next route (e.g. `/api/mcp`)
+- 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/`

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@se-studio/site-mcp",
+  "version": "0.1.0",
+  "description": "Public, read-only, stateless MCP for SE Studio marketing sites (search, markdown, site-info)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Something-Else-Studio/se-core-product",
+    "directory": "packages/site-mcp"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.0.0 <25"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "*.md",
+    "docs"
+  ],
+  "scripts": {
+    "generate:version": "node scripts/generate-version.mjs",
+    "build": "node scripts/generate-version.mjs && tsc --project tsconfig.build.json",
+    "dev": "node scripts/generate-version.mjs && tsc --project tsconfig.build.json --watch",
+    "type-check": "node scripts/generate-version.mjs && tsc --noEmit",
+    "lint": "biome lint .",
+    "test": "node scripts/generate-version.mjs && vitest run",
+    "clean": "rm -rf dist .turbo *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@se-studio/core-ui": "workspace:*",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.5",
+    "@types/node": "^24.13.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  }
+}