open-mcp-app 0.0.13 → 0.0.15

package/dist/server/index.d.ts

@@ -1,5 +1,6 @@
-import { z } from 'zod';
 import * as express from 'express';
+import express__default from 'express';
+import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { CreateMessageRequestParams, CreateMessageResult, CreateMessageResultWithTools } from '@modelcontextprotocol/sdk/types.js';
 
@@ -320,6 +321,35 @@ interface TransportSessionInfo {
     /** The transport type for this session */
     transport: TransportType;
 }
+type ServerlessTransportMode = "stateful" | "stateless";
+interface StateAdapter {
+    get: (instanceId: string) => Promise<unknown | undefined>;
+    set: (instanceId: string, state: unknown) => Promise<void>;
+    delete: (instanceId: string) => Promise<void>;
+}
+interface ServerlessAdapterOptions {
+    /**
+     * Controls whether MCP transport sessions are persisted between requests.
+     *
+     * - `"stateful"` keeps normal MCP session semantics and expects sticky routing.
+     * - `"stateless"` disables MCP transport session IDs so each request stands alone.
+     *
+     * For AWS Lambda and other serverless deployments, `"stateless"` is usually the
+     * safest default because requests may land on different warm instances.
+     */
+    transportMode?: ServerlessTransportMode;
+    /**
+     * Enables JSON POST responses for stateless streamable-http mode.
+     * This avoids relying on SSE session continuity in serverless environments.
+     */
+    enableJsonResponse?: boolean;
+    /**
+     * Optional backing store for `context.getState()` / `context.setState()`.
+     * This is only needed for tools that rely on server-side state across requests.
+     */
+    stateAdapter?: StateAdapter;
+}
+type AwsLambdaHandler = (...args: unknown[]) => Promise<unknown>;
 /**
  * App configuration.
  */
@@ -614,12 +644,26 @@ declare class App {
      * Get all resource definitions.
      */
     getResourceDefinitions(): Map<string, ResourceDefinition>;
+    /**
+     * Get the Express application for serverless wrapping (e.g. Lambda).
+     * Does NOT start listening on a port.
+     */
+    toExpressApp(options?: ServerlessAdapterOptions): express__default.Express;
+    toAwsLambda(options?: ServerlessAdapterOptions): AwsLambdaHandler;
     /**
      * Close a specific transport session.
      */
     closeTransportSession(sessionId: string): boolean;
     private getPort;
     private getCallerDir;
+    private lambdaEventToRequest;
+    private handleLambdaHttpRequest;
+    private writeLambdaResponse;
+    private isStatelessTransport;
+    private getStateAdapter;
+    private loadInstanceState;
+    private persistInstanceState;
+    private deleteInstanceState;
     /**
      * Handle an MCP JSON-RPC request directly.
      * Used for testing without starting a server.
@@ -786,6 +830,26 @@ declare function htmlLoader(htmlOrPath: string, basePath?: string): () => string
  */
 declare function wrapServer<T extends McpServer>(server: T): T;
 
+/**
+ * Storage RPC Client
+ *
+ * Provides storage operations via RPC to the Creature host.
+ * Used by experimental.ts to route KV and blob operations through the host
+ * instead of direct file I/O, ensuring consistent behavior for both local
+ * and hosted MCPs.
+ */
+
+interface KvSearchResult {
+    key: string;
+    snippet?: string;
+    score?: number;
+}
+interface VectorSearchResult {
+    key: string;
+    score: number;
+    metadata?: unknown;
+}
+
 /**
  * Experimental Server APIs
  *
@@ -801,7 +865,7 @@ declare function wrapServer<T extends McpServer>(server: T): T;
  * import { exp } from "open-mcp-app/server";
  *
  * const dir = exp.getWritableDirectory();
- * const content = await exp.readFile("state.json");
+ * await exp.kvSet("key", "value");
  * ```
  */
 
@@ -1032,6 +1096,348 @@ declare function experimental_rmdir(relativePath: string): Promise<void>;
  * @throws Error if storage unavailable or path escapes sandbox
  */
 declare function experimental_rmdirSync(relativePath: string): void;
+
+/**
+ * Check if KV storage is available.
+ *
+ * Returns true if running inside Creature with storage enabled.
+ * Use this to implement graceful fallbacks.
+ *
+ * @returns true if KV storage is available
+ *
+ * @example
+ * ```typescript
+ * import { experimental_kvIsAvailable } from "open-mcp-app/server";
+ *
+ * if (experimental_kvIsAvailable()) {
+ *   // Use persistent KV storage
+ * } else {
+ *   // Fall back to in-memory storage
+ * }
+ * ```
+ */
+declare function experimental_kvIsAvailable(): boolean;
+/**
+ * Get a value from the KV store.
+ *
+ * Uses RPC to communicate with the Creature host for storage operations.
+ * This ensures consistent behavior for both local and hosted MCPs.
+ *
+ * @param key - The key to retrieve
+ * @returns The value, or null if not found or storage unavailable
+ *
+ * @example
+ * ```typescript
+ * import { experimental_kvGet } from "open-mcp-app/server";
+ *
+ * const value = await experimental_kvGet("user:preferences");
+ * if (value) {
+ *   const prefs = JSON.parse(value);
+ * }
+ * ```
+ */
+declare function experimental_kvGet(key: string): Promise<string | null>;
+/**
+ * Get a value from the KV store synchronously.
+ *
+ * Note: Sync variants are not supported with RPC and will return null.
+ * Use the async version for reliable cross-platform behavior.
+ *
+ * @param key - The key to retrieve
+ * @returns The value, or null if not found or storage unavailable
+ * @deprecated Use experimental_kvGet instead for cross-platform support
+ */
+declare function experimental_kvGetSync(key: string): string | null;
+/**
+ * Set a value in the KV store.
+ *
+ * Uses RPC to communicate with the Creature host for storage operations.
+ * This ensures consistent behavior for both local and hosted MCPs.
+ *
+ * @param key - The key to set
+ * @param value - The value to store (string)
+ * @returns true if successful, false if storage unavailable
+ *
+ * @example
+ * ```typescript
+ * import { experimental_kvSet } from "open-mcp-app/server";
+ *
+ * await experimental_kvSet("user:preferences", JSON.stringify(prefs));
+ * ```
+ */
+declare function experimental_kvSet(key: string, value: string): Promise<boolean>;
+/**
+ * Set a value in the KV store synchronously.
+ *
+ * Note: Sync variants are not supported with RPC and will return false.
+ * Use the async version for reliable cross-platform behavior.
+ *
+ * @param key - The key to set
+ * @param value - The value to store (string)
+ * @returns true if successful, false if storage unavailable
+ * @deprecated Use experimental_kvSet instead for cross-platform support
+ */
+declare function experimental_kvSetSync(key: string, value: string): boolean;
+/**
+ * Delete a key from the KV store.
+ *
+ * Uses RPC to communicate with the Creature host for storage operations.
+ * This ensures consistent behavior for both local and hosted MCPs.
+ *
+ * @param key - The key to delete
+ * @returns true if the key existed and was deleted, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { experimental_kvDelete } from "open-mcp-app/server";
+ *
+ * const deleted = await experimental_kvDelete("user:preferences");
+ * ```
+ */
+declare function experimental_kvDelete(key: string): Promise<boolean>;
+/**
+ * Delete a key from the KV store synchronously.
+ *
+ * Note: Sync variants are not supported with RPC and will return false.
+ * Use the async version for reliable cross-platform behavior.
+ *
+ * @param key - The key to delete
+ * @returns true if the key existed and was deleted, false otherwise
+ * @deprecated Use experimental_kvDelete instead for cross-platform support
+ */
+declare function experimental_kvDeleteSync(key: string): boolean;
+/**
+ * List keys in the KV store.
+ *
+ * Uses RPC to communicate with the Creature host for storage operations.
+ * This ensures consistent behavior for both local and hosted MCPs.
+ *
+ * @param prefix - Optional prefix to filter keys
+ * @returns Array of matching keys, or null if storage unavailable
+ *
+ * @example
+ * ```typescript
+ * import { experimental_kvList } from "open-mcp-app/server";
+ *
+ * const userKeys = await experimental_kvList("user:");
+ * ```
+ */
+declare function experimental_kvList(prefix?: string): Promise<string[] | null>;
+/**
+ * List key-value pairs from the KV store.
+ *
+ * This is more efficient than calling kvList + kvGet for each key,
+ * as it fetches all data in a single RPC call.
+ *
+ * @param prefix - Optional prefix to filter keys
+ * @returns Array of key-value pairs, or null if storage unavailable
+ *
+ * @example
+ * ```typescript
+ * import { exp } from "open-mcp-app/server";
+ *
+ * const entries = await exp.kvListWithValues("todos:");
+ * for (const { key, value } of entries ?? []) {
+ *   console.log(key, JSON.parse(value));
+ * }
+ * ```
+ */
+declare function experimental_kvListWithValues(prefix?: string): Promise<Array<{
+    key: string;
+    value: string;
+}> | null>;
+/**
+ * List keys in the KV store synchronously.
+ *
+ * Note: Sync variants are not supported with RPC and will return null.
+ * Use the async version for reliable cross-platform behavior.
+ *
+ * @param prefix - Optional prefix to filter keys
+ * @returns Array of matching keys, or null if storage unavailable
+ * @deprecated Use experimental_kvList instead for cross-platform support
+ */
+declare function experimental_kvListSync(prefix?: string): string[] | null;
+/**
+ * Search values in the KV store using full-text search.
+ *
+ * Uses SQLite FTS5 on the Creature host for efficient full-text search.
+ * Returns results ranked by relevance with optional snippets.
+ *
+ * @param query - The search query (uses SQLite FTS5 syntax)
+ * @param options - Search options
+ * @param options.prefix - Optional key prefix to filter results
+ * @param options.limit - Maximum number of results (default 50, max 100)
+ * @returns Array of search results, or null if storage unavailable
+ *
+ * @example
+ * ```typescript
+ * import { experimental_kvSearch } from "open-mcp-app/server";
+ *
+ * // Search for notes containing "meeting"
+ * const results = await experimental_kvSearch("meeting");
+ *
+ * // Search with prefix filter
+ * const todoResults = await experimental_kvSearch("urgent", { prefix: "todos:" });
+ *
+ * for (const result of results ?? []) {
+ *   console.log(result.key, result.snippet, result.score);
+ * }
+ * ```
+ */
+declare function experimental_kvSearch(query: string, options?: {
+    prefix?: string;
+    limit?: number;
+}): Promise<KvSearchResult[] | null>;
+declare function experimental_vectorIsAvailable(): boolean;
+declare function experimental_vectorUpsert(key: string, text: string, metadata?: unknown): Promise<boolean>;
+declare function experimental_vectorSearch(query: string, options?: {
+    prefix?: string;
+    limit?: number;
+}): Promise<VectorSearchResult[] | null>;
+declare function experimental_vectorDelete(key: string): Promise<boolean>;
+
+/**
+ * Check if blob storage is available.
+ *
+ * Returns true if running inside Creature with storage enabled.
+ * Use this to implement graceful fallbacks.
+ *
+ * @returns true if blob storage is available
+ */
+declare function experimental_blobIsAvailable(): boolean;
+/**
+ * Store a blob.
+ *
+ * Uses RPC to communicate with the Creature host for storage operations.
+ * This ensures consistent behavior for both local and hosted MCPs.
+ *
+ * @param name - The blob name (acts as a path within the blobs directory)
+ * @param data - The blob data as a Buffer or Uint8Array
+ * @param mimeType - Optional MIME type metadata
+ * @returns Object with success and size, or null if storage unavailable
+ *
+ * @example
+ * ```typescript
+ * import { experimental_blobPut } from "open-mcp-app/server";
+ *
+ * const imageData = fs.readFileSync("image.png");
+ * await experimental_blobPut("images/photo.png", imageData, "image/png");
+ * ```
+ */
+declare function experimental_blobPut(name: string, data: Buffer | Uint8Array, mimeType?: string): Promise<{
+    success: true;
+    size: number;
+} | null>;
+/**
+ * Store a blob synchronously.
+ *
+ * Note: Sync variants are not supported with RPC and will return null.
+ * Use the async version for reliable cross-platform behavior.
+ *
+ * @param name - The blob name
+ * @param data - The blob data
+ * @param mimeType - Optional MIME type metadata
+ * @returns Object with success and size, or null if storage unavailable
+ * @deprecated Use experimental_blobPut instead for cross-platform support
+ */
+declare function experimental_blobPutSync(name: string, data: Buffer | Uint8Array, mimeType?: string): {
+    success: true;
+    size: number;
+} | null;
+/**
+ * Retrieve a blob.
+ *
+ * Uses RPC to communicate with the Creature host for storage operations.
+ * This ensures consistent behavior for both local and hosted MCPs.
+ *
+ * @param name - The blob name
+ * @returns Object with data and optional mimeType, or null if not found
+ *
+ * @example
+ * ```typescript
+ * import { experimental_blobGet } from "open-mcp-app/server";
+ *
+ * const result = await experimental_blobGet("images/photo.png");
+ * if (result) {
+ *   // result.data is a Buffer
+ *   // result.mimeType is optional string
+ * }
+ * ```
+ */
+declare function experimental_blobGet(name: string): Promise<{
+    data: Buffer;
+    mimeType?: string;
+} | null>;
+/**
+ * Retrieve a blob synchronously.
+ *
+ * Note: Sync variants are not supported with RPC and will return null.
+ * Use the async version for reliable cross-platform behavior.
+ *
+ * @param name - The blob name
+ * @returns Object with data and optional mimeType, or null if not found
+ * @deprecated Use experimental_blobGet instead for cross-platform support
+ */
+declare function experimental_blobGetSync(name: string): {
+    data: Buffer;
+    mimeType?: string;
+} | null;
+/**
+ * Delete a blob.
+ *
+ * Uses RPC to communicate with the Creature host for storage operations.
+ * This ensures consistent behavior for both local and hosted MCPs.
+ *
+ * @param name - The blob name
+ * @returns true if deleted, false if not found or storage unavailable
+ *
+ * @example
+ * ```typescript
+ * import { experimental_blobDelete } from "open-mcp-app/server";
+ *
+ * await experimental_blobDelete("images/old-photo.png");
+ * ```
+ */
+declare function experimental_blobDelete(name: string): Promise<boolean>;
+/**
+ * Delete a blob synchronously.
+ *
+ * Note: Sync variants are not supported with RPC and will return false.
+ * Use the async version for reliable cross-platform behavior.
+ *
+ * @param name - The blob name
+ * @returns true if deleted, false if not found or storage unavailable
+ * @deprecated Use experimental_blobDelete instead for cross-platform support
+ */
+declare function experimental_blobDeleteSync(name: string): boolean;
+/**
+ * List blobs.
+ *
+ * Uses RPC to communicate with the Creature host for storage operations.
+ * This ensures consistent behavior for both local and hosted MCPs.
+ *
+ * @param prefix - Optional prefix to filter blob names
+ * @returns Array of blob names, or null if storage unavailable
+ *
+ * @example
+ * ```typescript
+ * import { experimental_blobList } from "open-mcp-app/server";
+ *
+ * const images = await experimental_blobList("images/");
+ * ```
+ */
+declare function experimental_blobList(prefix?: string): Promise<string[] | null>;
+/**
+ * List blobs synchronously.
+ *
+ * Note: Sync variants are not supported with RPC and will return null.
+ * Use the async version for reliable cross-platform behavior.
+ *
+ * @param prefix - Optional prefix to filter blob names
+ * @returns Array of blob names, or null if storage unavailable
+ * @deprecated Use experimental_blobList instead for cross-platform support
+ */
+declare function experimental_blobListSync(prefix?: string): string[] | null;
 declare function experimental_sampleMessage(params: CreateMessageRequestParams): Promise<CreateMessageResult | CreateMessageResultWithTools>;
 /**
  * Experimental APIs namespace.
@@ -1044,7 +1450,13 @@ declare function experimental_sampleMessage(params: CreateMessageRequestParams):
  * import { exp } from "open-mcp-app/server";
  *
  * // Environment
- * const dir = exp.getWritableDirectory();
+ * if (exp.isCreatureHost()) {
+ *   const dir = exp.getWritableDirectory();
+ * }
+ *
+ * // KV Store
+ * await exp.kvSet("user:prefs", JSON.stringify(prefs));
+ * const value = await exp.kvGet("user:prefs");
  *
  * // File I/O
  * await exp.writeFile("config.json", JSON.stringify(config));
@@ -1069,7 +1481,39 @@ declare const exp: {
     mkdirSync: typeof experimental_mkdirSync;
     readdirSync: typeof experimental_readdirSync;
     rmdirSync: typeof experimental_rmdirSync;
+    kvIsAvailable: typeof experimental_kvIsAvailable;
+    kvGet: typeof experimental_kvGet;
+    kvSet: typeof experimental_kvSet;
+    kvDelete: typeof experimental_kvDelete;
+    kvList: typeof experimental_kvList;
+    kvListWithValues: typeof experimental_kvListWithValues;
+    kvSearch: typeof experimental_kvSearch;
+    vectorIsAvailable: typeof experimental_vectorIsAvailable;
+    vectorUpsert: typeof experimental_vectorUpsert;
+    vectorSearch: typeof experimental_vectorSearch;
+    vectorDelete: typeof experimental_vectorDelete;
+    /** @deprecated Use kvGet instead */
+    kvGetSync: typeof experimental_kvGetSync;
+    /** @deprecated Use kvSet instead */
+    kvSetSync: typeof experimental_kvSetSync;
+    /** @deprecated Use kvDelete instead */
+    kvDeleteSync: typeof experimental_kvDeleteSync;
+    /** @deprecated Use kvList instead */
+    kvListSync: typeof experimental_kvListSync;
+    blobIsAvailable: typeof experimental_blobIsAvailable;
+    blobPut: typeof experimental_blobPut;
+    blobGet: typeof experimental_blobGet;
+    blobDelete: typeof experimental_blobDelete;
+    blobList: typeof experimental_blobList;
+    /** @deprecated Use blobPut instead */
+    blobPutSync: typeof experimental_blobPutSync;
+    /** @deprecated Use blobGet instead */
+    blobGetSync: typeof experimental_blobGetSync;
+    /** @deprecated Use blobDelete instead */
+    blobDeleteSync: typeof experimental_blobDeleteSync;
+    /** @deprecated Use blobList instead */
+    blobListSync: typeof experimental_blobListSync;
     sampleMessage: typeof experimental_sampleMessage;
 };
 
-export { App, type AppConfig, type DisplayMode, type IconConfig, type InstanceDestroyContext, MIME_TYPES, type ResourceConfig, type ServerLogLevel, type ServerLogger, type ToolAnnotations, type ToolCallInfo, type ToolCallResultInfo, type ToolConfig, type ToolContext, type ToolHandler, type ToolResult, type ToolVisibility, type TransportSessionInfo, type TransportType, type WebSocketConnection, createApp, exp, experimental_deleteFile, experimental_deleteFileSync, experimental_exists, experimental_existsSync, experimental_getProjectId, experimental_getServerName, experimental_getWritableDirectory, experimental_mkdir, experimental_mkdirSync, experimental_readFile, experimental_readFileSync, experimental_readdir, experimental_readdirSync, experimental_rmdir, experimental_rmdirSync, experimental_sampleMessage, experimental_writeFile, experimental_writeFileSync, htmlLoader, isHtmlContent, loadHtml, svgToDataUri, wrapServer };
+export { App, type AppConfig, type AwsLambdaHandler, type DisplayMode, type IconConfig, type InstanceDestroyContext, type KvSearchResult, MIME_TYPES, type ResourceConfig, type ServerLogLevel, type ServerLogger, type ServerlessAdapterOptions, type ServerlessTransportMode, type StateAdapter, type ToolAnnotations, type ToolCallInfo, type ToolCallResultInfo, type ToolConfig, type ToolContext, type ToolHandler, type ToolResult, type ToolVisibility, type TransportSessionInfo, type TransportType, type VectorSearchResult, type WebSocketConnection, createApp, exp, experimental_blobDelete, experimental_blobDeleteSync, experimental_blobGet, experimental_blobGetSync, experimental_blobIsAvailable, experimental_blobList, experimental_blobListSync, experimental_blobPut, experimental_blobPutSync, experimental_deleteFile, experimental_deleteFileSync, experimental_exists, experimental_existsSync, experimental_getProjectId, experimental_getServerName, experimental_getWritableDirectory, experimental_kvDelete, experimental_kvDeleteSync, experimental_kvGet, experimental_kvGetSync, experimental_kvIsAvailable, experimental_kvList, experimental_kvListSync, experimental_kvSearch, experimental_kvSet, experimental_kvSetSync, experimental_mkdir, experimental_mkdirSync, experimental_readFile, experimental_readFileSync, experimental_readdir, experimental_readdirSync, experimental_rmdir, experimental_rmdirSync, experimental_sampleMessage, experimental_vectorDelete, experimental_vectorIsAvailable, experimental_vectorSearch, experimental_vectorUpsert, experimental_writeFile, experimental_writeFileSync, htmlLoader, isHtmlContent, loadHtml, svgToDataUri, wrapServer };