agentlang 0.9.0 → 0.9.1

package/src/runtime/mcpclient.ts

@@ -0,0 +1,542 @@
+// Ref: https://github.com/modelcontextprotocol/typescript-sdk/tree/v1.x
+import { Client } from '@modelcontextprotocol/sdk/client';
+import {
+  ClientCredentialsProvider,
+  PrivateKeyJwtProvider,
+} from '@modelcontextprotocol/sdk/client/auth-extensions.js';
+import {
+  StreamableHTTPClientTransport,
+  StreamableHTTPClientTransportOptions,
+} from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import {
+  ListToolsRequest,
+  ListToolsResultSchema,
+  CallToolRequest,
+  CallToolResultSchema,
+  ListPromptsRequest,
+  ListPromptsResultSchema,
+  GetPromptRequest,
+  GetPromptResultSchema,
+  ListResourcesRequest,
+  ListResourcesResultSchema,
+  LoggingMessageNotificationSchema,
+  ResourceListChangedNotificationSchema,
+  ElicitRequestSchema,
+  ReadResourceRequest,
+  ReadResourceResultSchema,
+  RELATED_TASK_META_KEY,
+  ErrorCode,
+  McpError,
+} from '@modelcontextprotocol/sdk/types.js';
+import { getDisplayName } from '@modelcontextprotocol/sdk/shared/metadataUtils.js';
+import { logger } from './logger.js';
+import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+import { addMcpEvent, addModule, Instance, isModule } from './module.js';
+
+export function createProvider(
+  clientId: string,
+  clientSecret?: string,
+  privateKeyPem?: string
+): OAuthClientProvider {
+  if (privateKeyPem) {
+    const algorithm = process.env.MCP_CLIENT_ALGORITHM || 'RS256';
+    return new PrivateKeyJwtProvider({
+      clientId,
+      privateKey: privateKeyPem,
+      algorithm,
+    });
+  }
+  if (clientSecret) {
+    return new ClientCredentialsProvider({
+      clientId,
+      clientSecret,
+    });
+  }
+  throw Error(`Either clientSecret or privateKeyPem is required for client: ${clientId}`);
+}
+
+export type McpAuthInfo = {
+  provider?: OAuthClientProvider;
+  bearerToken?: string;
+};
+
+export type McpTool = {
+  id: string;
+  name: string;
+  description: string;
+  inputSchema: any;
+};
+
+export class McpClient {
+  // Track received notifications for debugging resumability
+  private notificationCount = 0;
+
+  private name: string;
+  private version: string = '1.0.0';
+  private client: Client | undefined;
+  private transport: StreamableHTTPClientTransport | undefined;
+  private serverUrl: string; // e.g 'https://mcp.deepwiki.com/mcp'
+  private notificationsToolLastEventId: string | undefined;
+  private sessionId: string | undefined = undefined;
+
+  constructor(name: string, serverUrl: string) {
+    this.name = name;
+    this.serverUrl = serverUrl;
+  }
+
+  public setVersion(v: string): McpClient {
+    this.version = v;
+    return this;
+  }
+
+  public async connect(authInfo?: McpAuthInfo): Promise<void> {
+    if (this.client) {
+      return;
+    }
+    logger.info(`Connecting to ${this.serverUrl}...`);
+
+    try {
+      // Create a new client with form elicitation capability
+      this.client = new Client(
+        {
+          name: this.name,
+          version: this.version,
+        },
+        {
+          capabilities: {
+            elicitation: {
+              form: {},
+            },
+          },
+        }
+      );
+      this.client.onerror = error => {
+        throw new Error(`MCP Client ${this.name} error: ${error}`);
+      };
+
+      // Set up elicitation request handler with proper validation
+      this.client.setRequestHandler(ElicitRequestSchema, async request => {
+        if (request.params.mode !== 'form') {
+          throw new McpError(
+            ErrorCode.InvalidParams,
+            `Unsupported elicitation mode: ${request.params.mode}`
+          );
+        }
+        const log = `MCP Client ${this.name} - Elicitation (form) Request Received:
+                      Message: ${request.params.message}
+                      Related Task: ${request.params._meta?.[RELATED_TASK_META_KEY]?.taskId}
+                      Requested Schema:
+                      ${JSON.stringify(request.params.requestedSchema, null, 2)}
+                    Cancelling the request in non-interactive mode`;
+        logger.debug(log);
+        return { action: 'cancel' };
+      });
+
+      const transArgs: StreamableHTTPClientTransportOptions = {
+        sessionId: this.sessionId,
+      };
+      if (authInfo?.provider) {
+        transArgs.authProvider = authInfo.provider;
+      } else if (authInfo?.bearerToken) {
+        const customHeaders = {
+          Authorization: `Bearer ${authInfo.bearerToken}`,
+        };
+        transArgs.requestInit = {
+          headers: customHeaders,
+        };
+      }
+
+      this.transport = new StreamableHTTPClientTransport(new URL(this.serverUrl), transArgs);
+
+      // Set up notification handlers
+      this.client.setNotificationHandler(LoggingMessageNotificationSchema, notification => {
+        this.notificationCount++;
+        logger.debug(
+          `MCP Client ${this.name} - Notification ${this.notificationCount}: ${notification.params.level} - ${notification.params.data}`
+        );
+      });
+
+      this.client.setNotificationHandler(ResourceListChangedNotificationSchema, async _ => {
+        logger.debug(`MCP Client ${this.name} - Resource list changed notification received!`);
+        try {
+          if (!this.client) {
+            logger.warn(`MCP Client ${this.name} disconnected, cannot fetch resources`);
+            return;
+          }
+          const resourcesResult = await this.client.request(
+            {
+              method: 'resources/list',
+              params: {},
+            },
+            ListResourcesResultSchema
+          );
+          logger.debug(
+            `MCP Client ${this.name} - Available resources count: ${resourcesResult.resources.length}`
+          );
+        } catch {
+          logger.warn(
+            `MCP Client ${this.name} - Failed to list resources after change notification`
+          );
+        }
+      });
+
+      // Connect the client
+      await this.client.connect(this.transport);
+      this.sessionId = this.transport.sessionId;
+      logger.debug(
+        `MCP Client ${this.name} - Transport created with session ID: ${this.sessionId}`
+      );
+      logger.debug(`MCP Client ${this.name} - Connected to MCP server ${this.serverUrl}`);
+    } catch (error) {
+      this.client = undefined;
+      this.transport = undefined;
+      throw new Error(`MCP Client ${this.name} - Failed to connect: ${error}`);
+    }
+  }
+
+  public async disconnect(): Promise<boolean> {
+    if (this.client === undefined || this.transport === undefined) {
+      return false;
+    }
+
+    try {
+      await this.transport.close();
+      logger.debug(`MCP Client ${this.name} - Disconnected from MCP server`);
+      this.client = undefined;
+      this.transport = undefined;
+      return true;
+    } catch (error) {
+      logger.warn(`MCP Client ${this.name} - Error disconnecting: ${error}`);
+    }
+    return false;
+  }
+
+  public async terminateSession(): Promise<boolean> {
+    if (this.client === undefined || this.transport === undefined) {
+      return false;
+    }
+
+    try {
+      console.debug(
+        `MCP Client ${this.name} - Terminating session with ID: ${this.transport.sessionId}`
+      );
+      await this.transport.terminateSession();
+      // Check if sessionId was cleared after termination
+      if (!this.transport.sessionId) {
+        this.sessionId = undefined;
+
+        // Also close the transport and clear client objects
+        await this.disconnect();
+        return true;
+      } else {
+        logger.warn(
+          `MCP Client ${this.name} - Server responded with 405 Method Not Allowed (session termination not supported`
+        );
+      }
+    } catch (error) {
+      console.warn(`MCP Client ${this.name} - Error terminating session: ${error}`);
+    }
+    return false;
+  }
+
+  public async reconnect(): Promise<void> {
+    if (this.client) {
+      await this.disconnect();
+    }
+    await this.connect();
+  }
+
+  public async listTools(): Promise<McpTool[]> {
+    if (!this.client) {
+      return [];
+    }
+
+    try {
+      const toolsRequest: ListToolsRequest = {
+        method: 'tools/list',
+        params: {},
+      };
+      const toolsResult = await this.client.request(toolsRequest, ListToolsResultSchema);
+
+      if (toolsResult.tools.length === 0) {
+        return [];
+      } else {
+        const result = new Array<McpTool>();
+        for (const tool of toolsResult.tools) {
+          result.push({
+            id: tool.name,
+            name: getDisplayName(tool),
+            description: tool.description || '',
+            inputSchema: tool.inputSchema,
+          });
+        }
+        return result;
+      }
+    } catch (error) {
+      throw new Error(`Tools not supported by this server ${this.serverUrl} - ${error}`);
+    }
+    return [];
+  }
+
+  public async callTool(name: string, args: Record<string, unknown>): Promise<any> {
+    if (!this.client) {
+      return undefined;
+    }
+
+    try {
+      const request: CallToolRequest = {
+        method: 'tools/call',
+        params: {
+          name,
+          arguments: args,
+        },
+      };
+      return await this.client.request(request, CallToolResultSchema);
+    } catch (error) {
+      throw new Error(`MCP Client ${name} - Error calling tool ${name}: ${error}`);
+    }
+    return undefined;
+  }
+
+  public async callGreetTool(name: string): Promise<any> {
+    return await this.callTool('greet', { name });
+  }
+
+  public async callMultiGreetTool(name: string): Promise<any> {
+    return await this.callTool('multi-greet', { name });
+  }
+
+  public async callCollectInfoTool(infoType: string): Promise<any> {
+    return await this.callTool('collect-user-info', { infoType });
+  }
+
+  public async startNotifications(interval: number, count: number): Promise<any> {
+    return await this.callTool('start-notification-stream', { interval, count });
+  }
+
+  public async runNotificationsToolWithResumability(interval: number, count: number): Promise<any> {
+    if (!this.client) {
+      return undefined;
+    }
+
+    try {
+      const request: CallToolRequest = {
+        method: 'tools/call',
+        params: {
+          name: 'start-notification-stream',
+          arguments: { interval, count },
+        },
+      };
+
+      const onLastEventIdUpdate = (event: string) => {
+        this.notificationsToolLastEventId = event;
+        console.log(`Updated resumption token: ${event}`);
+      };
+
+      const result = await this.client.request(request, CallToolResultSchema, {
+        resumptionToken: this.notificationsToolLastEventId,
+        onresumptiontoken: onLastEventIdUpdate,
+      });
+      return result;
+    } catch (error) {
+      throw new Error(`MCP Client ${this.name} - Error starting notification stream: ${error}`);
+    }
+    return undefined;
+  }
+
+  public async listPrompts(): Promise<any> {
+    if (!this.client) {
+      return undefined;
+    }
+
+    try {
+      const promptsRequest: ListPromptsRequest = {
+        method: 'prompts/list',
+        params: {},
+      };
+      return await this.client.request(promptsRequest, ListPromptsResultSchema);
+    } catch (error) {
+      throw new Error(`MCP Client ${this.name} - Prompts not supported by this server (${error})`);
+    }
+    return undefined;
+  }
+
+  public async getPrompt(name: string, args: Record<string, unknown>): Promise<any> {
+    if (!this.client) {
+      return undefined;
+    }
+
+    try {
+      const promptRequest: GetPromptRequest = {
+        method: 'prompts/get',
+        params: {
+          name,
+          arguments: args as Record<string, string>,
+        },
+      };
+
+      return await this.client.request(promptRequest, GetPromptResultSchema);
+    } catch (error) {
+      throw new Error(`MCP Client ${this.name} - Error getting prompt ${name}: ${error}`);
+    }
+    return undefined;
+  }
+
+  public async listResources(): Promise<any> {
+    if (!this.client) {
+      return undefined;
+    }
+
+    try {
+      const resourcesRequest: ListResourcesRequest = {
+        method: 'resources/list',
+        params: {},
+      };
+      return await this.client.request(resourcesRequest, ListResourcesResultSchema);
+    } catch (error) {
+      throw new Error(
+        `MCP Client ${this.name} - Resources not supported by this server (${error})`
+      );
+    }
+    return undefined;
+  }
+
+  public async readResource(uri: string): Promise<any> {
+    if (!this.client) {
+      return undefined;
+    }
+
+    try {
+      const request: ReadResourceRequest = {
+        method: 'resources/read',
+        params: { uri },
+      };
+      return await this.client.request(request, ReadResourceResultSchema);
+    } catch (error) {
+      throw new Error(`MCP Client ${this.name} - Error reading resource ${uri}: ${error}`);
+    }
+    return undefined;
+  }
+
+  public async callToolTask(name: string, args: Record<string, unknown>): Promise<any> {
+    if (!this.client) {
+      return undefined;
+    }
+
+    // Use task-based execution - call now, fetch later
+    // Using the experimental tasks API - WARNING: may change without notice
+    try {
+      // Call the tool with task metadata using streaming API
+      const stream = this.client.experimental.tasks.callToolStream(
+        {
+          name,
+          arguments: args,
+        },
+        CallToolResultSchema,
+        {
+          task: {
+            ttl: 60000, // Keep results for 60 seconds
+          },
+        }
+      );
+      for await (const message of stream) {
+        switch (message.type) {
+          case 'taskCreated':
+            logger.info(
+              `MCP Client ${this.name} - Task created successfully with ID: ${message.task.taskId}`
+            );
+            break;
+          case 'taskStatus':
+            logger.info(`MCP Client ${this.name} - Task status: ${message.task.status}`);
+            break;
+          case 'result':
+            return message.result.content;
+          case 'error':
+            throw message.error;
+        }
+      }
+    } catch (error) {
+      throw new Error(`MCP Client ${this.name} - Error with task-based execution: ${error}`);
+    }
+    return undefined;
+  }
+
+  public async cleanup(): Promise<boolean> {
+    if (this.client && this.transport) {
+      try {
+        // First try to terminate the session gracefully
+        if (this.transport.sessionId) {
+          try {
+            await this.transport.terminateSession();
+          } catch (error) {
+            logger.warn(`MCP Client ${this.name} - Error terminating session: ${error}`);
+          }
+        }
+
+        // Then close the transport
+        await this.transport.close();
+        return true;
+      } catch (error) {
+        logger.warn(`MCP Client ${this.name} - Error closing transport:, ${error}`);
+      }
+    }
+    return false;
+  }
+}
+
+const ConnectedClients = new Map<string, McpClient>();
+
+export async function listClientTools(clientInst: Instance): Promise<any> {
+  if (clientInst) {
+    const n = clientInst.lookup('name');
+    let mcpClient: McpClient | undefined = ConnectedClients.get(n);
+    if (mcpClient === undefined) {
+      mcpClient = new McpClient(n, clientInst.lookup('serverUrl')).setVersion(
+        clientInst.lookup('version')
+      );
+      let authInfo: McpAuthInfo | undefined;
+      const clientId = clientInst.lookup('clientId');
+      const clientSecret = clientInst.lookup('clientSecret');
+      if (clientId && clientSecret) {
+        authInfo = { provider: createProvider(clientId, clientSecret) };
+      } else {
+        const bearerToken = clientInst.lookup('bearerToken');
+        authInfo = { bearerToken };
+      }
+      await mcpClient.connect(authInfo);
+      ConnectedClients.set(n, mcpClient);
+    }
+    const tools: any[] = await mcpClient.listTools();
+    if (tools && tools.length > 0) {
+      const moduleName = `${n}.mcp`;
+      if (!isModule(moduleName)) {
+        addModule(moduleName);
+      }
+      tools.forEach((tool: any) => {
+        addMcpEvent(tool.id, moduleName);
+      });
+    }
+    return tools;
+  }
+  return [];
+}
+
+export function mcpClientNameFromToolEvent(toolEventInst: Instance): string {
+  const parts = toolEventInst.moduleName.split('.');
+  return parts[0];
+}
+
+export async function callMcpTool(clientInst: Instance, toolEventInst: Instance): Promise<any> {
+  if (clientInst) {
+    const n = clientInst.lookup('name');
+    const mcpClient: McpClient | undefined = ConnectedClients.get(n);
+    if (mcpClient !== undefined) {
+      const args = toolEventInst.attributesAsObject();
+      return await mcpClient.callTool(toolEventInst.name, args as Record<string, unknown>);
+    } else {
+      return { error: `MCP client ${n} is not connected to server` };
+    }
+  } else {
+    return { error: 'MCP client not found' };
+  }
+}

package/src/runtime/module.ts

@@ -132,6 +132,7 @@ function normalizePropertyNames(props: Map<string, any>) {
 
 const SystemAttributeProperty: string = 'system-attribute';
 const SystemDefinedEvent = 'system-event';
+const McpToolEvent = 'mcp-tool';
 
 function asSystemAttribute(attrSpec: AttributeSpec): AttributeSpec {
   const props: Map<string, any> = attrSpec.properties ? attrSpec.properties : new Map();
@@ -1261,6 +1262,10 @@ export class Event extends Record {
   isSystemDefined(): boolean {
     return this.meta?.get(SystemDefinedEvent) === 'true';
   }
+
+  isMcpTool(): boolean {
+    return this.meta?.get(McpToolEvent) === 'true';
+  }
 }
 
 enum RelType {
@@ -1661,13 +1666,32 @@ export class Workflow extends ModuleEntry {
   }
 }
 
+type FlowGraphEdge = {
+  rep: string;
+  label: string;
+};
+
 export type FlowGraphNode = {
   label: string;
   type: 'action' | 'condition';
   on?: string[] | undefined;
-  next: string[];
+  next: FlowGraphEdge[];
 };
 
+function asFlowGraphEdge(stmt: Statement | undefined): FlowGraphEdge {
+  if (stmt === undefined) {
+    return {
+      rep: '',
+      label: '',
+    };
+  } else {
+    return {
+      rep: stmt.$cstNode?.text || '',
+      label: statementLabel(stmt),
+    };
+  }
+}
+
 function splitFlowSteps(flow: FlowDefinition): string[] {
   const steps = new Array<string>();
   flow.body?.entries.forEach((fe: FlowEntry) => {
@@ -1719,7 +1743,7 @@ export class Flow extends ModuleEntry {
         });
         if (orig) {
           const nxs = orig.next;
-          nxs?.push(fp.next);
+          nxs?.push(asFlowGraphEdge(fp.next));
           const conds = orig.on;
           conds?.push(fp.condition);
         } else {
@@ -1727,14 +1751,14 @@ export class Flow extends ModuleEntry {
             label: fp.first,
             type: 'condition',
             on: [fp.condition],
-            next: [fp.next],
+            next: [asFlowGraphEdge(fp.next)],
           });
         }
       } else {
         result.push({
           label: fp.first,
           type: 'action',
-          next: [fp.next],
+          next: [asFlowGraphEdge(fp.next)],
         });
       }
     }
@@ -1822,6 +1846,29 @@ export class GlossaryEntry extends ModuleEntry {
   }
 }
 
+function statementLabel(stmt: Statement | undefined): string {
+  if (stmt === undefined) return '';
+  let lbl: string | undefined = undefined;
+  if (isLiteral(stmt.pattern.expr)) {
+    lbl = stmt.pattern.expr.id || stmt.pattern.expr.ref || stmt.pattern.expr.str;
+  }
+  if (lbl !== undefined) return lbl;
+  if (stmt.hints.length > 0) {
+    for (let i = 0; i < stmt.hints.length; ++i) {
+      const rh = stmt.hints[i];
+      if (rh.aliasSpec?.alias) {
+        lbl = rh.aliasSpec.alias;
+        break;
+      }
+    }
+  }
+  if (lbl !== undefined) return lbl;
+  if (stmt.pattern.crudMap) {
+    return stmt.pattern.crudMap.name;
+  }
+  throw new Error(`Failed to extract label from flow step - ${stmt.$cstNode?.text}`);
+}
+
 export function flowGraphNext(
   graph: FlowGraphNode[],
   currentNode?: FlowGraphNode,
@@ -1841,15 +1888,15 @@ export function flowGraphNext(
       if (c !== undefined) {
         const next = node.next[c];
         const r = graph.find((n: FlowGraphNode) => {
-          return n.label == next;
+          return n.label == next.label;
         });
-        return r || { label: next, type: 'action', next: [] };
+        return r || { label: next.label, type: 'action', next: [] };
       } else {
         return undefined;
       }
     } else {
       return graph.find((n: FlowGraphNode) => {
-        return n.label == node.next[0];
+        return n.label == node.next[0].label;
       });
     }
   }
@@ -2955,6 +3002,14 @@ export function addEvent(
   return event;
 }
 
+export function addMcpEvent(name: string, moduleName: string): Event {
+  const event = addEvent(name, moduleName);
+  event.addMeta(SystemDefinedEvent, 'true');
+  event.addMeta(McpToolEvent, 'true');
+  event.setPublic(true);
+  return event;
+}
+
 export function addRecord(
   name: string,
   moduleName = activeModule,
@@ -4071,6 +4126,14 @@ export function isBetweenRelationship(relName: string, moduleName: string): bool
   return mod.isBetweenRelationship(fr.entryName);
 }
 
+export function isOneToOneBetweenRelationship(relName: string, moduleName: string): boolean {
+  if (isBetweenRelationship(relName, moduleName)) {
+    const rel = getRelationship(relName, moduleName);
+    return rel.isOneToOne();
+  }
+  return false;
+}
+
 export function isContainsRelationship(relName: string, moduleName: string): boolean {
   const fr: FetchModuleByEntryNameResult = fetchModuleByEntryName(relName, moduleName);
   const mod: Module = fr.module;