@mctx-ai/mcp-server 0.4.0 → 0.5.1

package/dist/index.d.ts

@@ -106,16 +106,33 @@ export interface Server {
   fetch(request: Request, env?: any, ctx?: any): Promise<Response>;
 }
 
+/**
+ * Server configuration options.
+ */
+export interface ServerOptions {
+  /**
+   * Instructions for LLM clients using this server.
+   * Helps guide the LLM on how to use the server's capabilities.
+   *
+   * @example
+   * "This server provides tools for managing customer data. Use list_customers to browse, get_customer to fetch details."
+   */
+  instructions?: string;
+}
+
 /**
  * Creates an MCP server instance.
  *
+ * @param options - Server configuration options
  * @returns Server instance with registration methods and fetch handler
  *
  * @example
  * ```typescript
  * import { createServer, T } from '@mctx-ai/mcp-server';
  *
- * const server = createServer();
+ * const server = createServer({
+ *   instructions: "You help developers debug CI pipelines..."
+ * });
  *
  * server.tool('greet', (args: { name: string }) => {
  *   return `Hello, ${args.name}!`;
@@ -124,7 +141,7 @@ export interface Server {
  * export default { fetch: server.fetch };
  * ```
  */
-export function createServer(): Server;
+export function createServer(options?: ServerOptions): Server;
 
 // ============================================================================
 // Handler Types
@@ -170,7 +187,10 @@ export type ToolHandler = {
  * ```
  */
 export type GeneratorToolHandler = {
-  (args: Record<string, any>, ask?: AskFunction | null): Generator<any, any, any> | AsyncGenerator<any, any, any>;
+  (
+    args: Record<string, any>,
+    ask?: AskFunction | null,
+  ): Generator<any, any, any> | AsyncGenerator<any, any, any>;
   description?: string;
   input?: Record<string, SchemaDefinition>;
   mimeType?: string;
@@ -185,7 +205,10 @@ export type GeneratorToolHandler = {
  * @returns Resource content
  */
 export type ResourceHandler = {
-  (params: Record<string, string>, ask?: AskFunction | null): any | Promise<any>;
+  (
+    params: Record<string, string>,
+    ask?: AskFunction | null,
+  ): any | Promise<any>;
   /** Resource name for display */
   name?: string;
   /** Resource description */
@@ -203,7 +226,14 @@ export type ResourceHandler = {
  * @returns Prompt messages (string, conversation result, or message array)
  */
 export type PromptHandler = {
-  (args: Record<string, any>, ask?: AskFunction | null): string | ConversationResult | Message[] | Promise<string | ConversationResult | Message[]>;
+  (
+    args: Record<string, any>,
+    ask?: AskFunction | null,
+  ):
+    | string
+    | ConversationResult
+    | Message[]
+    | Promise<string | ConversationResult | Message[]>;
   /** Prompt description */
   description?: string;
   /** Input schema definition using T types */
@@ -274,7 +304,7 @@ export interface SamplingOptions {
  * Represents a JSON Schema property with optional metadata.
  */
 export interface SchemaDefinition {
-  type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+  type: "string" | "number" | "boolean" | "array" | "object";
   description?: string;
   enum?: any[];
   default?: any;
@@ -460,7 +490,7 @@ export const T: {
  * ```
  */
 export function buildInputSchema(input?: Record<string, SchemaDefinition>): {
-  type: 'object';
+  type: "object";
   properties: Record<string, SchemaDefinition>;
   required?: string[];
 };
@@ -474,7 +504,7 @@ export function buildInputSchema(input?: Record<string, SchemaDefinition>): {
  */
 export interface Message {
   /** Message role */
-  role: 'user' | 'assistant';
+  role: "user" | "assistant";
   /** Message content */
   content: TextContent | ImageContent | ResourceContent;
 }
@@ -483,7 +513,7 @@ export interface Message {
  * Text content type.
  */
 export interface TextContent {
-  type: 'text';
+  type: "text";
   text: string;
 }
 
@@ -491,7 +521,7 @@ export interface TextContent {
  * Image content type (base64-encoded).
  */
 export interface ImageContent {
-  type: 'image';
+  type: "image";
   data: string;
   mimeType: string;
 }
@@ -500,7 +530,7 @@ export interface ImageContent {
  * Resource content type (embedded resource).
  */
 export interface ResourceContent {
-  type: 'resource';
+  type: "resource";
   resource: {
     uri: string;
     text: string;
@@ -571,7 +601,7 @@ export interface ConversationHelpers {
  * ```
  */
 export function conversation(
-  builderFn: (helpers: ConversationHelpers) => Message[]
+  builderFn: (helpers: ConversationHelpers) => Message[],
 ): ConversationResult;
 
 // ============================================================================
@@ -583,7 +613,7 @@ export function conversation(
  * Yielded by generator tools to report progress.
  */
 export interface ProgressNotification {
-  type: 'progress';
+  type: "progress";
   /** Current step number (1-indexed) */
   progress: number;
   /** Total steps (optional, for determinate progress) */
@@ -649,7 +679,15 @@ export const PROGRESS_DEFAULTS: {
 /**
  * Log severity level (RFC 5424).
  */
-export type LogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';
+export type LogLevel =
+  | "debug"
+  | "info"
+  | "notice"
+  | "warning"
+  | "error"
+  | "critical"
+  | "alert"
+  | "emergency";
 
 /**
  * Log object with methods for each severity level.

package/dist/security.js

@@ -187,18 +187,18 @@ export function validateStringInput(value, maxLength = 10485760) {
 }
 
 /**
- * Validate URI scheme against allowlist
+ * Validate URI scheme against denylist
  *
  * Security: Prevents injection attacks via dangerous URI schemes
- * - Blocks file://, javascript:, data:, etc. by default
- * - Allows http:// and https:// by default
- * - Supports custom allowlists for special cases
+ * - Blocks file://, javascript:, data:, vbscript:, about: by default
+ * - Allows all other schemes (http://, https://, custom schemes like docs://)
+ * - MCP spec explicitly supports custom URI schemes for resources
+ * - Validates scheme format per RFC 3986
  *
  * @param {string} uri - URI to validate
- * @param {string[]} allowedSchemes - Allowed schemes (default: ['http', 'https'])
- * @returns {boolean} True if URI scheme is allowed
+ * @returns {boolean} True if URI scheme is safe (not in denylist)
  */
-export function validateUriScheme(uri, allowedSchemes = ["http", "https"]) {
+export function validateUriScheme(uri) {
   if (!uri || typeof uri !== "string") return false;
 
   // Extract scheme (characters before first colon)
@@ -207,13 +207,25 @@ export function validateUriScheme(uri, allowedSchemes = ["http", "https"]) {
 
   const scheme = schemeMatch[1].toLowerCase();
 
+  // RFC 3986: scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
+  // Must start with a letter, followed by letters, digits, +, -, or .
+  const schemeRegex = /^[a-z][a-z0-9+.-]*$/;
+  if (!schemeRegex.test(scheme)) {
+    return false;
+  }
+
+  // Reasonable length limit to prevent abuse
+  if (scheme.length > 32) {
+    return false;
+  }
+
   // Check if scheme is explicitly dangerous
   if (DANGEROUS_SCHEMES.includes(scheme)) {
     return false;
   }
 
-  // Check if scheme is in allowlist
-  return allowedSchemes.some((allowed) => allowed.toLowerCase() === scheme);
+  // All other schemes (including custom ones) are allowed
+  return true;
 }
 
 /**

package/dist/server.js

@@ -132,9 +132,13 @@ function paginate(items, cursor, pageSize = 50) {
 
 /**
  * Create MCP server instance
+ * @param {Object} [options] - Server configuration options
+ * @param {string} [options.instructions] - Server instructions for LLM clients
  * @returns {Object} Server app with registration methods and fetch handler
  */
-export function createServer() {
+export function createServer(options = {}) {
+  const { instructions } = options;
+
   // Internal registries
   const tools = new Map();
   const resources = new Map();
@@ -434,24 +438,30 @@ export function createServer() {
     // Validate URI scheme (prevent dangerous schemes like file://, javascript:, data:)
     if (!validateUriScheme(uri)) {
       throw new Error(
-        `Invalid URI scheme: only http:// and https:// are allowed`,
+        `Disallowed URI scheme: dangerous schemes like file://, javascript:, data: are not allowed`,
       );
     }
 
-    // Canonicalize path to prevent traversal attacks
-    const canonicalUri = canonicalizePath(uri);
+    // Apply canonicalizePath to ALL URIs for consistent security validation
+    // This catches: null bytes, Unicode variants, multi-layer encoding, mixed encoding
+    // Path normalization (slash deduplication, backslash conversion) is safe for all schemes
+    const normalizedUri = canonicalizePath(uri);
 
     // Find matching resource (try exact match first, then templates)
     let handler = null;
     let extractedParams = {};
 
-    // Try exact match first (use canonical URI for matching)
-    if (resources.has(canonicalUri)) {
-      handler = resources.get(canonicalUri);
+    // Try exact match first (use normalized URI for matching)
+    if (resources.has(normalizedUri)) {
+      handler = resources.get(normalizedUri);
     } else {
       // Try template matching using uri.js module
+      // Canonicalize registered URIs for consistent matching
       for (const [registeredUri, h] of resources.entries()) {
-        const match = matchUri(registeredUri, canonicalUri);
+        // Canonicalize the registered URI for comparison
+        // This ensures consistent matching regardless of registration format
+        const normalizedRegisteredUri = canonicalizePath(registeredUri);
+        const match = matchUri(normalizedRegisteredUri, normalizedUri);
         if (match) {
           handler = h;
           extractedParams = match.params || {};
@@ -678,6 +688,55 @@ export function createServer() {
     return {}; // Success
   }
 
+  /**
+   * Handle initialize request
+   * Auto-detects capabilities from registered tools/resources/prompts
+   * @param {Object} _params - Initialize params (clientInfo, etc.)
+   * @returns {Object} Server capabilities and info
+   */
+  function handleInitialize(_params) {
+    // Build capabilities object by detecting what's registered
+    const capabilities = {};
+
+    // Add tools capability if any tools are registered
+    if (tools.size > 0) {
+      capabilities.tools = {};
+    }
+
+    // Add resources capability if any resources are registered
+    if (resources.size > 0) {
+      capabilities.resources = {
+        subscribe: false, // Resource subscriptions not supported yet
+        listChanged: false, // Resource change notifications not supported yet
+      };
+    }
+
+    // Add prompts capability if any prompts are registered
+    if (prompts.size > 0) {
+      capabilities.prompts = {};
+    }
+
+    // Always include logging capability
+    capabilities.logging = {};
+
+    // Build response
+    const response = {
+      protocolVersion: "2024-11-05",
+      capabilities,
+      serverInfo: {
+        name: "@mctx-ai/mcp-server",
+        version: "0.3.0",
+      },
+    };
+
+    // Include instructions if provided
+    if (instructions) {
+      response.instructions = instructions;
+    }
+
+    return response;
+  }
+
   /**
    * Route JSON-RPC request to appropriate handler
    * @param {Object} request - JSON-RPC request
@@ -687,6 +746,17 @@ export function createServer() {
     const { method, params, _meta } = request;
 
     switch (method) {
+      case "initialize":
+        return handleInitialize(params);
+
+      case "initialized":
+        // Notification - no response needed
+        return null;
+
+      case "ping":
+        // Respond to ping with empty result
+        return {};
+
       case "tools/list":
         return handleToolsList(params);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mctx-ai/mcp-server",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Build MCP servers with an Express-like API — no protocol knowledge required",
   "type": "module",
   "main": "./src/index.js",

package/src/index.d.ts

@@ -106,16 +106,33 @@ export interface Server {
   fetch(request: Request, env?: any, ctx?: any): Promise<Response>;
 }
 
+/**
+ * Server configuration options.
+ */
+export interface ServerOptions {
+  /**
+   * Instructions for LLM clients using this server.
+   * Helps guide the LLM on how to use the server's capabilities.
+   *
+   * @example
+   * "This server provides tools for managing customer data. Use list_customers to browse, get_customer to fetch details."
+   */
+  instructions?: string;
+}
+
 /**
  * Creates an MCP server instance.
  *
+ * @param options - Server configuration options
  * @returns Server instance with registration methods and fetch handler
  *
  * @example
  * ```typescript
  * import { createServer, T } from '@mctx-ai/mcp-server';
  *
- * const server = createServer();
+ * const server = createServer({
+ *   instructions: "You help developers debug CI pipelines..."
+ * });
  *
  * server.tool('greet', (args: { name: string }) => {
  *   return `Hello, ${args.name}!`;
@@ -124,7 +141,7 @@ export interface Server {
  * export default { fetch: server.fetch };
  * ```
  */
-export function createServer(): Server;
+export function createServer(options?: ServerOptions): Server;
 
 // ============================================================================
 // Handler Types
@@ -170,7 +187,10 @@ export type ToolHandler = {
  * ```
  */
 export type GeneratorToolHandler = {
-  (args: Record<string, any>, ask?: AskFunction | null): Generator<any, any, any> | AsyncGenerator<any, any, any>;
+  (
+    args: Record<string, any>,
+    ask?: AskFunction | null,
+  ): Generator<any, any, any> | AsyncGenerator<any, any, any>;
   description?: string;
   input?: Record<string, SchemaDefinition>;
   mimeType?: string;
@@ -185,7 +205,10 @@ export type GeneratorToolHandler = {
  * @returns Resource content
  */
 export type ResourceHandler = {
-  (params: Record<string, string>, ask?: AskFunction | null): any | Promise<any>;
+  (
+    params: Record<string, string>,
+    ask?: AskFunction | null,
+  ): any | Promise<any>;
   /** Resource name for display */
   name?: string;
   /** Resource description */
@@ -203,7 +226,14 @@ export type ResourceHandler = {
  * @returns Prompt messages (string, conversation result, or message array)
  */
 export type PromptHandler = {
-  (args: Record<string, any>, ask?: AskFunction | null): string | ConversationResult | Message[] | Promise<string | ConversationResult | Message[]>;
+  (
+    args: Record<string, any>,
+    ask?: AskFunction | null,
+  ):
+    | string
+    | ConversationResult
+    | Message[]
+    | Promise<string | ConversationResult | Message[]>;
   /** Prompt description */
   description?: string;
   /** Input schema definition using T types */
@@ -274,7 +304,7 @@ export interface SamplingOptions {
  * Represents a JSON Schema property with optional metadata.
  */
 export interface SchemaDefinition {
-  type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+  type: "string" | "number" | "boolean" | "array" | "object";
   description?: string;
   enum?: any[];
   default?: any;
@@ -460,7 +490,7 @@ export const T: {
  * ```
  */
 export function buildInputSchema(input?: Record<string, SchemaDefinition>): {
-  type: 'object';
+  type: "object";
   properties: Record<string, SchemaDefinition>;
   required?: string[];
 };
@@ -474,7 +504,7 @@ export function buildInputSchema(input?: Record<string, SchemaDefinition>): {
  */
 export interface Message {
   /** Message role */
-  role: 'user' | 'assistant';
+  role: "user" | "assistant";
   /** Message content */
   content: TextContent | ImageContent | ResourceContent;
 }
@@ -483,7 +513,7 @@ export interface Message {
  * Text content type.
  */
 export interface TextContent {
-  type: 'text';
+  type: "text";
   text: string;
 }
 
@@ -491,7 +521,7 @@ export interface TextContent {
  * Image content type (base64-encoded).
  */
 export interface ImageContent {
-  type: 'image';
+  type: "image";
   data: string;
   mimeType: string;
 }
@@ -500,7 +530,7 @@ export interface ImageContent {
  * Resource content type (embedded resource).
  */
 export interface ResourceContent {
-  type: 'resource';
+  type: "resource";
   resource: {
     uri: string;
     text: string;
@@ -571,7 +601,7 @@ export interface ConversationHelpers {
  * ```
  */
 export function conversation(
-  builderFn: (helpers: ConversationHelpers) => Message[]
+  builderFn: (helpers: ConversationHelpers) => Message[],
 ): ConversationResult;
 
 // ============================================================================
@@ -583,7 +613,7 @@ export function conversation(
  * Yielded by generator tools to report progress.
  */
 export interface ProgressNotification {
-  type: 'progress';
+  type: "progress";
   /** Current step number (1-indexed) */
   progress: number;
   /** Total steps (optional, for determinate progress) */
@@ -649,7 +679,15 @@ export const PROGRESS_DEFAULTS: {
 /**
  * Log severity level (RFC 5424).
  */
-export type LogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';
+export type LogLevel =
+  | "debug"
+  | "info"
+  | "notice"
+  | "warning"
+  | "error"
+  | "critical"
+  | "alert"
+  | "emergency";
 
 /**
  * Log object with methods for each severity level.

package/src/security.js

@@ -187,18 +187,18 @@ export function validateStringInput(value, maxLength = 10485760) {
 }
 
 /**
- * Validate URI scheme against allowlist
+ * Validate URI scheme against denylist
  *
  * Security: Prevents injection attacks via dangerous URI schemes
- * - Blocks file://, javascript:, data:, etc. by default
- * - Allows http:// and https:// by default
- * - Supports custom allowlists for special cases
+ * - Blocks file://, javascript:, data:, vbscript:, about: by default
+ * - Allows all other schemes (http://, https://, custom schemes like docs://)
+ * - MCP spec explicitly supports custom URI schemes for resources
+ * - Validates scheme format per RFC 3986
  *
  * @param {string} uri - URI to validate
- * @param {string[]} allowedSchemes - Allowed schemes (default: ['http', 'https'])
- * @returns {boolean} True if URI scheme is allowed
+ * @returns {boolean} True if URI scheme is safe (not in denylist)
  */
-export function validateUriScheme(uri, allowedSchemes = ["http", "https"]) {
+export function validateUriScheme(uri) {
   if (!uri || typeof uri !== "string") return false;
 
   // Extract scheme (characters before first colon)
@@ -207,13 +207,25 @@ export function validateUriScheme(uri, allowedSchemes = ["http", "https"]) {
 
   const scheme = schemeMatch[1].toLowerCase();
 
+  // RFC 3986: scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
+  // Must start with a letter, followed by letters, digits, +, -, or .
+  const schemeRegex = /^[a-z][a-z0-9+.-]*$/;
+  if (!schemeRegex.test(scheme)) {
+    return false;
+  }
+
+  // Reasonable length limit to prevent abuse
+  if (scheme.length > 32) {
+    return false;
+  }
+
   // Check if scheme is explicitly dangerous
   if (DANGEROUS_SCHEMES.includes(scheme)) {
     return false;
   }
 
-  // Check if scheme is in allowlist
-  return allowedSchemes.some((allowed) => allowed.toLowerCase() === scheme);
+  // All other schemes (including custom ones) are allowed
+  return true;
 }
 
 /**

package/src/server.js

@@ -132,9 +132,13 @@ function paginate(items, cursor, pageSize = 50) {
 
 /**
  * Create MCP server instance
+ * @param {Object} [options] - Server configuration options
+ * @param {string} [options.instructions] - Server instructions for LLM clients
  * @returns {Object} Server app with registration methods and fetch handler
  */
-export function createServer() {
+export function createServer(options = {}) {
+  const { instructions } = options;
+
   // Internal registries
   const tools = new Map();
   const resources = new Map();
@@ -434,24 +438,30 @@ export function createServer() {
     // Validate URI scheme (prevent dangerous schemes like file://, javascript:, data:)
     if (!validateUriScheme(uri)) {
       throw new Error(
-        `Invalid URI scheme: only http:// and https:// are allowed`,
+        `Disallowed URI scheme: dangerous schemes like file://, javascript:, data: are not allowed`,
       );
     }
 
-    // Canonicalize path to prevent traversal attacks
-    const canonicalUri = canonicalizePath(uri);
+    // Apply canonicalizePath to ALL URIs for consistent security validation
+    // This catches: null bytes, Unicode variants, multi-layer encoding, mixed encoding
+    // Path normalization (slash deduplication, backslash conversion) is safe for all schemes
+    const normalizedUri = canonicalizePath(uri);
 
     // Find matching resource (try exact match first, then templates)
     let handler = null;
     let extractedParams = {};
 
-    // Try exact match first (use canonical URI for matching)
-    if (resources.has(canonicalUri)) {
-      handler = resources.get(canonicalUri);
+    // Try exact match first (use normalized URI for matching)
+    if (resources.has(normalizedUri)) {
+      handler = resources.get(normalizedUri);
     } else {
       // Try template matching using uri.js module
+      // Canonicalize registered URIs for consistent matching
       for (const [registeredUri, h] of resources.entries()) {
-        const match = matchUri(registeredUri, canonicalUri);
+        // Canonicalize the registered URI for comparison
+        // This ensures consistent matching regardless of registration format
+        const normalizedRegisteredUri = canonicalizePath(registeredUri);
+        const match = matchUri(normalizedRegisteredUri, normalizedUri);
         if (match) {
           handler = h;
           extractedParams = match.params || {};
@@ -678,6 +688,55 @@ export function createServer() {
     return {}; // Success
   }
 
+  /**
+   * Handle initialize request
+   * Auto-detects capabilities from registered tools/resources/prompts
+   * @param {Object} _params - Initialize params (clientInfo, etc.)
+   * @returns {Object} Server capabilities and info
+   */
+  function handleInitialize(_params) {
+    // Build capabilities object by detecting what's registered
+    const capabilities = {};
+
+    // Add tools capability if any tools are registered
+    if (tools.size > 0) {
+      capabilities.tools = {};
+    }
+
+    // Add resources capability if any resources are registered
+    if (resources.size > 0) {
+      capabilities.resources = {
+        subscribe: false, // Resource subscriptions not supported yet
+        listChanged: false, // Resource change notifications not supported yet
+      };
+    }
+
+    // Add prompts capability if any prompts are registered
+    if (prompts.size > 0) {
+      capabilities.prompts = {};
+    }
+
+    // Always include logging capability
+    capabilities.logging = {};
+
+    // Build response
+    const response = {
+      protocolVersion: "2024-11-05",
+      capabilities,
+      serverInfo: {
+        name: "@mctx-ai/mcp-server",
+        version: "0.3.0",
+      },
+    };
+
+    // Include instructions if provided
+    if (instructions) {
+      response.instructions = instructions;
+    }
+
+    return response;
+  }
+
   /**
    * Route JSON-RPC request to appropriate handler
    * @param {Object} request - JSON-RPC request
@@ -687,6 +746,17 @@ export function createServer() {
     const { method, params, _meta } = request;
 
     switch (method) {
+      case "initialize":
+        return handleInitialize(params);
+
+      case "initialized":
+        // Notification - no response needed
+        return null;
+
+      case "ping":
+        // Respond to ping with empty result
+        return {};
+
       case "tools/list":
         return handleToolsList(params);