@casys/mcp-server 0.8.0

package/mod.ts

@@ -0,0 +1,161 @@
+/**
+ * MCP Concurrent Server Framework
+ *
+ * Production-ready MCP server framework with built-in concurrency control,
+ * backpressure strategies, and optional sampling support.
+ *
+ * Built on top of the official @modelcontextprotocol/sdk with added
+ * production features for reliability and performance.
+ *
+ * @example
+ * ```typescript
+ * import { ConcurrentMCPServer } from "@casys/mcp-server";
+ *
+ * const server = new ConcurrentMCPServer({
+ *   name: "my-server",
+ *   version: "1.0.0",
+ *   maxConcurrent: 10,
+ *   backpressureStrategy: 'queue'
+ * });
+ *
+ * server.registerTool(
+ *   { name: "greet", description: "Greet someone", inputSchema: { type: "object" } },
+ *   (args) => `Hello, ${args.name}!`,
+ * );
+ *
+ * // STDIO transport
+ * await server.start();
+ *
+ * // — or — HTTP transport with security-first defaults
+ * const http = await server.startHttp({
+ *   port: 3000,
+ *   maxBodyBytes: 1_048_576,                    // 1 MB (default)
+ *   corsOrigins: ["https://app.example.com"],   // allowlist
+ *   requireAuth: true,                          // fail-fast without auth
+ *   ipRateLimit: { maxRequests: 60, windowMs: 60_000 },
+ * });
+ * ```
+ *
+ * @module @casys/mcp-server
+ */
+
+// Main server class
+export { ConcurrentMCPServer } from "./src/concurrent-server.js";
+
+// Concurrency primitives
+export { RequestQueue } from "./src/concurrency/request-queue.js";
+
+// Rate limiting
+export { RateLimiter } from "./src/concurrency/rate-limiter.js";
+
+// Schema validation
+export { SchemaValidator } from "./src/validation/schema-validator.js";
+export type {
+  ValidationError,
+  ValidationResult,
+} from "./src/validation/schema-validator.js";
+
+// Sampling support
+export { SamplingBridge } from "./src/sampling/sampling-bridge.js";
+
+// Type exports
+export type {
+  ConcurrentServerOptions,
+  HttpRateLimitContext,
+  HttpRateLimitOptions,
+  HttpServerInstance,
+  // HTTP Server types
+  HttpServerOptions,
+  // MCP Apps types (SEP-1865)
+  MCPResource,
+  MCPTool,
+  MCPToolMeta,
+  McpUiToolMeta,
+  QueueMetrics,
+  RateLimitContext,
+  RateLimitOptions,
+  ResourceContent,
+  ResourceHandler,
+  SamplingClient,
+  SamplingParams,
+  SamplingResult,
+  ToolHandler,
+} from "./src/types.js";
+
+// MCP Apps constants
+export { MCP_APP_MIME_TYPE } from "./src/types.js";
+
+// Middleware pipeline
+export type {
+  Middleware,
+  MiddlewareContext,
+  MiddlewareResult,
+  NextFunction,
+} from "./src/middleware/mod.js";
+export { createMiddlewareRunner } from "./src/middleware/mod.js";
+
+// Auth - Core
+export { AuthProvider } from "./src/auth/mod.js";
+export {
+  AuthError,
+  createAuthMiddleware,
+  createForbiddenResponse,
+  createUnauthorizedResponse,
+  extractBearerToken,
+} from "./src/auth/mod.js";
+export { createScopeMiddleware } from "./src/auth/mod.js";
+export type {
+  AuthInfo,
+  AuthOptions,
+  ProtectedResourceMetadata,
+} from "./src/auth/mod.js";
+
+// Auth - JWT Provider + Presets
+export { JwtAuthProvider } from "./src/auth/mod.js";
+export type { JwtAuthProviderOptions } from "./src/auth/mod.js";
+export {
+  createAuth0AuthProvider,
+  createGitHubAuthProvider,
+  createGoogleAuthProvider,
+  createOIDCAuthProvider,
+} from "./src/auth/mod.js";
+export type { PresetOptions } from "./src/auth/mod.js";
+
+// Auth - Config (YAML + env)
+export {
+  createAuthProviderFromConfig,
+  loadAuthConfig,
+} from "./src/auth/mod.js";
+export type { AuthConfig, AuthProviderName } from "./src/auth/mod.js";
+
+// Observability
+export {
+  endToolCallSpan,
+  getServerTracer,
+  isOtelEnabled,
+  recordAuthEvent,
+  ServerMetrics,
+  type ServerMetricsSnapshot,
+  startToolCallSpan,
+  type ToolCallSpanAttributes,
+} from "./src/observability/mod.js";
+
+// Security - CSP utilities
+export { buildCspHeader, injectCspMetaTag } from "./src/security/csp.js";
+export type { CspOptions } from "./src/security/csp.js";
+
+// Security - HMAC channel authentication for PostMessage (MCP Apps)
+export { injectChannelAuth } from "./src/security/channel-hmac.js";
+export { MessageSigner } from "./src/security/message-signer.js";
+export type {
+  SignedMessage,
+  VerifyResult,
+} from "./src/security/message-signer.js";
+
+// Runtime port (for advanced consumers who need to inspect the adapter contract)
+export type {
+  FetchHandler,
+  RuntimePort,
+  ServeHandle,
+  ServeOptions,
+} from "./src/runtime/types.js";

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@casys/mcp-server",
+  "version": "0.8.0",
+  "description": "Production-ready MCP server framework with concurrency control, auth, and observability",
+  "type": "module",
+  "main": "mod.ts",
+  "types": "mod.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "tsx --test src/**/*_test.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.15.1",
+    "hono": "^4.0.0",
+    "ajv": "^8.17.1",
+    "jose": "^6.0.0",
+    "yaml": "^2.7.0",
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "tsx": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Casys-AI/mcp-server"
+  },
+  "license": "MIT"
+}

package/src/auth/config.ts

@@ -0,0 +1,229 @@
+/**
+ * Auth configuration loader.
+ *
+ * Loads auth config from YAML file with env var overrides.
+ * Priority: env vars > YAML > (nothing = no auth)
+ *
+ * @module lib/server/auth/config
+ */
+
+import { parse as parseYaml } from "yaml";
+import { env, readTextFile } from "../runtime/runtime.js";
+import type { AuthProvider } from "./provider.js";
+import {
+  createAuth0AuthProvider,
+  createGitHubAuthProvider,
+  createGoogleAuthProvider,
+  createOIDCAuthProvider,
+} from "./presets.js";
+
+/** Supported auth provider names */
+export type AuthProviderName = "github" | "google" | "auth0" | "oidc";
+
+const VALID_PROVIDERS: AuthProviderName[] = [
+  "github",
+  "google",
+  "auth0",
+  "oidc",
+];
+
+/**
+ * Parsed auth configuration (after YAML + env merge).
+ */
+export interface AuthConfig {
+  provider: AuthProviderName;
+  audience: string;
+  resource: string;
+  /** Auth0 tenant domain */
+  domain?: string;
+  /** OIDC issuer */
+  issuer?: string;
+  /** OIDC JWKS URI (optional, derived from issuer if absent) */
+  jwksUri?: string;
+  /** Supported scopes */
+  scopesSupported?: string[];
+}
+
+/**
+ * YAML file schema (top-level has `auth` key).
+ */
+interface ConfigFile {
+  auth?: {
+    provider?: string;
+    audience?: string;
+    resource?: string;
+    domain?: string;
+    issuer?: string;
+    jwksUri?: string;
+    scopesSupported?: string[];
+  };
+}
+
+/**
+ * Load auth configuration from YAML file + env var overrides.
+ *
+ * 1. Reads YAML file (if it exists)
+ * 2. Overlays env vars (MCP_AUTH_* take precedence)
+ * 3. Validates the merged config
+ * 4. Returns null if no auth is configured
+ *
+ * Env var mapping:
+ * - MCP_AUTH_PROVIDER → auth.provider
+ * - MCP_AUTH_AUDIENCE → auth.audience
+ * - MCP_AUTH_RESOURCE → auth.resource
+ * - MCP_AUTH_DOMAIN → auth.domain
+ * - MCP_AUTH_ISSUER → auth.issuer
+ * - MCP_AUTH_JWKS_URI → auth.jwksUri
+ * - MCP_AUTH_SCOPES → auth.scopesSupported (space-separated)
+ *
+ * @param configPath - Path to YAML config file. Defaults to "mcp-server.yaml" in cwd.
+ * @returns AuthConfig or null if no auth configured
+ * @throws Error if config is invalid (fail-fast)
+ */
+export async function loadAuthConfig(
+  configPath?: string,
+): Promise<AuthConfig | null> {
+  // 1. Load YAML (optional - file may not exist)
+  const yamlAuth = await loadYamlAuth(configPath ?? "mcp-server.yaml");
+
+  // 2. Read env vars
+  const envProvider = env("MCP_AUTH_PROVIDER");
+  const envAudience = env("MCP_AUTH_AUDIENCE");
+  const envResource = env("MCP_AUTH_RESOURCE");
+  const envDomain = env("MCP_AUTH_DOMAIN");
+  const envIssuer = env("MCP_AUTH_ISSUER");
+  const envJwksUri = env("MCP_AUTH_JWKS_URI");
+  const envScopes = env("MCP_AUTH_SCOPES");
+
+  // 3. Merge: env overrides YAML
+  const provider = envProvider ?? yamlAuth?.provider;
+
+  // No provider configured anywhere → no auth
+  if (!provider) return null;
+
+  // Validate provider name
+  if (!VALID_PROVIDERS.includes(provider as AuthProviderName)) {
+    throw new Error(
+      `[AuthConfig] Unknown auth provider: "${provider}". ` +
+        `Valid values: ${VALID_PROVIDERS.join(", ")}`,
+    );
+  }
+
+  const audience = envAudience ?? yamlAuth?.audience;
+  const resource = envResource ?? yamlAuth?.resource;
+
+  if (!audience) {
+    throw new Error(
+      `[AuthConfig] "audience" is required when provider="${provider}". ` +
+        "Set auth.audience in YAML or MCP_AUTH_AUDIENCE env var.",
+    );
+  }
+  if (!resource) {
+    throw new Error(
+      `[AuthConfig] "resource" is required when provider="${provider}". ` +
+        "Set auth.resource in YAML or MCP_AUTH_RESOURCE env var.",
+    );
+  }
+
+  const config: AuthConfig = {
+    provider: provider as AuthProviderName,
+    audience,
+    resource,
+    domain: envDomain ?? yamlAuth?.domain,
+    issuer: envIssuer ?? yamlAuth?.issuer,
+    jwksUri: envJwksUri ?? yamlAuth?.jwksUri,
+    scopesSupported: envScopes
+      ? envScopes.split(" ").filter(Boolean)
+      : yamlAuth?.scopesSupported,
+  };
+
+  // Provider-specific validation (fail-fast)
+  if (config.provider === "auth0" && !config.domain) {
+    throw new Error(
+      '[AuthConfig] "domain" is required for auth0 provider. ' +
+        "Set auth.domain in YAML or MCP_AUTH_DOMAIN env var.",
+    );
+  }
+  if (config.provider === "oidc" && !config.issuer) {
+    throw new Error(
+      '[AuthConfig] "issuer" is required for oidc provider. ' +
+        "Set auth.issuer in YAML or MCP_AUTH_ISSUER env var.",
+    );
+  }
+
+  return config;
+}
+
+/**
+ * Create an AuthProvider from a loaded AuthConfig.
+ *
+ * @param config - Validated auth config
+ * @returns AuthProvider instance
+ */
+export function createAuthProviderFromConfig(config: AuthConfig): AuthProvider {
+  const base = {
+    audience: config.audience,
+    resource: config.resource,
+    scopesSupported: config.scopesSupported,
+  };
+
+  switch (config.provider) {
+    case "github":
+      return createGitHubAuthProvider(base);
+    case "google":
+      return createGoogleAuthProvider(base);
+    case "auth0":
+      return createAuth0AuthProvider({ ...base, domain: config.domain! });
+    case "oidc":
+      return createOIDCAuthProvider({
+        ...base,
+        issuer: config.issuer!,
+        jwksUri: config.jwksUri,
+        authorizationServers: [config.issuer!],
+      });
+    default:
+      throw new Error(`[AuthConfig] Unsupported provider: ${config.provider}`);
+  }
+}
+
+/**
+ * Load the auth section from a YAML config file.
+ * Returns null if file doesn't exist (not an error).
+ */
+async function loadYamlAuth(
+  path: string,
+): Promise<ConfigFile["auth"] | null> {
+  // readTextFile returns null if file doesn't exist
+  const text = await readTextFile(path);
+  if (text === null) return null;
+
+  const parsed = parseYaml(text);
+
+  // Validate parsed YAML is an object (not string, array, null, etc.)
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return null;
+  }
+
+  const configFile = parsed as Record<string, unknown>;
+  if (
+    !configFile.auth || typeof configFile.auth !== "object" ||
+    Array.isArray(configFile.auth)
+  ) {
+    return null;
+  }
+
+  const auth = configFile.auth as Record<string, unknown>;
+  return {
+    provider: typeof auth.provider === "string" ? auth.provider : undefined,
+    audience: typeof auth.audience === "string" ? auth.audience : undefined,
+    resource: typeof auth.resource === "string" ? auth.resource : undefined,
+    domain: typeof auth.domain === "string" ? auth.domain : undefined,
+    issuer: typeof auth.issuer === "string" ? auth.issuer : undefined,
+    jwksUri: typeof auth.jwksUri === "string" ? auth.jwksUri : undefined,
+    scopesSupported: Array.isArray(auth.scopesSupported)
+      ? auth.scopesSupported.filter((s: unknown): s is string =>
+        typeof s === "string"
+      )
+      : undefined,
+  };
+}

package/src/auth/jwt-provider.ts

@@ -0,0 +1,175 @@
+/**
+ * JWT Auth Provider using JWKS for token validation.
+ *
+ * Validates JWT tokens against a remote JWKS endpoint,
+ * checking issuer, audience, and expiration.
+ *
+ * @module lib/server/auth/jwt-provider
+ */
+
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import { AuthProvider } from "./provider.js";
+import type { AuthInfo, ProtectedResourceMetadata } from "./types.js";
+import { isOtelEnabled, recordAuthEvent } from "../observability/otel.js";
+
+/**
+ * Configuration for JwtAuthProvider.
+ */
+export interface JwtAuthProviderOptions {
+  /** JWT issuer (iss claim) */
+  issuer: string;
+  /** JWT audience (aud claim) */
+  audience: string;
+  /** JWKS URI for signature validation. Defaults to {issuer}/.well-known/jwks.json */
+  jwksUri?: string;
+  /** Resource identifier for RFC 9728 */
+  resource: string;
+  /** Authorization servers that issue valid tokens */
+  authorizationServers: string[];
+  /** Scopes supported by this server */
+  scopesSupported?: string[];
+}
+
+/**
+ * JWT Auth Provider with JWKS validation.
+ *
+ * @example
+ * ```typescript
+ * const provider = new JwtAuthProvider({
+ *   issuer: "https://accounts.google.com",
+ *   audience: "https://my-mcp.example.com",
+ *   resource: "https://my-mcp.example.com",
+ *   authorizationServers: ["https://accounts.google.com"],
+ * });
+ * ```
+ */
+/**
+ * Cached auth result with expiration
+ */
+interface CachedAuth {
+  authInfo: AuthInfo;
+  expiresAt: number; // ms timestamp
+}
+
+export class JwtAuthProvider extends AuthProvider {
+  private jwks: ReturnType<typeof createRemoteJWKSet>;
+  private options: JwtAuthProviderOptions;
+
+  // Token verification cache: hash(token) → AuthInfo with TTL
+  // Prevents redundant JWKS fetches (network round-trip per tool call)
+  private tokenCache = new Map<string, CachedAuth>();
+  private static readonly MAX_CACHE_SIZE = 1000;
+  private static readonly DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+  constructor(options: JwtAuthProviderOptions) {
+    super();
+
+    if (!options.issuer) {
+      throw new Error("[JwtAuthProvider] issuer is required");
+    }
+    if (!options.audience) {
+      throw new Error("[JwtAuthProvider] audience is required");
+    }
+    if (!options.resource) {
+      throw new Error("[JwtAuthProvider] resource is required");
+    }
+    if (!options.authorizationServers?.length) {
+      throw new Error(
+        "[JwtAuthProvider] at least one authorizationServer is required",
+      );
+    }
+
+    this.options = options;
+    const jwksUri = options.jwksUri ??
+      `${options.issuer}/.well-known/jwks.json`;
+    this.jwks = createRemoteJWKSet(new URL(jwksUri));
+  }
+
+  async verifyToken(token: string): Promise<AuthInfo | null> {
+    // Check cache first (avoids JWKS network round-trip)
+    const cacheKey = await this.hashToken(token);
+    const cached = this.tokenCache.get(cacheKey);
+    if (cached && Date.now() < cached.expiresAt) {
+      if (isOtelEnabled()) {
+        recordAuthEvent("cache_hit", {
+          subject: cached.authInfo.subject ?? "",
+        });
+      }
+      return cached.authInfo;
+    }
+    // Evict expired entry if present
+    if (cached) this.tokenCache.delete(cacheKey);
+
+    try {
+      const { payload } = await jwtVerify(token, this.jwks, {
+        issuer: this.options.issuer,
+        audience: this.options.audience,
+      });
+
+      const authInfo: AuthInfo = {
+        subject: payload.sub ?? "unknown",
+        clientId: (payload.azp as string | undefined) ??
+          (payload.client_id as string | undefined),
+        scopes: this.extractScopes(payload),
+        claims: payload as Record<string, unknown>,
+        expiresAt: payload.exp,
+      };
+
+      // Cache with TTL = min(token remaining lifetime, 5 minutes)
+      const tokenExpiresMs = payload.exp ? payload.exp * 1000 : Infinity;
+      const cacheTtl = Math.min(
+        tokenExpiresMs - Date.now(),
+        JwtAuthProvider.DEFAULT_CACHE_TTL_MS,
+      );
+      if (cacheTtl > 0) {
+        // Evict oldest entries if cache is full
+        if (this.tokenCache.size >= JwtAuthProvider.MAX_CACHE_SIZE) {
+          const oldestKey = this.tokenCache.keys().next().value;
+          if (oldestKey) this.tokenCache.delete(oldestKey);
+        }
+        this.tokenCache.set(cacheKey, {
+          authInfo: Object.freeze(authInfo) as AuthInfo,
+          expiresAt: Date.now() + cacheTtl,
+        });
+      }
+
+      return authInfo;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Hash a token for cache key (avoids storing raw tokens in memory)
+   */
+  private async hashToken(token: string): Promise<string> {
+    const data = new TextEncoder().encode(token);
+    const hash = await crypto.subtle.digest("SHA-256", data);
+    return Array.from(new Uint8Array(hash)).map((b) =>
+      b.toString(16).padStart(2, "0")
+    ).join("");
+  }
+
+  getResourceMetadata(): ProtectedResourceMetadata {
+    return {
+      resource: this.options.resource,
+      authorization_servers: this.options.authorizationServers,
+      scopes_supported: this.options.scopesSupported,
+      bearer_methods_supported: ["header"],
+    };
+  }
+
+  /**
+   * Extract scopes from JWT payload.
+   * Supports: "scope" claim (space-separated string) and "scp" claim (array).
+   */
+  private extractScopes(payload: Record<string, unknown>): string[] {
+    if (typeof payload.scope === "string") {
+      return payload.scope.split(" ").filter(Boolean);
+    }
+    if (Array.isArray(payload.scp)) {
+      return payload.scp.filter((s): s is string => typeof s === "string");
+    }
+    return [];
+  }
+}