@cloudbase/cloudbase-mcp 2.34.8 → 2.35.2

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import CloudBase from '@cloudbase/manager-node';
+import type { IncomingMessage } from 'node:http';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServerResponse } from 'node:http';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { ToolAnnotations as ToolAnnotations_2 } from '@modelcontextprotocol/sdk/types.js';
@@ -72,6 +74,20 @@ export declare type CloudBaseRegisterToolConfig = {
     _meta?: Record<string, unknown>;
 };
 
+export declare type CloudBaseServerOptions = {
+    name?: string;
+    version?: string;
+    enableTelemetry?: boolean;
+    cloudBaseOptions?: HostedCloudBaseOptions;
+    cloudMode?: boolean;
+    ide?: string;
+    client?: string;
+    clientInfo?: HostedClientInfoRecord;
+    lang?: string;
+    pluginsEnabled?: string[];
+    pluginsDisabled?: string[];
+};
+
 /**
  * Create a manager with the provided CloudBase options, without using cache
  * @param cloudBaseOptions Provided CloudBase options
@@ -108,6 +124,14 @@ export declare function createCloudBaseMcpServer(options?: {
     cloudMode?: boolean;
     ide?: string;
     client?: string;
+    /**
+     * Client name/version to report when the MCP handshake clientInfo is empty.
+     * Metadata only. Hosted requests pass the value remembered for this credential.
+     */
+    clientInfo?: {
+        name: string;
+        version?: string;
+    };
     logger?: Logger;
     pluginsEnabled?: string[];
     pluginsDisabled?: string[];
@@ -210,6 +234,14 @@ export declare interface ExtendedMcpServer extends McpServer {
     ide?: string;
     /** MCP client 来源标识（hosted 场景由上游解析注入，如 cursor / claude-code） */
     client?: string;
+    /**
+     * Metadata-only client identity used when this request has no handshake.
+     * `{ name, version }` only. Not a protocol object.
+     */
+    clientInfo?: {
+        name: string;
+        version?: string;
+    };
     logger?: Logger;
     enabledPlugins?: string[];
     pluginOptions?: PluginOptions;
@@ -297,6 +329,59 @@ declare interface GetManagerOptions {
     authStrategy?: 'fail_fast' | 'ensure';
 }
 
+/**
+ * One stateless JSON MCP request: a new server and SDK 1.30 transport, then close both.
+ * Protocol versions are not rewritten. SDK 1.30 accepts `2025-11-25`. Later or
+ * malformed `mcp-protocol-version` headers are passed through and rejected by the transport.
+ */
+export declare function handleHostedMcpRequest(input: HostedMcpRequestInput): Promise<void>;
+
+/**
+ * Bounded memory of MCP client name/version, keyed by a credential hash.
+ *
+ * Process-level mutable state: one Map. Each value is `{ name, version, writtenAt }`.
+ * The map does not store servers, transports, or raw credentials.
+ */
+export declare const HOSTED_CLIENT_INFO_CACHE_CAPACITY = 256;
+
+export declare const HOSTED_CLIENT_INFO_CACHE_TTL_MS: number;
+
+export declare type HostedClientInfoRecord = {
+    name: string;
+    version?: string;
+};
+
+/**
+ * Plain options for a hosted request. No SDK types, so a TypeScript 4.9 host
+ * can pass this object without compiling against the MCP SDK.
+ */
+export declare type HostedCloudBaseOptions = {
+    envId?: string;
+    secretId?: string;
+    secretKey?: string;
+    token?: string;
+    useInternalEndpoint?: boolean;
+    region?: string;
+    site?: string;
+    credentialScope?: "env" | "account";
+    uin?: string;
+};
+
+export declare type HostedMcpLogEvent = {
+    type: string;
+    message?: string;
+    timeCost?: number;
+};
+
+export declare type HostedMcpRequestInput = {
+    req: IncomingMessage;
+    res: ServerResponse;
+    body: unknown;
+    serverOptions: CloudBaseServerOptions;
+    clientInfoHint?: HostedClientInfoRecord;
+    logger?: (event: HostedMcpLogEvent) => void;
+};
+
 declare interface IdeFileDescriptor {
     path: string;
     isMcpConfig?: boolean;
@@ -400,15 +485,33 @@ declare interface LoginState {
     /**
      * 主账号 uin。本地凭证（`~/.config/.cloudbase/auth.json`）自带，
      * 由 `@cloudbase/toolbox` 的 `resolveCredential()` 透传。
-     * 注意：临时密钥续期响应里没有 uin，须由调用方保留旧值（见 resolveSiteLoginState）。
+     * 注意：临时密钥续期响应里没有 uin，须由调用方保留旧值（见 resolveFlatLoginState）。
      */
     uin?: string | number;
 }
 
-export declare function logout(options?: {
+export declare function logout(_options?: {
     site?: string;
 }): Promise<void>;
 
+/**
+ * 归一化后的客户端能力（字段名保持语义，报表侧再映射到列）。
+ * `undefined` = 握手未完成，与「握手完成但什么都没声明」必须分开：
+ * 后者是客户端事实，前者只是我们还没拿到。
+ */
+declare type McpClientCapabilities = {
+    /** 表单模式 elicitation（客户端声明 `elicitation:{}` 或 `elicitation.form`） */
+    elicitationForm: boolean;
+    /** URL 模式 elicitation（凭据跳转用；本期不做，只记录） */
+    elicitationUrl: boolean;
+    /** 声明了 MCP Apps 扩展 */
+    ui: boolean;
+    roots: boolean;
+    sampling: boolean;
+    /** 报表友好摘要：`none` 或稳定排序的逗号串（elicitation:form / elicitation:url / ui / roots / sampling） */
+    summary: string;
+};
+
 /** MCP initialize clientInfo fields available after handshake via Server.getClientVersion(). */
 declare type McpClientInfo = {
     name?: string;
@@ -488,6 +591,7 @@ export declare const reportToolCall: (params: {
     ide?: string;
     client?: string;
     mcpClientInfo?: McpClientInfo;
+    mcpClientCapabilities?: McpClientCapabilities;
 }) => Promise<void>;
 
 export declare const reportToolkitLifecycle: (params: {
@@ -673,6 +777,12 @@ export declare interface UploadFileParams {
 
 export declare function validateTimerCron(config: string): string;
 
+/**
+ * Startup warmup for a hosted process: finish the resource download and build
+ * the skill index before the first request pays for it.
+ */
+export declare function warmupHostedResources(): Promise<void>;
+
 export declare const warn: (message: string, data?: object | Error) => void;
 
 export { }