@mctx-ai/mcp-server 0.4.0 → 0.5.0

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

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();
@@ -678,6 +682,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 +740,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.0",
   "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

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();
@@ -678,6 +682,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 +740,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);