@phake/mcp 0.0.1

package/dist/shared/storage/kv.d.ts

@@ -0,0 +1,68 @@
+import type { ProviderTokens, RsRecord, SessionRecord, SessionStore, TokenStore, Transaction } from "./interface.js";
+import { MemorySessionStore, MemoryTokenStore } from "./memory.js";
+type KVNamespace = {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expiration?: number;
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+};
+type EncryptFn = (plaintext: string) => Promise<string> | string;
+type DecryptFn = (ciphertext: string) => Promise<string> | string;
+export declare class KvTokenStore implements TokenStore {
+    private kv;
+    private encrypt;
+    private decrypt;
+    private fallback;
+    constructor(kv: KVNamespace, options?: {
+        encrypt?: EncryptFn;
+        decrypt?: DecryptFn;
+        fallback?: MemoryTokenStore;
+    });
+    private putJson;
+    private getJson;
+    storeRsMapping(rsAccess: string, provider: ProviderTokens, rsRefresh?: string): Promise<RsRecord>;
+    getByRsAccess(rsAccess: string): Promise<RsRecord | null>;
+    getByRsRefresh(rsRefresh: string): Promise<RsRecord | null>;
+    updateByRsRefresh(rsRefresh: string, provider: ProviderTokens, maybeNewRsAccess?: string): Promise<RsRecord | null>;
+    saveTransaction(txnId: string, txn: Transaction, ttlSeconds?: number): Promise<void>;
+    getTransaction(txnId: string): Promise<Transaction | null>;
+    deleteTransaction(txnId: string): Promise<void>;
+    saveCode(code: string, txnId: string, ttlSeconds?: number): Promise<void>;
+    getTxnIdByCode(code: string): Promise<string | null>;
+    deleteCode(code: string): Promise<void>;
+}
+/**
+ * KV-based session store for Cloudflare Workers.
+ * Provides persistent session storage with multi-tenant support.
+ *
+ * Storage structure:
+ * - session:{sessionId} → SessionRecord (main session data)
+ * - session:apikey:{apiKey} → string[] (list of session IDs for this API key)
+ */
+export declare class KvSessionStore implements SessionStore {
+    private kv;
+    private encrypt;
+    private decrypt;
+    private fallback;
+    constructor(kv: KVNamespace, options?: {
+        encrypt?: EncryptFn;
+        decrypt?: DecryptFn;
+        fallback?: MemorySessionStore;
+    });
+    private putSession;
+    private getSession;
+    private getApiKeySessionIds;
+    private setApiKeySessionIds;
+    create(sessionId: string, apiKey: string): Promise<SessionRecord>;
+    get(sessionId: string): Promise<SessionRecord | null>;
+    update(sessionId: string, data: Partial<SessionRecord>): Promise<void>;
+    delete(sessionId: string): Promise<void>;
+    getByApiKey(apiKey: string): Promise<SessionRecord[]>;
+    countByApiKey(apiKey: string): Promise<number>;
+    deleteOldestByApiKey(apiKey: string): Promise<void>;
+    ensure(sessionId: string): Promise<void>;
+    put(sessionId: string, value: SessionRecord): Promise<void>;
+}
+export {};

package/dist/shared/storage/memory.d.ts

@@ -0,0 +1,91 @@
+import type { ProviderTokens, RsRecord, SessionRecord, SessionStore, TokenStore, Transaction } from "./interface.js";
+/**
+ * Wrapper for entries with expiration time.
+ */
+interface TimedEntry<T> {
+    value: T;
+    expiresAt: number;
+    createdAt: number;
+}
+export declare class MemoryTokenStore implements TokenStore {
+    protected rsAccessMap: Map<string, RsRecord & {
+        expiresAt: number;
+    }>;
+    protected rsRefreshMap: Map<string, RsRecord & {
+        expiresAt: number;
+    }>;
+    protected transactions: Map<string, TimedEntry<Transaction>>;
+    protected codes: Map<string, TimedEntry<string>>;
+    private cleanupIntervalId;
+    constructor();
+    /**
+     * Start periodic cleanup of expired entries.
+     */
+    startCleanup(): void;
+    /**
+     * Stop periodic cleanup.
+     */
+    stopCleanup(): void;
+    /**
+     * Run cleanup of all expired entries.
+     */
+    cleanup(): {
+        tokens: number;
+        transactions: number;
+        codes: number;
+    };
+    storeRsMapping(rsAccess: string, provider: ProviderTokens, rsRefresh?: string, ttlMs?: number): Promise<RsRecord>;
+    getByRsAccess(rsAccess: string): Promise<RsRecord | null>;
+    getByRsRefresh(rsRefresh: string): Promise<RsRecord | null>;
+    updateByRsRefresh(rsRefresh: string, provider: ProviderTokens, maybeNewRsAccess?: string, ttlMs?: number): Promise<RsRecord | null>;
+    saveTransaction(txnId: string, txn: Transaction, ttlSeconds?: number): Promise<void>;
+    getTransaction(txnId: string): Promise<Transaction | null>;
+    deleteTransaction(txnId: string): Promise<void>;
+    saveCode(code: string, txnId: string, ttlSeconds?: number): Promise<void>;
+    getTxnIdByCode(code: string): Promise<string | null>;
+    deleteCode(code: string): Promise<void>;
+    /**
+     * Get current store statistics.
+     */
+    getStats(): {
+        rsTokens: number;
+        transactions: number;
+        codes: number;
+    };
+}
+/** Internal session type with expiration */
+type InternalSession = SessionRecord & {
+    expiresAt: number;
+    sessionId: string;
+};
+export declare class MemorySessionStore implements SessionStore {
+    protected sessions: Map<string, InternalSession>;
+    private cleanupIntervalId;
+    constructor();
+    /**
+     * Start periodic cleanup of expired sessions.
+     */
+    startCleanup(): void;
+    /**
+     * Stop periodic cleanup.
+     */
+    stopCleanup(): void;
+    /**
+     * Remove expired sessions.
+     */
+    cleanup(): number;
+    create(sessionId: string, apiKey: string, ttlMs?: number): Promise<SessionRecord>;
+    get(sessionId: string): Promise<SessionRecord | null>;
+    update(sessionId: string, data: Partial<SessionRecord>): Promise<void>;
+    delete(sessionId: string): Promise<void>;
+    getByApiKey(apiKey: string): Promise<SessionRecord[]>;
+    countByApiKey(apiKey: string): Promise<number>;
+    deleteOldestByApiKey(apiKey: string): Promise<void>;
+    ensure(sessionId: string, ttlMs?: number): Promise<void>;
+    put(sessionId: string, value: SessionRecord, ttlMs?: number): Promise<void>;
+    /**
+     * Get current session count.
+     */
+    getSessionCount(): number;
+}
+export {};

package/dist/shared/storage/singleton.d.ts

@@ -0,0 +1,4 @@
+import type { SessionStore, TokenStore } from "./interface.js";
+export declare function initializeStorage(tokenStore: TokenStore, sessionStore: SessionStore): void;
+export declare function getTokenStore(): TokenStore;
+export declare function getSessionStore(): SessionStore;

package/dist/shared/tools/echo.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+/**
+ * Input schema for echo tool.
+ */
+export declare const echoInputSchema: z.ZodObject<{
+    message: z.ZodString;
+    uppercase: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Echo tool - works in both Node and Workers.
+ * Simple test tool that echoes back input.
+ */
+export declare const echoTool: import("./types.js").SharedToolDefinition<{
+    message: z.ZodString;
+    uppercase: z.ZodOptional<z.ZodBoolean>;
+}>;

package/dist/shared/tools/health.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+/**
+ * Input schema for health tool.
+ */
+export declare const healthInputSchema: z.ZodObject<{
+    verbose: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Health check tool - works in both Node and Workers.
+ */
+export declare const healthTool: import("./types.js").SharedToolDefinition<{
+    verbose: z.ZodOptional<z.ZodBoolean>;
+}>;

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

@@ -0,0 +1,4 @@
+export * from "./echo.js";
+export * from "./health.js";
+export * from "./registry.js";
+export * from "./types.js";

package/dist/shared/tools/registry.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared tool registry - single source of truth for all tools.
+ * Tools defined here work in both Node.js and Cloudflare Workers.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ZodObject, ZodRawShape } from "zod";
+import type { SharedToolDefinition, ToolContext, ToolResult } from "./types.js";
+/**
+ * Optional context resolver for Node.js runtime.
+ * Allows looking up auth context by requestId.
+ */
+export type ContextResolver = (requestId: string | number) => {
+    authStrategy?: ToolContext["authStrategy"];
+    providerToken?: string;
+    provider?: ToolContext["provider"];
+    resolvedHeaders?: Record<string, string>;
+} | undefined;
+export type { SharedToolDefinition, ToolContext, ToolResult } from "./types.js";
+export { defineTool } from "./types.js";
+/**
+ * Simplified tool interface for the registry (type-erased for storage).
+ * This is the "any tool" type used when storing heterogeneous tools in an array.
+ */
+export interface RegisteredTool {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema: ZodObject<ZodRawShape>;
+    outputSchema?: ZodRawShape;
+    requiresAuth?: boolean;
+    annotations?: Record<string, unknown>;
+    handler: (args: Record<string, unknown>, context: ToolContext) => Promise<ToolResult>;
+}
+/**
+ * All shared tools available in both runtimes.
+ * Add new tools here to make them available everywhere.
+ */
+export declare const sharedTools: RegisteredTool[];
+/**
+ * Get a tool by name.
+ */
+export declare function getSharedTool(name: string): RegisteredTool | undefined;
+/**
+ * Get all tool names.
+ */
+export declare function getSharedToolNames(): string[];
+/**
+ * Execute a shared tool by name.
+ * Handles input validation, output validation, and error wrapping.
+ *
+ * Per MCP spec: When outputSchema is defined, structuredContent is required
+ * (unless isError is true). The SDK validates this automatically for Node,
+ * and we replicate that behavior here for Workers.
+ */
+export declare function executeSharedTool(name: string, args: Record<string, unknown>, context: ToolContext, tools?: SharedToolDefinition[]): Promise<ToolResult>;
+/**
+ * Register all tools with an MCP server.
+ * This is the main entry point for Node.js runtime.
+ *
+ * @param server - MCP server instance
+ * @param contextResolver - Optional function to resolve auth context by requestId.
+ *                          Required for tools to receive auth data in Node.js.
+ */
+export declare function registerTools(server: McpServer, contextResolver?: ContextResolver): void;

package/dist/shared/tools/types.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Shared tool types for cross-runtime compatibility.
+ * These definitions work in both Node.js (Hono) and Cloudflare Workers.
+ *
+ * Uses Zod for schema validation (works in both runtimes).
+ */
+import type { ZodObject, ZodRawShape, z } from "zod";
+import type { AuthStrategy } from "../types/auth.js";
+import type { ProviderInfo } from "../types/provider.js";
+export type { AuthStrategy } from "../types/auth.js";
+/**
+ * Context passed to every tool handler.
+ * Provides access to auth, session, and cancellation.
+ */
+export interface ToolContext {
+    /** Current MCP session ID */
+    sessionId: string;
+    /** Abort signal for cancellation support */
+    signal?: AbortSignal;
+    /** Request metadata from MCP */
+    meta?: {
+        progressToken?: string | number;
+        requestId?: string;
+    };
+    /**
+     * Active auth strategy.
+     * - 'oauth': Full OAuth flow with RS token mapping
+     * - 'bearer': Static bearer token from BEARER_TOKEN env
+     * - 'api_key': Static API key from API_KEY env
+     * - 'custom': Custom headers from CUSTOM_HEADERS env
+     * - 'none': No authentication
+     */
+    authStrategy?: AuthStrategy;
+    /**
+     * Provider access token (e.g., Google, Spotify, GitHub token).
+     * Use this to call external APIs on behalf of the user.
+     *
+     * For OAuth: the mapped provider token
+     * For Bearer: the BEARER_TOKEN value
+     * For API Key: the API_KEY value
+     *
+     * @example
+     * ```typescript
+     * const response = await fetch('https://api.example.com/data', {
+     *   headers: { Authorization: `Bearer ${context.providerToken}` }
+     * });
+     * ```
+     */
+    providerToken?: string;
+    /**
+     * Provider information (OAuth only).
+     * Uses camelCase (JS convention) - converted from storage format.
+     */
+    provider?: ProviderInfo;
+    /**
+     * Resolved headers ready for API calls.
+     * This includes the appropriate auth header based on strategy:
+     * - OAuth: Authorization header with provider token
+     * - Bearer: Authorization header from config
+     * - API Key: Custom header (e.g., x-api-key) from config
+     * - Custom: All custom headers from config
+     *
+     * Use these headers directly in fetch calls:
+     * @example
+     * ```typescript
+     * const response = await fetch('https://api.example.com/data', {
+     *   headers: context.resolvedHeaders
+     * });
+     * ```
+     */
+    resolvedHeaders?: Record<string, string>;
+    /**
+     * Raw authorization headers from the request (before resolution).
+     * Usually you should use `resolvedHeaders` instead.
+     * @deprecated Use `resolvedHeaders` for API calls
+     */
+    authHeaders?: Record<string, string>;
+}
+/**
+ * Type guard to assert providerToken is present.
+ * Use this when you know auth is required (e.g., tools with requiresAuth: true).
+ */
+export declare function assertProviderToken(context: ToolContext): asserts context is ToolContext & {
+    providerToken: string;
+};
+/**
+ * Content block in tool results.
+ */
+export type ToolContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+} | {
+    type: "resource";
+    uri: string;
+    mimeType?: string;
+    text?: string;
+};
+/**
+ * Result returned from tool handlers.
+ */
+export interface ToolResult {
+    content: ToolContentBlock[];
+    /** If true, indicates the tool encountered an error */
+    isError?: boolean;
+    /** Structured output matching outputSchema (if defined) */
+    structuredContent?: Record<string, unknown>;
+}
+/**
+ * Context passed to handlers of tools that require authentication.
+ * The dispatcher guarantees providerToken is present.
+ */
+export interface AuthenticatedToolContext extends ToolContext {
+    providerToken: string;
+}
+/**
+ * Framework-agnostic tool definition using Zod schemas.
+ * Can be registered with McpServer (Node) or custom dispatcher (Workers).
+ */
+export interface SharedToolDefinition<TShape extends ZodRawShape = ZodRawShape> {
+    /** Unique tool name (lowercase, underscores allowed) */
+    name: string;
+    /** Human-readable title */
+    title?: string;
+    /** Tool description for LLM */
+    description: string;
+    /** Zod schema for input validation */
+    inputSchema: ZodObject<TShape>;
+    /** Optional Zod schema for structured output */
+    outputSchema?: ZodRawShape;
+    /** Tool handler function */
+    handler: (args: z.infer<ZodObject<TShape>>, context: ToolContext) => Promise<ToolResult>;
+    /**
+     * Whether this tool requires authentication.
+     * If true, the handler will automatically return an error if providerToken is missing.
+     */
+    requiresAuth?: boolean;
+    /**
+     * Tool annotations per MCP specification.
+     * These are hints for clients about tool behavior (not enforced by SDK).
+     */
+    annotations?: {
+        /** Human-readable display title */
+        title?: string;
+        /** Tool does NOT modify environment (default: false) */
+        readOnlyHint?: boolean;
+        /** Tool may delete/overwrite data (default: true) */
+        destructiveHint?: boolean;
+        /** Repeated calls have no additional effect (default: false) */
+        idempotentHint?: boolean;
+        /** Tool interacts with external entities (default: true) */
+        openWorldHint?: boolean;
+    };
+}
+/**
+ * Helper to create a type-safe tool definition.
+ */
+export declare function defineTool<TShape extends ZodRawShape>(def: SharedToolDefinition<TShape>): SharedToolDefinition<TShape>;

package/dist/shared/types/auth.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Canonical authentication types.
+ * Single source of truth for auth strategy definitions.
+ */
+/**
+ * Supported authentication strategies.
+ *
+ * - 'oauth': Full OAuth 2.1 PKCE flow with RS token → provider token mapping
+ * - 'bearer': Simple static Bearer token (from BEARER_TOKEN env)
+ * - 'api_key': API key in custom header (from API_KEY env)
+ * - 'custom': Arbitrary headers from CUSTOM_HEADERS config
+ * - 'none': No authentication required
+ */
+export type AuthStrategy = "oauth" | "bearer" | "api_key" | "custom" | "none";
+/**
+ * Auth headers extracted from incoming requests.
+ */
+export interface AuthHeaders {
+    authorization?: string;
+    "x-api-key"?: string;
+    "x-auth-token"?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Resolved authentication result.
+ * Contains headers ready for API calls and token information.
+ */
+export interface ResolvedAuth {
+    /** Auth strategy used */
+    strategy: AuthStrategy;
+    /** Headers to pass to API calls */
+    headers: Record<string, string>;
+    /** Raw access token (if bearer/oauth) */
+    accessToken?: string;
+}

package/dist/shared/types/context.d.ts

@@ -0,0 +1,79 @@
+import type { CancellationToken } from "../utils/cancellation.js";
+import type { AuthHeaders, AuthStrategy } from "./auth.js";
+import type { ProviderTokens } from "./provider.js";
+export type { AuthHeaders, AuthStrategy } from "./auth.js";
+/**
+ * Request context passed to tool handlers.
+ * Contains metadata and utilities for the current request.
+ */
+export interface RequestContext {
+    /**
+     * Session ID from the MCP transport (if available).
+     * This is managed by the SDK's StreamableHTTPServerTransport.
+     */
+    sessionId?: string;
+    /**
+     * Cancellation token for the current request.
+     * Tools should check this periodically and throw CancellationError if cancelled.
+     */
+    cancellationToken: CancellationToken;
+    /**
+     * Request ID from JSON-RPC message.
+     */
+    requestId?: string | number;
+    /**
+     * Timestamp when the request was received.
+     */
+    timestamp: number;
+    /**
+     * Active auth strategy.
+     * - 'oauth': Full OAuth flow with RS token mapping
+     * - 'bearer': Static bearer token from BEARER_TOKEN env
+     * - 'api_key': Static API key from API_KEY env
+     * - 'custom': Custom headers from CUSTOM_HEADERS env
+     * - 'none': No authentication
+     */
+    authStrategy?: AuthStrategy;
+    /**
+     * Raw auth headers from the request (before resolution).
+     * @deprecated Use resolvedHeaders for API calls
+     */
+    authHeaders?: AuthHeaders;
+    /**
+     * Resolved headers ready for API calls.
+     * This includes the appropriate auth header based on strategy:
+     * - OAuth: Authorization header with provider token
+     * - Bearer: Authorization header from config
+     * - API Key: Custom header (e.g., x-api-key) from config
+     * - Custom: All custom headers from config
+     */
+    resolvedHeaders?: Record<string, string>;
+    /**
+     * Original RS token (if OAuth was used).
+     */
+    rsToken?: string;
+    /**
+     * Provider access token (e.g., Google, Spotify, GitHub token).
+     * This is the token to use when calling external APIs.
+     *
+     * For OAuth: the mapped provider token
+     * For Bearer: the BEARER_TOKEN value
+     * For API Key: the API_KEY value
+     *
+     * @example
+     * ```typescript
+     * const response = await fetch('https://api.example.com/data', {
+     *   headers: { Authorization: `Bearer ${context.providerToken}` }
+     * });
+     * ```
+     */
+    providerToken?: string;
+    /**
+     * Full provider token information (OAuth only).
+     * Uses snake_case to match storage format.
+     * Use this to check expiry or access scopes.
+     */
+    provider?: ProviderTokens;
+    /** @deprecated Use providerToken instead */
+    serviceToken?: string;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Canonical types index.
+ * Import types from here for consistency across the codebase.
+ */
+export type { AuthHeaders, AuthStrategy, ResolvedAuth } from "./auth.js";
+export type { RequestContext } from "./context.js";
+export type { ProviderInfo, ProviderTokens } from "./provider.js";
+export { toProviderInfo, toProviderTokens } from "./provider.js";

package/dist/shared/types/provider.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Provider token types and conversion utilities.
+ *
+ * ProviderTokens (snake_case) - storage/OAuth API format, defined in storage/interface.ts
+ * ProviderInfo (camelCase) - tool handler format, defined here
+ */
+export type { ProviderTokens } from "../storage/interface.js";
+import type { ProviderTokens } from "../storage/interface.js";
+/**
+ * Provider info in camelCase for tool handlers.
+ * Converted from ProviderTokens when passing to tools.
+ */
+export interface ProviderInfo {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    scopes?: string[];
+}
+/**
+ * Convert snake_case ProviderTokens to camelCase ProviderInfo.
+ * Use when bridging storage layer to tool context.
+ */
+export declare function toProviderInfo(tokens: ProviderTokens): ProviderInfo;
+/**
+ * Convert camelCase ProviderInfo to snake_case ProviderTokens.
+ * Use when storing tool-provided data.
+ */
+export declare function toProviderTokens(info: ProviderInfo): ProviderTokens;

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

@@ -0,0 +1,12 @@
+/**
+ * Base64/base64url utilities for Cloudflare Workers.
+ * Uses Web APIs (btoa/atob).
+ */
+export declare function base64Encode(input: string): string;
+export declare function base64Decode(input: string): string;
+export declare function base64UrlEncode(bytes: Uint8Array): string;
+export declare function base64UrlDecode(str: string): Uint8Array;
+export declare function base64UrlEncodeString(input: string): string;
+export declare function base64UrlDecodeString(input: string): string;
+export declare function base64UrlEncodeJson(obj: unknown): string;
+export declare function base64UrlDecodeJson<T = unknown>(value: string): T | null;

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

@@ -0,0 +1,13 @@
+export declare class CancellationError extends Error {
+    constructor(message?: string);
+}
+export declare class CancellationToken {
+    private _isCancelled;
+    private _listeners;
+    get isCancelled(): boolean;
+    cancel(): void;
+    onCancelled(listener: () => void): void;
+    throwIfCancelled(): void;
+}
+export declare function createCancellationToken(): CancellationToken;
+export declare function withCancellation<T>(operation: (token: CancellationToken) => Promise<T>, token: CancellationToken): Promise<T>;