@devries-cameron20 / composio Mirror · read-only
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 04:45 UTC

next
ts 228 lines 7.34 KB
Raw
1 /**
2 * Claude Agents Provider
3 * To be used with the Claude Agent SDK (@anthropic-ai/claude-agent-sdk)
4 *
5 * This provider enables integration with Claude Code Agents SDK,
6 * allowing Composio tools to be used as MCP tools within Claude agents.
7 *
8 * @packageDocumentation
9 * @module providers/claude-agents
10 */
11 import {
12 BaseAgenticProvider,
13 Tool,
14 ExecuteToolFn,
15 McpUrlResponse,
16 McpServerGetResponse,
17 dereferenceJsonSchema,
18 normalizeToolArguments,
19 JsonSchemaToZodError,
20 } from '@composio/core';
21 import { jsonSchemaToZod, type JsonSchema } from '@composio/json-schema-to-zod/v4';
22 import type { ZodType } from 'zod/v4';
23 import {
24 tool as sdkTool,
25 type Options as ClaudeAgentOptions,
26 } from '@anthropic-ai/claude-agent-sdk';
27
28 /**
29 * Builds the Zod v4 schema the SDK registers. The SDK renders it as the tool's
30 * JSON Schema with `z.toJSONSchema`, and the v4 builder forwards `format`,
31 * `contentEncoding`, `contentMediaType`, and `type: "integer"` into the
32 * schema's metadata, so those keywords reach the model. It accepts and rejects
33 * the same values as the v3 builder behind `jsonSchemaToZodSchema`.
34 */
35 const toInputSchema = (schema: Record<string, unknown>): ZodType => {
36 try {
37 return jsonSchemaToZod(schema as JsonSchema);
38 } catch (error) {
39 const detail = error instanceof Error ? `: ${error.message}` : '';
40 throw new JsonSchemaToZodError(`Failed to convert JSON Schema to Zod Schema${detail}`, {
41 cause: error,
42 });
43 }
44 };
45
46 /**
47 * Type for a single Claude Agent SDK MCP tool definition
48 */
49 export type ClaudeAgentTool = ReturnType<typeof sdkTool>;
50
51 /**
52 * Type for a collection of Claude Agent SDK MCP tools
53 */
54 export type ClaudeAgentToolCollection = ClaudeAgentTool[];
55
56 /**
57 * Provider for integrating Composio tools with Claude Code Agents SDK.
58 *
59 * This provider wraps Composio tools as MCP tools that can be used with
60 * the Claude Agent SDK's `query()` function via the `mcpServers` option.
61 *
62 * @example
63 * ```typescript
64 * import { Composio } from '@composio/core';
65 * import { ClaudeAgentSDKProvider } from '@composio/claude-agent-sdk';
66 * import { query, createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';
67 *
68 * const composio = new Composio({
69 * apiKey: process.env.COMPOSIO_API_KEY,
70 * provider: new ClaudeAgentSDKProvider(),
71 * });
72 *
73 * // Get tools and create MCP server config using claude-agent-sdk's `createSdkMcpServer`
74 * const tools = await composio.tools.get('default', 'GMAIL_SEND_EMAIL');
75 * const mcpServer = createSdkMcpServer({
76 * name: 'composio',
77 * version: '1.0.0',
78 * tools,
79 * });
80 *
81 * // Use with Claude Agent SDK
82 * for await (const message of query({
83 * prompt: 'Send an email',
84 * options: {
85 * mcpServers: { composio: mcpServer },
86 * },
87 * })) {
88 * console.log(message);
89 * }
90 * ```
91 */
92 export class ClaudeAgentSDKProvider extends BaseAgenticProvider<
93 ClaudeAgentToolCollection,
94 ClaudeAgentTool,
95 McpServerGetResponse
96 > {
97 readonly name = 'claude-agent-sdk';
98
99 /**
100 * Wraps a Composio tool as a Claude Agent SDK MCP tool.
101 *
102 * @param composioTool - The Composio tool to wrap
103 * @param executeTool - Function to execute the tool
104 * @returns A Claude Agent SDK MCP tool definition
105 *
106 * @example
107 * ```typescript
108 * const composioTool = {
109 * slug: 'GMAIL_SEND_EMAIL',
110 * description: 'Send an email via Gmail',
111 * inputParameters: {
112 * type: 'object',
113 * properties: {
114 * to: { type: 'string', description: 'Recipient email' },
115 * subject: { type: 'string', description: 'Email subject' },
116 * body: { type: 'string', description: 'Email body' },
117 * },
118 * required: ['to', 'subject', 'body'],
119 * },
120 * };
121 *
122 * const mcpTool = provider.wrapTool(composioTool, executeFn);
123 * ```
124 */
125 wrapTool(composioTool: Tool, executeTool: ExecuteToolFn): ClaudeAgentTool {
126 // Register the complete object schema rather than its raw property shape. A raw shape is only
127 // the per-property map, so every root-level constraint — `additionalProperties`, whether
128 // boolean or schema-valued, and `patternProperties` — is structurally unrepresentable and gets
129 // dropped at registration. The SDK then silently strips unknown keys instead of rejecting them,
130 // and free-form roots lose the content they exist to carry.
131 //
132 // A tool with no input parameters stays closed: the fallback spells out
133 // `additionalProperties: false`, because a bare `properties: {}` is now an open object.
134 const inputZodSchema = toInputSchema(
135 dereferenceJsonSchema(
136 composioTool.inputParameters ?? {
137 type: 'object',
138 properties: {},
139 additionalProperties: false,
140 },
141 { onUnresolved: 'sentinel' }
142 )
143 );
144
145 // The SDK runtime accepts a complete schema, but `tool()` only exposes the raw-shape type, and
146 // that generic signature also makes the handler argument instantiate excessively deep (TS2589).
147 // Narrow it to a concrete, monomorphic signature once, instead of scattering casts at the call.
148 const defineTool = sdkTool as unknown as (
149 name: string,
150 description: string,
151 inputSchema: ZodType,
152 handler: (
153 args: Record<string, unknown>
154 ) => Promise<{ content: Array<{ type: 'text'; text: string }> }>
155 ) => ClaudeAgentTool;
156
157 return defineTool(
158 composioTool.slug,
159 composioTool.description ?? `Execute ${composioTool.slug}`,
160 inputZodSchema,
161 async args => {
162 try {
163 // Models occasionally emit tool input as a JSON string rather than an object (issue #2406).
164 const result = await executeTool(
165 composioTool.slug,
166 normalizeToolArguments(args, composioTool.slug)
167 );
168 return {
169 content: [
170 {
171 type: 'text' as const,
172 text: typeof result === 'string' ? result : (JSON.stringify(result) ?? ''),
173 },
174 ],
175 };
176 } catch (error) {
177 return {
178 content: [
179 {
180 type: 'text' as const,
181 text: JSON.stringify({
182 successful: false,
183 error: error instanceof Error ? error.message : String(error),
184 data: null,
185 }),
186 },
187 ],
188 };
189 }
190 }
191 );
192 }
193
194 /**
195 * Wraps multiple Composio tools as Claude Agent SDK MCP tools.
196 *
197 * @param tools - Array of Composio tools to wrap
198 * @param executeTool - Function to execute the tools
199 * @returns Array of Claude Agent SDK MCP tool definitions
200 *
201 * @example
202 * ```typescript
203 * const tools = await composio.tools.get('default', ['GMAIL_SEND_EMAIL', 'SLACK_POST_MESSAGE']);
204 * const mcpTools = provider.wrapTools(tools, composio.tools.execute);
205 * ```
206 */
207 wrapTools(tools: Tool[], executeTool: ExecuteToolFn): ClaudeAgentToolCollection {
208 return tools.map(tool => this.wrapTool(tool, executeTool));
209 }
210
211 /**
212 * Transform MCP URL response into standard format.
213 *
214 * @param data - The MCP URL response data
215 * @returns Standard MCP server response format
216 */
217 wrapMcpServerResponse(data: McpUrlResponse): McpServerGetResponse {
218 return data.map(item => ({
219 url: new URL(item.url),
220 name: item.name,
221 })) as McpServerGetResponse;
222 }
223 }
224
225 /**
226 * Re-export useful types from Claude Agent SDK for convenience
227 */
228 export type { ClaudeAgentOptions };