@phake/mcp 0.0.1

package/dist/shared/utils/elicitation.d.ts

@@ -0,0 +1,247 @@
+/**
+ * Elicitation utilities for servers to request user input from clients.
+ *
+ * ⚠️ NODE.JS ONLY - These utilities require SDK bidirectional support
+ * (server.request()) which is not available in the Cloudflare Workers runtime.
+ * The Workers dispatcher does not support server→client requests.
+ *
+ * Two modes:
+ * - Form: Structured input via a schema (text fields, checkboxes, dropdowns)
+ * - URL: Redirect user to external URL for out-of-band interaction
+ *
+ * Per MCP spec:
+ * - Elicitation is a CLIENT capability
+ * - Servers send elicitation/create requests TO clients
+ * - Clients display the form/URL and return user response
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+/** Boolean field schema */
+export interface BooleanFieldSchema {
+    type: "boolean";
+    title?: string;
+    description?: string;
+    default?: boolean;
+}
+/** String field schema */
+export interface StringFieldSchema {
+    type: "string";
+    title?: string;
+    description?: string;
+    minLength?: number;
+    maxLength?: number;
+    format?: "email" | "uri" | "date" | "date-time";
+    default?: string;
+}
+/** Number field schema */
+export interface NumberFieldSchema {
+    type: "number" | "integer";
+    title?: string;
+    description?: string;
+    minimum?: number;
+    maximum?: number;
+    default?: number;
+}
+/** Single-select enum with titles (preferred) */
+export interface TitledEnumFieldSchema {
+    type: "string";
+    title?: string;
+    description?: string;
+    oneOf: Array<{
+        const: string;
+        title: string;
+    }>;
+    default?: string;
+}
+/** Single-select enum without titles */
+export interface UntitledEnumFieldSchema {
+    type: "string";
+    title?: string;
+    description?: string;
+    enum: string[];
+    default?: string;
+}
+/** Multi-select enum */
+export interface MultiSelectFieldSchema {
+    type: "array";
+    title?: string;
+    description?: string;
+    minItems?: number;
+    maxItems?: number;
+    items: {
+        type: "string";
+        enum: string[];
+    } | {
+        anyOf: Array<{
+            const: string;
+            title: string;
+        }>;
+    };
+    default?: string[];
+}
+/** All supported field schema types */
+export type FieldSchema = BooleanFieldSchema | StringFieldSchema | NumberFieldSchema | TitledEnumFieldSchema | UntitledEnumFieldSchema | MultiSelectFieldSchema;
+/** Schema for form elicitation (flat object with primitive fields only) */
+export interface ElicitationSchema {
+    type: "object";
+    properties: Record<string, FieldSchema>;
+    required?: string[];
+}
+/** Form elicitation request */
+export interface FormElicitationRequest {
+    mode?: "form";
+    message: string;
+    requestedSchema: ElicitationSchema;
+}
+/** URL elicitation request */
+export interface UrlElicitationRequest {
+    mode: "url";
+    message: string;
+    elicitationId: string;
+    url: string;
+}
+export type ElicitationRequest = FormElicitationRequest | UrlElicitationRequest;
+/** User's response to elicitation */
+export interface ElicitResult {
+    action: "accept" | "decline" | "cancel";
+    content?: Record<string, string | number | boolean | string[]>;
+}
+export declare const ElicitResultSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        cancel: "cancel";
+        accept: "accept";
+        decline: "decline";
+    }>;
+    content: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
+}, z.core.$strip>;
+/**
+ * Validate that elicitation schema is flat (no nested objects/arrays of objects).
+ * Per MCP spec: requestedSchema must have type: 'object' at root with only
+ * primitive properties (no nesting).
+ *
+ * @throws Error if schema contains nested objects or invalid structure
+ */
+export declare function validateElicitationSchema(schema: ElicitationSchema): void;
+/**
+ * Check if client supports form elicitation.
+ */
+export declare function clientSupportsFormElicitation(server: McpServer): boolean;
+/**
+ * Check if client supports URL elicitation.
+ */
+export declare function clientSupportsUrlElicitation(server: McpServer): boolean;
+/**
+ * Request user input via form elicitation.
+ *
+ * @example
+ * ```typescript
+ * const result = await elicitForm(server, {
+ *   message: 'Configure your preferences:',
+ *   requestedSchema: {
+ *     type: 'object',
+ *     properties: {
+ *       apiKey: { type: 'string', title: 'API Key' },
+ *       enabled: { type: 'boolean', title: 'Enable feature', default: true },
+ *       theme: {
+ *         type: 'string',
+ *         title: 'Theme',
+ *         oneOf: [
+ *           { const: 'light', title: 'Light' },
+ *           { const: 'dark', title: 'Dark' }
+ *         ]
+ *       }
+ *     },
+ *     required: ['apiKey']
+ *   }
+ * });
+ *
+ * if (result.action === 'accept') {
+ *   console.log('API Key:', result.content?.apiKey);
+ * }
+ * ```
+ */
+export declare function elicitForm(server: McpServer, request: FormElicitationRequest): Promise<ElicitResult>;
+/**
+ * Request user interaction via URL elicitation.
+ *
+ * @example
+ * ```typescript
+ * const elicitationId = crypto.randomUUID();
+ *
+ * const result = await elicitUrl(server, {
+ *   message: 'Please complete authentication:',
+ *   elicitationId,
+ *   url: 'https://auth.example.com/oauth/authorize?state=xyz'
+ * });
+ *
+ * // After external callback completes:
+ * await notifyElicitationComplete(server, elicitationId);
+ * ```
+ */
+export declare function elicitUrl(server: McpServer, request: Omit<UrlElicitationRequest, "mode">): Promise<ElicitResult>;
+/**
+ * Notify client that URL elicitation has completed (external flow finished).
+ */
+export declare function notifyElicitationComplete(server: McpServer, elicitationId: string): Promise<void>;
+/**
+ * Request a simple confirmation from the user.
+ *
+ * @example
+ * ```typescript
+ * const confirmed = await confirm(server, 'Delete all items?');
+ * if (confirmed) {
+ *   // proceed with deletion
+ * }
+ * ```
+ */
+export declare function confirm(server: McpServer, message: string, options?: {
+    confirmLabel?: string;
+    declineLabel?: string;
+}): Promise<boolean>;
+/**
+ * Request a single text input from the user.
+ *
+ * @example
+ * ```typescript
+ * const apiKey = await promptText(server, 'Enter your API key:', {
+ *   title: 'API Key',
+ *   required: true
+ * });
+ *
+ * if (apiKey) {
+ *   // use the API key
+ * }
+ * ```
+ */
+export declare function promptText(server: McpServer, message: string, options?: {
+    title?: string;
+    description?: string;
+    defaultValue?: string;
+    required?: boolean;
+    minLength?: number;
+    maxLength?: number;
+}): Promise<string | undefined>;
+/**
+ * Request a selection from a list of options.
+ *
+ * @example
+ * ```typescript
+ * const choice = await promptSelect(server, 'Choose a model:', [
+ *   { value: 'gpt-4', label: 'GPT-4 (Best quality)' },
+ *   { value: 'gpt-3.5', label: 'GPT-3.5 (Faster)' },
+ *   { value: 'claude', label: 'Claude (Alternative)' }
+ * ]);
+ *
+ * if (choice) {
+ *   console.log('Selected:', choice);
+ * }
+ * ```
+ */
+export declare function promptSelect(server: McpServer, message: string, options: Array<{
+    value: string;
+    label: string;
+}>, config?: {
+    title?: string;
+    defaultValue?: string;
+    required?: boolean;
+}): Promise<string | undefined>;

package/dist/shared/utils/formatting.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Message formatting utilities for consistent, LLM-friendly output.
+ *
+ * These utilities help create clear, scannable responses that are optimized
+ * for both LLM understanding and human readability.
+ */
+/**
+ * Summarize a list of items with preview and details sections.
+ *
+ * @param items - Array of items to summarize
+ * @param formatPreview - Function to format a single-line preview of each item
+ * @param options - Formatting options
+ * @returns Formatted summary with preview list and optional details
+ *
+ * @example
+ * const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+ * const summary = summarizeList(users, (u) => `${u.id}. ${u.name}`);
+ * // Returns:
+ * // ## List (2 items)
+ * // 1. Alice
+ * // 2. Bob
+ */
+export declare function summarizeList<T>(items: T[], formatPreview: (item: T) => string, options?: {
+    title?: string;
+    maxPreview?: number;
+    detailsFormatter?: (item: T) => string;
+    maxDetails?: number;
+}): string;
+/**
+ * Summarize the results of a batch operation.
+ *
+ * @param results - Array of operation results
+ * @param options - Formatting options
+ * @returns Formatted batch summary with success/failure counts
+ *
+ * @example
+ * const results = [
+ *   { success: true, id: '1', message: 'Created user Alice' },
+ *   { success: false, id: '2', message: 'User Bob already exists' },
+ * ];
+ * const summary = summarizeBatch(results, {
+ *   operationName: 'Create Users',
+ *   successFormatter: (r) => `✓ ${r.message}`,
+ *   errorFormatter: (r) => `✗ ${r.message}`,
+ * });
+ */
+export declare function summarizeBatch<T extends {
+    success: boolean;
+}>(results: T[], options: {
+    operationName: string;
+    successFormatter: (result: T) => string;
+    errorFormatter: (result: T) => string;
+}): string;
+/**
+ * Format a field change for before/after comparison.
+ *
+ * @param fieldName - Human-readable field name
+ * @param before - Value before change
+ * @param after - Value after change
+ * @returns Formatted change description
+ *
+ * @example
+ * formatFieldChange('Status', 'pending', 'completed')
+ * // Returns: "Status: pending → completed"
+ */
+export declare function formatFieldChange(fieldName: string, before: string | number | boolean | null | undefined, after: string | number | boolean | null | undefined): string;
+/**
+ * Create a structured markdown section with optional tags.
+ *
+ * @param content - Content to wrap
+ * @param options - Section options
+ * @returns Formatted section with tags
+ *
+ * @example
+ * createSection('User details: Alice', { tag: 'user_info' })
+ * // Returns:
+ * // <ove tag="user_info">
+ * // User details: Alice
+ * // </ove>
+ */
+export declare function createSection(content: string, options?: {
+    tag?: string;
+    indent?: number;
+}): string;
+/**
+ * Truncate text to a maximum length with ellipsis.
+ *
+ * @param text - Text to truncate
+ * @param maxLength - Maximum length (default: 100)
+ * @returns Truncated text
+ */
+export declare function truncate(text: string, maxLength?: number): string;
+/**
+ * Format a list of key-value pairs as markdown.
+ *
+ * @param pairs - Object with key-value pairs
+ * @returns Formatted markdown list
+ *
+ * @example
+ * formatKeyValueList({ name: 'Alice', age: 30, role: 'Admin' })
+ * // Returns:
+ * // - **Name**: Alice
+ * // - **Age**: 30
+ * // - **Role**: Admin
+ */
+export declare function formatKeyValueList(pairs: Record<string, string | number | boolean | null | undefined>): string;

package/dist/shared/utils/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./base64.js";
+export * from "./cancellation.js";
+export * from "./elicitation.js";
+export * from "./formatting.js";
+export * from "./limits.js";
+export * from "./logger.js";
+export * from "./pagination.js";
+export * from "./progress.js";
+export * from "./roots.js";
+export * from "./sampling.js";
+export * from "./security.js";

package/dist/shared/utils/limits.d.ts

@@ -0,0 +1,6 @@
+export type TokenBucket = {
+    take: (n?: number) => boolean;
+    refill: (tokens?: number) => void;
+};
+export declare const makeTokenBucket: (capacity: number, refillPerSec: number) => TokenBucket;
+export declare const makeConcurrencyGate: (max: number) => <T>(fn: () => Promise<T>) => Promise<T>;

package/dist/shared/utils/logger.d.ts

@@ -0,0 +1,20 @@
+export type LogLevel = "debug" | "info" | "warning" | "error";
+interface LogData {
+    message: string;
+    [key: string]: unknown;
+}
+export declare const sharedLogger: {
+    setLevel(level: LogLevel): void;
+    debug(logger: string, data: LogData): void;
+    info(logger: string, data: LogData): void;
+    warning(logger: string, data: LogData): void;
+    error(logger: string, data: LogData): void;
+};
+export declare const logger: {
+    setLevel(level: LogLevel): void;
+    debug(logger: string, data: LogData): void;
+    info(logger: string, data: LogData): void;
+    warning(logger: string, data: LogData): void;
+    error(logger: string, data: LogData): void;
+};
+export {};

package/dist/shared/utils/pagination.d.ts

@@ -0,0 +1,11 @@
+export type PaginationCursor = string;
+export interface PaginatedRequest {
+    cursor?: PaginationCursor;
+}
+export interface PaginatedResponse<T> {
+    data: T[];
+    nextCursor?: PaginationCursor;
+}
+export declare function createCursor(offset: number): PaginationCursor;
+export declare function parseCursor(cursor?: PaginationCursor): number;
+export declare function paginateArray<T>(items: T[], cursor?: PaginationCursor, limit?: number): PaginatedResponse<T>;

package/dist/shared/utils/progress.d.ts

@@ -0,0 +1,56 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export type ProgressToken = string | number;
+export interface ProgressNotification {
+    progressToken: ProgressToken;
+    progress: number;
+    total?: number;
+    message?: string;
+}
+/**
+ * Reports progress for long-running operations.
+ *
+ * Per review finding #12: Progress notifications sent after request completion
+ * are silently ignored by the client (no handler exists for completed requests).
+ * Always send progress BEFORE returning from the handler.
+ */
+export declare class ProgressReporter {
+    private server;
+    private progressToken;
+    private completed;
+    constructor(server: McpServer, progressToken: ProgressToken);
+    /**
+     * Send a progress notification.
+     *
+     * @param progress - Current progress value (should increase with each call)
+     * @param total - Optional total value (for percentage calculation)
+     * @param message - Optional human-readable progress message
+     */
+    report(progress: number, total?: number, message?: string): Promise<void>;
+    /**
+     * Mark the operation as complete.
+     * Sends final 100% progress notification.
+     * Further progress reports will be logged as warnings.
+     */
+    complete(message?: string): Promise<void>;
+}
+/**
+ * Create a progress reporter for a request.
+ *
+ * @param server - The MCP server instance
+ * @param progressToken - Token from request._meta.progressToken
+ * @returns ProgressReporter instance, or null if no token provided
+ *
+ * @example
+ * ```typescript
+ * const reporter = createProgressReporter(server, extra._meta?.progressToken);
+ * if (reporter) {
+ *   await reporter.report(0, 100, 'Starting...');
+ *   // ... do work ...
+ *   await reporter.report(50, 100, 'Halfway done');
+ *   // ... more work ...
+ *   await reporter.complete();
+ * }
+ * return result; // Progress sent BEFORE return
+ * ```
+ */
+export declare function createProgressReporter(server: McpServer, progressToken: ProgressToken | undefined): ProgressReporter | null;

package/dist/shared/utils/roots.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Roots utilities for server→client requests.
+ *
+ * ⚠️ NODE.JS ONLY - These utilities require SDK bidirectional support
+ * (server.request()) which is not available in the Cloudflare Workers runtime.
+ * The Workers dispatcher does not support server→client requests.
+ *
+ * Per MCP spec (review finding #2):
+ * - Roots is a CLIENT capability
+ * - Servers send roots/list requests TO clients
+ * - Clients respond with filesystem locations they have access to
+ * - This enables file-based tools to know allowed paths
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * A root directory or file that the client has access to.
+ * Per spec: URI MUST start with "file://"
+ */
+export interface Root {
+    /** The URI identifying the root. MUST start with "file://" */
+    uri: string;
+    /** Optional display name for the root */
+    name?: string;
+    /** Extension metadata */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Result from roots/list request.
+ */
+export interface ListRootsResult {
+    roots: Root[];
+}
+/**
+ * Request the list of roots from the client.
+ *
+ * @param server - The MCP server instance
+ * @returns Array of Root objects representing accessible filesystem locations
+ * @throws Error if client doesn't support roots capability
+ *
+ * @example
+ * ```typescript
+ * const roots = await requestRoots(server);
+ * for (const root of roots) {
+ *   console.log(`Root: ${root.name ?? root.uri}`);
+ * }
+ * ```
+ */
+export declare function requestRoots(server: McpServer): Promise<Root[]>;
+/**
+ * Check if the client supports roots.
+ *
+ * @param server - The MCP server instance
+ * @returns true if client declared roots capability
+ */
+export declare function clientSupportsRoots(server: McpServer): boolean;
+/**
+ * Check if the client supports roots list change notifications.
+ *
+ * @param server - The MCP server instance
+ * @returns true if client declared roots.listChanged capability
+ */
+export declare function clientSupportsRootsListChanged(server: McpServer): boolean;

package/dist/shared/utils/sampling.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Sampling utilities for servers to request LLM completions from clients.
+ *
+ * ⚠️ NODE.JS ONLY - These utilities require SDK bidirectional support
+ * (server.request()) which is not available in the Cloudflare Workers runtime.
+ * The Workers dispatcher does not support server→client requests.
+ *
+ * Per MCP spec:
+ * - Sampling is a CLIENT capability
+ * - Servers send sampling/createMessage requests TO clients
+ * - Clients handle the actual LLM interaction
+ * - This enables agentic behaviors in server tools
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Message content types for sampling requests.
+ */
+export type SamplingContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+} | {
+    type: "audio";
+    data: string;
+    mimeType: string;
+};
+/**
+ * Sampling message with role and content.
+ */
+export interface SamplingMessage {
+    role: "user" | "assistant";
+    content: SamplingContent;
+}
+/**
+ * Model preferences for sampling requests.
+ */
+export interface ModelPreferences {
+    /** Model name hints (evaluated in order) */
+    hints?: Array<{
+        name: string;
+    }>;
+    /** Cost priority (0-1, higher = prefer cheaper models) */
+    costPriority?: number;
+    /** Speed priority (0-1, higher = prefer faster models) */
+    speedPriority?: number;
+    /** Intelligence priority (0-1, higher = prefer more capable models) */
+    intelligencePriority?: number;
+}
+/**
+ * Tool choice mode for sampling requests.
+ */
+export interface ToolChoice {
+    /** 'auto' | 'required' | 'none' */
+    mode: "auto" | "required" | "none";
+}
+/**
+ * Tool definition for sampling requests.
+ */
+export interface SamplingTool {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * Sampling request parameters.
+ */
+export interface CreateMessageRequest {
+    messages: SamplingMessage[];
+    /** REQUIRED: Maximum tokens to generate (prevents runaway completions) */
+    maxTokens: number;
+    modelPreferences?: ModelPreferences;
+    systemPrompt?: string;
+    temperature?: number;
+    stopSequences?: string[];
+    metadata?: Record<string, unknown>;
+    /** Tools available for the LLM to use. Requires client sampling.tools capability. */
+    tools?: SamplingTool[];
+    /** Control tool usage. Can be specified without tools array to control built-in tools. */
+    toolChoice?: ToolChoice;
+}
+/**
+ * Sampling response from client.
+ */
+export interface CreateMessageResponse {
+    role: "assistant";
+    content: SamplingContent;
+    model: string;
+    stopReason?: "endTurn" | "stopSequence" | "maxTokens";
+}
+/**
+ * Request LLM sampling from the client.
+ *
+ * Uses the public server.createMessage() API which handles Zod schema
+ * validation internally — avoids the _zod errors from raw request().
+ *
+ * @param server - The MCP server instance
+ * @param request - Sampling request parameters
+ * @returns The LLM response from the client
+ *
+ * @example
+ * ```typescript
+ * const response = await requestSampling(server, {
+ *   messages: [
+ *     {
+ *       role: 'user',
+ *       content: { type: 'text', text: 'What is the capital of France?' }
+ *     }
+ *   ],
+ *   modelPreferences: {
+ *     hints: [{ name: 'claude-3-sonnet' }],
+ *     intelligencePriority: 0.8,
+ *     speedPriority: 0.5
+ *   },
+ *   maxTokens: 100
+ * });
+ *
+ * console.log(response.content.text); // "The capital of France is Paris."
+ * ```
+ */
+export declare function requestSampling(server: McpServer, request: CreateMessageRequest): Promise<CreateMessageResponse>;
+/**
+ * Check if the client supports sampling.
+ *
+ * @param server - The MCP server instance
+ * @returns true if client declared sampling capability
+ */
+export declare function clientSupportsSampling(server: McpServer): boolean;
+/**
+ * Check if the client supports sampling with tools.
+ *
+ * @param server - The MCP server instance
+ * @returns true if client declared sampling.tools capability
+ */
+export declare function clientSupportsSamplingTools(server: McpServer): boolean;
+/**
+ * Simple helper for text-only sampling requests.
+ *
+ * @param server - The MCP server instance
+ * @param prompt - User prompt text
+ * @param maxTokens - Maximum tokens to generate (REQUIRED per spec)
+ * @param options - Optional additional sampling parameters
+ * @returns The text response from the LLM
+ *
+ * @example
+ * ```typescript
+ * const answer = await requestTextCompletion(server, 'What is 2+2?', 50, {
+ *   modelPreferences: { hints: [{ name: 'claude' }] }
+ * });
+ * console.log(answer); // "2+2 equals 4."
+ * ```
+ */
+export declare function requestTextCompletion(server: McpServer, prompt: string, maxTokens: number, options?: Omit<CreateMessageRequest, "messages" | "maxTokens">): Promise<string>;

package/dist/shared/utils/security.d.ts

@@ -0,0 +1,6 @@
+import type { UnifiedConfig } from "../config/env.js";
+export declare const makeSessionId: () => string;
+export declare const makeEventId: () => string;
+export declare const validateProtocolVersion: (headers: Headers, expectedVersion: string) => void;
+export declare const validateOrigin: (headers: Headers, config: Pick<UnifiedConfig, "NODE_ENV">) => void;
+export declare const redactSensitiveData: (obj: Record<string, unknown>) => Record<string, unknown>;