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

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