feat(ai-proxy): add forest connectors

packages/agent-testing/src/forest-admin-client-mock.ts

@@ -44,12 +44,12 @@
 export default class ForestAdminClientMock implements ForestAdminClient {
   readonly chartHandler: ChartHandlerInterface;
   readonly contextVariablesInstantiator: ContextVariablesInstantiatorInterface = {
     buildContextVariables: () => ({} as any), // TODO: return actual context variables
   };
 
   readonly modelCustomizationService: ModelCustomizationService;
   readonly mcpServerConfigService: ForestAdminClient['mcpServerConfigService'] = {
-    getConfiguration: () => Promise.resolve({ configs: {} }),
+    getConfiguration: () => Promise.resolve({}),
   };
 
   readonly schemaService: ForestAdminClient['schemaService'] = {
@@ -61,8 +61,8 @@
     updateActivityLogStatus: () => Promise.resolve(),
   };
 
   readonly permissionService: any;
   readonly authService: any;
 
   constructor() {
     this.permissionService = {

packages/agent-toolkit/src/interfaces/ai.ts

@@ -24,7 +24,7 @@ export interface AiRouter {
     route: string;
     body?: unknown;
     query?: Record<string, string | string[] | undefined>;
-    mcpServerConfigs?: unknown;
+    toolConfigs?: unknown;
     headers?: Record<string, string | string[] | undefined>;
   }): Promise<unknown>;
 }

packages/agent/src/routes/ai/ai-proxy.ts

@@ -25,15 +25,15 @@ export default class AiProxyRoute extends BaseRoute {
   }
 
   private async handleAiProxy(context: Context): Promise<void> {
-    const mcpServerConfigs =
+    const toolConfigs =
       await this.options.forestAdminClient.mcpServerConfigService.getConfiguration();
 
     context.response.body = await this.aiRouter.route({
       route: context.params.route,
       body: context.request.body,
       query: context.query,
       headers: context.request.headers,
-      mcpServerConfigs,
+      toolConfigs,
     });
     context.response.status = HttpCode.Ok;
   }

packages/agent/test/routes/ai/ai-proxy.test.ts

@@ -51,13 +51,13 @@
         requestBody: { messages: [] },
       });
 
       await (route as any).handleAiProxy(context);
 
       expect(context.response.status).toBe(HttpCode.Ok);
       expect(context.response.body).toEqual(expectedResponse);
     });
 
-    test('should pass route, body, query, mcpServerConfigs and headers to router', async () => {
+    test('should pass route, body, query, toolConfigs and headers to router', async () => {
       const route = new AiProxyRoute(services, options, aiRouter);
       mockRoute.mockResolvedValueOnce({});
 
@@ -69,25 +69,23 @@
       });
       context.query = { 'ai-name': 'gpt4' };
 
       await (route as any).handleAiProxy(context);
 
       expect(mockRoute).toHaveBeenCalledWith({
         route: 'ai-query',
         body: { messages: [{ role: 'user', content: 'Hello' }] },
         query: { 'ai-name': 'gpt4' },
-        mcpServerConfigs: undefined,
+        toolConfigs: undefined,
         headers: context.request.headers,
       });
     });
 
-    test('should pass mcpServerConfigs from forestAdminClient to router', async () => {
+    test('should pass toolConfigs from forestAdminClient to router', async () => {
       const route = new AiProxyRoute(services, options, aiRouter);
       mockRoute.mockResolvedValueOnce({});
 
       const mcpConfigs = {
-        configs: {
-          server1: { type: 'http' as const, url: 'https://server1.com' },
-        },
+        server1: { type: 'http' as const, url: 'https://server1.com' },
       };
       jest
         .spyOn(options.forestAdminClient.mcpServerConfigService, 'getConfiguration')
@@ -101,11 +99,11 @@
       });
       context.query = {};
 
       await (route as any).handleAiProxy(context);
 
       expect(mockRoute).toHaveBeenCalledWith(
         expect.objectContaining({
-          mcpServerConfigs: mcpConfigs,
+          toolConfigs: mcpConfigs,
           headers: context.request.headers,
         }),
       );
@@ -124,7 +122,7 @@
         requestBody: {},
       });
 
       await expect((route as any).handleAiProxy(context)).rejects.toBe(error);
     });
   });
 });

packages/ai-proxy/src/create-ai-provider.ts

@@ -1,18 +1,20 @@
-import type { McpConfiguration } from './mcp-client';
 import type { AiConfiguration } from './provider';
 import type { RouterRouteArgs } from './schemas/route';
+import type { ToolConfig } from './tool-provider-factory';
 import type { AiProviderDefinition, AiRouter } from '@forestadmin/agent-toolkit';
 
 import { extractMcpOauthTokensFromHeaders, injectOauthTokens } from './oauth-token-injector';
 import { Router } from './router';
 
-function resolveMcpConfigs(args: Parameters<AiRouter['route']>[0]): McpConfiguration | undefined {
+function resolveMcpConfigs(
+  args: Parameters<AiRouter['route']>[0],
+): Record<string, ToolConfig> | undefined {
   const tokensByMcpServerName = args.headers
     ? extractMcpOauthTokensFromHeaders(args.headers)
     : undefined;
 
   return injectOauthTokens({
-    mcpConfigs: args.mcpServerConfigs as McpConfiguration | undefined,
+    configs: args.toolConfigs as Record<string, ToolConfig> | undefined,
     tokensByMcpServerName,
   });
 }
@@ -32,7 +34,7 @@ export function createAiProvider(config: AiConfiguration): AiProviderDefinition
             route: args.route,
             body: args.body,
             query: args.query,
-            mcpConfigs: resolveMcpConfigs(args),
+            toolConfigs: resolveMcpConfigs(args),
           } as RouterRouteArgs),
       };
     },

packages/ai-proxy/src/forest-integration-client.ts

@@ -0,0 +1,68 @@
+import type RemoteTool from './remote-tool';
+import type { ToolProvider } from './tool-provider';
+import type { Logger } from '@forestadmin/datasource-toolkit';
+
+import getZendeskTools, { type ZendeskConfig } from './integrations/zendesk/tools';
+import { validateZendeskConfig } from './integrations/zendesk/utils';
+
+export type CustomConfig = ZendeskConfig;
+export type ForestIntegrationName = 'Zendesk';
+
+export interface ForestIntegrationConfig {
+  integrationName: ForestIntegrationName;
+  config: CustomConfig;
+  isForestConnector: true;
+}
+
+export function isForestIntegrationConfig(
+  config: ForestIntegrationConfig | Record<string, unknown>,
+): config is ForestIntegrationConfig {
+  return (
+    'isForestConnector' in config && (config as ForestIntegrationConfig).isForestConnector === true
+  );
+}
+
+export default class ForestIntegrationClient implements ToolProvider {
+  private readonly logger?: Logger;
+  private readonly configs: ForestIntegrationConfig[];
+
+  constructor(configs: ForestIntegrationConfig[], logger?: Logger) {
+    this.logger = logger;
+    this.configs = configs;
+  }
+
+  async loadTools(): Promise<RemoteTool[]> {
+    const tools: RemoteTool[] = [];
+
+    this.configs.forEach(({ integrationName, config }) => {
+      switch (integrationName) {
+        case 'Zendesk':
+          tools.push(...getZendeskTools(config as ZendeskConfig));
+          break;
+        default:
+          this.logger?.('Warn', `Unsupported integration: ${integrationName}`);
+      }
+    });
+
+    return tools;
+  }
+
+  async checkConnection(): Promise<true> {
+    await Promise.all(
+      this.configs.map(({ integrationName, config }) => {
+        switch (integrationName) {
+          case 'Zendesk':
+            return validateZendeskConfig(config as ZendeskConfig);
+          default:
+            throw new Error(`Unsupported integration: ${integrationName}`);
+        }
+      }),
+    );
+
+    return true;
+  }
+
+  async dispose(): Promise<void> {
+    // No-op: integrations don't hold persistent connections
+  }
+}

packages/ai-proxy/src/index.ts

@@ -1,16 +1,30 @@
-import type { McpConfiguration } from './mcp-client';
+import type { ToolConfig } from './tool-provider-factory';
+import type { Logger } from '@forestadmin/datasource-toolkit';
 
-import McpConfigChecker from './mcp-config-checker';
+import ToolSourceChecker from './tool-source-checker';
 
 export { createAiProvider } from './create-ai-provider';
 export { default as ProviderDispatcher } from './provider-dispatcher';
+
+export {
+  ForestIntegrationConfig,
+  CustomConfig,
+  ForestIntegrationName,
+} from './forest-integration-client';
+
 export * from './provider-dispatcher';
 export * from './remote-tools';
+export { default as RemoteTool } from './remote-tool';
 export * from './router';
 export * from './mcp-client';
 export * from './oauth-token-injector';
 export * from './errors';
+export * from './tool-provider';
+export * from './tool-provider-factory';
 
-export function validMcpConfigurationOrThrow(mcpConfig: McpConfiguration) {
-  return McpConfigChecker.check(mcpConfig);
+export function validToolConfigurationOrThrow(
+  configs: Record<string, ToolConfig>,
+  logger?: Logger,
+) {
+  return ToolSourceChecker.check(configs, logger);
 }

packages/ai-proxy/src/integrations/brave/brave-tool-provider.ts

@@ -0,0 +1,25 @@
+import type RemoteTool from '../../remote-tool';
+import type { ToolProvider } from '../../tool-provider';
+
+import getBraveTools, { type BraveConfig } from './tools';
+
+export default class BraveToolProvider implements ToolProvider {
+  private readonly config: BraveConfig;
+
+  constructor(config: BraveConfig) {
+    this.config = config;
+  }
+
+  async loadTools(): Promise<RemoteTool[]> {
+    return getBraveTools(this.config);
+  }
+
+  async checkConnection(): Promise<true> {
+    return true;
+  }
+
+  // eslint-disable-next-line class-methods-use-this
+  async dispose(): Promise<void> {
+    // No-op: Brave search has no persistent connections
+  }
+}

packages/ai-proxy/src/integrations/brave/tools.ts

@@ -0,0 +1,18 @@
+import type RemoteTool from '../../remote-tool';
+
+import { BraveSearch } from '@langchain/community/tools/brave_search';
+
+import ServerRemoteTool from '../../server-remote-tool';
+
+export interface BraveConfig {
+  apiKey: string;
+}
+
+export default function getBraveTools(config: BraveConfig): RemoteTool[] {
+  return [
+    new ServerRemoteTool({
+      sourceId: 'brave_search',
+      tool: new BraveSearch({ apiKey: config.apiKey }),
+    }),
+  ];
+}

packages/ai-proxy/src/integrations/zendesk/tools.ts

@@ -0,0 +1,35 @@
+import type RemoteTool from '../../remote-tool';
+
+import createCreateTicketTool from './tools/create-ticket';
+import createCreateTicketCommentTool from './tools/create-ticket-comment';
+import createGetTicketTool from './tools/get-ticket';
+import createGetTicketCommentsTool from './tools/get-ticket-comments';
+import createGetTicketsTool from './tools/get-tickets';
+import createUpdateTicketTool from './tools/update-ticket';
+import { getZendeskConfig } from './utils';
+import ServerRemoteTool from '../../server-remote-tool';
+
+export interface ZendeskConfig {
+  subdomain: string;
+  email: string;
+  apiToken: string;
+}
+
+export default function getZendeskTools(config: ZendeskConfig): RemoteTool[] {
+  const { baseUrl, headers } = getZendeskConfig(config);
+
+  return [
+    createGetTicketsTool(headers, baseUrl),
+    createGetTicketTool(headers, baseUrl),
+    createGetTicketCommentsTool(headers, baseUrl),
+    createCreateTicketTool(headers, baseUrl),
+    createCreateTicketCommentTool(headers, baseUrl),
+    createUpdateTicketTool(headers, baseUrl),
+  ].map(
+    tool =>
+      new ServerRemoteTool({
+        sourceId: 'zendesk',
+        tool,
+      }),
+  );
+}

packages/ai-proxy/src/integrations/zendesk/tools/create-ticket-comment.ts

@@ -0,0 +1,45 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+
+import { assertResponseOk } from '../utils';
+
+export default function createCreateTicketCommentTool(
+  headers: Record<string, string>,
+  baseUrl: string,
+): DynamicStructuredTool {
+  return new DynamicStructuredTool({
+    name: 'zendesk_create_ticket_comment',
+    description: 'Add a new comment to an existing Zendesk ticket',
+    schema: z.object({
+      ticket_id: z.number().int().positive().describe('The ID of the ticket to add a comment to'),
+      comment: z.string().min(1).describe('The comment text to add'),
+      public: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe(
+          'Whether the comment is visible to the requester (true) or internal only (false)',
+        ),
+    }),
+    func: async ({ ticket_id, comment, public: isPublic }) => {
+      const updateData = {
+        ticket: {
+          comment: {
+            body: comment,
+            public: isPublic,
+          },
+        },
+      };
+
+      const response = await fetch(`${baseUrl}/tickets/${ticket_id}.json`, {
+        method: 'PUT',
+        headers,
+        body: JSON.stringify(updateData),
+      });
+
+      await assertResponseOk(response, 'create ticket comment');
+
+      return JSON.stringify(await response.json());
+    },
+  });
+}