@phake/mcp 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fuongz
+
+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,187 @@
+# @phake/mcp
+
+A TypeScript library for building MCP (Model Context Protocol) servers, designed to run on Cloudflare Workers and Node.js.
+
+## Features
+
+- **Multi-runtime support** — Deploy to Cloudflare Workers (itty-router) or Node.js (Hono)
+- **OAuth 2.0 authentication** — Full PKCE flow with dynamic token resolution and proactive refresh
+- **5 auth strategies** — `oauth`, `bearer`, `api_key`, `custom`, `none`
+- **Tool registration** — Define and register MCP tools with Zod input/output schemas
+- **Session & token management** — Persistent storage with LRU eviction and TTL
+- **Multiple storage backends** — Cloudflare KV, SQLite, file-based, and in-memory
+- **CORS support** — Configurable CORS headers
+- **Type-safe** — Full TypeScript support with Zod validation
+
+## Installation
+
+```bash
+bun add @phake/mcp
+```
+
+## Quick Start
+
+### Cloudflare Workers
+
+```typescript
+import { createMCPServer } from "@phake/mcp";
+
+const server = createMCPServer({
+  adapter: "worker",
+  tools: [
+    // your tool definitions
+  ],
+});
+
+export default {
+  fetch: (request: Request, env: unknown) => server.fetch(request, env),
+};
+```
+
+### Node.js
+
+```typescript
+import { createHttpApp, createAuthApp } from "@phake/mcp/runtime/node";
+
+const { app, sessionStore } = createHttpApp({
+  tools: [
+    // your tool definitions
+  ],
+});
+
+const authApp = createAuthApp({ sessionStore });
+```
+
+## API
+
+### `createMCPServer(options)`
+
+Creates an MCP server instance.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `adapter` | `"worker" \| "node"` | Runtime adapter |
+| `tools` | `SharedToolDefinition[]` | Array of tool definitions to register |
+
+### Exports
+
+| Module | Path |
+|--------|------|
+| Core | `@phake/mcp` |
+| Node runtime | `@phake/mcp/runtime/node` |
+| Worker runtime | `@phake/mcp/runtime/worker` |
+
+## Authentication Strategies
+
+| Strategy | Description | Config Env Vars |
+|----------|-------------|-----------------|
+| `oauth` | Full OAuth 2.1 PKCE flow with RS token → provider token mapping | `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`, `OAUTH_SCOPES`, `OAUTH_REDIRECT_URI`, `PROVIDER_CLIENT_ID`, `PROVIDER_CLIENT_SECRET`, `PROVIDER_ACCOUNTS_URL` |
+| `bearer` | Static Bearer token | `BEARER_TOKEN` |
+| `api_key` | Static API key in custom header (default: `x-api-key`) | `API_KEY`, `API_KEY_HEADER` |
+| `custom` | Arbitrary custom headers | `CUSTOM_HEADERS` |
+| `none` | No authentication required | — |
+
+## Storage Backends
+
+| Backend | Stores | Key Features |
+|---------|--------|--------------|
+| `MemoryTokenStore` | Tokens, transactions, codes | TTL expiration, size limits (10K tokens), LRU eviction |
+| `MemorySessionStore` | Sessions | TTL (24h), size limit (10K), per-API-key limits (5) |
+| `KvTokenStore` | Tokens, transactions, codes | Cloudflare KV + memory fallback, AES-256-GCM encryption |
+| `KvSessionStore` | Sessions | Cloudflare KV + memory fallback, encryption, API-key indexing |
+| `FileTokenStore` | RS token mappings | JSON file persistence, AES-256-GCM encryption, secure permissions (0600) |
+| `SqliteSessionStore` | Sessions | SQLite via better-sqlite3 + Drizzle ORM, WAL mode, atomic transactions |
+
+## Built-in Tools
+
+| Tool | Input | Output | Description |
+|------|-------|--------|-------------|
+| `echo` | `{ message, uppercase? }` | `{ echoed, length }` | Echoes back a message, optionally uppercased |
+| `health` | `{ verbose? }` | `{ status, timestamp, runtime, uptime? }` | Reports server health, uptime, runtime detection |
+
+## Project Structure
+
+```
+src/
+├── adapters/
+│   ├── http-node/           # Node.js adapter (Hono)
+│   │   ├── http/            # MCP server app, routes, middleware
+│   │   ├── routes.discovery.ts
+│   │   ├── routes.oauth.ts
+│   │   └── middleware.security.ts
+│   └── http-worker/         # Cloudflare Workers adapter (itty-router)
+│       ├── index.ts
+│       ├── mcp.handler.ts
+│       ├── routes.discovery.ts
+│       ├── routes.oauth.ts
+│       └── security.ts
+├── runtime/
+│   └── node/
+│       ├── capabilities.ts
+│       ├── context.ts
+│       ├── mcp.ts
+│       └── storage/
+│           ├── file.ts
+│           └── sqlite.ts
+├── shared/
+│   ├── auth/                # Authentication strategies
+│   ├── config/              # Environment configuration (40+ fields)
+│   ├── crypto/              # AES-256-GCM utilities
+│   ├── http/                # CORS, JSON-RPC responses
+│   ├── mcp/                 # Protocol dispatcher, security, server internals
+│   ├── oauth/               # Full OAuth 2.0 implementation (PKCE, CIMD, discovery)
+│   ├── services/            # HTTP client
+│   ├── storage/             # Token/session store interfaces and implementations
+│   ├── tools/               # Tool definitions, registry, execution
+│   ├── types/               # Shared type definitions
+│   └── utils/               # Base64, cancellation, logger, pagination, etc.
+├── mcp-server.ts            # Server factory
+└── index.ts                 # Main entry point
+```
+
+## MCP Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/mcp` | SSE stream initialization |
+| `POST` | `/mcp` | JSON-RPC message handling |
+| `DELETE` | `/mcp` | Session termination |
+| `GET` | `/health` | Health check |
+
+## OAuth Endpoints
+
+| Path | Description |
+|------|-------------|
+| `/.well-known/oauth-authorization-server` | OAuth discovery |
+| `/.well-known/oauth-protected-resource` | Protected resource metadata |
+| `/authorize` | Authorization request |
+| `/token` | Token exchange |
+| `/oauth/callback` | OAuth callback |
+| `/oauth/provider-callback` | Provider callback |
+| `/revoke` | Token revocation |
+| `/register` | Dynamic client registration |
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `bun run build` | Build with Bun |
+| `bun run typecheck` | Run TypeScript type checking |
+
+## Dependencies
+
+- `@modelcontextprotocol/sdk` — MCP protocol implementation
+- `zod` — Schema validation
+- `jose` — JWT and JWS/JWE
+- `oauth4webapi` — OAuth 2.0 for Web API
+- `itty-router` — Lightweight router (Workers)
+- `hono` / `@hono/node-server` — Node.js HTTP framework (optional)
+- `drizzle-orm` / `better-sqlite3` — Database layer (optional)
+
+## Inspired By
+
+This project was inspired by [streamable-mcp-server-template](https://github.com/iceener/streamable-mcp-server-template).
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.

package/dist/adapters/http-node/http/app.d.ts

@@ -0,0 +1,5 @@
+import type { HttpBindings } from "@hono/node-server";
+import { Hono } from "hono";
+export declare function buildHttpApp(): Hono<{
+    Bindings: HttpBindings;
+}>;

package/dist/adapters/http-node/http/auth-app.d.ts

@@ -0,0 +1,5 @@
+import type { HttpBindings } from "@hono/node-server";
+import { Hono } from "hono";
+export declare function buildAuthApp(): Hono<{
+    Bindings: HttpBindings;
+}>;

package/dist/adapters/http-node/http/middlewares/auth.d.ts

@@ -0,0 +1,39 @@
+import type { HttpBindings } from "@hono/node-server";
+import type { MiddlewareHandler } from "hono";
+import type { AuthStrategyType } from "../../../../shared/auth/strategy.js";
+import type { ProviderTokens } from "../../../../shared/storage/interface.js";
+/**
+ * Auth context attached to Hono context.
+ */
+export interface AuthContext {
+    /** Auth strategy in use */
+    strategy: AuthStrategyType;
+    /** Raw authorization headers from request */
+    authHeaders: Record<string, string>;
+    /** Resolved headers for API calls (includes static config headers) */
+    resolvedHeaders: Record<string, string>;
+    /** Provider access token (OAuth: mapped from RS token, Bearer: from config) */
+    providerToken?: string;
+    /** Full provider token info (OAuth only) */
+    provider?: ProviderTokens;
+    /** Original RS token (OAuth only) */
+    rsToken?: string;
+}
+/**
+ * Auth middleware that handles multiple strategies.
+ *
+ * Strategies:
+ * - 'oauth': Map RS token → Provider token (full OAuth flow)
+ * - 'bearer': Use static BEARER_TOKEN from config
+ * - 'api_key': Use static API_KEY in API_KEY_HEADER
+ * - 'custom': Use static CUSTOM_HEADERS
+ * - 'none': No auth, pass through
+ *
+ * After this middleware:
+ * - c.authContext.resolvedHeaders: Headers ready for API calls
+ * - c.authContext.providerToken: Access token (if available)
+ * - c.authContext.provider: Full token info (OAuth only)
+ */
+export declare function createAuthHeaderMiddleware(): MiddlewareHandler<{
+    Bindings: HttpBindings;
+}>;

package/dist/adapters/http-node/http/middlewares/cors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * CORS middleware configured for MCP endpoints.
+ * Uses Hono's built-in cors() middleware.
+ *
+ * Note: Preflight returns 204 (Hono default) vs original 200.
+ * Both are valid per CORS spec - browsers accept either.
+ */
+export declare const corsMiddleware: () => import("hono").MiddlewareHandler;

package/dist/adapters/http-node/http/routes/health.d.ts

@@ -0,0 +1,5 @@
+import type { HttpBindings } from "@hono/node-server";
+import { Hono } from "hono";
+export declare function healthRoutes(): Hono<{
+    Bindings: HttpBindings;
+}, import("hono/types").BlankSchema, "/">;

package/dist/adapters/http-node/http/routes/mcp.d.ts

@@ -0,0 +1,11 @@
+/** biome-ignore-all lint/style/noNonNullAssertion: no need */
+import type { HttpBindings } from "@hono/node-server";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { Hono } from "hono";
+export declare function buildMcpRoutes(params: {
+    server: McpServer;
+    transports: Map<string, StreamableHTTPServerTransport>;
+}): Hono<{
+    Bindings: HttpBindings;
+}, import("hono/types").BlankSchema, "/">;

package/dist/adapters/http-node/middleware.security.d.ts

@@ -0,0 +1,6 @@
+import type { HttpBindings } from "@hono/node-server";
+import type { MiddlewareHandler } from "hono";
+import type { UnifiedConfig } from "../../shared/config/env.js";
+export declare function createMcpSecurityMiddleware(config: UnifiedConfig): MiddlewareHandler<{
+    Bindings: HttpBindings;
+}>;

package/dist/adapters/http-node/routes.discovery.d.ts

@@ -0,0 +1,6 @@
+import type { HttpBindings } from "@hono/node-server";
+import { Hono } from "hono";
+import type { UnifiedConfig } from "../../shared/config/env.js";
+export declare function buildDiscoveryRoutes(config: UnifiedConfig): Hono<{
+    Bindings: HttpBindings;
+}>;

package/dist/adapters/http-node/routes.oauth.d.ts

@@ -0,0 +1,7 @@
+import type { HttpBindings } from "@hono/node-server";
+import { Hono } from "hono";
+import type { UnifiedConfig } from "../../shared/config/env.js";
+import type { TokenStore } from "../../shared/storage/interface.js";
+export declare function buildOAuthRoutes(store: TokenStore, config: UnifiedConfig): Hono<{
+    Bindings: HttpBindings;
+}>;

package/dist/adapters/http-worker/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Cloudflare Workers router factory.
+ * Creates a complete router with OAuth, discovery, and MCP endpoints.
+ */
+import type { UnifiedConfig } from "../../shared/config/env.js";
+import type { SessionStore, TokenStore } from "../../shared/storage/interface.js";
+export interface WorkerEnv {
+    /** KV namespace for token storage */
+    TOKENS?: KVNamespace;
+    /** Base64url-encoded 32-byte key for AES-256-GCM encryption */
+    RS_TOKENS_ENC_KEY?: string;
+    /** All other env vars */
+    [key: string]: unknown;
+}
+interface KVNamespace {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expiration?: number;
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export interface RouterContext {
+    tokenStore: TokenStore;
+    sessionStore: SessionStore;
+    config: UnifiedConfig;
+    tools?: import("../../shared/tools/types.js").SharedToolDefinition[];
+}
+/**
+ * Initialize storage for the worker.
+ * Uses KV with memory fallback and optional encryption.
+ */
+export declare function initializeWorkerStorage(env: WorkerEnv, config: UnifiedConfig): {
+    tokenStore: TokenStore;
+    sessionStore: SessionStore;
+} | null;
+/**
+ * Create a configured router for the worker.
+ */
+export declare function createWorkerRouter(ctx: RouterContext): {
+    fetch: (request: Request) => Promise<Response>;
+};
+/**
+ * Shim process.env for shared modules that expect Node.js environment.
+ * Workers don't have process.env natively, so we polyfill it.
+ */
+export declare function shimProcessEnv(env: WorkerEnv): void;
+export {};

package/dist/adapters/http-worker/mcp.handler.d.ts

@@ -0,0 +1,24 @@
+/**
+ * MCP endpoint handler for Cloudflare Workers.
+ * Uses the shared dispatcher for JSON-RPC processing.
+ */
+import type { UnifiedConfig } from "../../shared/config/env.js";
+import type { SessionStore, TokenStore } from "../../shared/storage/interface.js";
+export interface McpHandlerDeps {
+    tokenStore: TokenStore;
+    sessionStore: SessionStore;
+    config: UnifiedConfig;
+    tools?: import("../../shared/tools/types.js").SharedToolDefinition[];
+}
+/**
+ * Handle MCP POST request.
+ */
+export declare function handleMcpRequest(request: Request, deps: McpHandlerDeps): Promise<Response>;
+/**
+ * Handle MCP GET request (returns 405 per spec).
+ */
+export declare function handleMcpGet(): Response;
+/**
+ * Handle MCP DELETE request (session termination).
+ */
+export declare function handleMcpDelete(request: Request, deps: McpHandlerDeps): Promise<Response>;

package/dist/adapters/http-worker/routes.discovery.d.ts

@@ -0,0 +1,7 @@
+interface IttyRouter {
+    get(path: string, handler: (request: Request) => Promise<Response>): void;
+    post(path: string, handler: (request: Request) => Promise<Response>): void;
+}
+import type { UnifiedConfig } from "../../shared/config/env.js";
+export declare function attachDiscoveryRoutes(router: IttyRouter, config: UnifiedConfig): void;
+export {};

package/dist/adapters/http-worker/routes.oauth.d.ts

@@ -0,0 +1,8 @@
+interface IttyRouter {
+    get(path: string, handler: (request: Request) => Promise<Response>): void;
+    post(path: string, handler: (request: Request) => Promise<Response>): void;
+}
+import type { UnifiedConfig } from "../../shared/config/env.js";
+import type { TokenStore } from "../../shared/storage/interface.js";
+export declare function attachOAuthRoutes(router: IttyRouter, store: TokenStore, config: UnifiedConfig): void;
+export {};

package/dist/adapters/http-worker/security.d.ts

@@ -0,0 +1,7 @@
+import type { UnifiedConfig } from "../../shared/config/env.js";
+import type { TokenStore } from "../../shared/storage/interface.js";
+/**
+ * Check if request needs authentication and challenge if missing
+ * Returns null if authorized, otherwise returns 401 challenge response
+ */
+export declare function checkAuthAndChallenge(request: Request, store: TokenStore, config: UnifiedConfig, sid: string): Promise<Response | null>;