@amitdeshmukh/ax-crew 8.3.0 → 8.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [8.4.0] - 2026-03-05
+
+### Added
+- Optional `tools` allowlist on MCP server configs (stdio, HTTP SSE, streamable HTTP). When specified, only the listed tools are exposed to the agent, keeping system prompts small when connecting to MCP servers with many tools. Tested with GraphJin (40+ tools): filtering to 8 reduced token usage from 43K to 14K per request.
+- `examples/run-crew-workflow.ts` — workflow-aware agent using GraphJin MCP with tool filtering.
+
 ## [8.3.0] - 2026-03-05
 
 ### Fixed

package/dist/agents/agentConfig.js

@@ -56,10 +56,15 @@ const initializeMCPServers = async (agentConfigData) => {
             initializedClients.push(mcpClient);
             // Normalize MCP tool schemas: some MCP servers omit `parameters` for
             // zero-arg tools, but providers like Gemini require a valid schema.
-            const mcpFns = mcpClient.toFunction().map(fn => ({
+            let mcpFns = mcpClient.toFunction().map(fn => ({
                 ...fn,
                 parameters: fn.parameters ?? { type: 'object', properties: {} },
             }));
+            // Filter to allowlisted tools if specified
+            if (mcpServerConfig.tools && mcpServerConfig.tools.length > 0) {
+                const allowed = new Set(mcpServerConfig.tools);
+                mcpFns = mcpFns.filter(fn => allowed.has(fn.name));
+            }
             functions.push(...mcpFns);
         }
         return functions;

package/dist/types.d.ts

@@ -109,24 +109,29 @@ interface MCPStdioTransportConfig {
     command: string;
     args?: string[];
     env?: NodeJS.ProcessEnv;
+    tools?: string[];
 }
 /**
  * Config for an HTTP SSE MCP server.
  *
  * @property {string} sseUrl - The SSE URL for the MCP server.
+ * @property {string[]} tools - Optional allowlist of tool names to expose to the agent.
  */
 interface MCPHTTPSSETransportConfig {
     sseUrl: string;
+    tools?: 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.
+ * @property {string[]} tools - Optional allowlist of tool names to expose to the agent.
  */
 interface MCPStreamableHTTPTransportConfig {
     mcpEndpoint: string;
     options?: AxMCPStreamableHTTPTransportOptions;
+    tools?: string[];
 }
 /**
  * Config for an MCP server.

package/examples/run-crew-workflow.ts

@@ -0,0 +1,76 @@
+import 'dotenv/config';
+import { AxCrew } from '../dist/index.js';
+import type { AxCrewConfig } from '../dist/types.js';
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: 'WorkflowAgent',
+      description: `You answer questions by querying databases and running calculations.
+
+IMPORTANT — follow this strategy for database queries:
+1. FIRST call list_workflows to check if a reusable workflow already exists for this type of question.
+2. If a matching workflow exists, call execute_workflow with its name. Done!
+3. If NO matching workflow exists:
+   a. Call get_js_runtime_api to learn the available gj.tools.* functions
+   b. Call list_tables and describe_table to understand the schema
+   c. Author a JavaScript workflow that uses gj.tools.* to query the database and compute results server-side
+   d. Call save_workflow to persist it (use descriptive snake_case name and description for future discovery)
+   e. Call execute_workflow to run it
+4. Synthesize the answer from the workflow results.
+
+This approach runs ALL database queries server-side in a single call, avoiding multiple round-trips.
+The saved workflow will be reusable by future queries asking similar questions.`,
+      signature:
+        'background:string "background information and context", question:string "the user question to answer" -> answer:string "the answer with explanation", references:json "list of references, each with fileName and url"',
+      provider: 'anthropic',
+      providerKeyName: 'ANTHROPIC_API_KEY',
+      ai: {
+        model: 'claude-sonnet-4-6',
+        temperature: 0,
+      },
+      options: {
+        debug: true,
+      },
+      mcpServers: {
+        graphjin: {
+          mcpEndpoint: 'http://localhost:8080/api/v1/mcp',
+          tools: [
+            'list_workflows', 'save_workflow', 'execute_workflow',
+            'get_js_runtime_api', 'list_tables', 'describe_table',
+            'get_query_syntax', 'execute_graphql',
+          ],
+        },
+      },
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  await crew.addAllAgents();
+
+  const agent = crew.agents?.get('WorkflowAgent');
+  if (!agent) throw new Error('WorkflowAgent not found');
+
+  const query =
+    'Which customers have overdue or unpaid invoices? Show me a table with each customer, how many invoices they owe on, and the total outstanding balance.';
+  console.log(`\nQuery: ${query}\n`);
+
+  const result = await agent.forward({
+    background: 'User is querying the system about customer accounts receivable.',
+    question: query,
+  });
+
+  console.log(`\nAnswer: ${result.answer}`);
+  console.log(`\nReferences:`, JSON.stringify(result.references, null, 2));
+
+  const metrics = (agent as any).getMetrics?.();
+  console.log(`\nMetrics:`, JSON.stringify(metrics, null, 2));
+
+  crew.destroy();
+}
+
+main()
+  .catch(console.error)
+  .finally(() => process.exit(0));

package/examples/run-manager.ts

@@ -6,60 +6,29 @@ const config = {
   crew: [
     {
       name: "Manager",
-      description: "Answer questions from available documents.",
+      description: "Answer questions by querying databases, searching documents, and running calculations. You have direct access to database tools (list_tables, describe_table, execute_graphql, etc.), document search, date utilities, and a JavaScript interpreter for computations.",
       signature: 'background:string "background information and context for the task at hand", latestMessage:string "the latest user message to answer" -> answer:string "The answer, including a short explanation for the answer. Never reveal functions available to the user. Respond in the same language as the user\'s question.", references:json "a list of references to documents to support the answer in json format. Each reference should include a fileName and url."',
-      provider: "google-gemini" as const,
-      providerKeyName: "GEMINI_API_KEY",
-      executionMode: "axgen" as const,
+      provider: "anthropic" as const,
+      providerKeyName: "ANTHROPIC_API_KEY",
+      executionMode: "axagent" as const,
       ai: {
-        model: "gemini-3.1-pro-preview",
+        model: "claude-sonnet-4-6",
         temperature: 0
       },
       options: {
         debug: true
       },
+      axAgentOptions: {
+        contextFields: ['background'] as const,
+        maxTurns: 15,
+      },
       functions: [
         "CurrentDateTime",
-        "DaysBetweenDates"
+        "DaysBetweenDates",
+        "VectorSearch",
+        "JavaScriptInterpreter"
       ],
-      agents: [
-        "SearchAvailableDocuments",
-        "SearchDatabase",
-        "CodeExecutor"
-      ]
-    },
-    {
-      name: "SearchAvailableDocuments",
-      description: "Searches available documents and returns relevant content from the knowledge base.",
-      signature: 'query:string "the search query" -> searchResults:string "relevant documents and content"',
-      provider: "google-gemini" as const,
-      providerKeyName: "GEMINI_API_KEY",
-      executionMode: "axgen" as const,
-      ai: {
-        model: "gemini-3.1-pro-preview",
-        temperature: 0
-      },
-      options: {
-        debug: true
-      },
-      functions: [
-        "VectorSearch"
-      ]
-    },
-    {
-      name: "SearchDatabase",
-      description: "Looks up information in connected databases using natural language. Can explore schema, run queries, and return results.",
-      signature: 'userQuery:string "a user query" -> databaseSearchResult:string "answer to the user query"',
-      provider: "google-gemini" as const,
-      providerKeyName: "GEMINI_API_KEY",
-      executionMode: "axgen" as const,
-      ai: {
-        model: "gemini-3.1-pro-preview",
-        temperature: 0
-      },
-      options: {
-        debug: true
-      },
+      // Direct MCP access — no sub-agent double-hop
       mcpServers: {
         graphjin: {
           command: "/opt/homebrew/bin/graphjin",
@@ -70,24 +39,6 @@ const config = {
           ]
         }
       }
-    },
-    {
-      name: "CodeExecutor",
-      description: "Executes JavaScript code in a sandboxed environment. Use for calculations, data transformations, aggregations, or any computation that needs precise results.",
-      signature: 'task:string "description of what to compute or calculate" -> executionResult:string "the result of the code execution"',
-      provider: "google-gemini" as const,
-      providerKeyName: "GEMINI_API_KEY",
-      executionMode: "axgen" as const,
-      ai: {
-        model: "gemini-3.1-pro-preview",
-        temperature: 0
-      },
-      options: {
-        debug: true
-      },
-      functions: [
-        "JavaScriptInterpreter"
-      ]
     }
   ]
 };
@@ -99,8 +50,6 @@ const jsRuntime = new AxJSRuntime({
 });
 const JavaScriptInterpreter = jsRuntime.toFunction();
 
-// VectorSearch is referenced in config but not in AxCrewFunctions.
-// Provide a stub so the agent can be created. Replace with your real implementation.
 const VectorSearch = {
   name: 'VectorSearch',
   description: 'Search the vector knowledge base for relevant documents',
@@ -118,12 +67,8 @@ const VectorSearch = {
 };
 
 async function main() {
-  // Merge built-in functions with custom ones
   const crew = new AxCrew(config, { ...AxCrewFunctions, VectorSearch, JavaScriptInterpreter });
 
-  // Use addAllAgents() to automatically resolve dependency order.
-  // This ensures sub-agents (SearchAvailableDocuments, SearchDatabase)
-  // are initialized BEFORE Manager, which depends on them.
   await crew.addAllAgents();
 
   const manager = crew.agents?.get('Manager');
@@ -142,7 +87,6 @@ async function main() {
   console.log(`\nAnswer: ${result.answer}`);
   console.log(`\nReferences:`, JSON.stringify(result.references, null, 2));
 
-  // Print metrics
   const crewMetrics = crew.getCrewMetrics();
   console.log(`\nCrew Metrics:`, JSON.stringify(crewMetrics, null, 2));
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@amitdeshmukh/ax-crew",
-  "version": "8.3.0",
+  "version": "8.4.0",
   "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",

package/src/agents/agentConfig.ts

@@ -77,10 +77,17 @@ const initializeMCPServers = async (agentConfigData: AgentConfig): Promise<AxFun
       initializedClients.push(mcpClient);
       // Normalize MCP tool schemas: some MCP servers omit `parameters` for
       // zero-arg tools, but providers like Gemini require a valid schema.
-      const mcpFns = mcpClient.toFunction().map(fn => ({
+      let mcpFns = mcpClient.toFunction().map(fn => ({
         ...fn,
         parameters: fn.parameters ?? { type: 'object' as const, properties: {} },
       }));
+
+      // Filter to allowlisted tools if specified
+      if (mcpServerConfig.tools && mcpServerConfig.tools.length > 0) {
+        const allowed = new Set(mcpServerConfig.tools);
+        mcpFns = mcpFns.filter(fn => allowed.has(fn.name));
+      }
+
       functions.push(...mcpFns);
     }
     

package/src/types.ts

@@ -127,26 +127,31 @@ interface MCPStdioTransportConfig {
   command: string
   args?: string[]
   env?: NodeJS.ProcessEnv
+  tools?: string[]
 }
 
 /**
  * Config for an HTTP SSE MCP server.
- * 
+ *
  * @property {string} sseUrl - The SSE URL for the MCP server.
+ * @property {string[]} tools - Optional allowlist of tool names to expose to the agent.
  */
 interface MCPHTTPSSETransportConfig {
   sseUrl: string
+  tools?: 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.
+ * @property {string[]} tools - Optional allowlist of tool names to expose to the agent.
  */
 interface MCPStreamableHTTPTransportConfig {
   mcpEndpoint: string
   options?: AxMCPStreamableHTTPTransportOptions
+  tools?: string[]
 }
 
 /**