@obov/mext 0.0.0-stage → 0.2.0

package/dist/mcp/dispatch.js

@@ -0,0 +1,249 @@
+import { isMextError, MextError } from "../errors.js";
+import { invoke } from "../invoke.js";
+import { formatHelp, help, HELP_COMMAND } from "./help.js";
+import { createAskSession, hasPending, inputRequiredResult, } from "./mrtr.js";
+/** 핸들러 예외 (MextError 외) 의 결과 code. CLI --json 과 같음 */
+export const EXECUTION_ERROR = "EXECUTION_ERROR";
+/** 도구 설명에 나열할 명령어 수 상한. 넘으면 help 안내만 */
+const DESCRIPTION_COMMAND_LIMIT = 50;
+/** 노출 방식별 dispatcher 도구 (정렬 순서 고정: execute · query, mutate) */
+export function dispatcherTools(registry, exposure = "execute") {
+    const all = [...registry.commands.values()];
+    if (exposure === "split") {
+        const reads = all.filter((e) => e.command.readOnly);
+        const writes = all.filter((e) => !e.command.readOnly);
+        return [
+            {
+                name: "query",
+                description: describeTool("query", "Run a read-only command.", reads, 'Commands that are not read-only are rejected here; call them with the "mutate" tool.'),
+                inputSchema: dispatcherInputSchema(),
+                annotations: { title: "Query", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+                readOnly: true,
+            },
+            {
+                name: "mutate",
+                description: describeTool("mutate", "Run a command that changes state.", writes),
+                inputSchema: dispatcherInputSchema(),
+                annotations: { title: "Mutate", readOnlyHint: false, destructiveHint: true },
+                readOnly: false,
+            },
+        ];
+    }
+    const readOnly = all.every((e) => e.command.readOnly);
+    return [
+        {
+            name: "execute",
+            description: describeTool("execute", "Run a command.", all),
+            inputSchema: dispatcherInputSchema(),
+            // 단일 dispatcher 는 최악값 (researches/others.md 9)
+            annotations: readOnly
+                ? { title: "Execute", readOnlyHint: true, destructiveHint: false }
+                : { title: "Execute", readOnlyHint: false, destructiveHint: all.some((e) => e.command.destructive) },
+            readOnly: false,
+        },
+    ];
+}
+export function findDispatcherTool(tools, name) {
+    return tools.find((t) => t.name === name);
+}
+/**
+ * dispatcher 도구 호출: { command, args } → help 또는 invoke.
+ * MextError · 핸들러 예외는 isError 결과로 (throw 하지 않음). 인증 (UNAUTHENTICATED → 401) 은 transport 몫.
+ * options.input 이 있으면 ctx.ask 가 InputRequiredResult 를 돌려준다 (mrtr.ts).
+ */
+export async function callDispatcher(registry, tool, rawArguments, options) {
+    try {
+        const { command, args } = parseDispatcherArguments(tool, rawArguments);
+        if (command === HELP_COMMAND) {
+            const target = args?.target;
+            if (target !== undefined && typeof target !== "string") {
+                throw dispatcherArgumentError(tool, "help", "args.target must be a string", [], {
+                    path: "args.target",
+                    code: "invalid_type",
+                    message: "expected string",
+                });
+            }
+            const toolFor = splitToolFor(options.tools);
+            const value = help(registry, target, toolFor ? { toolFor } : {});
+            return { content: [{ type: "text", text: formatHelp(value, tool.name) }], structuredContent: value };
+        }
+        const { input, tools: _tools, ...invokeOptions } = options;
+        const result = input
+            ? await invokeRound(registry, tool, command, args, invokeOptions, input)
+            : await invoke(registry, command, args, { ...invokeOptions, readOnly: tool.readOnly });
+        if ("resultType" in result)
+            return result;
+        const value = result.value === undefined ? null : result.value;
+        return { content: [{ type: "text", text: stringify(value) }], structuredContent: value };
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+}
+/**
+ * MRTR 한 라운드: requestState 검증 → ask 세션으로 invoke. 답 없는 ask 가 있으면 (핸들러가 오류를 삼켜도)
+ * 결과를 버리고 InputRequiredResult. elicitation 미선언 클라이언트 = ask 미주입 (INPUT_UNAVAILABLE)
+ */
+async function invokeRound(registry, tool, command, args, options, input) {
+    const { ask: _ask, ...rest } = options;
+    if (!input.elicitation)
+        return invoke(registry, command, args, { ...rest, readOnly: tool.readOnly });
+    const binding = {
+        principal: `${options.principal.kind}:${options.principal.id}`,
+        tool: tool.name,
+        command,
+        args: args ?? {},
+    };
+    let answers = { ...input.inputResponses };
+    if (input.requestState !== undefined) {
+        const prior = input.signer.verify(input.requestState, binding);
+        if (!prior)
+            throw invalidRequestState(tool, command);
+        answers = { ...answers, ...prior };
+    }
+    const session = createAskSession(answers);
+    const signal = options.signal ? AbortSignal.any([options.signal, session.signal]) : session.signal;
+    try {
+        const result = await invoke(registry, command, args, { ...rest, signal, ask: session.ask, readOnly: tool.readOnly });
+        return hasPending(session) ? inputRequiredResult(session, input.signer, binding) : result;
+    }
+    catch (error) {
+        if (hasPending(session))
+            return inputRequiredResult(session, input.signer, binding);
+        throw error;
+    }
+}
+/** 서명 · 만료 · 바인딩 검증 실패한 requestState. 처음부터 다시 호출하도록 안내 */
+function invalidRequestState(tool, command) {
+    return new MextError("INVALID_ARGUMENT", `Invalid arguments for ${command}: requestState is invalid or expired. Call ${tool.name} again without requestState and inputResponses.`, {
+        command,
+        missing_fields: [],
+        issues: [
+            {
+                path: "requestState",
+                code: "invalid_request_state",
+                message: "requestState failed verification (tampered, expired, or for a different call or server key)",
+            },
+        ],
+        expected_schema: tool.inputSchema,
+        examples: [],
+    });
+}
+/** 오류 → isError 결과. MextError = toJSON, 그 외 = EXECUTION_ERROR */
+export function errorResult(error) {
+    const body = isMextError(error)
+        ? error.toJSON()
+        : { code: EXECUTION_ERROR, message: error instanceof Error ? error.message : String(error) };
+    return {
+        content: [{ type: "text", text: `${body.code}: ${body.message}\n${stringify(body)}` }],
+        structuredContent: { error: body },
+        isError: true,
+    };
+}
+/** dispatcher 도구 inputSchema. command 를 Mcp-Param-Command 헤더로 복사 (SEP-2243) */
+export function dispatcherInputSchema() {
+    return {
+        type: "object",
+        properties: {
+            command: {
+                type: "string",
+                description: 'Command ID (e.g. "users.get"), or "help" to list namespaces and commands.',
+                "x-mcp-header": "Command",
+            },
+            args: {
+                type: "object",
+                description: 'Command input. For "help": { "target": "<namespace or command ID>" }.',
+                additionalProperties: true,
+            },
+        },
+        required: ["command"],
+        additionalProperties: false,
+    };
+}
+function parseDispatcherArguments(tool, raw) {
+    const input = raw === undefined ? {} : raw;
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        throw dispatcherArgumentError(tool, tool.name, "arguments must be an object", [], {
+            path: "",
+            code: "invalid_type",
+            message: "expected object",
+        });
+    }
+    const { command, args, ...rest } = input;
+    if (command === undefined) {
+        throw dispatcherArgumentError(tool, tool.name, "missing required: command", ["command"], {
+            path: "command",
+            code: "invalid_type",
+            message: "expected string, received undefined",
+        });
+    }
+    if (typeof command !== "string") {
+        throw dispatcherArgumentError(tool, tool.name, "command must be a string", [], {
+            path: "command",
+            code: "invalid_type",
+            message: "expected string",
+        });
+    }
+    const unknownKeys = Object.keys(rest);
+    if (unknownKeys.length > 0) {
+        throw dispatcherArgumentError(tool, tool.name, `unrecognized keys: ${unknownKeys.join(", ")}`, [], {
+            path: "",
+            code: "unrecognized_keys",
+            message: `Unrecognized keys: ${unknownKeys.join(", ")}. Put command input under "args".`,
+        });
+    }
+    if (args !== undefined && (args === null || typeof args !== "object" || Array.isArray(args))) {
+        throw dispatcherArgumentError(tool, command, "args must be an object", [], {
+            path: "args",
+            code: "invalid_type",
+            message: "expected object",
+        });
+    }
+    return { command, args };
+}
+function dispatcherArgumentError(tool, command, summary, missing, issue) {
+    return new MextError("INVALID_ARGUMENT", `Invalid arguments for ${command}: ${summary}`, {
+        command,
+        missing_fields: missing,
+        issues: [issue],
+        expected_schema: tool.inputSchema,
+        examples: [{ command: HELP_COMMAND }],
+    });
+}
+function splitToolFor(tools) {
+    if (!tools || tools.length < 2)
+        return undefined;
+    const query = tools.find((t) => t.readOnly)?.name;
+    const mutate = tools.find((t) => !t.readOnly)?.name;
+    if (query === undefined || mutate === undefined)
+        return undefined;
+    return (e) => (e.command.readOnly ? query : mutate);
+}
+function describeTool(name, lead, commands, note) {
+    const lines = [
+        lead,
+        `Arguments: { "command": "<command ID>", "args": { ...input } }. ` +
+            `Call ${name}({ "command": "help" }) to list namespaces and commands, ` +
+            `${name}({ "command": "help", "args": { "target": "<namespace or command ID>" } }) for input schemas and examples.`,
+    ];
+    if (note)
+        lines.push(note);
+    if (commands.length > 0 && commands.length <= DESCRIPTION_COMMAND_LIMIT) {
+        lines.push("", "Commands:");
+        for (const e of commands)
+            lines.push(`- ${e.id}: ${firstLine(e.command.description)}`);
+    }
+    return lines.join("\n");
+}
+function firstLine(text) {
+    return text.split("\n", 1)[0].trim();
+}
+function stringify(value) {
+    try {
+        return JSON.stringify(value, null, 2) ?? "null";
+    }
+    catch {
+        return String(value);
+    }
+}
+//# 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":"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","sourcesContent":["import { isMextError, MextError } from \"../errors.ts\"\nimport { invoke, type InvokeOptions } from \"../invoke.ts\"\nimport type { JsonSchema, RegisteredCommand, Registry } from \"../registry.ts\"\nimport { formatHelp, help, HELP_COMMAND } from \"./help.ts\"\nimport {\n  createAskSession,\n  hasPending,\n  inputRequiredResult,\n  type InputRequiredResult,\n  type InputRound,\n  type RequestStateBinding,\n  type RequestStateSigner,\n} from \"./mrtr.ts\"\n\n/**\n * MCP 어댑터의 transport 무관 부분: dispatcher 도구 정의 · tools/call 실행 · help · 오류 → 결과 변환.\n * SDK · HTTP 에 의존하지 않는다 (HTTP · stdio 가 공유).\n */\n\n/** execute = 도구 1개 (기본), split = query (readOnly · help) + mutate (그 외) */\nexport type ToolExposure = \"execute\" | \"split\"\n\nexport type DispatcherToolName = \"execute\" | \"query\" | \"mutate\"\n\n/** MCP ToolAnnotations 중 mext 가 쓰는 항목 */\nexport interface DispatcherAnnotations {\n  title?: string\n  readOnlyHint: boolean\n  destructiveHint?: boolean\n  idempotentHint?: boolean\n  openWorldHint?: boolean\n}\n\nexport interface DispatcherTool {\n  name: DispatcherToolName\n  description: string\n  /** JSON Schema 2020-12. command 에 x-mcp-header: \"Command\" */\n  inputSchema: JsonSchema\n  annotations: DispatcherAnnotations\n  /** readOnly 명령어만 실행 (split 의 query). 그 외 = PERMISSION_DENIED */\n  readOnly: boolean\n}\n\nexport interface TextContent {\n  type: \"text\"\n  text: string\n}\n\n/** MCP CallToolResult 와 같은 형태 (SDK 타입 비의존) */\nexport interface ToolCallResult {\n  content: TextContent[]\n  /** 성공 = 핸들러 반환값 (undefined 는 null), 오류 = { error: MextError.toJSON() } */\n  structuredContent: unknown\n  isError?: true\n}\n\n/** 핸들러 예외 (MextError 외) 의 결과 code. CLI --json 과 같음 */\nexport const EXECUTION_ERROR = \"EXECUTION_ERROR\"\n\n/** 도구 설명에 나열할 명령어 수 상한. 넘으면 help 안내만 */\nconst DESCRIPTION_COMMAND_LIMIT = 50\n\n/** 노출 방식별 dispatcher 도구 (정렬 순서 고정: execute · query, mutate) */\nexport function dispatcherTools(registry: Registry, exposure: ToolExposure = \"execute\"): DispatcherTool[] {\n  const all = [...registry.commands.values()]\n  if (exposure === \"split\") {\n    const reads = all.filter((e) => e.command.readOnly)\n    const writes = all.filter((e) => !e.command.readOnly)\n    return [\n      {\n        name: \"query\",\n        description: describeTool(\n          \"query\",\n          \"Run a read-only command.\",\n          reads,\n          'Commands that are not read-only are rejected here; call them with the \"mutate\" tool.',\n        ),\n        inputSchema: dispatcherInputSchema(),\n        annotations: { title: \"Query\", readOnlyHint: true, destructiveHint: false, idempotentHint: true },\n        readOnly: true,\n      },\n      {\n        name: \"mutate\",\n        description: describeTool(\"mutate\", \"Run a command that changes state.\", writes),\n        inputSchema: dispatcherInputSchema(),\n        annotations: { title: \"Mutate\", readOnlyHint: false, destructiveHint: true },\n        readOnly: false,\n      },\n    ]\n  }\n  const readOnly = all.every((e) => e.command.readOnly)\n  return [\n    {\n      name: \"execute\",\n      description: describeTool(\"execute\", \"Run a command.\", all),\n      inputSchema: dispatcherInputSchema(),\n      // 단일 dispatcher 는 최악값 (researches/others.md 9)\n      annotations: readOnly\n        ? { title: \"Execute\", readOnlyHint: true, destructiveHint: false }\n        : { title: \"Execute\", readOnlyHint: false, destructiveHint: all.some((e) => e.command.destructive) },\n      readOnly: false,\n    },\n  ]\n}\n\nexport function findDispatcherTool(tools: readonly DispatcherTool[], name: string): DispatcherTool | undefined {\n  return tools.find((t) => t.name === name)\n}\n\nexport interface DispatchOptions extends Omit<InvokeOptions, \"readOnly\"> {\n  /** help 의 tool 표시용. dispatcherTools 결과 */\n  tools?: readonly DispatcherTool[]\n  /**\n   * MRTR (MCP 2026-07-28). 지정하면 ctx.ask = InputRequiredResult 반환 · 재시도의 inputResponses 로 resolve\n   * (ask 옵션 무시). requiresConfirmation 확인도 이 경로\n   */\n  input?: InputRound & { signer: RequestStateSigner }\n}\n\n/** tools/call 결과: 완료 (CallToolResult 형태) 또는 입력 요청 (InputRequiredResult) */\nexport type DispatchResult = ToolCallResult | InputRequiredResult\n\n/**\n * dispatcher 도구 호출: { command, args } → help 또는 invoke.\n * MextError · 핸들러 예외는 isError 결과로 (throw 하지 않음). 인증 (UNAUTHENTICATED → 401) 은 transport 몫.\n * options.input 이 있으면 ctx.ask 가 InputRequiredResult 를 돌려준다 (mrtr.ts).\n */\nexport async function callDispatcher(\n  registry: Registry,\n  tool: DispatcherTool,\n  rawArguments: unknown,\n  options: DispatchOptions,\n): Promise<DispatchResult> {\n  try {\n    const { command, args } = parseDispatcherArguments(tool, rawArguments)\n    if (command === HELP_COMMAND) {\n      const target = (args as { target?: unknown } | undefined)?.target\n      if (target !== undefined && typeof target !== \"string\") {\n        throw dispatcherArgumentError(tool, \"help\", \"args.target must be a string\", [], {\n          path: \"args.target\",\n          code: \"invalid_type\",\n          message: \"expected string\",\n        })\n      }\n      const toolFor = splitToolFor(options.tools)\n      const value = help(registry, target, toolFor ? { toolFor } : {})\n      return { content: [{ type: \"text\", text: formatHelp(value, tool.name) }], structuredContent: value }\n    }\n    const { input, tools: _tools, ...invokeOptions } = options\n    const result = input\n      ? await invokeRound(registry, tool, command, args, invokeOptions, input)\n      : await invoke(registry, command, args, { ...invokeOptions, readOnly: tool.readOnly })\n    if (\"resultType\" in result) return result\n    const value = result.value === undefined ? null : result.value\n    return { content: [{ type: \"text\", text: stringify(value) }], structuredContent: value }\n  } catch (error) {\n    return errorResult(error)\n  }\n}\n\n/**\n * MRTR 한 라운드: requestState 검증 → ask 세션으로 invoke. 답 없는 ask 가 있으면 (핸들러가 오류를 삼켜도)\n * 결과를 버리고 InputRequiredResult. elicitation 미선언 클라이언트 = ask 미주입 (INPUT_UNAVAILABLE)\n */\nasync function invokeRound(\n  registry: Registry,\n  tool: DispatcherTool,\n  command: string,\n  args: unknown,\n  options: Omit<InvokeOptions, \"readOnly\">,\n  input: NonNullable<DispatchOptions[\"input\"]>,\n): Promise<{ command: string; value: unknown } | InputRequiredResult> {\n  const { ask: _ask, ...rest } = options\n  if (!input.elicitation) return invoke(registry, command, args, { ...rest, readOnly: tool.readOnly })\n  const binding: RequestStateBinding = {\n    principal: `${options.principal.kind}:${options.principal.id}`,\n    tool: tool.name,\n    command,\n    args: args ?? {},\n  }\n  let answers: Record<string, unknown> = { ...input.inputResponses }\n  if (input.requestState !== undefined) {\n    const prior = input.signer.verify(input.requestState, binding)\n    if (!prior) throw invalidRequestState(tool, command)\n    answers = { ...answers, ...prior }\n  }\n  const session = createAskSession(answers)\n  const signal = options.signal ? AbortSignal.any([options.signal, session.signal]) : session.signal\n  try {\n    const result = await invoke(registry, command, args, { ...rest, signal, ask: session.ask, readOnly: tool.readOnly })\n    return hasPending(session) ? inputRequiredResult(session, input.signer, binding) : result\n  } catch (error) {\n    if (hasPending(session)) return inputRequiredResult(session, input.signer, binding)\n    throw error\n  }\n}\n\n/** 서명 · 만료 · 바인딩 검증 실패한 requestState. 처음부터 다시 호출하도록 안내 */\nfunction invalidRequestState(tool: DispatcherTool, command: string): MextError<\"INVALID_ARGUMENT\"> {\n  return new MextError(\n    \"INVALID_ARGUMENT\",\n    `Invalid arguments for ${command}: requestState is invalid or expired. Call ${tool.name} again without requestState and inputResponses.`,\n    {\n      command,\n      missing_fields: [],\n      issues: [\n        {\n          path: \"requestState\",\n          code: \"invalid_request_state\",\n          message: \"requestState failed verification (tampered, expired, or for a different call or server key)\",\n        },\n      ],\n      expected_schema: tool.inputSchema,\n      examples: [],\n    },\n  )\n}\n\n/** 오류 → isError 결과. MextError = toJSON, 그 외 = EXECUTION_ERROR */\nexport function errorResult(error: unknown): ToolCallResult {\n  const body = isMextError(error)\n    ? error.toJSON()\n    : { code: EXECUTION_ERROR, message: error instanceof Error ? error.message : String(error) }\n  return {\n    content: [{ type: \"text\", text: `${body.code}: ${body.message}\\n${stringify(body)}` }],\n    structuredContent: { error: body },\n    isError: true,\n  }\n}\n\n/** dispatcher 도구 inputSchema. command 를 Mcp-Param-Command 헤더로 복사 (SEP-2243) */\nexport function dispatcherInputSchema(): JsonSchema {\n  return {\n    type: \"object\",\n    properties: {\n      command: {\n        type: \"string\",\n        description: 'Command ID (e.g. \"users.get\"), or \"help\" to list namespaces and commands.',\n        \"x-mcp-header\": \"Command\",\n      },\n      args: {\n        type: \"object\",\n        description: 'Command input. For \"help\": { \"target\": \"<namespace or command ID>\" }.',\n        additionalProperties: true,\n      },\n    },\n    required: [\"command\"],\n    additionalProperties: false,\n  }\n}\n\nfunction parseDispatcherArguments(tool: DispatcherTool, raw: unknown): { command: string; args: unknown } {\n  const input = raw === undefined ? {} : raw\n  if (input === null || typeof input !== \"object\" || Array.isArray(input)) {\n    throw dispatcherArgumentError(tool, tool.name, \"arguments must be an object\", [], {\n      path: \"\",\n      code: \"invalid_type\",\n      message: \"expected object\",\n    })\n  }\n  const { command, args, ...rest } = input as Record<string, unknown>\n  if (command === undefined) {\n    throw dispatcherArgumentError(tool, tool.name, \"missing required: command\", [\"command\"], {\n      path: \"command\",\n      code: \"invalid_type\",\n      message: \"expected string, received undefined\",\n    })\n  }\n  if (typeof command !== \"string\") {\n    throw dispatcherArgumentError(tool, tool.name, \"command must be a string\", [], {\n      path: \"command\",\n      code: \"invalid_type\",\n      message: \"expected string\",\n    })\n  }\n  const unknownKeys = Object.keys(rest)\n  if (unknownKeys.length > 0) {\n    throw dispatcherArgumentError(tool, tool.name, `unrecognized keys: ${unknownKeys.join(\", \")}`, [], {\n      path: \"\",\n      code: \"unrecognized_keys\",\n      message: `Unrecognized keys: ${unknownKeys.join(\", \")}. Put command input under \"args\".`,\n    })\n  }\n  if (args !== undefined && (args === null || typeof args !== \"object\" || Array.isArray(args))) {\n    throw dispatcherArgumentError(tool, command, \"args must be an object\", [], {\n      path: \"args\",\n      code: \"invalid_type\",\n      message: \"expected object\",\n    })\n  }\n  return { command, args }\n}\n\nfunction dispatcherArgumentError(\n  tool: DispatcherTool,\n  command: string,\n  summary: string,\n  missing: string[],\n  issue: { path: string; code: string; message: string },\n): MextError<\"INVALID_ARGUMENT\"> {\n  return new MextError(\"INVALID_ARGUMENT\", `Invalid arguments for ${command}: ${summary}`, {\n    command,\n    missing_fields: missing,\n    issues: [issue],\n    expected_schema: tool.inputSchema,\n    examples: [{ command: HELP_COMMAND }],\n  })\n}\n\nfunction splitToolFor(tools: readonly DispatcherTool[] | undefined): ((e: RegisteredCommand) => string) | undefined {\n  if (!tools || tools.length < 2) return undefined\n  const query = tools.find((t) => t.readOnly)?.name\n  const mutate = tools.find((t) => !t.readOnly)?.name\n  if (query === undefined || mutate === undefined) return undefined\n  return (e) => (e.command.readOnly ? query : mutate)\n}\n\nfunction describeTool(name: string, lead: string, commands: readonly RegisteredCommand[], note?: string): string {\n  const lines = [\n    lead,\n    `Arguments: { \"command\": \"<command ID>\", \"args\": { ...input } }. ` +\n      `Call ${name}({ \"command\": \"help\" }) to list namespaces and commands, ` +\n      `${name}({ \"command\": \"help\", \"args\": { \"target\": \"<namespace or command ID>\" } }) for input schemas and examples.`,\n  ]\n  if (note) lines.push(note)\n  if (commands.length > 0 && commands.length <= DESCRIPTION_COMMAND_LIMIT) {\n    lines.push(\"\", \"Commands:\")\n    for (const e of commands) lines.push(`- ${e.id}: ${firstLine(e.command.description)}`)\n  }\n  return lines.join(\"\\n\")\n}\n\nfunction firstLine(text: string): string {\n  return text.split(\"\\n\", 1)[0]!.trim()\n}\n\nfunction stringify(value: unknown): string {\n  try {\n    return JSON.stringify(value, null, 2) ?? \"null\"\n  } catch {\n    return String(value)\n  }\n}\n"]}

package/dist/mcp/help.d.ts

@@ -0,0 +1,57 @@
+import { type ManifestCommand } from "../manifest.ts";
+import type { RegisteredCommand, Registry } from "../registry.ts";
+/** help 의 예약 명령어 이름. 루트 세그먼트 help 는 Registry 에서 금지 */
+export declare const HELP_COMMAND = "help";
+export interface HelpNamespaceSummary {
+    id: string;
+    /** _index.md 첫 줄 */
+    description?: string;
+}
+export interface HelpCommandSummary {
+    id: string;
+    description: string;
+    readOnly: boolean;
+    destructive: boolean;
+    requiresConfirmation: boolean;
+    /** split 노출에서 이 명령어를 호출할 도구 (query · mutate). execute 노출에서는 없음 */
+    tool?: string;
+}
+/** execute({ command: "help" }) */
+export interface RootHelp {
+    kind: "root";
+    /** commands/_index.md */
+    description?: string;
+    namespaces: HelpNamespaceSummary[];
+    /** 루트 직속 명령어 */
+    commands: HelpCommandSummary[];
+}
+/** execute({ command: "help", args: { target: "users" } }) */
+export interface NamespaceHelp {
+    kind: "namespace";
+    id: string;
+    /** _index.md 전체 */
+    description?: string;
+    namespaces: HelpNamespaceSummary[];
+    commands: HelpCommandSummary[];
+    /** 같은 ID 의 명령어 (users/index.ts) */
+    command?: CommandHelp;
+}
+/** execute({ command: "help", args: { target: "users.get" } }) */
+export interface CommandHelp extends Omit<ManifestCommand, "file"> {
+    kind: "command";
+    /** 이 명령어 호출이 돌려줄 수 있는 구조화 오류 code */
+    errors: string[];
+    tool?: string;
+}
+export type Help = RootHelp | NamespaceHelp | CommandHelp;
+export interface HelpOptions {
+    /** 명령어 → 호출할 도구 이름. split 노출이 지정 */
+    toolFor?: (entry: RegisteredCommand) => string | undefined;
+}
+/**
+ * help 3단계: target 없음 = 루트 (네임스페이스 · 루트 명령어), 네임스페이스 ID = 그 명령어 목록,
+ * 명령어 ID · 별칭 = 설명 · 입력 스키마 · 예시 · 오류 · 권한. 없는 target = UNKNOWN_COMMAND.
+ */
+export declare function help(registry: Registry, target: string | undefined, options?: HelpOptions): Help;
+/** help 의 사람용 텍스트 (MCP text content). 구조는 structuredContent 가 원본 */
+export declare function formatHelp(value: Help, call?: string): string;

package/dist/mcp/help.js

@@ -0,0 +1,136 @@
+import { findCommand } from "../invoke.js";
+import { describeCommand } from "../manifest.js";
+/** help 의 예약 명령어 이름. 루트 세그먼트 help 는 Registry 에서 금지 */
+export const HELP_COMMAND = "help";
+/**
+ * help 3단계: target 없음 = 루트 (네임스페이스 · 루트 명령어), 네임스페이스 ID = 그 명령어 목록,
+ * 명령어 ID · 별칭 = 설명 · 입력 스키마 · 예시 · 오류 · 권한. 없는 target = UNKNOWN_COMMAND.
+ */
+export function help(registry, target, options = {}) {
+    const id = target?.trim() ?? "";
+    if (id === "") {
+        const root = registry.namespaces.get("");
+        const out = {
+            kind: "root",
+            namespaces: root.namespaces.map((n) => namespaceSummary(registry, n)),
+            commands: root.commands.map((c) => commandSummary(registry.commands.get(c), options)),
+        };
+        if (root.description !== undefined)
+            out.description = root.description;
+        return out;
+    }
+    const ns = registry.namespaces.get(id);
+    if (ns) {
+        const out = {
+            kind: "namespace",
+            id,
+            namespaces: ns.namespaces.map((n) => namespaceSummary(registry, n)),
+            commands: ns.commands.map((c) => commandSummary(registry.commands.get(c), options)),
+        };
+        if (ns.description !== undefined)
+            out.description = ns.description;
+        const self = registry.commands.get(id);
+        if (self)
+            out.command = commandHelp(self, options);
+        return out;
+    }
+    return commandHelp(findCommand(registry, id), options);
+}
+function namespaceSummary(registry, id) {
+    const description = registry.namespaces.get(id)?.description;
+    const first = description?.split("\n").find((l) => l.trim() !== "");
+    return first === undefined ? { id } : { id, description: first.replace(/^#+\s*/, "").trim() };
+}
+function commandSummary(entry, options) {
+    const c = entry.command;
+    const out = {
+        id: entry.id,
+        description: c.description,
+        readOnly: c.readOnly,
+        destructive: c.destructive,
+        requiresConfirmation: c.requiresConfirmation,
+    };
+    const tool = options.toolFor?.(entry);
+    if (tool !== undefined)
+        out.tool = tool;
+    return out;
+}
+function commandHelp(entry, options) {
+    const { file: _file, ...meta } = describeCommand(entry);
+    const c = entry.command;
+    const errors = ["INVALID_ARGUMENT"];
+    if (!c.readOnly || c.scopes.length > 0)
+        errors.push("UNAUTHENTICATED", "PERMISSION_DENIED");
+    if (c.requiresConfirmation)
+        errors.push("INPUT_UNAVAILABLE", "INPUT_DECLINED");
+    const out = { kind: "command", ...meta, errors };
+    const tool = options.toolFor?.(entry);
+    if (tool !== undefined)
+        out.tool = tool;
+    return out;
+}
+/** help 의 사람용 텍스트 (MCP text content). 구조는 structuredContent 가 원본 */
+export function formatHelp(value, call = "execute") {
+    const lines = [];
+    const hint = (target) => `${call}({ command: "help", args: { target: "${target}" } })`;
+    const listCommands = (commands) => {
+        if (commands.length === 0)
+            return;
+        lines.push("Commands:");
+        const width = Math.max(...commands.map((c) => c.id.length));
+        for (const c of commands) {
+            const flags = safetyFlags(c);
+            const via = c.tool !== undefined ? ` (via ${c.tool})` : "";
+            lines.push(`  ${c.id.padEnd(width)}  ${c.description}${flags ? ` [${flags}]` : ""}${via}`);
+        }
+    };
+    const listNamespaces = (namespaces) => {
+        if (namespaces.length === 0)
+            return;
+        lines.push("Namespaces:");
+        const width = Math.max(...namespaces.map((n) => n.id.length));
+        for (const n of namespaces)
+            lines.push(`  ${n.id.padEnd(width)}  ${n.description ?? ""}`.trimEnd());
+    };
+    if (value.kind === "command") {
+        lines.push(`${value.id}: ${value.description}`);
+        if (value.aliases.length > 0)
+            lines.push(`Aliases: ${value.aliases.join(", ")}`);
+        const flags = safetyFlags(value);
+        lines.push(`Safety: ${flags || "none"}`);
+        if (value.scopes.length > 0)
+            lines.push(`Scopes: ${value.scopes.join(", ")}`);
+        if (value.tool !== undefined)
+            lines.push(`Tool: ${value.tool}`);
+        lines.push("Input schema:", JSON.stringify(value.inputSchema, null, 2));
+        if (value.examples.length > 0) {
+            lines.push("Examples:");
+            for (const e of value.examples)
+                lines.push(`  ${JSON.stringify(e)}`);
+        }
+        lines.push(`Errors: ${value.errors.join(", ")}`);
+        return lines.join("\n");
+    }
+    if (value.kind === "namespace")
+        lines.push(value.id);
+    if (value.description !== undefined)
+        lines.push(value.description, "");
+    listNamespaces(value.namespaces);
+    listCommands(value.commands);
+    if (value.kind === "namespace" && value.command !== undefined) {
+        lines.push("", formatHelp(value.command, call));
+    }
+    lines.push("", `Details: ${hint(value.kind === "root" ? "<namespace or command>" : `${value.id}.<command>`)}`);
+    return lines.join("\n").replace(/^\n+/, "");
+}
+function safetyFlags(c) {
+    const flags = [];
+    if (c.readOnly)
+        flags.push("read-only");
+    if (c.destructive)
+        flags.push("destructive");
+    if (c.requiresConfirmation)
+        flags.push("requires confirmation");
+    return flags.join(", ");
+}
+//# sourceMappingURL=help.js.map

package/dist/mcp/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/mcp/help.ts"],"names":[],"mappings":"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","sourcesContent":["import { findCommand } from \"../invoke.ts\"\nimport { describeCommand, type ManifestCommand } from \"../manifest.ts\"\nimport type { RegisteredCommand, Registry } from \"../registry.ts\"\n\n/** help 의 예약 명령어 이름. 루트 세그먼트 help 는 Registry 에서 금지 */\nexport const HELP_COMMAND = \"help\"\n\nexport interface HelpNamespaceSummary {\n  id: string\n  /** _index.md 첫 줄 */\n  description?: string\n}\n\nexport interface HelpCommandSummary {\n  id: string\n  description: string\n  readOnly: boolean\n  destructive: boolean\n  requiresConfirmation: boolean\n  /** split 노출에서 이 명령어를 호출할 도구 (query · mutate). execute 노출에서는 없음 */\n  tool?: string\n}\n\n/** execute({ command: \"help\" }) */\nexport interface RootHelp {\n  kind: \"root\"\n  /** commands/_index.md */\n  description?: string\n  namespaces: HelpNamespaceSummary[]\n  /** 루트 직속 명령어 */\n  commands: HelpCommandSummary[]\n}\n\n/** execute({ command: \"help\", args: { target: \"users\" } }) */\nexport interface NamespaceHelp {\n  kind: \"namespace\"\n  id: string\n  /** _index.md 전체 */\n  description?: string\n  namespaces: HelpNamespaceSummary[]\n  commands: HelpCommandSummary[]\n  /** 같은 ID 의 명령어 (users/index.ts) */\n  command?: CommandHelp\n}\n\n/** execute({ command: \"help\", args: { target: \"users.get\" } }) */\nexport interface CommandHelp extends Omit<ManifestCommand, \"file\"> {\n  kind: \"command\"\n  /** 이 명령어 호출이 돌려줄 수 있는 구조화 오류 code */\n  errors: string[]\n  tool?: string\n}\n\nexport type Help = RootHelp | NamespaceHelp | CommandHelp\n\nexport interface HelpOptions {\n  /** 명령어 → 호출할 도구 이름. split 노출이 지정 */\n  toolFor?: (entry: RegisteredCommand) => string | undefined\n}\n\n/**\n * help 3단계: target 없음 = 루트 (네임스페이스 · 루트 명령어), 네임스페이스 ID = 그 명령어 목록,\n * 명령어 ID · 별칭 = 설명 · 입력 스키마 · 예시 · 오류 · 권한. 없는 target = UNKNOWN_COMMAND.\n */\nexport function help(registry: Registry, target: string | undefined, options: HelpOptions = {}): Help {\n  const id = target?.trim() ?? \"\"\n  if (id === \"\") {\n    const root = registry.namespaces.get(\"\")!\n    const out: RootHelp = {\n      kind: \"root\",\n      namespaces: root.namespaces.map((n) => namespaceSummary(registry, n)),\n      commands: root.commands.map((c) => commandSummary(registry.commands.get(c)!, options)),\n    }\n    if (root.description !== undefined) out.description = root.description\n    return out\n  }\n  const ns = registry.namespaces.get(id)\n  if (ns) {\n    const out: NamespaceHelp = {\n      kind: \"namespace\",\n      id,\n      namespaces: ns.namespaces.map((n) => namespaceSummary(registry, n)),\n      commands: ns.commands.map((c) => commandSummary(registry.commands.get(c)!, options)),\n    }\n    if (ns.description !== undefined) out.description = ns.description\n    const self = registry.commands.get(id)\n    if (self) out.command = commandHelp(self, options)\n    return out\n  }\n  return commandHelp(findCommand(registry, id), options)\n}\n\nfunction namespaceSummary(registry: Registry, id: string): HelpNamespaceSummary {\n  const description = registry.namespaces.get(id)?.description\n  const first = description?.split(\"\\n\").find((l) => l.trim() !== \"\")\n  return first === undefined ? { id } : { id, description: first.replace(/^#+\\s*/, \"\").trim() }\n}\n\nfunction commandSummary(entry: RegisteredCommand, options: HelpOptions): HelpCommandSummary {\n  const c = entry.command\n  const out: HelpCommandSummary = {\n    id: entry.id,\n    description: c.description,\n    readOnly: c.readOnly,\n    destructive: c.destructive,\n    requiresConfirmation: c.requiresConfirmation,\n  }\n  const tool = options.toolFor?.(entry)\n  if (tool !== undefined) out.tool = tool\n  return out\n}\n\nfunction commandHelp(entry: RegisteredCommand, options: HelpOptions): CommandHelp {\n  const { file: _file, ...meta } = describeCommand(entry)\n  const c = entry.command\n  const errors = [\"INVALID_ARGUMENT\"]\n  if (!c.readOnly || c.scopes.length > 0) errors.push(\"UNAUTHENTICATED\", \"PERMISSION_DENIED\")\n  if (c.requiresConfirmation) errors.push(\"INPUT_UNAVAILABLE\", \"INPUT_DECLINED\")\n  const out: CommandHelp = { kind: \"command\", ...meta, errors }\n  const tool = options.toolFor?.(entry)\n  if (tool !== undefined) out.tool = tool\n  return out\n}\n\n/** help 의 사람용 텍스트 (MCP text content). 구조는 structuredContent 가 원본 */\nexport function formatHelp(value: Help, call = \"execute\"): string {\n  const lines: string[] = []\n  const hint = (target: string) => `${call}({ command: \"help\", args: { target: \"${target}\" } })`\n  const listCommands = (commands: HelpCommandSummary[]) => {\n    if (commands.length === 0) return\n    lines.push(\"Commands:\")\n    const width = Math.max(...commands.map((c) => c.id.length))\n    for (const c of commands) {\n      const flags = safetyFlags(c)\n      const via = c.tool !== undefined ? ` (via ${c.tool})` : \"\"\n      lines.push(`  ${c.id.padEnd(width)}  ${c.description}${flags ? ` [${flags}]` : \"\"}${via}`)\n    }\n  }\n  const listNamespaces = (namespaces: HelpNamespaceSummary[]) => {\n    if (namespaces.length === 0) return\n    lines.push(\"Namespaces:\")\n    const width = Math.max(...namespaces.map((n) => n.id.length))\n    for (const n of namespaces) lines.push(`  ${n.id.padEnd(width)}  ${n.description ?? \"\"}`.trimEnd())\n  }\n\n  if (value.kind === \"command\") {\n    lines.push(`${value.id}: ${value.description}`)\n    if (value.aliases.length > 0) lines.push(`Aliases: ${value.aliases.join(\", \")}`)\n    const flags = safetyFlags(value)\n    lines.push(`Safety: ${flags || \"none\"}`)\n    if (value.scopes.length > 0) lines.push(`Scopes: ${value.scopes.join(\", \")}`)\n    if (value.tool !== undefined) lines.push(`Tool: ${value.tool}`)\n    lines.push(\"Input schema:\", JSON.stringify(value.inputSchema, null, 2))\n    if (value.examples.length > 0) {\n      lines.push(\"Examples:\")\n      for (const e of value.examples) lines.push(`  ${JSON.stringify(e)}`)\n    }\n    lines.push(`Errors: ${value.errors.join(\", \")}`)\n    return lines.join(\"\\n\")\n  }\n\n  if (value.kind === \"namespace\") lines.push(value.id)\n  if (value.description !== undefined) lines.push(value.description, \"\")\n  listNamespaces(value.namespaces)\n  listCommands(value.commands)\n  if (value.kind === \"namespace\" && value.command !== undefined) {\n    lines.push(\"\", formatHelp(value.command, call))\n  }\n  lines.push(\"\", `Details: ${hint(value.kind === \"root\" ? \"<namespace or command>\" : `${value.id}.<command>`)}`)\n  return lines.join(\"\\n\").replace(/^\\n+/, \"\")\n}\n\nfunction safetyFlags(c: { readOnly: boolean; destructive: boolean; requiresConfirmation: boolean }): string {\n  const flags: string[] = []\n  if (c.readOnly) flags.push(\"read-only\")\n  if (c.destructive) flags.push(\"destructive\")\n  if (c.requiresConfirmation) flags.push(\"requires confirmation\")\n  return flags.join(\", \")\n}\n"]}

package/dist/mcp/http.d.ts

@@ -0,0 +1,96 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import type { MextApp } from "../command.ts";
+import { type Principal } from "../principal.ts";
+import type { Registry } from "../registry.ts";
+import type { Instrumentation } from "../instrumentation.ts";
+import type { ToolExposure } from "./dispatch.ts";
+import { type McpCoreOptions } from "./server.ts";
+/** 요청 본문 상한 (SDK 기본과 같음) */
+export declare const MAX_BODY_BYTES: number;
+export interface McpAuthRequest {
+    /** Authorization 헤더 원문 */
+    authorization: string | undefined;
+}
+export interface McpHttpOptions {
+    registry: Registry;
+    app?: () => MextApp | Promise<MextApp>;
+    /**
+     * 요청마다 Authorization → Principal. 없으면 모든 요청 = ANONYMOUS (readOnly 명령어만).
+     * 잘못된 토큰은 unauthenticated() 를 던진다 → HTTP 401. anonymous 로 낮추지 않는다
+     */
+    auth?: (req: McpAuthRequest) => Principal | Promise<Principal>;
+    tools?: ToolExposure;
+    server?: {
+        /** 기본 127.0.0.1 */
+        host?: string;
+        /** 기본 3100. 0 = 임의 포트 */
+        port?: number;
+        /**
+         * Origin 허용 목록 (https://app.example.com 형식, "*" = 전체).
+         * 미지정 = loopback (localhost · 127.0.0.1 · [::1], 포트 무관) 만. Origin 헤더 없는 요청은 항상 통과
+         */
+        allowedOrigins?: string[];
+    };
+    /** serverInfo.name · 안내 문구. 기본 "mext" */
+    name?: string;
+    /** initialize · server/discover 결과 instructions */
+    instructions?: string;
+    /** 서버 capabilities 에 병합 (experimental) */
+    capabilities?: McpCoreOptions["capabilities"];
+    /** 응답에 영향 없는 오류 보고 (auth 예외 · SDK 내부 오류) */
+    onerror?: (error: Error) => void;
+    /** MRTR requestState 서명 키. McpCoreOptions.requestStateKey */
+    requestStateKey?: McpCoreOptions["requestStateKey"];
+    /** 주기 progress 간격 (ms). McpCoreOptions.progressInterval */
+    progressInterval?: number;
+    /** loadInstrumentation 결과 (onCommandError · span, transport = "http") */
+    instrumentation?: Instrumentation;
+    /** _meta["dev.mext/manifestHash"]. McpCoreOptions.manifestHash (기본 = registry 로 계산) */
+    manifestHash?: string;
+    /**
+     * OAuth 보호 자원 메타데이터 (RFC 9728). 지정하면 GET /.well-known/oauth-protected-resource/mcp ·
+     * /.well-known/oauth-protected-resource 응답, 401 의 WWW-Authenticate 에 resource_metadata.
+     * 클라이언트 (mext login · MCP 클라이언트) 가 인가 서버를 찾는 데 쓴다
+     */
+    oauth?: OAuthResourceOptions;
+}
+export interface OAuthResourceOptions {
+    /** 인가 서버 issuer URL (1개 이상) */
+    authorizationServers: string[];
+    scopesSupported?: string[];
+    /** 토큰 대상 자원 ID (RFC 8707). 기본 = 요청 Host 기준 http://<host>/mcp (프록시 · TLS 뒤에서는 지정) */
+    resource?: string;
+}
+/** RFC 9728 well-known 경로 */
+export declare const PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
+export type McpHttpListener = ((req: IncomingMessage, res: ServerResponse) => void) & {
+    /** 진행 중인 요청 abort · SDK handler 정리 */
+    close(): Promise<void>;
+};
+/** Web 표준 (Request → Response) MCP 처리기. handler.js · 다른 런타임 · node:http 어댑터가 공유 */
+export interface McpFetchHandler {
+    /** 거부하지 않는다 (내부 오류 = 500 JSON-RPC 오류). request.signal abort = 핸들러 ctx.signal abort */
+    fetch(request: Request): Promise<Response>;
+    /** SDK handler 정리 */
+    close(): Promise<void>;
+}
+/**
+ * Streamable HTTP (2026-07-28) 의 transport 무관 처리 (Web Request → Response).
+ * 순서: 경로 (404) → Origin (403) → 메서드 (POST 외 405) → 본문 (413) → auth (401) → SDK createMcpHandler.
+ * SDK 가 요청별 버전 · 헤더 검증 (-32020) · server/discover · Mcp-Param-Command · 2025 레거시 stateless 를 처리.
+ * progressToken 있는 2026-07-28 요청 = SSE 응답 (진행률 알림), 그 외 = JSON.
+ */
+export declare function createMcpFetchHandler(options: McpHttpOptions): McpFetchHandler;
+/** createMcpFetchHandler 의 node:http 어댑터. 응답 · SSE 를 스트리밍, 클라이언트 연결 종료 = request.signal abort */
+export declare function createMcpHttpHandler(options: McpHttpOptions): McpHttpListener;
+export interface McpHttpServer {
+    /** http://<host>:<port>/mcp */
+    url: string;
+    host: string;
+    port: number;
+    close(): Promise<void>;
+}
+/** createMcpHttpHandler + node:http listen. 기본 127.0.0.1:3100 */
+export declare function startMcpHttpServer(options: McpHttpOptions): Promise<McpHttpServer>;
+/** Origin 허용 여부. allowed 미지정 = loopback 만, 지정 = 목록의 origin 과 정확히 일치 ("*" = 전체) */
+export declare function originAllowed(origin: string, allowed: readonly string[] | undefined): boolean;