feat(tool): add toClaudeAgentSdk() method for Claude Agent SDK integration [ENG-11770] (#283)

* chore(deps): add @anthropic-ai/claude-agent-sdk as peer dependency

Add Claude Agent SDK as an optional peer dependency to support the new
toClaudeAgentSdk() method. This allows users to convert StackOne tools
to Claude Agent SDK format without manual wrapping.

The package is marked as optional in peerDependenciesMeta, so users
only need to install it when using Claude Agent SDK integration.

* feat(utils): add JSON Schema to Zod conversion utility

Add jsonSchemaToZod() function that converts JSON Schema definitions
to Zod schemas at runtime. This is required for Claude Agent SDK
integration, which expects Zod schemas for tool definitions.

Supports converting:
- Primitive types (string, number, boolean, null)
- Complex types (object, array)
- String formats (email, url, uuid, datetime)
- Numeric constraints (min, max, integer)
- Length constraints for strings and arrays
- Enum values
- Required/optional properties

* feat(types): add Claude Agent SDK types

Add ClaudeAgentSdkMcpServer interface and ClaudeAgentSdkOptions type
to support the new toClaudeAgentSdk() method.

ClaudeAgentSdkMcpServer represents the MCP server configuration that
can be passed to the Claude Agent SDK query() function's mcpServers
option.

* feat(tool): add toClaudeAgentSdk() method to Tools class

Add toClaudeAgentSdk() method that converts all tools in a collection
to Claude Agent SDK format, automatically creating an MCP server.

This simplifies integration with Claude Agent SDK from requiring
manual Zod schema definitions and MCP server setup to a single method
call. The method:

- Converts JSON Schema parameters to Zod schemas dynamically
- Creates Claude Agent SDK tool definitions with handlers
- Wraps tools in an MCP server via createSdkMcpServer()
- Supports configurable server name and version

Also adds toClaudeAgentSdkTool() helper method on BaseTool for
converting individual tools.

* refactor(examples): use toClaudeAgentSdk() in Claude Agent SDK example

Simplify the Claude Agent SDK example by using the new toClaudeAgentSdk()
method instead of manual tool wrapping with Zod schemas.

Before: Required importing tool(), createSdkMcpServer(), z from
dependencies and manually defining Zod schemas for each tool.

After: Single method call tools.toClaudeAgentSdk() handles all
conversion and MCP server creation automatically.

Also updates account ID placeholder to use generic 'hris' prefix
for consistency with other examples.

* docs(readme): simplify Claude Agent SDK integration example

Update the README to showcase the simplified toClaudeAgentSdk() API.
The new example is much shorter and easier to follow:

- Removed manual tool wrapping with Zod schemas
- Removed createSdkMcpServer() setup code
- Single method call now handles all conversion

* refactor(utils): use Zod's native z.fromJSONSchema() for JSON Schema conversion

- Replace custom JSON Schema to Zod conversion with Zod v4.3+ native method
- Update Zod peer dependency to require >=4.3.0 for fromJSONSchema support
- Simplify json-schema-to-zod.ts from ~210 lines to ~50 lines

* chore: use jsonSchema from ai

* chore(deps): relax zod peer dependency to support v3.25.0+

Since we no longer use z.fromJSONSchema(), we can support Zod v3.25.0+
instead of requiring v4.3.0+. This matches the main branch and allows
users with older Zod versions to use this package.

* refactor(types): use McpSdkServerConfigWithInstance from Claude Agent SDK

Import the return type directly from @anthropic-ai/claude-agent-sdk
instead of maintaining our own ClaudeAgentSdkMcpServer interface.
This removes code duplication and ensures type compatibility.

* test(tool): add tests for toClaudeAgentSdk and toClaudeAgentSdkTool

- Add unit test for BaseTool.toClaudeAgentSdkTool() conversion
- Add unit tests for Tools.toClaudeAgentSdk() with default options
- Add unit test for Tools.toClaudeAgentSdk() with custom server name/version

Author: ryoppippi

README.md

@@ -281,35 +281,17 @@ npm install @stackone/ai @anthropic-ai/claude-agent-sdk zod  # or: yarn/pnpm/bun
 ```
 
 ```typescript
-import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
-import { z } from "zod";
+import { query } from "@anthropic-ai/claude-agent-sdk";
 import { StackOneToolSet } from "@stackone/ai";
 
 const toolset = new StackOneToolSet({
   baseUrl: "https://api.stackone.com",
   accountId: "your-account-id",
 });
 
+// Fetch tools and convert to Claude Agent SDK format
 const tools = await toolset.fetchTools();
-const employeeTool = tools.getTool("bamboohr_get_employee");
-
-// Create a Claude Agent SDK tool from the StackOne tool
-const getEmployeeTool = tool(
-  employeeTool.name,
-  employeeTool.description,
-  { id: z.string().describe("The employee ID") },
-  async (args) => {
-    const result = await employeeTool.execute(args);
-    return { content: [{ type: "text", text: JSON.stringify(result) }] };
-  }
-);
-
-// Create an MCP server with the StackOne tool
-const mcpServer = createSdkMcpServer({
-  name: "stackone-tools",
-  version: "1.0.0",
-  tools: [getEmployeeTool],
-});
+const mcpServer = await tools.toClaudeAgentSdk();
 
 // Use with Claude Agent SDK query
 const result = query({

examples/claude-agent-sdk-integration.ts

@@ -3,12 +3,14 @@
  *
  * Claude Agent SDK allows you to create autonomous agents with custom tools
  * via MCP (Model Context Protocol) servers.
+ *
+ * The `toClaudeAgentSdk()` method automatically converts StackOne tools
+ * to Claude Agent SDK format, handling the MCP server creation internally.
  */
 
 import assert from 'node:assert';
 import process from 'node:process';
-import { query, tool, createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';
-import { z } from 'zod';
+import { query } from '@anthropic-ai/claude-agent-sdk';
 import { StackOneToolSet } from '@stackone/ai';
 
 const apiKey = process.env.STACKONE_API_KEY;
@@ -18,7 +20,7 @@ if (!apiKey) {
 }
 
 // Replace with your actual account ID from StackOne dashboard
-const accountId = 'your-bamboohr-account-id';
+const accountId = 'your-hris-account-id';
 
 const claudeAgentSdkIntegration = async (): Promise<void> => {
 	// Initialize StackOne
@@ -27,42 +29,19 @@ const claudeAgentSdkIntegration = async (): Promise<void> => {
 		baseUrl: process.env.STACKONE_BASE_URL ?? 'https://api.stackone.com',
 	});
 
-	// Fetch tools from StackOne
+	// Fetch tools from StackOne and convert to Claude Agent SDK format
 	const tools = await toolset.fetchTools();
+	const mcpServer = await tools.toClaudeAgentSdk();
 
-	// Get a specific tool
-	const employeeTool = tools.getTool('bamboohr_get_employee');
-	assert(employeeTool !== undefined, 'Expected to find bamboohr_get_employee tool');
-
-	// Create a Claude Agent SDK tool from the StackOne tool
-	const getEmployeeTool = tool(
-		employeeTool.name,
-		employeeTool.description,
-		{
-			id: z.string().describe('The employee ID'),
-		},
-		async (args) => {
-			const result = await employeeTool.execute(args);
-			return {
-				content: [{ type: 'text', text: JSON.stringify(result) }],
-			};
-		},
-	);
-
-	// Create an MCP server with the StackOne tool
-	const mcpServer = createSdkMcpServer({
-		name: 'stackone-tools',
-		version: '1.0.0',
-		tools: [getEmployeeTool],
-	});
-
-	// Use the Claude Agent SDK query with the custom MCP server
+	// Use the Claude Agent SDK query with the StackOne MCP server
+	// Type assertion is needed because our interface is compatible but not identical
 	const result = query({
 		prompt: 'Get the employee with id: c28xIQaWQ6MzM5MzczMDA2NzMzMzkwNzIwNA',
 		options: {
 			model: 'claude-sonnet-4-5-20250929',
 			mcpServers: {
-				'stackone-tools': mcpServer,
+				// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Compatible MCP server type
+				'stackone-tools': mcpServer as any,
 			},
 			// Disable built-in tools, only use our custom tools
 			tools: [],
@@ -75,14 +54,14 @@ const claudeAgentSdkIntegration = async (): Promise<void> => {
 	for await (const message of result) {
 		if (message.type === 'assistant') {
 			for (const block of message.message.content) {
-				if (block.type === 'tool_use' && block.name === 'bamboohr_get_employee') {
+				if (block.type === 'tool_use' && block.name === 'hris_get_employee') {
 					hasToolCall = true;
 				}
 			}
 		}
 	}
 
-	assert(hasToolCall, 'Expected at least one tool call to bamboohr_get_employee');
+	assert(hasToolCall, 'Expected at least one tool call to hris_get_employee');
 };
 
 await claudeAgentSdkIntegration();

package.json

@@ -81,12 +81,16 @@
 		"zod": "catalog:dev"
 	},
 	"peerDependencies": {
+		"@anthropic-ai/claude-agent-sdk": "catalog:peer",
 		"@anthropic-ai/sdk": "catalog:peer",
 		"ai": "catalog:peer",
 		"openai": "catalog:peer",
 		"zod": "catalog:peer"
 	},
 	"peerDependenciesMeta": {
+		"@anthropic-ai/claude-agent-sdk": {
+			"optional": true
+		},
 		"@anthropic-ai/sdk": {
 			"optional": true
 		},