@faapi/mcp 0.0.0-canary.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 faapi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @faapi/mcp
+
+> MCP Server SDK for faapi — 不依赖 @modelcontextprotocol/sdk，纯手写 MCP 协议
+
+`@faapi/mcp` 实现 MCP（Model Context Protocol）服务端，通过 Streamable HTTP transport 暴露 tool 给 AI 助手（如 Claude、Cursor）。用 zod 声明 tool 输入参数，自动转为 JSON Schema。
+
+## 安装
+
+```bash
+pnpm add @faapi/mcp
+```
+
+要求 Node.js >= 24。
+
+## 快速开始
+
+在 faapi 应用中创建 MCP 端点：
+
+```ts
+// api/mcp/handler.ts
+import { createMcpServer, createMcpHandler } from '@faapi/mcp';
+import { z } from 'zod';
+
+const mcp = createMcpServer({ name: 'my-app', version: '1.0.0' });
+
+mcp.tool('hello', {
+  description: 'Say hello',
+  input: { name: z.string().describe('Name to greet') },
+  handler: async ({ name }) => ({
+    content: [{ type: 'text', text: `Hello, ${name}!` }],
+  }),
+});
+
+export const { POST, GET, DELETE } = createMcpHandler(mcp);
+```
+
+启动后，MCP 端点在 `/api/mcp` 可用，AI 助手通过 Streamable HTTP 连接。
+
+## MCP 方法
+
+| 方法 | 行为 |
+|------|------|
+| `initialize` | 协议握手，返回 serverInfo + capabilities |
+| `tools/list` | 列出所有 tool（含 JSON Schema） |
+| `tools/call` | 调用 tool，返回结果 |
+| `ping` | 心跳 |
+
+## Transport
+
+仅支持 Streamable HTTP（MCP 2025-06-18 规范）：
+
+- **POST**：发送 JSON-RPC 消息，返回 JSON 响应
+- **GET**：v1 返回 405（不支持独立 SSE 流）
+- **DELETE**：按 `Mcp-Session-Id` 销毁会话
+
+## 与 @modelcontextprotocol/sdk 的区别
+
+| 方面 | @modelcontextprotocol/sdk | @faapi/mcp |
+|------|--------------------------|------------|
+| Transport | stdio + Streamable HTTP + 旧版 SSE | 仅 Streamable HTTP |
+| 依赖 | @modelcontextprotocol/sdk + zod-to-json-schema | 仅 zod（v4 内置 toJSONSchema） |
+| 集成 | 独立进程 | faapi 路由（函数即接口） |
+| Tool 定义 | `server.tool(name, schema, cb)` | `mcp.tool(name, { input, handler })` |
+
+## 许可证
+
+[MIT](https://github.com/faapi/faapi/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,600 @@
+import { z } from 'zod';
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+/**
+ * JSON-RPC 2.0 协议消息类型、解析和响应构建
+ *
+ * MCP 协议基于 JSON-RPC 2.0，所有通信都是 JSON-RPC 消息。
+ * 本模块提供类型定义、消息判定函数和响应构建工具。
+ */
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: string | number;
+    method: string;
+    params?: unknown;
+}
+interface JsonRpcNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params?: unknown;
+}
+interface JsonRpcResultResponse {
+    jsonrpc: '2.0';
+    id: string | number;
+    result: unknown;
+}
+interface JsonRpcErrorResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    error: JsonRpcError;
+}
+interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResultResponse | JsonRpcErrorResponse;
+declare const ErrorCode: {
+    readonly ParseError: -32700;
+    readonly InvalidRequest: -32600;
+    readonly MethodNotFound: -32601;
+    readonly InvalidParams: -32602;
+    readonly InternalError: -32603;
+    readonly ConnectionClosed: -32000;
+    readonly RequestTimeout: -32001;
+};
+declare function isRequest(msg: JsonRpcMessage): msg is JsonRpcRequest;
+declare function isNotification(msg: JsonRpcMessage): msg is JsonRpcNotification;
+declare function isResultResponse(msg: JsonRpcMessage): msg is JsonRpcResultResponse;
+declare function isErrorResponse(msg: JsonRpcMessage): msg is JsonRpcErrorResponse;
+declare function createResultResponse(id: string | number, result: unknown): JsonRpcResultResponse;
+declare function createErrorResponse(id: string | number | null, code: number, message: string, data?: unknown): JsonRpcErrorResponse;
+/**
+ * 解析 JSON-RPC 消息（单条或批量）
+ *
+ * @throws ParseError（返回 Error 对象，不抛异常）
+ * @returns 消息数组（单条也包装为数组）
+ */
+declare function parseJsonRpcMessage(data: unknown): JsonRpcMessage[];
+declare class JsonRpcParseError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * MCP 会话管理
+ *
+ * Streamable HTTP transport 通过 Mcp-Session-Id header 维持会话。
+ * 会话在 initialize 请求时创建，在 DELETE 请求时销毁。
+ *
+ * 内置 TTL 机制：超过空闲时间的会话自动过期，防止内存泄漏。
+ * 惰性清理：在 get/create 时检查过期会话，无需定时器。
+ *
+ * 每个 session 维护 SSE subscriber 集合,用于服务端主动推送
+ * (logging/message, resources/updated, progress 等通知)。
+ */
+/** 日志级别(syslog 严重度,从低到高) */
+type LoggingLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';
+/** SSE 流订阅者(controller + 关联的 session id) */
+interface SseSubscriber {
+    /** SSE 流控制器 */
+    controller: ReadableStreamDefaultController<Uint8Array>;
+    /** 关联的 session id */
+    sessionId: string;
+}
+interface McpSession {
+    /** 会话 ID（cryptographically secure UUID） */
+    id: string;
+    /** 是否已完成 initialize 握手 */
+    initialized: boolean;
+    /** 协商的协议版本 */
+    protocolVersion: string;
+    /** 客户端信息（来自 initialize 请求） */
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+    /** 创建时间戳 */
+    createdAt: number;
+    /** 最后活动时间戳（每次 get 时更新） */
+    lastActivity: number;
+    /** 当前日志级别(低于此级别的日志不推送),默认 info */
+    loggingLevel: LoggingLevel;
+    /** SSE 流订阅者集合(GET 流注册,用于服务端主动推送) */
+    subscribers: Set<SseSubscriber>;
+    /** 已订阅的资源 URI 集合(resources/subscribe 注册) */
+    subscribedResources: Set<string>;
+}
+/**
+ * 内存会话管理器
+ *
+ * 生产环境如需多实例共享会话，可替换为 Redis 等外部存储实现。
+ *
+ * @param ttl 会话空闲超时（毫秒），超过此时间未活动的会话自动过期。默认 30 分钟。设为 0 表示永不过期。
+ */
+declare class SessionManager {
+    private sessions;
+    private readonly ttl;
+    constructor(ttl?: number);
+    /** 是否启用 TTL 过期检查(ttl > 0) */
+    private get ttlEnabled();
+    /** 创建新会话，返回 session 对象 */
+    create(): McpSession;
+    /** 按 ID 获取会话（更新最后活动时间，过期返回 undefined） */
+    get(id: string): McpSession | undefined;
+    /** 是否存在（不更新活动时间，过期会话返回 false） */
+    has(id: string): boolean;
+    /** 销毁会话(关闭所有 SSE 订阅者) */
+    delete(id: string): boolean;
+    /** 当前会话数（含可能尚未清理的过期会话） */
+    get size(): number;
+    /** 获取所有 session ID 列表(用于全局广播通知) */
+    allSessionIds(): string[];
+    /** 清空所有会话 */
+    clear(): void;
+    /** 注册 SSE 订阅者到 session */
+    addSubscriber(sessionId: string, controller: ReadableStreamDefaultController<Uint8Array>): SseSubscriber | undefined;
+    /** 注销 SSE 订阅者 */
+    removeSubscriber(subscriber: SseSubscriber): void;
+    /** 向 session 的所有订阅者推送 SSE 数据 */
+    broadcastToSession(sessionId: string, data: string): void;
+    /** 判断指定级别的日志是否应该推送(>= session.loggingLevel) */
+    shouldLog(sessionId: string, level: LoggingLevel): boolean;
+    /** 添加资源订阅(将 uri 加入 session.subscribedResources) */
+    subscribeResource(sessionId: string, uri: string): boolean;
+    /** 取消资源订阅(从 session.subscribedResources 移除 uri) */
+    unsubscribeResource(sessionId: string, uri: string): boolean;
+    /** 找出所有订阅了指定 URI 的 session id 列表 */
+    findSubscribersOfUri(uri: string): string[];
+    /** 关闭 session 的所有订阅者(用于 session 销毁/过期) */
+    private closeSubscribers;
+    /** 清理所有过期会话 */
+    private cleanupExpired;
+}
+
+/**
+ * MCP Server 核心：tool/resource/prompt 注册 + JSON-RPC 方法分发
+ *
+ * 实现 MCP 协议的核心方法：
+ * - initialize：握手，返回 serverInfo + capabilities（根据注册情况动态生成）
+ * - notifications/initialized：通知，无响应
+ * - tools/list、tools/call：tool 列表与调用
+ * - resources/list、resources/read：资源列表与读取
+ * - prompts/list、prompts/get：提示列表与获取
+ * - ping：心跳
+ *
+ * Tool 输入参数用 zod schema 声明，通过 zod v4 内置 toJSONSchema 转为 JSON Schema。
+ */
+
+/** MCP 协议版本（当前实现遵循 2025-06-18 规范） */
+declare const PROTOCOL_VERSION = "2025-06-18";
+/** 支持的协议版本列表 */
+declare const SUPPORTED_PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26"];
+interface McpServerOptions {
+    /** Server 名称 */
+    name: string;
+    /** Server 版本 */
+    version: string;
+    /** 可选显示名称 */
+    title?: string;
+    /** 可选给客户端的指引说明 */
+    instructions?: string;
+    /** 会话空闲超时(毫秒),默认 30 分钟;设为 0 表示永不过期 */
+    sessionTtl?: number;
+    /** GET SSE 流心跳间隔(毫秒),默认 30 秒 */
+    sseHeartbeatMs?: number;
+    /** list 方法默认每页项数,默认 100 */
+    defaultPageSize?: number;
+    /** tools 列表是否可变(声明 listChanged: true + removeTool 时推送通知)。默认 false */
+    toolsListChanged?: boolean;
+    /** resources 列表是否可变(声明 listChanged: true + removeResource 时推送通知)。默认 false */
+    resourcesListChanged?: boolean;
+    /** prompts 列表是否可变(声明 listChanged: true + removePrompt 时推送通知)。默认 false */
+    promptsListChanged?: boolean;
+}
+interface McpToolResult {
+    /** 内容数组（text/image/audio/resource_link/resource） */
+    content: Array<Record<string, unknown>>;
+    /** 是否为 tool 执行错误（区别于协议错误） */
+    isError?: boolean;
+    /** 结构化输出（配合 outputSchema 使用） */
+    structuredContent?: unknown;
+}
+/** sendLogging 函数类型——推送日志到 session 的 SSE 订阅者 */
+type SendLoggingFn = (level: LoggingLevel, data: unknown, logger?: string) => void;
+/** sendProgress 函数类型——推送进度到 session 的 SSE 订阅者 */
+type SendProgressFn = (progress: number, total?: number) => void;
+/** 自定义方法的请求 extra(与 tool/resource/prompt handler extra 共享 send* 能力) */
+interface RequestExtra {
+    /** 会话 ID */
+    sessionId: string;
+    /** 推送日志到客户端 SSE 流(无订阅者或被级别过滤时静默丢弃) */
+    sendLogging: SendLoggingFn;
+    /** 推送进度到客户端 SSE 流(无 progressToken 或无订阅者时静默丢弃) */
+    sendProgress: SendProgressFn;
+}
+/** 自定义方法 handler 返回值——对象作为 result,JsonRpcErrorResponse 作为错误 */
+type MethodHandlerResult = Record<string, unknown> | JsonRpcErrorResponse;
+/** 自定义 JSON-RPC 方法 handler 类型 */
+type MethodHandler = (params: unknown, session: McpSession | undefined, extra: RequestExtra) => Promise<MethodHandlerResult> | MethodHandlerResult;
+interface ToolCallExtra {
+    /** 会话 ID */
+    sessionId: string;
+    /** 推送日志到客户端 SSE 流(无订阅者或被级别过滤时静默丢弃) */
+    sendLogging: SendLoggingFn;
+    /** 推送进度到客户端 SSE 流(无 progressToken 或无订阅者时静默丢弃) */
+    sendProgress: SendProgressFn;
+}
+interface McpToolDefinition {
+    /** 工具描述 */
+    description?: string;
+    /** 输入参数 schema（zod raw shape，如 { name: z.string() }） */
+    input?: Record<string, z.ZodType>;
+    /** 工具注解（如 readOnlyHint、destructiveHint 等） */
+    annotations?: Record<string, unknown>;
+    /** 处理函数 */
+    handler: (args: Record<string, unknown>, extra: ToolCallExtra) => Promise<McpToolResult> | McpToolResult;
+}
+interface McpResourceContent {
+    /** 资源 URI */
+    uri: string;
+    /** MIME 类型 */
+    mimeType?: string;
+    /** 文本内容(与 blob 二选一) */
+    text?: string;
+    /** 二进制内容(Base64 编码,与 text 二选一) */
+    blob?: string;
+}
+interface McpResourceReadResult {
+    /** 资源内容数组(支持一个 URI 返回多段内容) */
+    contents: McpResourceContent[];
+}
+interface ResourceReadExtra {
+    /** 会话 ID */
+    sessionId: string;
+    /** 推送日志到客户端 SSE 流(无订阅者或被级别过滤时静默丢弃) */
+    sendLogging: SendLoggingFn;
+    /** 推送进度到客户端 SSE 流(无 progressToken 或无订阅者时静默丢弃) */
+    sendProgress: SendProgressFn;
+}
+interface McpResourceDefinition {
+    /** 资源名称(必填) */
+    name: string;
+    /** 资源描述 */
+    description?: string;
+    /** MIME 类型 */
+    mimeType?: string;
+    /** 读取 handler(必填) */
+    read: (uri: string, extra: ResourceReadExtra) => Promise<McpResourceReadResult> | McpResourceReadResult;
+}
+interface ResourceTemplateReadExtra {
+    /** 会话 ID */
+    sessionId: string;
+    /** 推送日志到客户端 SSE 流(无订阅者或被级别过滤时静默丢弃) */
+    sendLogging: SendLoggingFn;
+    /** 推送进度到客户端 SSE 流(无 progressToken 或无订阅者时静默丢弃) */
+    sendProgress: SendProgressFn;
+}
+interface McpResourceTemplateDefinition {
+    /** 资源名称(必填) */
+    name: string;
+    /** 资源描述 */
+    description?: string;
+    /** MIME 类型 */
+    mimeType?: string;
+    /** 读取 handler(必填):接收实际 URI 和从 URI 模板提取的 params */
+    read: (uri: string, params: Record<string, string>, extra: ResourceTemplateReadExtra) => Promise<McpResourceReadResult> | McpResourceReadResult;
+}
+interface McpPromptArgument {
+    /** 参数名称 */
+    name: string;
+    /** 参数描述 */
+    description?: string;
+    /** 是否必填 */
+    required?: boolean;
+}
+interface McpPromptContent {
+    /** 内容类型:text 或 image */
+    type: 'text' | 'image';
+    /** 文本内容(type=text 时) */
+    text?: string;
+    /** Base64 编码的图片数据(type=image 时) */
+    data?: string;
+    /** 图片 MIME 类型(type=image 时) */
+    mimeType?: string;
+}
+interface McpPromptMessage {
+    /** 角色 */
+    role: 'user' | 'assistant';
+    /** 内容 */
+    content: McpPromptContent;
+}
+interface McpPromptGetResult {
+    /** 提示消息列表 */
+    messages: McpPromptMessage[];
+}
+interface PromptGetExtra {
+    /** 会话 ID */
+    sessionId: string;
+    /** 推送日志到客户端 SSE 流(无订阅者或被级别过滤时静默丢弃) */
+    sendLogging: SendLoggingFn;
+    /** 推送进度到客户端 SSE 流(无 progressToken 或无订阅者时静默丢弃) */
+    sendProgress: SendProgressFn;
+}
+interface McpPromptDefinition {
+    /** 提示描述 */
+    description?: string;
+    /** 参数定义 */
+    arguments?: McpPromptArgument[];
+    /** 获取 handler(必填) */
+    get: (args: Record<string, string>, extra: PromptGetExtra) => Promise<McpPromptGetResult> | McpPromptGetResult;
+}
+/** completion 引用——指向某个 prompt 或 resource template */
+type CompletionRef = {
+    type: 'ref/prompt';
+    name: string;
+} | {
+    type: 'ref/resource';
+    uri: string;
+};
+/** completion 调用上下文——传递给 handler */
+interface CompletionContext {
+    /** 客户端已填写的其他参数(部分填充,key 为参数名,value 为已填值) */
+    arguments: Record<string, string>;
+}
+/** completion 返回结果 */
+interface CompletionResult {
+    /** 候选值数组 */
+    values: string[];
+    /** 总数(可选,用于客户端提示"还有 N 项") */
+    total?: number;
+    /** 是否还有更多(可选,提示客户端可分页或继续输入) */
+    hasMore?: boolean;
+}
+/** completion handler 函数类型 */
+type CompletionHandler = (value: string, context: CompletionContext) => Promise<CompletionResult> | CompletionResult;
+declare class McpServer {
+    private options;
+    private tools;
+    private resources;
+    private resourceTemplates;
+    private prompts;
+    private completions;
+    private methods;
+    private sessions;
+    private readonly pageSize;
+    private readonly toolsListChanged;
+    private readonly resourcesListChanged;
+    private readonly promptsListChanged;
+    constructor(options: McpServerOptions);
+    /** 注册 tool */
+    tool(name: string, definition: McpToolDefinition): void;
+    /** 注册 resource */
+    resource(uri: string, definition: McpResourceDefinition): void;
+    /** 注册 resource template(RFC 6570 URI 模板) */
+    resourceTemplate(uriTemplate: string, definition: McpResourceTemplateDefinition): void;
+    /** 注册 prompt */
+    prompt(name: string, definition: McpPromptDefinition): void;
+    /**
+     * 注册参数补全 handler
+     *
+     * - `ref`:`{ type: 'ref/prompt', name }` 或 `{ type: 'ref/resource', uri }`(对资源模板,uri 是模板字符串)
+     * - `argumentName`:补全的参数名(对应 prompt arguments 中的 name,或 resource template URI 模板中的变量名)
+     * - 同一 (ref, argumentName) 重复注册抛错
+     */
+    completion(ref: CompletionRef, argumentName: string, handler: CompletionHandler): void;
+    /**
+     * 注册自定义 JSON-RPC 方法 handler(业务拓展)
+     *
+     * - 方法名建议使用 `appName/action` 格式,避免与 MCP 标准方法冲突
+     * - 与 MCP 内置方法(initialize/ping/tools/* 等)冲突时抛错
+     * - 重复注册同名方法抛错
+     *
+     * handler 返回值规则:
+     * - 返回普通对象:作为 JSON-RPC result 字段
+     * - 返回 JsonRpcErrorResponse(含 error 字段):作为错误响应
+     */
+    method(name: string, handler: MethodHandler): void;
+    /** 获取已注册 tool 名称列表 */
+    listTools(): string[];
+    /** 获取已注册 resource URI 列表 */
+    listResources(): string[];
+    /** 获取已注册 prompt 名称列表 */
+    listPrompts(): string[];
+    /** 获取已注册自定义方法名列表(业务拓展) */
+    listMethods(): string[];
+    /**
+     * 删除已注册 tool
+     *
+     * - `toolsListChanged: true` 时自动推送 `notifications/tools/list_changed`
+     * - `toolsListChanged: false` 时静默删除(用于 dev 热替换,客户端不感知)
+     */
+    removeTool(name: string): boolean;
+    /**
+     * 删除已注册 resource
+     *
+     * - `resourcesListChanged: true` 时自动推送 `notifications/resources/list_changed`
+     */
+    removeResource(uri: string): boolean;
+    /**
+     * 删除已注册 resource template
+     *
+     * - `resourcesListChanged: true` 时自动推送 `notifications/resources/list_changed`
+     */
+    removeResourceTemplate(uriTemplate: string): boolean;
+    /**
+     * 删除已注册 prompt
+     *
+     * - `promptsListChanged: true` 时自动推送 `notifications/prompts/list_changed`
+     */
+    removePrompt(name: string): boolean;
+    /**
+     * 删除已注册 completion handler
+     *
+     * - completion 无 list_changed 通知机制(客户端按需请求,无需感知列表变化)
+     */
+    removeCompletion(ref: CompletionRef, argumentName: string): boolean;
+    /** 删除已注册自定义方法 */
+    removeMethod(name: string): boolean;
+    /**
+     * 推送 `notifications/tools/list_changed` 到所有 session 的 SSE 订阅者
+     *
+     * 客户端收到后应重新调用 `tools/list` 拉取最新列表。
+     * `removeTool` 在 `toolsListChanged: true` 时自动调用本方法,
+     * 业务方也可手动调用(如批量删除后只推送一次)。
+     */
+    notifyToolsListChanged(): void;
+    /** 推送 `notifications/resources/list_changed` 到所有 session 的 SSE 订阅者 */
+    notifyResourcesListChanged(): void;
+    /** 推送 `notifications/prompts/list_changed` 到所有 session 的 SSE 订阅者 */
+    notifyPromptsListChanged(): void;
+    /**
+     * 向所有 session 的所有 SSE 订阅者广播通知(内部工具方法)
+     *
+     * 用于 list_changed 这种"全局广播"语义——所有 session 都应感知列表变化。
+     */
+    private broadcastNotificationToAllSessions;
+    /** 获取会话管理器 */
+    getSessionManager(): SessionManager;
+    /** 获取 GET SSE 流心跳间隔(毫秒) */
+    getSseHeartbeatMs(): number;
+    /**
+     * 处理 JSON-RPC 请求，返回响应消息
+     *
+     * 通知（无 id）不返回响应，返回 null。
+     */
+    handleJsonRpc(message: JsonRpcMessage, session: McpSession | undefined): Promise<JsonRpcMessage | null>;
+    private handleNotification;
+    private handleRequest;
+    private handleInitialize;
+    private handleToolsList;
+    private handleToolsCall;
+    private handleResourcesList;
+    private handleResourcesRead;
+    private handleResourcesTemplatesList;
+    private handlePromptsList;
+    private handlePromptsGet;
+    private handleLoggingSetLevel;
+    private handleResourcesSubscribe;
+    private handleResourcesUnsubscribe;
+    private handleCompletionComplete;
+    private handleCustomMethod;
+    /**
+     * 推送 notifications/message 到 session 的所有 SSE 订阅者
+     *
+     * - 无 session 或无订阅者:静默丢弃
+     * - level 低于 session.loggingLevel:静默丢弃
+     * - SSE 行格式:`data: ${JSON.stringify(notification)}\n\n`
+     */
+    sendLogging(sessionId: string, level: LoggingLevel, data: unknown, logger?: string): void;
+    /**
+     * 推送 notifications/resources/updated 到所有订阅了该 URI 的 session
+     *
+     * - 找出所有 subscribedResources 包含该 URI 的 session
+     * - 对每个 session 的所有 SSE 订阅者推送通知
+     * - 无订阅者的 session 静默跳过
+     */
+    sendResourceUpdated(uri: string): void;
+    /**
+     * 推送 notifications/progress 到 session 的所有 SSE 订阅者
+     *
+     * - 无 session 或无订阅者:静默丢弃
+     * - progressToken 为 undefined/null:静默丢弃(无法关联进度与请求)
+     *
+     * @param sessionId 会话 ID
+     * @param progressToken 客户端在请求 _meta.progressToken 中传入的 token(任意 JSON 值)
+     * @param progress 当前进度(数值)
+     * @param total 总数(可选)
+     */
+    sendProgress(sessionId: string, progressToken: unknown, progress: number, total?: number): void;
+    /**
+     * 通用通知推送(业务拓展)——向指定 session 的所有 SSE 订阅者推送任意通知
+     *
+     * - 无 session 或无订阅者:静默丢弃
+     * - 不校验 method 是否符合 MCP 规范——业务方自行负责
+     * - SSE 行格式:`data: ${JSON.stringify(notification)}\n\n`
+     *
+     * @param sessionId 目标 session ID
+     * @param method 通知方法名(如 `notifications/myapp/sync`)
+     * @param params 通知参数(可选)
+     */
+    sendNotification(sessionId: string, method: string, params?: unknown): void;
+}
+declare function createMcpServer(options: McpServerOptions): McpServer;
+
+/**
+ * Streamable HTTP transport：Web Request → JSON-RPC → Response
+ *
+ * MCP Streamable HTTP transport 规范：
+ * - POST：发送 JSON-RPC 消息，返回 JSON 响应或 SSE 流
+ * - GET：打开 SSE 流接收服务端推送
+ * - DELETE：终止会话
+ *
+ * 会话管理通过 Mcp-Session-Id header。
+ * 实现：POST 返回 JSON,GET 返回 SSE 流(仅心跳,不推送业务消息),DELETE 销毁会话。
+ */
+
+/**
+ * 处理 MCP HTTP 请求
+ *
+ * 接收 Web API Request，返回 Web API Response。
+ * 可直接在 faapi handler 中使用：
+ * ```ts
+ * export function POST(ctx) {
+ *   return mcp.handleWebRequest(ctx.request);
+ * }
+ * ```
+ */
+declare function handleMcpRequest(request: Request, server: McpServer): Promise<Response>;
+
+/**
+ * faapi 适配器：把 MCP Server 挂载到 faapi 路由
+ *
+ * 两种集成方式：
+ *
+ * 1. handler 风格（推荐）——在 handler.ts 中使用：
+ *    ```ts
+ *    // api/mcp/handler.ts
+ *    import { createMcpServer, createMcpHandler } from '@faapi/mcp';
+ *    const mcp = createMcpServer({ name: 'my-app', version: '1.0.0' });
+ *    mcp.tool('hello', { ... });
+ *    export const { POST, GET, DELETE } = createMcpHandler(mcp);
+ *    ```
+ *
+ * 2. 插件风格——在 faapi.config.ts 中声明：
+ *    ```ts
+ *    plugins: [['@faapi/mcp', { path: '/mcp' }]]
+ *    ```
+ *    需配合 mcp.tool() 注册（通常在 lifecycle.onReady 中）。
+ *
+ * 函数即接口：MCP endpoint 就是 faapi 的一个路由。
+ */
+
+/**
+ * 创建 faapi handler 函数
+ *
+ * 返回 { POST, GET, DELETE }，可直接在 handler.ts 中导出。
+ * faapi 按参数名注入 ctx，函数内通过 ctx.request 获取 Web Request。
+ */
+declare function createMcpHandler(mcp: McpServer): {
+    POST: (ctx: {
+        request: Request;
+    }) => Promise<Response>;
+    GET: (ctx: {
+        request: Request;
+    }) => Promise<Response>;
+    DELETE: (ctx: {
+        request: Request;
+    }) => Promise<Response>;
+};
+/**
+ * 创建 Node.js 请求处理函数（供 wrapHandler 使用）
+ *
+ * 用于 faapi 插件场景：插件通过 wrapHandler 拦截指定路径，
+ * 将 Node.js IncomingMessage/ServerResponse 转为 Web Request 处理。
+ *
+ * 使用 Node.js 原生 `Readable.toWeb(req)` 转换 body,正确处理 chunked transfer
+ * (多 chunk 累积)、backpressure 和 stream error。
+ */
+declare function createMcpNodeHandler(mcp: McpServer): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+
+export { type CompletionContext, type CompletionHandler, type CompletionRef, type CompletionResult, ErrorCode, type JsonRpcError, type JsonRpcErrorResponse, type JsonRpcMessage, type JsonRpcNotification, JsonRpcParseError, type JsonRpcRequest, type JsonRpcResultResponse, type LoggingLevel, type McpPromptArgument, type McpPromptContent, type McpPromptDefinition, type McpPromptGetResult, type McpPromptMessage, type McpResourceContent, type McpResourceDefinition, type McpResourceReadResult, type McpResourceTemplateDefinition, McpServer, type McpServerOptions, type McpSession, type McpToolDefinition, type McpToolResult, type MethodHandler, type MethodHandlerResult, PROTOCOL_VERSION, type PromptGetExtra, type RequestExtra, type ResourceReadExtra, type ResourceTemplateReadExtra, SUPPORTED_PROTOCOL_VERSIONS, type SendLoggingFn, type SendProgressFn, SessionManager, type SseSubscriber, type ToolCallExtra, createErrorResponse, createMcpHandler, createMcpNodeHandler, createMcpServer, createResultResponse, handleMcpRequest, isErrorResponse, isNotification, isRequest, isResultResponse, parseJsonRpcMessage };