@crowi/api 2.0.0-alpha.0

package/dist/mcp/attach.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachMcp = void 0;
+const mcp_1 = require("@hono/mcp");
+const http_exception_1 = require("hono/http-exception");
+const rate_limit_1 = require("../util/rate-limit");
+const auth_1 = require("../hono/middleware/auth");
+const dispatch_1 = require("./dispatch");
+const server_1 = require("./server");
+/**
+ * Per-user budget for the `/mcp` endpoint. A single budget covers all
+ * tool calls (reads + writes); a runaway agent cannot hammer the wiki.
+ * Note the dispatched routes that have their own limiter (autocomplete)
+ * are double-counted — accepted for v1 (RFC-0011 open question).
+ */
+const RATE_LIMIT = 120;
+const RATE_WINDOW_MS = 60_000;
+/**
+ * JSON-RPC error codes for the few responses we emit before the MCP
+ * transport takes over (rate-limit / missing-bearer). `-32000` is the
+ * JSON-RPC "server error" range; `-32001` distinguishes the auth case.
+ */
+const JSONRPC_RATE_LIMITED = -32000;
+const JSONRPC_AUTH_REQUIRED = -32001;
+/** A bare JSON-RPC error envelope (`id: null` — pre-dispatch, no request id). */
+const jsonRpcError = (code, message) => ({ jsonrpc: '2.0', error: { code, message }, id: null });
+const attachMcp = (app, crowi) => {
+    // One shared limiter per process (Redis-backed when `crowi.redis !==
+    // null`, in-memory fallback otherwise — same pattern as autocomplete).
+    const limiter = (0, rate_limit_1.createRateLimiter)({
+        name: 'mcp',
+        limit: RATE_LIMIT,
+        windowMs: RATE_WINDOW_MS,
+        redisClient: crowi.redis ?? null,
+    });
+    // Auth gate: a valid PAT / OAuth token is required to reach the
+    // endpoint at all. Per-tool scope is enforced downstream.
+    app.use('/mcp', (0, auth_1.createJwtAuth)(crowi));
+    // Rate limit AFTER jwtAuth so `c.get('user')` is populated. The 429 is
+    // emitted as a JSON-RPC-ish error envelope (an MCP client speaks
+    // JSON-RPC; a bare HTTP 429 with a `Retry-After` header is still
+    // honoured by well-behaved clients, and the body is informational).
+    app.use('/mcp', async (c, next) => {
+        const user = c.get('user');
+        // Defensive: jwtAuth always populates `user` before this runs.
+        if (user) {
+            const result = await limiter.hit(user._id.toString());
+            if (!result.allowed) {
+                c.header('Retry-After', String(result.retryAfterSeconds));
+                return c.json(jsonRpcError(JSONRPC_RATE_LIMITED, `Rate limit exceeded. Retry after ${result.retryAfterSeconds}s.`), 429);
+            }
+        }
+        await next();
+        return;
+    });
+    // The MCP route itself: a fresh server + transport per request.
+    app.all('/mcp', async (c) => {
+        const authorization = c.req.header('authorization');
+        if (!authorization) {
+            // jwtAuth would have rejected a missing header already; this is a
+            // type-narrowing guard (a cookie-authenticated request has no
+            // header to forward, which the MCP transport does not support).
+            return c.json(jsonRpcError(JSONRPC_AUTH_REQUIRED, 'MCP requires a Bearer Authorization header.'), 401);
+        }
+        const dispatch = (0, dispatch_1.makeDispatch)(app, authorization);
+        const server = (0, server_1.buildMcpServer)({ dispatch });
+        const transport = new mcp_1.StreamableHTTPTransport({
+            // Stateless: no session id, no long-lived session map.
+            sessionIdGenerator: undefined,
+            // DNS-rebinding protection is intentionally OFF. It is a defence for
+            // unauthenticated / ambient-authority (browser) servers; `/mcp` is
+            // Bearer-gated (a rebinding attacker cannot mint the user's PAT — the
+            // custom Authorization header forces a CORS preflight) and is hit by
+            // non-browser clients (Claude Code, the SDK), so Host pinning adds
+            // nothing here. Browser cross-origin access is governed by `createCors`.
+            // Pinning to a host (e.g. `CLIENT_URL`, the web origin) would instead
+            // reject every legitimate client whenever the api runs on its own
+            // host/port (dev's :4301 vs web :4302, or any split api/web deploy).
+            enableDnsRebindingProtection: false,
+        });
+        await server.connect(transport);
+        let response;
+        try {
+            response = await transport.handleRequest(c);
+        }
+        catch (err) {
+            // `@hono/mcp` signals protocol-level rejections (DNS-rebinding /
+            // Accept-header / unsupported method) by throwing an `HTTPException`
+            // that already carries a fully-formed JSON-RPC error response.
+            // Crowi's global `onError` would flatten that into a generic 500, so
+            // we return the exception's own response here to preserve the
+            // correct status (403 / 406 / 405) and JSON-RPC body.
+            if (err instanceof http_exception_1.HTTPException) {
+                return err.getResponse();
+            }
+            throw err;
+        }
+        // `handleRequest` returns `Response | undefined`; a defined Response
+        // is always produced for POST/GET MCP traffic.
+        return response ?? c.body(null, 204);
+    });
+};
+exports.attachMcp = attachMcp;
+//# sourceMappingURL=attach.js.map

package/dist/mcp/attach.js.map

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

package/dist/mcp/dispatch.d.ts

@@ -0,0 +1,59 @@
+/**
+ * RFC-0011 — in-process dispatch helper for the MCP tools.
+ *
+ * Each MCP tool reuses the existing API by dispatching **in-process** to
+ * the same Hono routes the HTTP server serves, so validation, scope
+ * enforcement, and business logic stay single-source-of-truth. The MCP
+ * layer is a thin protocol translator — see RFC-0011 §3.1.
+ *
+ * Two boundary facts make this safe and simple:
+ *  - Routes are registered on the Hono app at **root** (`/pages`,
+ *    `/search`, …). The `/api/v2` prefix is a boundary concern stripped
+ *    by `stripApiV2Prefix` before `honoApp.fetch` (`hono/path-rewrite.ts`,
+ *    `crowi/index.ts`). So internal dispatch uses the **bare** route path
+ *    (`/pages`), never `/api/v2/pages`.
+ *  - We forward the caller's `Authorization` header verbatim, so the
+ *    dispatched route re-runs `createJwtAuth` + `requireScope` for the
+ *    same principal (RFC-0011 §10.4 "forward-the-header"; the optional
+ *    fast-path that injects the resolved context is deferred).
+ *
+ * Non-2xx responses are surfaced as a typed `ApiToolError(status, body)`
+ * so the tool layer can map them to an MCP `isError` result that carries
+ * the API error envelope's `error.code` / `error.message` (RFC-0011 §9).
+ */
+import type { OpenAPIHono } from '@hono/zod-openapi';
+import type { CrowiHonoBindings } from '../hono/app';
+/**
+ * Thrown by `dispatch` when the in-process route returns a non-2xx
+ * status. Carries the parsed JSON body (the API error envelope) so the
+ * tool layer can extract `error.code` / `error.message`.
+ */
+export declare class ApiToolError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}
+/**
+ * A query value bag. Values are coerced to strings; `undefined` entries
+ * are dropped so optional contract fields (which Zod fills with defaults
+ * server-side) don't serialise as the literal string `"undefined"`.
+ */
+export type DispatchQuery = Record<string, string | number | boolean | undefined | null>;
+export interface DispatchInit {
+    /** Query parameters for GET dispatches. */
+    query?: DispatchQuery;
+    /** JSON body for POST / PUT / DELETE dispatches. */
+    json?: unknown;
+}
+export type Dispatch = (method: string, path: string, init?: DispatchInit) => Promise<unknown>;
+/**
+ * Build a dispatcher bound to a single request's authorization. The
+ * `honoApp` is captured at attach time (the same app `buildHonoApp`
+ * builds); `authorization` is the caller's verbatim `Authorization`
+ * header so the dispatched route authenticates as the MCP caller.
+ *
+ * The host is irrelevant for in-process dispatch (no socket is opened),
+ * but `honoApp.request` needs an absolute-or-rooted URL; a rooted path
+ * is what we pass, matching the test harness (`hono/path-rewrite.ts`).
+ */
+export declare const makeDispatch: (honoApp: OpenAPIHono<CrowiHonoBindings>, authorization: string) => Dispatch;

package/dist/mcp/dispatch.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeDispatch = exports.ApiToolError = void 0;
+/**
+ * Thrown by `dispatch` when the in-process route returns a non-2xx
+ * status. Carries the parsed JSON body (the API error envelope) so the
+ * tool layer can extract `error.code` / `error.message`.
+ */
+class ApiToolError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`MCP dispatch failed with status ${status}`);
+        this.status = status;
+        this.body = body;
+        this.name = 'ApiToolError';
+    }
+}
+exports.ApiToolError = ApiToolError;
+/** Serialise a query bag, skipping `undefined` / `null`. */
+const buildQueryString = (query) => {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null)
+            continue;
+        params.set(key, String(value));
+    }
+    const qs = params.toString();
+    return qs ? `?${qs}` : '';
+};
+/**
+ * Build a dispatcher bound to a single request's authorization. The
+ * `honoApp` is captured at attach time (the same app `buildHonoApp`
+ * builds); `authorization` is the caller's verbatim `Authorization`
+ * header so the dispatched route authenticates as the MCP caller.
+ *
+ * The host is irrelevant for in-process dispatch (no socket is opened),
+ * but `honoApp.request` needs an absolute-or-rooted URL; a rooted path
+ * is what we pass, matching the test harness (`hono/path-rewrite.ts`).
+ */
+const makeDispatch = (honoApp, authorization) => {
+    return async (method, path, init) => {
+        const url = `${path}${init?.query ? buildQueryString(init.query) : ''}`;
+        const hasJsonBody = init?.json !== undefined;
+        const res = await honoApp.request(url, {
+            method,
+            headers: {
+                Authorization: authorization,
+                ...(hasJsonBody ? { 'content-type': 'application/json' } : {}),
+            },
+            body: hasJsonBody ? JSON.stringify(init?.json) : undefined,
+        });
+        // Every Crowi API route replies JSON (success envelopes + error
+        // envelopes). A non-JSON body would be an unexpected 5xx; parse
+        // defensively so a malformed body still surfaces as an ApiToolError.
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            body = { error: { code: 'INTERNAL_ERROR', message: `Non-JSON response (status ${res.status})` } };
+        }
+        if (!res.ok) {
+            throw new ApiToolError(res.status, body);
+        }
+        return body;
+    };
+};
+exports.makeDispatch = makeDispatch;
+//# sourceMappingURL=dispatch.js.map

package/dist/mcp/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../../src/mcp/dispatch.ts"],"names":[],"mappings":";;;AA2BA;;;;GAIG;AACH,MAAa,YAAa,SAAQ,KAAK;IAEnB;IACA;IAFlB,YACkB,MAAc,EACd,IAAa;QAE7B,KAAK,CAAC,mCAAmC,MAAM,EAAE,CAAC,CAAC;QAHnC,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAS;QAG7B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AARD,oCAQC;AAgBD,4DAA4D;AAC5D,MAAM,gBAAgB,GAAG,CAAC,KAAoB,EAAU,EAAE;IACxD,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QACpD,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACjC,CAAC;IACD,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;IAC7B,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC5B,CAAC,CAAC;AAIF;;;;;;;;;GASG;AACI,MAAM,YAAY,GAAG,CAAC,OAAuC,EAAE,aAAqB,EAAY,EAAE;IACvG,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QAClC,MAAM,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QAExE,MAAM,WAAW,GAAG,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC;QAC7C,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE;YACrC,MAAM;YACN,OAAO,EAAE;gBACP,aAAa,EAAE,aAAa;gBAC5B,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC/D;YACD,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;SAC3D,CAAC,CAAC;QAEH,gEAAgE;QAChE,gEAAgE;QAChE,qEAAqE;QACrE,IAAI,IAAa,CAAC;QAClB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,GAAG,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,6BAA6B,GAAG,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QACpG,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC3C,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;AACJ,CAAC,CAAC;AA7BW,QAAA,YAAY,gBA6BvB"}

package/dist/mcp/result.d.ts

@@ -0,0 +1,40 @@
+/**
+ * RFC-0011 §9 — mapping in-process dispatch results into MCP tool
+ * results.
+ *
+ * MCP tool results carry `content` (an array of typed blocks; the model
+ * reads `text`) plus optional `structuredContent` (machine-readable
+ * data) and an `isError` flag. The helpers here turn the JSON envelope a
+ * dispatched route returns into that shape, and turn an `ApiToolError`
+ * (non-2xx) into an `isError` result whose text is derived from the API
+ * error envelope so the model can recover (e.g. re-fetch on a 409).
+ */
+import { ApiToolError } from './dispatch';
+/** Minimal MCP tool-result shape (subset of the SDK's `CallToolResult`). */
+export interface McpToolResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+/** A plain object whose values we want as `structuredContent`. */
+type Structured = Record<string, unknown>;
+/** Build a success result: a text block plus optional structured data. */
+export declare const okResult: (text: string, structuredContent?: Structured) => McpToolResult;
+/**
+ * Build an error result from an `ApiToolError`. The text is the API
+ * error envelope's `code` + `message` (RFC-0011 §9) so the model gets a
+ * human-readable, recoverable signal. The full body is echoed in
+ * `structuredContent` for clients that introspect it.
+ */
+export declare const errorResult: (err: ApiToolError) => McpToolResult;
+/**
+ * Run a tool body and convert a thrown `ApiToolError` into an `isError`
+ * result. Any other throw is rethrown — the SDK turns an uncaught throw
+ * into a protocol-level error, which is the right behaviour for genuine
+ * bugs (vs. an expected 4xx from the dispatched route).
+ */
+export declare const runTool: (body: () => Promise<McpToolResult>) => Promise<McpToolResult>;
+export {};

package/dist/mcp/result.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTool = exports.errorResult = exports.okResult = void 0;
+/**
+ * RFC-0011 §9 — mapping in-process dispatch results into MCP tool
+ * results.
+ *
+ * MCP tool results carry `content` (an array of typed blocks; the model
+ * reads `text`) plus optional `structuredContent` (machine-readable
+ * data) and an `isError` flag. The helpers here turn the JSON envelope a
+ * dispatched route returns into that shape, and turn an `ApiToolError`
+ * (non-2xx) into an `isError` result whose text is derived from the API
+ * error envelope so the model can recover (e.g. re-fetch on a 409).
+ */
+const dispatch_1 = require("./dispatch");
+/** Build a success result: a text block plus optional structured data. */
+const okResult = (text, structuredContent) => ({
+    content: [{ type: 'text', text }],
+    ...(structuredContent ? { structuredContent } : {}),
+});
+exports.okResult = okResult;
+/**
+ * Build an error result from an `ApiToolError`. The text is the API
+ * error envelope's `code` + `message` (RFC-0011 §9) so the model gets a
+ * human-readable, recoverable signal. The full body is echoed in
+ * `structuredContent` for clients that introspect it.
+ */
+const errorResult = (err) => {
+    const envelope = extractErrorEnvelope(err.body);
+    const code = envelope.code ?? `HTTP_${err.status}`;
+    const message = envelope.message ?? 'The Crowi API rejected the request.';
+    return {
+        content: [{ type: 'text', text: `Error (${code}): ${message}` }],
+        structuredContent: { status: err.status, error: { code, message } },
+        isError: true,
+    };
+};
+exports.errorResult = errorResult;
+/**
+ * Run a tool body and convert a thrown `ApiToolError` into an `isError`
+ * result. Any other throw is rethrown — the SDK turns an uncaught throw
+ * into a protocol-level error, which is the right behaviour for genuine
+ * bugs (vs. an expected 4xx from the dispatched route).
+ */
+const runTool = async (body) => {
+    try {
+        return await body();
+    }
+    catch (err) {
+        if (err instanceof dispatch_1.ApiToolError) {
+            return (0, exports.errorResult)(err);
+        }
+        throw err;
+    }
+};
+exports.runTool = runTool;
+/** Best-effort extraction of `{ error: { code, message } }`. */
+const extractErrorEnvelope = (body) => {
+    if (body && typeof body === 'object' && 'error' in body) {
+        const error = body.error;
+        // Most routes use the nested `{ error: { code, message } }` shape;
+        // the rate-limit envelopes use a flat `{ error: 'rate_limited',
+        // message }`. Handle both.
+        if (error && typeof error === 'object') {
+            const e = error;
+            return {
+                code: typeof e.code === 'string' ? e.code : undefined,
+                message: typeof e.message === 'string' ? e.message : undefined,
+            };
+        }
+        if (typeof error === 'string') {
+            const message = body.message;
+            return { code: error, message: typeof message === 'string' ? message : undefined };
+        }
+    }
+    return {};
+};
+//# sourceMappingURL=result.js.map

package/dist/mcp/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/mcp/result.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;GAUG;AACH,yCAA0C;AAY1C,0EAA0E;AACnE,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAE,iBAA8B,EAAiB,EAAE,CAAC,CAAC;IACxF,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACjC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;CACpD,CAAC,CAAC;AAHU,QAAA,QAAQ,YAGlB;AAEH;;;;;GAKG;AACI,MAAM,WAAW,GAAG,CAAC,GAAiB,EAAiB,EAAE;IAC9D,MAAM,QAAQ,GAAG,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,IAAI,QAAQ,GAAG,CAAC,MAAM,EAAE,CAAC;IACnD,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,IAAI,qCAAqC,CAAC;IAC1E,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,IAAI,MAAM,OAAO,EAAE,EAAE,CAAC;QAChE,iBAAiB,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;QACnE,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC,CAAC;AATW,QAAA,WAAW,eAStB;AAEF;;;;;GAKG;AACI,MAAM,OAAO,GAAG,KAAK,EAAE,IAAkC,EAA0B,EAAE;IAC1F,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,EAAE,CAAC;IACtB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,uBAAY,EAAE,CAAC;YAChC,OAAO,IAAA,mBAAW,EAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC,CAAC;AATW,QAAA,OAAO,WASlB;AAEF,gEAAgE;AAChE,MAAM,oBAAoB,GAAG,CAAC,IAAa,EAAuC,EAAE;IAClF,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;QACxD,MAAM,KAAK,GAAI,IAA2B,CAAC,KAAK,CAAC;QACjD,mEAAmE;QACnE,gEAAgE;QAChE,2BAA2B;QAC3B,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACvC,MAAM,CAAC,GAAG,KAA8C,CAAC;YACzD,OAAO;gBACL,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;gBACrD,OAAO,EAAE,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;aAC/D,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,OAAO,GAAI,IAA8B,CAAC,OAAO,CAAC;YACxD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;QACrF,CAAC;IACH,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC,CAAC"}

package/dist/mcp/server.d.ts

@@ -0,0 +1,67 @@
+/**
+ * RFC-0011 §7 — per-request MCP server factory + data-driven tool table.
+ *
+ * `buildMcpServer(ctx)` builds a fresh `McpServer` per request (stateless
+ * transport, RFC-0011 §4). The server registers the static tool catalog,
+ * but every tool closes over the request's `dispatch` (which carries the
+ * caller's `Authorization`), so tool calls run with the caller's identity
+ * and inherit the dispatched route's scope enforcement (RFC-0011 §5.2).
+ *
+ * The tool catalog is **data-driven**: each tool is a `ToolDescriptor`
+ * row `{ name, method, path, ... }`, so adding a tool is one row, not a
+ * new code path (RFC-0011 §8). Three request shapes are supported:
+ *   - **query** tools (GET): the validated input becomes the query bag.
+ *   - **body** tools (POST/PUT/DELETE): the validated input becomes the
+ *     JSON body.
+ *   - **path-param** tools: one or more input fields are spliced into the
+ *     route path (e.g. `/pages/{page_id}/revisions`) and the remainder
+ *     becomes the query / body.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ZodRawShape } from 'zod';
+import type { Dispatch } from './dispatch';
+import { type McpToolResult, okResult } from './result';
+/** How a tool's validated input is turned into a dispatch request. */
+export type ToolKind = 'query' | 'body';
+/**
+ * A single tool definition. The dispatched route is `method path` (bare,
+ * no `/api/v2`); the route enforces scope, so the `scope` field here is
+ * documentation only (it is never re-checked in the MCP layer).
+ */
+export interface ToolDescriptor {
+    /** MCP tool name, `crowi_<verb>_<noun>`. */
+    name: string;
+    /** Human + model-facing description. Documents revision_id etc. */
+    description: string;
+    /** HTTP method of the dispatched route. */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /**
+     * Route path with optional `{param}` placeholders filled from the
+     * input (e.g. `/pages/{page_id}/revisions`). Placeholder fields are
+     * removed from the query / body after substitution.
+     */
+    path: string;
+    /** Input schema shape passed to `registerTool` for boundary validation. */
+    schema: ZodRawShape;
+    /**
+     * Whether the non-path input becomes the query string (GET) or the
+     * JSON body (POST/PUT/DELETE).
+     */
+    kind: ToolKind;
+    /** Scope the dispatched route requires (documentation only). */
+    scope: string;
+    /** Map the dispatched route's JSON result into an MCP tool result. */
+    resultMapper: (body: unknown) => McpToolResult;
+}
+/** Context captured per request and closed over by every tool. */
+export interface McpServerContext {
+    dispatch: Dispatch;
+}
+/**
+ * Build a per-request `McpServer` with the full tool catalog registered.
+ * Stateless: a fresh server is connected to a fresh transport per request
+ * by `attachMcp`.
+ */
+export declare const buildMcpServer: (ctx: McpServerContext) => McpServer;
+/** Re-export the result helper so tool tables can build success results. */
+export { okResult };

package/dist/mcp/server.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.okResult = exports.buildMcpServer = void 0;
+/**
+ * RFC-0011 §7 — per-request MCP server factory + data-driven tool table.
+ *
+ * `buildMcpServer(ctx)` builds a fresh `McpServer` per request (stateless
+ * transport, RFC-0011 §4). The server registers the static tool catalog,
+ * but every tool closes over the request's `dispatch` (which carries the
+ * caller's `Authorization`), so tool calls run with the caller's identity
+ * and inherit the dispatched route's scope enforcement (RFC-0011 §5.2).
+ *
+ * The tool catalog is **data-driven**: each tool is a `ToolDescriptor`
+ * row `{ name, method, path, ... }`, so adding a tool is one row, not a
+ * new code path (RFC-0011 §8). Three request shapes are supported:
+ *   - **query** tools (GET): the validated input becomes the query bag.
+ *   - **body** tools (POST/PUT/DELETE): the validated input becomes the
+ *     JSON body.
+ *   - **path-param** tools: one or more input fields are spliced into the
+ *     route path (e.g. `/pages/{page_id}/revisions`) and the remainder
+ *     becomes the query / body.
+ */
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const result_1 = require("./result");
+Object.defineProperty(exports, "okResult", { enumerable: true, get: function () { return result_1.okResult; } });
+const page_1 = require("./tools/page");
+const search_1 = require("./tools/search");
+/** Server identity advertised to MCP clients (`initialize` response). */
+const SERVER_INFO = {
+    name: 'crowi',
+    version: '1.0.0',
+};
+/**
+ * Server-level usage guidance returned in the `initialize` response. MCP
+ * clients surface this to the model as a system-prompt-style hint (MCP
+ * spec: `instructions`), so it is the place for cross-cutting Crowi
+ * conventions that no single tool owns — path shape, date-page nesting,
+ * the get-before-update lock dance, and grant values.
+ */
+const SERVER_INSTRUCTIONS = `This server exposes a Crowi wiki (team knowledge base). When the user asks to
+search/read/create/update wiki pages, use these crowi_* tools — they operate on
+the wiki, not the local filesystem or codebase.
+
+Path conventions:
+- Paths are slash-separated hierarchies. A trailing slash means a portal
+  (directory) page; no trailing slash is the page itself.
+- Date-based pages nest by slash, NOT hyphens: \`/parent/YYYY/MM/DD/title\`
+  (e.g. /crowi/qa/2026/06/08/mcp-server), never \`/parent/2026-06-08-title\`.
+
+Choosing where to create a page:
+- Personal notes / daily memos belong under the author's own user page:
+  \`/user/<username>/memo/YYYY/MM/DD/title\`. If you do not know the username, ask
+  the user rather than guessing.
+- Project / team content follows the existing structure of that project. Before
+  creating, explore with crowi_search_pages / crowi_list_child_pages /
+  crowi_autocomplete_pages to see where similar pages already live, then place the
+  new page to match that hierarchy instead of inventing a new top-level path.
+
+Editing:
+- Before crowi_update_page, call crowi_get_page to read the current revision_id
+  (optimistic lock). A stale revision_id returns a 409 conflict — refetch and retry.
+
+Visibility (\`grant\` on create): 1 = public, 2 = restricted, 3 = specified users,
+4 = owner only. Omit to default to public.`;
+/** Names of `{param}` placeholders in a path template. */
+const pathParamNames = (path) => [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
+/**
+ * Substitute `{param}` placeholders in `path` from `input`, returning the
+ * concrete path plus the remaining (non-path) input fields.
+ */
+const splicePathParams = (path, input) => {
+    const names = pathParamNames(path);
+    if (names.length === 0)
+        return { path, rest: input };
+    let concrete = path;
+    const rest = { ...input };
+    for (const name of names) {
+        const value = rest[name];
+        concrete = concrete.replace(`{${name}}`, encodeURIComponent(String(value ?? '')));
+        delete rest[name];
+    }
+    return { path: concrete, rest };
+};
+/**
+ * Build a per-request `McpServer` with the full tool catalog registered.
+ * Stateless: a fresh server is connected to a fresh transport per request
+ * by `attachMcp`.
+ */
+const buildMcpServer = (ctx) => {
+    const server = new mcp_js_1.McpServer(SERVER_INFO, { instructions: SERVER_INSTRUCTIONS });
+    const descriptors = [...page_1.pageTools, ...search_1.searchTools];
+    for (const tool of descriptors) {
+        // The SDK validates `args` against `tool.schema` before invoking the
+        // callback, so `args` is the parsed input — invalid input never
+        // reaches here (it is rejected at the MCP boundary as `isError`,
+        // RFC §6). The handler return type (`McpToolResult`) is structurally
+        // a `CallToolResult` but lacks the SDK type's `[x: string]: unknown`
+        // index signature, so we cast at the registration boundary.
+        const handler = async (args) => (0, result_1.runTool)(async () => {
+            const { path, rest } = splicePathParams(tool.path, args ?? {});
+            const init = tool.kind === 'query' ? { query: rest } : { json: rest };
+            const body = await ctx.dispatch(tool.method, path, init);
+            return tool.resultMapper(body);
+        });
+        server.registerTool(tool.name, {
+            description: tool.description,
+            inputSchema: tool.schema,
+        }, handler);
+    }
+    return server;
+};
+exports.buildMcpServer = buildMcpServer;
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

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

package/dist/mcp/tools/page.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDescriptor } from '../server';
+export declare const pageTools: ToolDescriptor[];