@amitdeshmukh/ax-crew 3.10.0 → 3.11.1

package/CHANGELOG.md

@@ -5,6 +5,29 @@ This Changelog format is based on [Keep a Changelog]
 adheres to [Semantic Versioning](https://semver.org/spec/
 v2.0.0.html).
 
+## [3.11.1] - 2025-06-04
+
+### Changed
+- Updated MCP (Model Context Protocol) transport implementation to support current ax-llm/ax framework
+- Replaced deprecated `AxMCPHTTPTransport` with `AxMCPHTTPSSETransport` for HTTP SSE transport
+- Added support for `AxMCPStreambleHTTPTransport` for streamable HTTP communication
+- Enhanced MCP configuration with proper TypeScript types using `AxMCPStreamableHTTPTransportOptions`
+- Updated transport configuration to use `mcpEndpoint` parameter for streamable HTTP transport
+
+### Removed
+- Removed all references to deprecated `MCPHTTPTransportConfig` interface
+- Cleaned up deprecated MCP transport type definitions
+
+### Added
+- Comprehensive MCP documentation in README.md with examples for all transport types
+- Added examples for STDIO, HTTP SSE, and streamable HTTP transport configurations
+- Enhanced MCP server configuration examples including filesystem, search, and database servers
+- Added migration guide for users upgrading from deprecated transport types
+
+### Fixed
+- Improved type safety for MCP transport configurations
+- Enhanced error handling for unsupported MCP transport types
+
 ## [3.10.0] - 2025-05-28
 
 ### Added

package/README.md

@@ -424,6 +424,247 @@ Key streaming features:
 - Compatible with all agent types and configurations
 - Maintains cost tracking and state management functionality
 
+### Model Context Protocol (MCP) Support
+
+AxCrew provides built-in support for the Model Context Protocol (MCP), allowing agents to connect to and use MCP servers for enhanced functionality. MCP enables agents to access external tools, data sources, and services in a standardized way.
+
+#### Supported Transport Types
+
+AxCrew supports three MCP transport types, replacing the deprecated `AxMCPHTTPTransport`:
+
+1. **AxMCPStdioTransport** - For standard input/output communication
+2. **AxMCPHTTPSSETransport** - For HTTP with Server-Sent Events
+3. **AxMCPStreambleHTTPTransport** - For streamable HTTP communication
+
+#### Configuration
+
+Add MCP servers to your agent configuration using the `mcpServers` field:
+
+##### STDIO Transport Configuration
+
+For MCP servers that communicate via standard input/output:
+
+```json
+{
+  "name": "DataAnalyst",
+  "description": "Analyzes data using MCP tools",
+  "signature": "data:string -> analysis:string",
+  "provider": "openai",
+  "providerKeyName": "OPENAI_API_KEY",
+  "ai": {
+    "model": "gpt-4",
+    "temperature": 0
+  },
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"],
+      "env": {
+        "NODE_ENV": "production"
+      }
+    },
+    "brave-search": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-brave-search"]
+    }
+  }
+}
+```
+
+##### HTTP SSE Transport Configuration
+
+For MCP servers accessible via HTTP with Server-Sent Events:
+
+```json
+{
+  "name": "WebAnalyst",
+  "description": "Analyzes web content using MCP tools",
+  "signature": "url:string -> analysis:string",
+  "provider": "anthropic",
+  "providerKeyName": "ANTHROPIC_API_KEY",
+  "ai": {
+    "model": "claude-3-haiku",
+    "temperature": 0
+  },
+  "mcpServers": {
+    "api-server": {
+      "sseUrl": "https://api.example.com/mcp/sse"
+    }
+  }
+}
+```
+
+##### Streamable HTTP Transport Configuration
+
+For MCP servers that support streamable HTTP communication:
+
+```json
+{
+  "name": "StreamAnalyst",
+  "description": "Processes streaming data using MCP tools",
+  "signature": "stream:string -> results:string",
+  "provider": "google-gemini",
+  "providerKeyName": "GEMINI_API_KEY",
+  "ai": {
+    "model": "gemini-1.5-pro",
+    "temperature": 0
+  },
+  "mcpServers": {
+    "stream-processor": {
+      "mcpEndpoint": "http://localhost:3002/stream",
+      "options": {
+        "authorization": "Bearer ey.JhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..-1234567890.1234567890",
+        "headers": { // Custom headers to include with all HTTP requests Note: Content-Type, Accept, and Mcp-Session-Id are managed automatically
+          "X-Custom-Header": "custom-value"
+        }
+      }
+    }
+  }
+}
+```
+
+##### Mixed Transport Configuration
+
+You can use multiple transport types within the same agent:
+
+```json
+{
+  "name": "MultiModalAgent",
+  "description": "Uses multiple MCP servers with different transports",
+  "signature": "task:string -> result:string",
+  "provider": "openai",
+  "providerKeyName": "OPENAI_API_KEY",
+  "ai": {
+    "model": "gpt-4",
+    "temperature": 0
+  },
+  "mcpServers": {
+    "local-files": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
+    },
+    "web-search": {
+      "sseUrl": "http://localhost:3001/sse"
+    },
+    "data-stream": {
+      "mcpEndpoint": "http://localhost:3002/stream"
+    }
+  }
+}
+```
+
+#### MCP Server Examples
+
+Here are some popular MCP servers you can use:
+
+**Filesystem Server** (STDIO):
+```json
+"filesystem": {
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
+}
+```
+
+**Brave Search Server** (STDIO):
+```json
+"brave-search": {
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+  "env": {
+    "BRAVE_API_KEY": "your-brave-api-key"
+  }
+}
+```
+
+**GitHub Server** (STDIO):
+```json
+"github": {
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-github"],
+  "env": {
+    "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token"
+  }
+}
+```
+
+**PostgreSQL Server** (STDIO):
+```json
+"postgres": {
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-postgres"],
+  "env": {
+    "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost/db"
+  }
+}
+```
+
+#### Usage in Code
+
+MCP functions are automatically available to agents once the servers are configured:
+
+```javascript
+import { AxCrew } from '@amitdeshmukh/ax-crew';
+
+// Create crew with MCP-enabled agents
+const crew = new AxCrew('./agentConfig.json');
+await crew.addAgent('DataAnalyst'); // Agent with MCP servers configured
+
+const analyst = crew.agents.get('DataAnalyst');
+
+// The agent can now use MCP functions automatically
+const response = await analyst.forward({
+  data: "Please analyze the sales data in /workspace/sales.csv"
+});
+// The agent will automatically use the filesystem MCP server to read the file
+// and any other configured MCP tools for analysis
+```
+
+#### Best Practices
+
+1. **Environment Variables**: Store sensitive information like API keys in environment variables rather than in the configuration file.
+
+2. **Path Security**: For filesystem servers, always specify allowed paths to prevent unauthorized file access.
+
+3. **Server Health**: Implement health checks for HTTP-based MCP servers to ensure reliability.
+
+4. **Error Handling**: MCP server failures are handled gracefully - agents will continue to work with available tools.
+
+5. **Debugging**: Enable debug mode to see MCP server initialization and communication logs:
+```json
+{
+  "debug": true,
+  "mcpServers": { ... }
+}
+```
+
+#### Migration from Deprecated Transport
+
+If you're upgrading from the deprecated `AxMCPHTTPTransport`, update your configuration:
+
+**Before (deprecated):**
+```json
+"mcpServers": {
+  "my-server": {
+    "sseUrl": "http://localhost:3001/sse"
+  }
+}
+```
+
+**After (current):**
+The configuration remains the same - the transport type is automatically detected and `AxMCPHTTPSSETransport` is used for `sseUrl` configurations. No changes to your configuration files are needed.
+
+For new streamable HTTP servers, use:
+```json
+"mcpServers": {
+  "my-stream-server": {
+    "mcpEndpoint": "http://localhost:3002/stream",
+    "options": {
+      "timeout": 30000
+    }
+  }
+}
+```
+
 ### Tracking Usage Costs
 
 The package provides precise cost tracking capabilities for monitoring API usage across individual agents and the entire crew. Costs are calculated using high-precision decimal arithmetic to ensure accuracy.

package/agentConfig.json

@@ -108,6 +108,33 @@
           "solution": "Let's solve this step by step:\n1. The cube root of a number is a value that, when multiplied by itself twice, gives the original number\n2. For 27, we need to find a number that when cubed equals 27\n3. 3 × 3 × 3 = 27\nTherefore, the cube root of 27 is 3"
         }
       ]
+    },
+    {
+      "name": "DataAnalyst",
+      "description": "Analyzes data using MCP tools for file access and web search",
+      "signature": "analysisRequest:string \"a request to analyze data from files or web sources\" -> analysis:string \"detailed analysis with insights\"",
+      "provider": "openai",
+      "providerKeyName": "OPENAI_API_KEY",
+      "ai": {
+        "model": "gpt-4o-mini",
+        "temperature": 0
+      },
+      "options": {
+        "debug": true
+      },
+      "mcpServers": {
+        "filesystem": {
+          "command": "npx",
+          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+        },
+        "brave-search": {
+          "command": "npx",
+          "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+          "env": {
+            "BRAVE_API_KEY": "sk-1234567890"
+          }
+        }
+      }
     }
   ]
 }

package/dist/agents/agentConfig.d.ts

@@ -1,9 +1,10 @@
 import type { AxFunction } from '@ax-llm/ax';
-import type { AgentConfig, CrewConfigInput, FunctionRegistryType, MCPTransportConfig, MCPStdioTransportConfig, MCPHTTPTransportConfig } from '../types.js';
+import type { AgentConfig, CrewConfigInput, FunctionRegistryType, MCPTransportConfig, MCPStdioTransportConfig, MCPHTTPSSETransportConfig, MCPStreambleHTTPTransportConfig } from '../types.js';
 declare const AIConstructors: Record<string, any>;
 export type Provider = keyof typeof AIConstructors;
 export declare function isStdioTransport(config: MCPTransportConfig): config is MCPStdioTransportConfig;
-export declare function isHTTPTransport(config: MCPTransportConfig): config is MCPHTTPTransportConfig;
+export declare function isHTTPSSETransport(config: MCPTransportConfig): config is MCPHTTPSSETransportConfig;
+export declare function isStreambleHTTPTransport(config: MCPTransportConfig): config is MCPStreambleHTTPTransportConfig;
 /**
  * Parses and returns the AxCrew config from either a JSON config file or a direct JSON object.
  * @param {CrewConfigInput} input - Either a path to the agent config json file or a JSON object with crew configuration.

package/dist/agents/agentConfig.js

@@ -2,7 +2,7 @@ import fs from 'fs';
 // Import all the providers
 import { AxAIAnthropic, AxAIOpenAI, AxAIAzureOpenAI, AxAICohere, AxAIDeepSeek, AxAIGoogleGemini, AxAIGroq, AxAIHuggingFace, AxAIMistral, AxAIOllama, AxAITogether, AxAIReka, AxAIGrok } from '@ax-llm/ax';
 // Import the MCP client and transports
-import { AxMCPClient, AxMCPStdioTransport, AxMCPHTTPTransport } from '@ax-llm/ax';
+import { AxMCPClient, AxMCPStdioTransport, AxMCPHTTPSSETransport, AxMCPStreambleHTTPTransport } from '@ax-llm/ax';
 import { PROVIDER_API_KEYS } from '../config/index.js';
 // Define a mapping from provider names to their respective constructors
 const AIConstructors = {
@@ -24,10 +24,14 @@ const AIConstructors = {
 export function isStdioTransport(config) {
     return 'command' in config;
 }
-// Type guard to check if config is http transport
-export function isHTTPTransport(config) {
+// Type guard to check if config is HTTP SSE transport (also handles legacy HTTP transport)
+export function isHTTPSSETransport(config) {
     return 'sseUrl' in config;
 }
+// Type guard to check if config is streamable HTTP transport
+export function isStreambleHTTPTransport(config) {
+    return 'mcpEndpoint' in config;
+}
 /**
  * Type guard to check if a value is a constructor function for a type T.
  *
@@ -97,8 +101,12 @@ const initializeMCPServers = async (agentConfigData) => {
                     env: mcpServerConfig.env
                 });
             }
-            else if (isHTTPTransport(mcpServerConfig)) {
-                transport = new AxMCPHTTPTransport(mcpServerConfig.sseUrl);
+            else if (isStreambleHTTPTransport(mcpServerConfig)) {
+                transport = new AxMCPStreambleHTTPTransport(mcpServerConfig.mcpEndpoint, mcpServerConfig.options);
+            }
+            else if (isHTTPSSETransport(mcpServerConfig)) {
+                // This handles both new SSE transport and legacy HTTP transport (both use sseUrl)
+                transport = new AxMCPHTTPSSETransport(mcpServerConfig.sseUrl);
             }
             else {
                 throw new Error(`Unsupported transport type: ${JSON.stringify(mcpServerConfig)}`);

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { AxFunction, AxSignature, AxModelConfig } from '@ax-llm/ax';
+import type { AxFunction, AxSignature, AxModelConfig, AxMCPStreamableHTTPTransportOptions } from '@ax-llm/ax';
 import type { Provider } from './agents/agentConfig.js';
 /**
  * A state instance that is shared between agents.
@@ -103,15 +103,30 @@ interface MCPStdioTransportConfig {
     args?: string[];
     env?: NodeJS.ProcessEnv;
 }
-interface MCPHTTPTransportConfig {
+/**
+ * Config for an HTTP SSE MCP server.
+ *
+ * @property {string} sseUrl - The SSE URL for the MCP server.
+ */
+interface MCPHTTPSSETransportConfig {
     sseUrl: string;
 }
+/**
+ * Config for a streamable HTTP MCP server.
+ *
+ * @property {string} mcpEndpoint - The HTTP endpoint URL for the MCP server.
+ * @property {AxMCPStreamableHTTPTransportOptions} options - Optional transport options.
+ */
+interface MCPStreambleHTTPTransportConfig {
+    mcpEndpoint: string;
+    options?: AxMCPStreamableHTTPTransportOptions;
+}
 /**
  * Config for an MCP server.
  *
- * @property {MCPStdioTransportConfig | MCPHTTPTransportConfig} config - The config for the MCP server. Config can be either a stdio or http transport.
+ * @property {MCPStdioTransportConfig | MCPHTTPSSETransportConfig | MCPStreambleHTTPTransportConfig} config - The config for the MCP server. Config can be either stdio, http-sse, or streamable http transport.
  */
-type MCPTransportConfig = MCPStdioTransportConfig | MCPHTTPTransportConfig;
+type MCPTransportConfig = MCPStdioTransportConfig | MCPHTTPSSETransportConfig | MCPStreambleHTTPTransportConfig;
 /**
  * The configuration for an agent.
  *
@@ -152,4 +167,4 @@ interface AgentConfig {
 type CrewConfigInput = string | {
     crew: AgentConfig[];
 };
-export { type AgentConfig, type CrewConfigInput, type AggregatedMetrics, type StateInstance, type FunctionRegistryType, type MCPStdioTransportConfig, type MCPHTTPTransportConfig, type MCPTransportConfig, type ModelUsage, type ModelInfo, type UsageCost, type AggregatedCosts };
+export { type AgentConfig, type CrewConfigInput, type AggregatedMetrics, type StateInstance, type FunctionRegistryType, type MCPStdioTransportConfig, type MCPHTTPSSETransportConfig, type MCPStreambleHTTPTransportConfig, type MCPTransportConfig, type ModelUsage, type ModelInfo, type UsageCost, type AggregatedCosts };

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@amitdeshmukh/ax-crew",
-  "version": "3.10.0",
+  "version": "3.11.1",
   "description": "Build and launch a crew of AI agents with shared state. Built with axllm.dev",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,14 +17,12 @@
     "test:ui": "vitest --ui"
   },
   "dependencies": {
+    "@ax-llm/ax": "^11.0.50",
     "decimal.js": "^10.5.0",
     "dotenv": "^16.4.5",
     "upgrade": "^1.1.0",
     "uuid": "^10.0.0"
   },
-  "peerDependencies": {
-    "@ax-llm/ax": "^11.0.47"
-  },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",
     "@types/node": "^20.14.9",

package/src/agents/agentConfig.ts

@@ -4,7 +4,7 @@ import { AxAIAnthropic, AxAIOpenAI, AxAIAzureOpenAI, AxAICohere, AxAIDeepSeek, A
 // Import Ax types
 import type { AxFunction } from '@ax-llm/ax';
 // Import the MCP client and transports
-import { AxMCPClient, AxMCPStdioTransport, AxMCPHTTPTransport } from '@ax-llm/ax'
+import { AxMCPClient, AxMCPStdioTransport, AxMCPHTTPSSETransport, AxMCPStreambleHTTPTransport } from '@ax-llm/ax'
 import { PROVIDER_API_KEYS } from '../config/index.js';
 import type { 
   AgentConfig,
@@ -12,7 +12,8 @@ import type {
   FunctionRegistryType, 
   MCPTransportConfig, 
   MCPStdioTransportConfig, 
-  MCPHTTPTransportConfig 
+  MCPHTTPSSETransportConfig,
+  MCPStreambleHTTPTransportConfig
 } from '../types.js';
 
 // Define a mapping from provider names to their respective constructors
@@ -40,11 +41,16 @@ export function isStdioTransport(config: MCPTransportConfig): config is MCPStdio
   return 'command' in config;
 }
 
-// Type guard to check if config is http transport
-export function isHTTPTransport(config: MCPTransportConfig): config is MCPHTTPTransportConfig {
+// Type guard to check if config is HTTP SSE transport (also handles legacy HTTP transport)
+export function isHTTPSSETransport(config: MCPTransportConfig): config is MCPHTTPSSETransportConfig {
   return 'sseUrl' in config;
 }
 
+// Type guard to check if config is streamable HTTP transport
+export function isStreambleHTTPTransport(config: MCPTransportConfig): config is MCPStreambleHTTPTransportConfig {
+  return 'mcpEndpoint' in config;
+}
+
 /**
  * Type guard to check if a value is a constructor function for a type T.
  * 
@@ -122,8 +128,11 @@ const initializeMCPServers = async (agentConfigData: AgentConfig): Promise<AxFun
           args: mcpServerConfig.args,
           env: mcpServerConfig.env
         });
-      } else if (isHTTPTransport(mcpServerConfig)) {
-        transport = new AxMCPHTTPTransport(mcpServerConfig.sseUrl);
+      } else if (isStreambleHTTPTransport(mcpServerConfig)) {
+        transport = new AxMCPStreambleHTTPTransport(mcpServerConfig.mcpEndpoint, mcpServerConfig.options);
+      } else if (isHTTPSSETransport(mcpServerConfig)) {
+        // This handles both new SSE transport and legacy HTTP transport (both use sseUrl)
+        transport = new AxMCPHTTPSSETransport(mcpServerConfig.sseUrl);
       } else {  
         throw new Error(`Unsupported transport type: ${JSON.stringify(mcpServerConfig)}`);
       }

package/src/types.ts

@@ -1,7 +1,8 @@
 import type { 
   AxFunction, 
   AxSignature, 
-  AxModelConfig 
+  AxModelConfig,
+  AxMCPStreamableHTTPTransportOptions
 } from '@ax-llm/ax';
 
 import type { Provider } from './agents/agentConfig.js';
@@ -115,15 +116,32 @@ interface MCPStdioTransportConfig {
   env?: NodeJS.ProcessEnv
 }
 
-interface MCPHTTPTransportConfig {
+/**
+ * Config for an HTTP SSE MCP server.
+ * 
+ * @property {string} sseUrl - The SSE URL for the MCP server.
+ */
+interface MCPHTTPSSETransportConfig {
   sseUrl: string
 }
+
+/**
+ * Config for a streamable HTTP MCP server.
+ * 
+ * @property {string} mcpEndpoint - The HTTP endpoint URL for the MCP server.
+ * @property {AxMCPStreamableHTTPTransportOptions} options - Optional transport options.
+ */
+interface MCPStreambleHTTPTransportConfig {
+  mcpEndpoint: string
+  options?: AxMCPStreamableHTTPTransportOptions
+}
+
 /**
  * Config for an MCP server.
  * 
- * @property {MCPStdioTransportConfig | MCPHTTPTransportConfig} config - The config for the MCP server. Config can be either a stdio or http transport.
+ * @property {MCPStdioTransportConfig | MCPHTTPSSETransportConfig | MCPStreambleHTTPTransportConfig} config - The config for the MCP server. Config can be either stdio, http-sse, or streamable http transport.
  */
-type MCPTransportConfig = MCPStdioTransportConfig | MCPHTTPTransportConfig
+type MCPTransportConfig = MCPStdioTransportConfig | MCPHTTPSSETransportConfig | MCPStreambleHTTPTransportConfig
 
 /**
  * The configuration for an agent.
@@ -170,7 +188,8 @@ export {
   type StateInstance,
   type FunctionRegistryType,
   type MCPStdioTransportConfig,
-  type MCPHTTPTransportConfig,
+  type MCPHTTPSSETransportConfig,
+  type MCPStreambleHTTPTransportConfig,
   type MCPTransportConfig,
   type ModelUsage,
   type ModelInfo,