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
| 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 }; |