Merge branch 'main' into docs/add-anthropic-openai-responses-integration

Resolve README.md conflict by:
- Keeping all integration examples (OpenAI, Anthropic, AI SDK, TanStack AI, Claude Agent SDK)
- Reorganising structure: Installation → Usage → Integrations → Features
- Using collapsible sections for integration examples
- Removing dead link to non-existent custom-base-url.ts example

Author: ryoppippi

.oxfmtrc.jsonc

@@ -3,4 +3,5 @@
 	"useTabs": true,
 	"semi": true,
 	"singleQuote": true,
+	"ignorePatterns": [".claude/settings.local.json"],
 }

README.md

@@ -26,6 +26,21 @@ pnpm add @stackone/ai
 bun add @stackone/ai
 ```
 
+### Optional: AI SDK Integration
+
+If you plan to use the AI SDK integration (Vercel AI SDK), install it separately:
+
+```bash
+# Using npm
+npm install ai
+
+# Using yarn
+yarn add ai
+
+# Using pnpm
+pnpm add ai
+```
+
 ## Usage
 
 ```typescript
@@ -41,8 +56,6 @@ const employeeTool = tools.getTool("bamboohr_list_employees");
 const employees = await employeeTool.execute();
 ```
 
-[View full example](examples/index.ts)
-
 ### Authentication
 
 Set the `STACKONE_API_KEY` environment variable:
@@ -223,6 +236,114 @@ await generateText({
 
 </details>
 
+<details>
+<summary><strong>With TanStack AI</strong></summary>
+
+```bash
+npm install @tanstack/ai @tanstack/ai-openai zod  # or: yarn/pnpm/bun add
+```
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { openai } from "@tanstack/ai-openai";
+import { z } from "zod";
+import { StackOneToolSet } from "@stackone/ai";
+
+const toolset = new StackOneToolSet({
+  baseUrl: "https://api.stackone.com",
+  accountId: "your-account-id",
+});
+
+const tools = await toolset.fetchTools();
+const employeeTool = tools.getTool("bamboohr_get_employee");
+
+// TanStack AI requires Zod schemas for tool input validation
+const getEmployeeTool = {
+  name: employeeTool.name,
+  description: employeeTool.description,
+  inputSchema: z.object({
+    id: z.string().describe("The employee ID"),
+  }),
+  execute: async (args: { id: string }) => {
+    return employeeTool.execute(args);
+  },
+};
+
+const adapter = openai();
+const stream = chat({
+  adapter,
+  model: "gpt-4o",
+  messages: [{ role: "user", content: "Get employee with id: abc123" }],
+  tools: [getEmployeeTool],
+});
+
+for await (const chunk of stream) {
+  // Process streaming chunks
+}
+```
+
+[View full example](examples/tanstack-ai-integration.ts)
+
+</details>
+
+<details>
+<summary><strong>With Claude Agent SDK</strong></summary>
+
+```bash
+npm install @anthropic-ai/claude-agent-sdk zod  # or: yarn/pnpm/bun add
+```
+
+```typescript
+import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import { StackOneToolSet } from "@stackone/ai";
+
+const toolset = new StackOneToolSet({
+  baseUrl: "https://api.stackone.com",
+  accountId: "your-account-id",
+});
+
+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],
+});
+
+// Use with Claude Agent SDK query
+const result = query({
+  prompt: "Get the employee with id: abc123",
+  options: {
+    model: "claude-sonnet-4-5-20250929",
+    mcpServers: { "stackone-tools": mcpServer },
+    tools: [], // Disable built-in tools
+    maxTurns: 3,
+  },
+});
+
+for await (const message of result) {
+  // Process streaming messages
+}
+```
+
+[View full example](examples/claude-agent-sdk-integration.ts)
+
+</details>
+
 ## Features
 
 ### Filtering Tools with fetchTools()
@@ -269,7 +390,7 @@ This is especially useful when you want to:
 
 Meta tools enable dynamic tool discovery and execution, allowing AI agents to search for relevant tools based on natural language queries without hardcoding tool names.
 
-> ⚠️ **Beta Feature**: Meta tools are currently in beta and the API may change in future versions.
+> **Beta Feature**: Meta tools are currently in beta and the API may change in future versions.
 
 #### How Meta Tools Work
 
@@ -345,8 +466,6 @@ import { StackOneToolSet } from "@stackone/ai";
 const toolset = new StackOneToolSet({ baseUrl: "https://api.example-dev.com" });
 ```
 
-[View full example](examples/custom-base-url.ts)
-
 ### Testing with dryRun
 
 You can use the `dryRun` option to return the api arguments from a tool call without making the actual api call:

examples/ai-sdk-integration.test.ts

@@ -0,0 +1,52 @@
+/**
+ * E2E test for ai-sdk-integration.ts example
+ *
+ * Tests the complete flow of using StackOne tools with the AI SDK.
+ */
+
+import { openai } from '@ai-sdk/openai';
+import { generateText, stepCountIs } from 'ai';
+import { StackOneToolSet } from '../src';
+
+describe('ai-sdk-integration example e2e', () => {
+	beforeEach(() => {
+		vi.stubEnv('STACKONE_API_KEY', 'test-key');
+		vi.stubEnv('OPENAI_API_KEY', 'test-openai-key');
+	});
+
+	afterEach(() => {
+		vi.unstubAllEnvs();
+	});
+
+	it('should fetch tools, convert to AI SDK format, and generate text with tool calls', async () => {
+		const toolset = new StackOneToolSet({
+			accountId: 'your-bamboohr-account-id',
+			baseUrl: 'https://api.stackone.com',
+		});
+
+		// Fetch all tools for this account via MCP
+		const tools = await toolset.fetchTools();
+		expect(tools.length).toBeGreaterThan(0);
+
+		// Convert to AI SDK tools
+		const aiSdkTools = await tools.toAISDK();
+		expect(aiSdkTools).toBeDefined();
+		expect(Object.keys(aiSdkTools).length).toBeGreaterThan(0);
+
+		// Verify the tools have the expected structure
+		const toolNames = Object.keys(aiSdkTools);
+		expect(toolNames).toContain('bamboohr_list_employees');
+		expect(toolNames).toContain('bamboohr_get_employee');
+
+		// The AI SDK will automatically call the tool if needed
+		const { text } = await generateText({
+			model: openai('gpt-5'),
+			tools: aiSdkTools,
+			prompt: 'Get all details about employee with id: c28xIQaWQ6MzM5MzczMDA2NzMzMzkwNzIwNA',
+			stopWhen: stepCountIs(3),
+		});
+
+		// The mocked OpenAI response includes 'Michael' in the text
+		expect(text).toContain('Michael');
+	});
+});

examples/ai-sdk-integration.ts

@@ -1,5 +1,13 @@
 /**
  * This example shows how to use StackOne tools with the AI SDK.
+ *
+ * The AI SDK provides an agent-like pattern through the `stopWhen` parameter
+ * with `stepCountIs()`. This creates a multi-step tool loop where the model
+ * can autonomously call tools and reason over results until the stop condition
+ * is met.
+ *
+ * In AI SDK v6+, you can use the `ToolLoopAgent` class for more explicit
+ * agent functionality.
  */
 
 import assert from 'node:assert';

examples/claude-agent-sdk-integration.test.ts

@@ -0,0 +1,140 @@
+/**
+ * E2E test for claude-agent-sdk-integration.ts example
+ *
+ * Tests the setup of StackOne tools with Claude Agent SDK.
+ *
+ * Note: The Claude Agent SDK spawns a subprocess to run claude-code, which
+ * requires the ANTHROPIC_API_KEY environment variable and a running claude-code
+ * installation. This test validates the tool setup and MCP server creation,
+ * but does not test the actual query execution.
+ */
+
+import { tool, createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { StackOneToolSet } from '../src';
+
+describe('claude-agent-sdk-integration example e2e', () => {
+	beforeEach(() => {
+		vi.stubEnv('STACKONE_API_KEY', 'test-key');
+	});
+
+	afterEach(() => {
+		vi.unstubAllEnvs();
+	});
+
+	it('should fetch tools and create Claude Agent SDK tool wrapper', async () => {
+		const toolset = new StackOneToolSet({
+			accountId: 'your-bamboohr-account-id',
+			baseUrl: 'https://api.stackone.com',
+		});
+
+		// Fetch all tools for this account via MCP
+		const tools = await toolset.fetchTools();
+		expect(tools.length).toBeGreaterThan(0);
+
+		// Get a specific tool
+		const employeeTool = tools.getTool('bamboohr_get_employee');
+		expect(employeeTool).toBeDefined();
+		assert(employeeTool !== undefined);
+
+		// Create Claude Agent SDK tool from 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' as const, text: JSON.stringify(result) }],
+				};
+			},
+		);
+
+		expect(getEmployeeTool.name).toBe('bamboohr_get_employee');
+		expect(getEmployeeTool.description).toContain('employee');
+		expect(getEmployeeTool.inputSchema).toHaveProperty('id');
+		expect(typeof getEmployeeTool.handler).toBe('function');
+	});
+
+	it('should create MCP server with StackOne tools', async () => {
+		const toolset = new StackOneToolSet({
+			accountId: 'your-bamboohr-account-id',
+			baseUrl: 'https://api.stackone.com',
+		});
+
+		const tools = await toolset.fetchTools();
+		const employeeTool = tools.getTool('bamboohr_get_employee');
+		assert(employeeTool !== undefined);
+
+		// Create Claude Agent SDK 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' as const, text: JSON.stringify(result) }],
+				};
+			},
+		);
+
+		// Create an MCP server with the StackOne tool
+		const mcpServer = createSdkMcpServer({
+			name: 'stackone-tools',
+			version: '1.0.0',
+			tools: [getEmployeeTool],
+		});
+
+		// Verify MCP server was created
+		expect(mcpServer).toBeDefined();
+		expect(mcpServer.name).toBe('stackone-tools');
+		expect(mcpServer.instance).toBeDefined();
+	});
+
+	it('should execute tool handler directly', async () => {
+		const toolset = new StackOneToolSet({
+			accountId: 'your-bamboohr-account-id',
+			baseUrl: 'https://api.stackone.com',
+		});
+
+		const tools = await toolset.fetchTools();
+		const employeeTool = tools.getTool('bamboohr_get_employee');
+		assert(employeeTool !== undefined);
+
+		// Create Claude Agent SDK 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' as const, text: JSON.stringify(result) }],
+				};
+			},
+		);
+
+		// Execute the tool handler directly
+		const result = await getEmployeeTool.handler(
+			{ id: 'c28xIQaWQ6MzM5MzczMDA2NzMzMzkwNzIwNA' },
+			{} as unknown,
+		);
+
+		expect(result).toBeDefined();
+		expect(result.content).toHaveLength(1);
+		expect(result.content[0]?.type).toBe('text');
+
+		// Parse the result text and verify it contains employee data
+		const textContent = result.content[0];
+		assert(textContent?.type === 'text');
+		const data = JSON.parse(textContent.text) as unknown;
+		expect(data).toHaveProperty('data');
+	});
+});