@casys/mcp-server 0.11.0 → 0.13.0

package/README.md

@@ -4,9 +4,12 @@
 [![JSR](https://jsr.io/badges/@casys/mcp-server)](https://jsr.io/@casys/mcp-server)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**The "Hono for MCP"** — a production-grade framework for building Model Context Protocol servers in TypeScript.
+**The "Hono for MCP"** — a production-grade framework for building Model Context
+Protocol servers in TypeScript.
 
-Composable middleware, OAuth2 auth, dual transport, observability, and everything you need to ship reliable MCP servers. Built on the official [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk).
+Composable middleware, OAuth2 auth, dual transport, observability, and
+everything you need to ship reliable MCP servers. Built on the official
+[@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk).
 
 ```
 rate-limit → auth → custom middleware → scope-check → validation → backpressure → handler
@@ -16,7 +19,8 @@ rate-limit → auth → custom middleware → scope-check → validation → bac
 
 ## Why @casys/mcp-server?
 
-The official SDK gives you the protocol. This framework gives you the production stack.
+The official SDK gives you the protocol. This framework gives you the production
+stack.
 
 |                         | Official SDK |       @casys/mcp-server        |
 | ----------------------- | :----------: | :----------------------------: |
@@ -51,9 +55,9 @@ deno add jsr:@casys/mcp-server
 ### STDIO Server (5 lines)
 
 ```typescript
-import { ConcurrentMCPServer } from "@casys/mcp-server";
+import { McpApp } from "@casys/mcp-server";
 
-const server = new ConcurrentMCPServer({ name: "my-server", version: "1.0.0" });
+const server = new McpApp({ name: "my-server", version: "1.0.0" });
 
 server.registerTool(
   {
@@ -74,12 +78,9 @@ await server.start();
 ### HTTP Server with Auth
 
 ```typescript
-import {
-  ConcurrentMCPServer,
-  createGoogleAuthProvider,
-} from "@casys/mcp-server";
+import { createGoogleAuthProvider, McpApp } from "@casys/mcp-server";
 
-const server = new ConcurrentMCPServer({
+const server = new McpApp({
   name: "my-api",
   version: "1.0.0",
   maxConcurrent: 10,
@@ -156,7 +157,8 @@ const timing: Middleware = async (ctx, next) => {
 server.use(timing);
 ```
 
-Built-in pipeline: `rate-limit → auth → custom → scope-check → validation → backpressure → handler`
+Built-in pipeline:
+`rate-limit → auth → custom → scope-check → validation → backpressure → handler`
 
 ### OAuth2 / JWT Auth
 
@@ -164,9 +166,9 @@ Four OIDC presets out of the box:
 
 ```typescript
 import {
-  createGoogleAuthProvider, // Google OIDC
   createAuth0AuthProvider, // Auth0
   createGitHubAuthProvider, // GitHub Actions OIDC
+  createGoogleAuthProvider, // Google OIDC
   createOIDCAuthProvider, // Generic OIDC (Keycloak, Okta, etc.)
 } from "@casys/mcp-server";
 
@@ -191,7 +193,8 @@ const provider = new JwtAuthProvider({
 });
 ```
 
-Token verification is cached (SHA-256 hash → AuthInfo, TTL = min(token expiry, 5min)) to avoid redundant JWKS round-trips.
+Token verification is cached (SHA-256 hash → AuthInfo, TTL = min(token expiry,
+5min)) to avoid redundant JWKS round-trips.
 
 ### YAML + Env Config
 
@@ -217,7 +220,9 @@ Priority: `programmatic > env vars > YAML > no auth`
 
 ### RFC 9728
 
-When auth is configured, the framework automatically exposes `GET /.well-known/oauth-protected-resource` per [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728).
+When auth is configured, the framework automatically exposes
+`GET /.well-known/oauth-protected-resource` per
+[RFC 9728](https://www.rfc-editor.org/rfc/rfc9728).
 
 ### Observability
 
@@ -272,7 +277,7 @@ Three backpressure strategies when the server is at capacity:
 | `reject`          | Fail fast with immediate error             |
 
 ```typescript
-new ConcurrentMCPServer({
+new McpApp({
   maxConcurrent: 10,
   backpressureStrategy: "queue",
 });
@@ -283,7 +288,7 @@ new ConcurrentMCPServer({
 Sliding window rate limiter with per-client tracking:
 
 ```typescript
-new ConcurrentMCPServer({
+new McpApp({
   rateLimit: {
     maxRequests: 100,
     windowMs: 60_000,
@@ -293,15 +298,19 @@ new ConcurrentMCPServer({
 });
 ```
 
-For HTTP endpoints, use `startHttp({ ipRateLimit: ... })` to rate limit by client IP (or custom key).
+For HTTP endpoints, use `startHttp({ ipRateLimit: ... })` to rate limit by
+client IP (or custom key).
 
 ### Security Best Practices (Tool Handlers)
 
 Tool handlers receive **untrusted JSON input**. Treat args as hostile:
 
-- **Define strict schemas**: `additionalProperties: false`, `minLength`, `pattern`, `enum`.
-- **Never pass raw args to a shell** (`Deno.Command`, `child_process.exec`). If you must, use an allowlist + argv array (no shell).
-- **Validate paths & resources**: allowlisted roots, deny `..`, restrict env access.
+- **Define strict schemas**: `additionalProperties: false`, `minLength`,
+  `pattern`, `enum`.
+- **Never pass raw args to a shell** (`Deno.Command`, `child_process.exec`). If
+  you must, use an allowlist + argv array (no shell).
+- **Validate paths & resources**: allowlisted roots, deny `..`, restrict env
+  access.
 - **Prefer safe APIs**: parameterized DB queries, SDK methods, typed clients.
 - **Log sensitive actions**: file writes, network calls, admin ops.
 
@@ -310,7 +319,7 @@ Tool handlers receive **untrusted JSON input**. Treat args as hostile:
 Register interactive UIs as MCP resources:
 
 ```typescript
-import { ConcurrentMCPServer, MCP_APP_MIME_TYPE } from "@casys/mcp-server";
+import { MCP_APP_MIME_TYPE, McpApp } from "@casys/mcp-server";
 
 server.registerResource(
   { uri: "ui://my-server/viewer", name: "Data Viewer" },
@@ -326,10 +335,15 @@ server.registerResource(
 
 ## API Reference
 
-### ConcurrentMCPServer
+### McpApp
+
+> **Note:** `ConcurrentMCPServer` and `ConcurrentServerOptions` remain exported
+> as `@deprecated` aliases for backwards compatibility and will be removed in
+> v1.0. New code should use `McpApp` / `McpAppOptions`. The aliases point to the
+> exact same class — `instanceof` checks pass on both.
 
 ```typescript
-const server = new ConcurrentMCPServer(options: ConcurrentServerOptions);
+const server = new McpApp(options: McpAppOptions);
 
 // Registration (before start)
 server.registerTool(tool, handler);

package/mod.ts

@@ -1,33 +1,32 @@
 /**
- * MCP Concurrent Server Framework
+ * @casys/mcp-server — Hono-style framework for MCP servers
  *
- * Production-ready MCP server framework with built-in concurrency control,
- * backpressure strategies, and optional sampling support.
+ * Production-ready MCP server framework with built-in middleware pipeline,
+ * auth, concurrency control, backpressure, and observability.
  *
- * Built on top of the official @modelcontextprotocol/sdk with added
- * production features for reliability and performance.
+ * Built on top of the official @modelcontextprotocol/sdk.
  *
  * @example
  * ```typescript
- * import { ConcurrentMCPServer } from "@casys/mcp-server";
+ * import { McpApp } from "@casys/mcp-server";
  *
- * const server = new ConcurrentMCPServer({
+ * const app = new McpApp({
  *   name: "my-server",
  *   version: "1.0.0",
  *   maxConcurrent: 10,
  *   backpressureStrategy: 'queue'
  * });
  *
- * server.registerTool(
+ * app.registerTool(
  *   { name: "greet", description: "Greet someone", inputSchema: { type: "object" } },
  *   (args) => `Hello, ${args.name}!`,
  * );
  *
  * // STDIO transport
- * await server.start();
+ * await app.start();
  *
  * // — or — HTTP transport with security-first defaults
- * const http = await server.startHttp({
+ * const http = await app.startHttp({
  *   port: 3000,
  *   maxBodyBytes: 1_048_576,                    // 1 MB (default)
  *   corsOrigins: ["https://app.example.com"],   // allowlist
@@ -39,8 +38,18 @@
  * @module @casys/mcp-server
  */
 
-// Main server class
-export { ConcurrentMCPServer } from "./src/concurrent-server.js";
+// Main server class — canonical name
+export { McpApp } from "./src/mcp-app.js";
+
+/**
+ * @deprecated Use {@link McpApp} instead. `ConcurrentMCPServer` is kept as
+ * a re-export for backwards compatibility and will be removed in v1.0.
+ *
+ * Both names point to the exact same class — `McpApp === ConcurrentMCPServer`
+ * is true at runtime, and `instanceof` checks pass in both directions.
+ * Migration is a one-line import swap.
+ */
+export { McpApp as ConcurrentMCPServer } from "./src/mcp-app.js";
 
 // Concurrency primitives
 export { RequestQueue } from "./src/concurrency/request-queue.js";
@@ -60,12 +69,12 @@ export { SamplingBridge } from "./src/sampling/sampling-bridge.js";
 
 // Type exports
 export type {
-  ConcurrentServerOptions,
   HttpRateLimitContext,
   HttpRateLimitOptions,
   HttpServerInstance,
   // HTTP Server types
   HttpServerOptions,
+  McpAppOptions,
   // MCP Apps types (SEP-1865)
   MCPResource,
   MCPTool,
@@ -79,22 +88,36 @@ export type {
   SamplingClient,
   SamplingParams,
   SamplingResult,
+  StructuredToolResult,
+  ToolAnnotations,
+  ToolErrorMapper,
   ToolHandler,
 } from "./src/types.js";
 
+/**
+ * @deprecated Use {@link McpAppOptions} instead. `ConcurrentServerOptions`
+ * is kept as a re-export for backwards compatibility and will be removed
+ * in v1.0.
+ */
+export type { McpAppOptions as ConcurrentServerOptions } from "./src/types.js";
+
 // MCP Apps constants & viewer utilities
 export { MCP_APP_MIME_TYPE } from "./src/types.js";
 export type {
   RegisterViewersConfig,
   RegisterViewersSummary,
-} from "./src/concurrent-server.js";
+} from "./src/mcp-app.js";
 export {
-  resolveViewerDistPath,
   discoverViewers,
+  resolveViewerDistPath,
 } from "./src/ui/viewer-utils.js";
 
 // MCP Compose — UI composition helpers (re-exported from @casys/mcp-compose)
-export { composeEvents, COMPOSE_EVENT_METHOD, uiMeta } from "@casys/mcp-compose/sdk";
+export {
+  COMPOSE_EVENT_METHOD,
+  composeEvents,
+  uiMeta,
+} from "@casys/mcp-compose/sdk";
 export type {
   ComposeEventHandler,
   ComposeEventPayload,
@@ -131,6 +154,14 @@ export type {
   ProtectedResourceMetadata,
 } from "./src/auth/mod.js";
 
+// Auth - Multi-tenant resolution
+export { createMultiTenantMiddleware } from "./src/auth/mod.js";
+export type {
+  MultiTenantMiddlewareOptions,
+  TenantResolution,
+  TenantResolver,
+} from "./src/auth/mod.js";
+
 // Auth - JWT Provider + Presets
 export { JwtAuthProvider } from "./src/auth/mod.js";
 export type { JwtAuthProviderOptions } from "./src/auth/mod.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@casys/mcp-server",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Production-ready MCP server framework with concurrency control, auth, and observability",
   "type": "module",
   "main": "mod.ts",

package/src/auth/mod.ts

@@ -1,5 +1,5 @@
 /**
- * Auth module for ConcurrentMCPServer.
+ * Auth module for McpApp.
  *
  * @module lib/server/auth
  */
@@ -26,6 +26,14 @@ export {
 // Scope enforcement
 export { createScopeMiddleware } from "./scope-middleware.js";
 
+// Multi-tenant resolution (tenant enforcement on top of auth)
+export { createMultiTenantMiddleware } from "./multi-tenant-middleware.js";
+export type {
+  MultiTenantMiddlewareOptions,
+  TenantResolution,
+  TenantResolver,
+} from "./multi-tenant-middleware.js";
+
 // JWT Provider
 export { JwtAuthProvider } from "./jwt-provider.js";
 export type { JwtAuthProviderOptions } from "./jwt-provider.js";

package/src/auth/multi-tenant-middleware.ts

@@ -0,0 +1,236 @@
+/**
+ * Multi-tenant resolution middleware for MCP servers.
+ *
+ * Extends the auth pipeline with tenant identification and validation.
+ * Consumers provide a {@link TenantResolver} that knows how to map an
+ * authenticated request to a tenant identifier — typically by combining
+ * the HTTP Host header (subdomain-based tenancy) with a custom JWT claim.
+ *
+ * The resolved `tenantId` is injected into `ctx.authInfo.tenantId` so
+ * downstream middlewares and tool handlers can scope data access.
+ *
+ * This middleware is **optional**. Single-tenant servers do not need it.
+ * When used, it MUST be placed AFTER the auth middleware (which populates
+ * `ctx.authInfo`) and BEFORE the scope middleware and tool handlers.
+ *
+ * @example Pipeline wiring
+ * ```typescript
+ * server.use(createAuthMiddleware(authProvider));
+ * server.use(createMultiTenantMiddleware(new MyTenantResolver(), {
+ *   onRejection: (ctx, reason) => auditLog.warn("tenant_reject", { reason }),
+ * }));
+ * server.use(createScopeMiddleware(toolScopes));
+ * ```
+ *
+ * @module lib/server/auth/multi-tenant-middleware
+ */
+
+import type { Middleware, MiddlewareContext } from "../middleware/types.js";
+import type { AuthInfo } from "./types.js";
+import { AuthError } from "./middleware.js";
+
+/**
+ * Result of a tenant resolution attempt.
+ *
+ * Use `{ ok: true, tenantId }` when the request is valid and the tenant
+ * has been identified. Use `{ ok: false, reason }` to reject the request
+ * (the reason is passed to `onRejection` for logging but NEVER returned
+ * to the client, to avoid leaking tenant topology).
+ */
+export type TenantResolution =
+  | { ok: true; tenantId: string }
+  | { ok: false; reason: string };
+
+/**
+ * Resolves and validates the tenant for an incoming MCP request.
+ *
+ * Implementations typically:
+ *   1. Read a tenant hint from the request (subdomain, path, header, …)
+ *   2. Read the authoritative tenant from `ctx.authInfo.claims`
+ *   3. Validate they match
+ *   4. Return the tenant identifier, or a rejection reason
+ *
+ * @example Subdomain + JWT claim matching
+ * ```typescript
+ * class SubdomainTenantResolver implements TenantResolver {
+ *   async resolve(ctx: MiddlewareContext): Promise<TenantResolution> {
+ *     const host = ctx.request!.headers.get("host") ?? "";
+ *     const subdomain = host.split(".")[0];
+ *
+ *     const authInfo = ctx.authInfo as AuthInfo;
+ *     const claim = authInfo.claims?.["urn:my-app:tenant_id"];
+ *
+ *     if (typeof claim !== "string") {
+ *       return { ok: false, reason: "tenant_id claim missing or not a string" };
+ *     }
+ *     if (claim !== subdomain) {
+ *       return { ok: false, reason: `subdomain=${subdomain} claim=${claim}` };
+ *     }
+ *     return { ok: true, tenantId: subdomain };
+ *   }
+ * }
+ * ```
+ */
+export interface TenantResolver {
+  /**
+   * Resolve the tenant for this request.
+   *
+   * @param ctx - Middleware context with `ctx.request` and `ctx.authInfo` populated
+   * @returns A successful resolution with the tenant id, or a rejection with a reason
+   * @throws May throw — throwing is treated identically to returning `{ ok: false }`
+   */
+  resolve(ctx: MiddlewareContext): Promise<TenantResolution>;
+}
+
+/**
+ * Options for {@link createMultiTenantMiddleware}.
+ */
+export interface MultiTenantMiddlewareOptions {
+  /**
+   * Called whenever a request is rejected — either because the resolver
+   * returned `{ ok: false }`, threw an exception, or returned an empty
+   * `tenantId`.
+   *
+   * Typical use: write an audit log entry for compliance / forensics.
+   * The `reason` string may contain sensitive details (tenant ids, claim
+   * values) — log it server-side but never expose it to clients.
+   *
+   * Awaited before the client receives the 401 response, so audit writes
+   * are guaranteed to land before the error is observable. Keep it fast —
+   * slow callbacks delay the rejection.
+   *
+   * If this hook itself throws, the exception is **caught and logged to
+   * stderr** but NOT rethrown — the client still receives the standard
+   * generic `invalid_token` AuthError. A crashing audit hook must never
+   * change client-visible behaviour, otherwise a buggy audit path becomes
+   * an observable oracle for attackers probing tenant topology.
+   */
+  onRejection?: (
+    ctx: MiddlewareContext,
+    reason: string,
+  ) => void | Promise<void>;
+}
+
+/**
+ * Create a tenant resolution middleware.
+ *
+ * Pipeline behaviour:
+ *
+ * - **STDIO transport** (no `ctx.request`) → pass through unchanged. STDIO
+ *   is a local trusted transport with no meaningful notion of tenant.
+ *
+ * - **HTTP without `ctx.authInfo`** → throws a configuration error. This
+ *   indicates the auth middleware is missing from the pipeline. Fail fast
+ *   rather than silently skipping tenant enforcement.
+ *
+ * - **HTTP with `ctx.authInfo`** → calls `resolver.resolve(ctx)`:
+ *   - On success with a non-empty `tenantId`: copies `authInfo`, injects
+ *     `tenantId`, re-freezes, continues.
+ *   - On rejection (`ok: false`, thrown, or empty `tenantId`): calls
+ *     `onRejection`, then throws {@link AuthError}`("invalid_token")` —
+ *     the client sees a generic 401 with no tenant details leaked.
+ *
+ * @param resolver - Implementation that maps requests to tenant ids
+ * @param options - Optional hooks (notably `onRejection` for audit logging)
+ */
+export function createMultiTenantMiddleware(
+  resolver: TenantResolver,
+  options: MultiTenantMiddlewareOptions = {},
+): Middleware {
+  return async (ctx, next) => {
+    // STDIO transport: no request, tenant routing does not apply
+    if (!ctx.request) {
+      return next();
+    }
+
+    // Auth middleware MUST have populated authInfo before we run.
+    // MiddlewareContext is indexed as `[key: string]: unknown` for extensibility,
+    // so every auth-aware middleware in this lib casts to the concrete type —
+    // matches the convention in middleware.ts and scope-middleware.ts.
+    const authInfo = ctx.authInfo as AuthInfo | undefined;
+    if (!authInfo) {
+      throw new Error(
+        "[MultiTenantMiddleware] ctx.authInfo is not set. Ensure auth " +
+          "middleware is placed BEFORE multi-tenant middleware in the pipeline.",
+      );
+    }
+
+    // Resolve the tenant — any failure path collapses to a generic 401
+    let resolution: TenantResolution;
+    try {
+      resolution = await resolver.resolve(ctx);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      throw await rejectWithAudit(ctx, reason, options.onRejection);
+    }
+
+    if (!resolution.ok) {
+      throw await rejectWithAudit(ctx, resolution.reason, options.onRejection);
+    }
+
+    // Defense-in-depth: reject empty string tenantId even when the resolver
+    // reports success. Some consumers use truthy guards (`if (tenantId)`),
+    // and an empty string would slip past them without being noticed.
+    if (!resolution.tenantId) {
+      throw await rejectWithAudit(
+        ctx,
+        "resolver returned empty tenantId",
+        options.onRejection,
+      );
+    }
+
+    // Re-freeze authInfo with tenantId injected. Two reasons for the re-freeze:
+    //   1. Preserves the immutability guarantee downstream middleware and
+    //      tool handlers rely on — they must never observe a mutable tenantId.
+    //   2. The original authInfo is already frozen by the auth middleware,
+    //      so in-place mutation is impossible anyway. We must spread-copy.
+    ctx.authInfo = Object.freeze({
+      ...authInfo,
+      tenantId: resolution.tenantId,
+    });
+
+    return next();
+  };
+}
+
+/**
+ * Run the audit hook (if any) and return a generic `invalid_token` AuthError.
+ *
+ * The hook is intentionally shielded with try/catch: a crashing audit hook
+ * must NEVER change the client-visible response. If the hook throws, the
+ * audit is lost (logged to stderr as a last resort) but the client still
+ * receives the standard 401 AuthError — preserving the non-leak guarantee.
+ *
+ * @internal
+ */
+async function rejectWithAudit(
+  ctx: MiddlewareContext,
+  reason: string,
+  onRejection: MultiTenantMiddlewareOptions["onRejection"],
+): Promise<AuthError> {
+  if (onRejection) {
+    try {
+      await onRejection(ctx, reason);
+    } catch (hookErr) {
+      // Last-resort logging: stderr is the only safe channel here — we must
+      // not rethrow (would defeat the non-leak guarantee) and we must not
+      // silently drop (would leave no trace of an audit failure).
+      console.error(
+        "[MultiTenantMiddleware] onRejection hook threw; audit entry lost:",
+        hookErr,
+      );
+    }
+  }
+  return buildAuthError(ctx);
+}
+
+/**
+ * Build a generic `invalid_token` AuthError using the resource metadata URL
+ * already set by the upstream auth middleware. If the URL is missing (should
+ * not happen in a well-formed pipeline), fall back to an empty string — the
+ * AuthError still produces a valid 401 response.
+ */
+function buildAuthError(ctx: MiddlewareContext): AuthError {
+  const metadataUrl = (ctx.resourceMetadataUrl as string | undefined) ?? "";
+  return new AuthError("invalid_token", metadataUrl);
+}

package/src/auth/types.ts

@@ -1,5 +1,5 @@
 /**
- * Authentication types for ConcurrentMCPServer.
+ * Authentication types for McpApp.
  *
  * Types follow RFC 9728 (OAuth Protected Resource Metadata)
  * and MCP Auth spec (draft 2025-11-25).
@@ -26,6 +26,17 @@ export interface AuthInfo {
 
   /** Token expiration timestamp (Unix epoch seconds) */
   expiresAt?: number;
+
+  /**
+   * Tenant identifier for multi-tenant servers.
+   *
+   * Populated by `createMultiTenantMiddleware` when a `TenantResolver`
+   * is configured. Undefined on single-tenant servers.
+   *
+   * Tool handlers in multi-tenant servers should read this (never trust
+   * raw JWT claims directly) to scope data access to the current tenant.
+   */
+  tenantId?: string;
 }
 
 /**

package/src/inspector/launcher.ts

@@ -54,8 +54,12 @@ export async function launchInspector(
     CLIENT_PORT: String(port),
   };
 
-  console.error(`[mcp-inspector] Starting inspector on http://localhost:${port}`);
-  console.error(`[mcp-inspector] Server: ${serverCommand} ${filteredArgs.join(" ")}`);
+  console.error(
+    `[mcp-inspector] Starting inspector on http://localhost:${port}`,
+  );
+  console.error(
+    `[mcp-inspector] Server: ${serverCommand} ${filteredArgs.join(" ")}`,
+  );
 
   // Use npx to run the inspector
   const command = new Deno.Command("npx", {