### FastMCP Server Setup

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/README.md

Example of the generated `server.ts` file, demonstrating the FastMCP server initialization with registered tools and the server start configuration.

```typescript
export const server: FastMCPServer = new FastMCPServer({
  name: "OpenAPI Petstore",
  version: "3.0.0",
  tools: [
    { name: "addPet", description: "Add a new pet to the store", handler: addPetHandler },
    { name: "getPetById", description: "Find pet by ID", handler: getPetByIdHandler },
    // ... more operations
  ],
})

server.start({ transportType: "httpStream", httpStream: { port: 8080 } })
```

--------------------------------

### Test Tools with Parameters

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/TESTING.md

This section shows how to test tools that require parameters. Examples include fetching a pet by ID, getting a user by name, and logging in a user with credentials.

```bash
# Get pet by ID
bunx @modelcontextprotocol/inspector --cli bun ./test/generated/fastmcp/server.ts --transport stdio --method tools/call --tool-name getPetById --tool-arg 'petId=1'
```

```bash
# Get user by name
bunx @modelcontextprotocol/inspector --cli bun ./test/generated/fastmcp/server.ts --transport stdio --method tools/call --tool-name getUserByName --tool-arg 'username=user1'
```

```bash
# Login user
bunx @modelcontextprotocol/inspector --cli bun ./test/generated/fastmcp/server.ts --transport stdio --method tools/call --tool-name loginUser --tool-arg 'username=testuser' --tool-arg 'password=testpass'
```

--------------------------------

### Test Simple Tools (No Parameters)

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/TESTING.md

These commands demonstrate how to call simple tools that do not require any parameters. Examples include getting store inventory and logging out a user.

```bash
# Get store inventory
bunx @modelcontextprotocol/inspector --cli bun ./test/generated/fastmcp/server.ts --transport stdio --method tools/call --tool-name getInventory
```

```bash
# Logout user
bunx @modelcontextprotocol/inspector --cli bun ./test/generated/fastmcp/server.ts --transport stdio --method tools/call --tool-name logoutUser
```

--------------------------------

### Example Output Configuration

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/types.md

Provides an example of configuring the output settings for the pluginFastMCP, including specifying the output path, barrel export type, and a custom banner.

```typescript
pluginFastMCP({
  output: {
    path: './src/gen/fastmcp',
    barrelType: 'named',
    banner: '/* FastMCP Generated Code */\n',
  },
})
```

--------------------------------

### Import and Start Custom FastMCP Server

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/generated-output.md

Import necessary components from the FastMCP library to create and configure a custom server instance. This example shows how to add a tool with a specific handler.

```typescript
import { server } from './fastmcp'
import { addPetHandler, getPetByIdHandler } from './fastmcp'
import { client } from './fastmcp'

// Start custom server instance
const myServer = new FastMCP({
  name: "Custom",
  version: "1.0.0",
})

myServer.addTool({
  name: "addPet",
  description: "Add pet",
  parameters: z.any(),
  execute: async (args) => addPetHandler(args)
})
```

--------------------------------

### FastMCP Plugin Configuration Example

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/types.md

An example demonstrating how to set up the FastMCP plugin options. This includes specifying import style, runtime, output directory, client base URL, import path, data return type, operation grouping, and name transformation functions.

```typescript
const options: Options = {
  importStyle: 'ts-extensions-allowed',
  runtime: 'bun',
  output: {
    path: './src/gen/fastmcp',
    barrelType: 'named',
    banner: '/* Generated Code */',
  },
  client: {
    baseURL: 'https://api.example.com',
    importPath: 'axios',
    dataReturnType: 'data',
  },
  group: {
    type: 'tag',
    name: ({ group }) => `${group}API`,
  },
  transformers: {
    name: (name, type) => {
      if (type === 'function') return `${name}Handler`
      return name
    },
  },
}
```

--------------------------------

### Example Grouping Configuration

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/types.md

Demonstrates how to configure the 'group' option within the plugin. This example groups by 'tag', customizes the group name to append 'Handlers', and sets the output path.

```typescript
pluginFastMCP({
  group: {
    type: 'tag',
    name: ({ group }) => `${group}Handlers`,
    output: './handlers/{{group}}',
  },
})
```

--------------------------------

### Install Kubb Plugin FastMCP

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/README.md

Install the plugin as a development dependency using bun.

```bash
bun add -D @beshkenadze/kubb-plugin-fastmcp
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/README.md

Clone the Kubb Plugin FastMCP repository and install its dependencies using bun.

```bash
git clone https://github.com/beshkenadze/kubb-plugin-fastmcp
cd kubb-plugin-fastmcp
bun install
```

--------------------------------

### Example Exclude and Include Configuration

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/types.md

Shows how to use 'exclude' and 'include' options to filter operations. This example excludes internal tags and deprecated operationIds, while including only public tags.

```typescript
pluginFastMCP({
  exclude: [
    { type: 'tag', pattern: 'internal' },
    { type: 'operationId', pattern: 'deprecated*' },
  ],
  include: [
    { type: 'tag', pattern: 'public' },
  ],
})
```

--------------------------------

### Test Server Setup with Vitest

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/integration-examples.md

Verify the FastMCP server setup using Vitest. This test ensures that the server instance is defined and available for use, confirming basic integration.

```typescript
// server.test.ts
import { describe, it, expect } from 'vitest'
import { server } from './src/gen/fastmcp/server'

describe('FastMCP Server', () => {
  it('should have tools registered', async () => {
    // Access server tools (FastMCP API)
    expect(server).toBeDefined()
  })
})
```

--------------------------------

### MCP Configuration File

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/TESTING.md

Example of an mcp.json configuration file to define FastMCP servers for different runtimes.

```json
{
  "mcpServers": {
    "petstore-bun": {
      "type": "stdio",
      "command": "bun",
      "args": ["./test/generated/fastmcp/server.ts", "--transport", "stdio"]
    },
    "petstore-node": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "./test/generated/fastmcp/server.ts", "--transport", "stdio"]
    }
  }
}
```

--------------------------------

### Basic Kubb Configuration with FastMCP

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/integration-examples.md

Demonstrates the basic setup for Kubb Plugin FastMCP in a Kubb configuration file. Ensure you have the necessary plugins imported.

```typescript
// kubb.config.ts
import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginZod } from '@kubb/plugin-zod'
import { pluginFastMCP } from '@beshkenadze/kubb-plugin-fastmcp'

export default defineConfig({
  input: {
    path: './openapi.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    pluginOas(),
    pluginTs(),
    pluginZod(),
    pluginFastMCP({
      output: {
        path: './fastmcp',
        barrelType: 'named',
      },
    }),
  ],
})
```

--------------------------------

### Test Array Parameters

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/TESTING.md

These examples demonstrate how to pass array parameters to tools. This includes finding pets by status and creating multiple users using an array input.

```bash
# Find pets by status
bunx @modelcontextprotocol/inspector --cli bun ./test/generated/fastmcp/server.ts --transport stdio --method tools/call --tool-name findPetsByStatus --tool-arg 'status=["available", "pending"]'
```

```bash
# Create multiple users (array wrapped in object)
bunx @modelcontextprotocol/inspector --cli bun ./test/generated/fastmcp/server.ts --transport stdio --method tools/call --tool-name createUsersWithArrayInput --tool-arg 'data=[{"username": "user1", "email": "user1@example.com"}, {"username": "user2", "email": "user2@example.com"}]'
```

--------------------------------

### Minimal Setup for FastMCP

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/configuration.md

Basic configuration to integrate FastMCP plugin with other Kubb plugins.

```typescript
import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginZod } from '@kubb/plugin-zod'
import { pluginFastMCP } from '@beshkenadze/kubb-plugin-fastmcp'

export default defineConfig({
  input: { path: './openapi.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginOas(),
    pluginTs(),
    pluginZod(),
    pluginFastMCP(),
  ],
})
```

--------------------------------

### Example Request with Base URL

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/configuration.md

Demonstrates how a generated handler request automatically includes the configured baseURL.

```typescript
const res = await client<ResponseType>({
  method: 'POST',
  url: '/pets',
  baseURL: 'https://api.example.com',  // From config
})
```

--------------------------------

### Example Service Component Usage

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/api-reference-components.md

Demonstrates how to use the Server component within a code generator, mapping OpenAPI operations to the required format.

```typescript
// In serverGenerator.tsx
import { Server } from '../components/Server'

const operationsMapped = operations.map((operation) => ({
  tool: {
    name: operation.getOperationId(),
    description: operation.getDescription(),
  },
  fastmcp: {
    name: getName(operation, { type: 'function', suffix: 'handler' }),
    file: getFile(operation),
  },
  zod: {
    name: getName(operation, { type: 'function', pluginKey: [pluginZodName] }),
    schemas: getSchemas(operation, { pluginKey: [pluginZodName], type: 'function' }),
    file: getFile(operation, { pluginKey: [pluginZodName] }),
  },
  type: {
    schemas: getSchemas(operation, { pluginKey: [pluginTsName], type: 'type' }),
  },
}))

return <Server name="server" serverName={oas.api.info?.title} serverVersion={oas.getVersion()} operations={operationsMapped} />
```

--------------------------------

### Minimal FastMCP Plugin Configuration

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/quick-reference.md

Use this minimal configuration for basic plugin setup.

```typescript
pluginFastMCP()
```

--------------------------------

### Docker Deployment of FastMCP Server

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/integration-examples.md

A Dockerfile to build an image for running the FastMCP server. It installs dependencies, generates code, exposes the necessary port, and starts the server using HTTP stream transport.

```dockerfile
FROM oven/bun:latest

WORKDIR /app

COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile

COPY . .

# Generate code
RUN bun run generate

# Expose for HTTP stream
EXPOSE 8080

# Start FastMCP server
CMD ["bun", "src/gen/fastmcp/server.ts", "--transport", "httpStream", "--port", "8080"]

```

--------------------------------

### Transport Configuration via Command-Line Arguments

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/api-reference-generators.md

Demonstrates how to start the generated FastMCP server using different transport types via command-line arguments. The stdio transport is the default.

```bash
# stdio transport (default)
node server.ts --transport stdio

# httpStream transport on custom port
node server.ts --transport httpStream --port 9000
```

--------------------------------

### Example Generated Server Code

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/api-reference-components.md

Illustrates the TypeScript code generated by the Server component for initializing FastMCP and registering tools.

```typescript
import { z } from "zod"

export const server = new FastMCP({
  name: "Pet Store API",
  version: "1.0.0",
})

server.addTool({
  name: "addPet",
  description: "Add a new pet to the store",
  parameters: z.object({ data: AddPetRequest, petId: AddPetPathParams['petId'] }),
  execute: async (args) => {
    return await addPetHandler(args)
  }
})

server.addTool({
  name: "getPet",
  description: "Get pet by ID",
  parameters: z.object({ petId: GetPetPathParams['petId'] }),
  execute: async (args) => {
    return await getPetHandler(args)
  }
})

// Parse command-line arguments
const args = process.argv.slice(2)
const transportIndex = args.indexOf('--transport')
const transportType = transportIndex > -1 ? args[transportIndex + 1] : 'stdio'
const portIndex = args.indexOf('--port')
const port = portIndex > -1 ? parseInt(args[portIndex + 1]) : 8080

// Start server with dynamic transport
if (transportType === 'httpStream') {
  server.start({
    transportType: "httpStream",
    httpStream: { port }
  })
} else {
  server.start({
    transportType: "stdio"
  })
}

console.log(`[FastMCP info] Starting server with transport: ${transportType}...`)
```

--------------------------------

### Runtime Configuration in Kubb

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/TESTING.md

Example of configuring the FastMCP plugin's runtime in `kubb.config.ts`. Choose 'bun' for speed or 'node' for compatibility.

```typescript
pluginFastMCP({
  runtime: "bun", // or "node"
  // ... other options
})
```

--------------------------------

### Example Generated Server Initialization

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/api-reference-generators.md

This snippet shows the structure of a generated FastMCP server file. It includes imports for FastMCP, handler functions, Zod schemas, server instantiation, and tool registration for operations.

```typescript
import { FastMCP } from 'fastmcp'
import { addPetHandler } from './petHandlers/addPet.ts'
import { getPetByIdHandler } from './petHandlers/getPetById.ts'
import { AddPetRequest, GetPetByIdPathParams } from '../zod/addPetSchema.ts'
import { z } from "zod"

export const server = new FastMCP({
  name: "Swagger Petstore",
  version: "1.0.0",
})

server.addTool({
  name: "addPet",
  description: "Add a new pet to the store",
  parameters: z.object({ data: AddPetRequest }),
  execute: async (args) => {
    return await addPetHandler(args)
  }
})

server.addTool({
  name: "getPetById",
  description: "Find pet by ID",
  parameters: z.object({ petId: GetPetByIdPathParams['petId'] }),
  execute: async (args) => {
    return await getPetByIdHandler(args)
  }
})

// ... transport setup and server.start() ...
```

--------------------------------

### Kubb Configuration for Faker and MSW

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/MOCK_TESTING.md

Configuration example for Kubb plugins. This sets up the output paths, Faker seed for consistent data, and enables MSW handler generation.

```typescript
pluginFaker({
  output: { path: "./mocks/data" },
  seed: [100],  // Consistent test data
}),
pluginMsw({
  output: { path: "./mocks/handlers" },
  parser: "faker",  // Use Faker for responses
  handlers: true,   // Generate handlers.ts
})
```

--------------------------------

### Configure FastMCP Plugin with Options

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/api-reference-plugin.md

Example of configuring the `pluginFastMCP` with custom output paths, client settings, and grouping strategies. This is useful for tailoring the generated code to specific project needs.

```typescript
import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginZod } from '@kubb/plugin-zod'
import { pluginFastMCP } from '@beshkenadze/kubb-plugin-fastmcp'

export default defineConfig({
  input: { path: './openapi.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginOas(),
    pluginTs(),
    pluginZod(),
    pluginFastMCP({
      output: {
        path: './fastmcp',
        barrelType: 'named',
      },
      client: {
        baseURL: 'https://api.example.com',
        dataReturnType: 'data',
      },
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Handlers`,
      },
    }),
  ],
})
```

--------------------------------

### Custom Import Styles for FastMCP

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/configuration.md

Examples demonstrating how to customize import styles for FastMCP, including forcing .js extensions, allowing .ts extensions, or using no extensions for CommonJS.

```typescript
// Force .js extensions for Node.js ESM
pluginFastMCP({
  importStyle: 'needs-js-extension',
})
```

```typescript
// Allow .ts extensions for bundler
pluginFastMCP({
  importStyle: 'ts-extensions-allowed',
})
```

```typescript
// No extensions for CommonJS
pluginFastMCP({
  importStyle: 'no-extension-ok',
})
```

--------------------------------

### Run FastMCP Server with stdio Transport

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/generated-output.md

Use this command to start the FastMCP server with the default stdio transport. This is suitable for local development and environments where direct process communication is available.

```bash
bun fastmcp/server.ts
# or
npx tsx fastmcp/server.ts
```

--------------------------------

### Using ImportStyle in Plugin Options

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/types.md

Demonstrates how to import and set the ImportStyle type when configuring the plugin. This example forces the use of '.js' extensions for all relative imports.

```typescript
import type { ImportStyle } from '@beshkenadze/kubb-plugin-fastmcp'

// In plugin options
pluginFastMCP({
  importStyle: 'needs-js-extension'  // Force .js extensions
})
```

--------------------------------

### Add tsconfig-paths for Testing

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/README.md

Install the tsconfig-paths package to enable advanced testing with tsconfig path mappings. This is useful for projects with complex module resolution configurations.

```bash
bun add -D jonaskello/tsconfig-paths
```

--------------------------------

### Integration Testing with Real Server

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/advanced-patterns.md

Perform integration tests by starting the FastMCP server and executing its tools. This verifies the end-to-end functionality of your API handlers and tool execution.

```typescript
import { server } from './src/gen/fastmcp/server'

describe('FastMCP Server', () => {
  it('should execute tools correctly', async () => {
    // Get a tool
    const tool = server.tools['addPet']
    
    // Execute it
    const result = await tool.execute({
      data: { name: 'Test' }
    })
    
    // Verify result
    expect(result.content[0].type).toBe('text')
  })
})
```

--------------------------------

### MCP Python SDK Integration

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/integration-examples.md

Connect to a stdio server using the MCP Python SDK, list available tools, and call a tool. Ensure the server is started with the correct command and arguments.

```python
import asyncio
from mcp.client.session import ClientSession
from mcp.client.stdio import StdioTransport

async def main():
    # Connect to stdio server
    transport = StdioTransport(
        command="bun",
        args=["src/gen/fastmcp/server.ts", "--transport", "stdio"]
    )
    
    async with ClientSession(transport) as session:
        # List available tools
        tools = await session.list_tools()
        print("Available tools:")
        for tool in tools.tools:
            print(f"  - {tool.name}: {tool.description}")
        
        # Call a tool
        result = await session.call_tool(
            "addPet",
            {
                "data": {
                    "name": "Fluffy",
                    "status": "available"
                }
            }
        )
        print("Result:", result)

asyncio.run(main())
```

--------------------------------

### Create Custom React Generator

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/advanced-patterns.md

Define a custom React generator using `createReactGenerator`. This example shows how to set up both per-operation and all-operations generators, including accessing plugin options and operation managers.

```typescript
import { createReactGenerator } from '@kubb/plugin-oas'
import { File, useApp } from '@kubb/react'
import type { PluginFastMCP } from '@beshkenadze/kubb-plugin-fastmcp'

export const myCustomGenerator = createReactGenerator<PluginFastMCP>({
  name: 'my-generator',
  
  // Per-operation generator
  Operation({ operation }) {
    const { plugin } = useApp<PluginFastMCP>()
    const { getName } = useOperationManager()
    
    return (
      <File baseName={`${getName(operation)}.custom.ts`}> 
        <File.Source>
          {`// Custom code for ${operation.getOperationId()}`}
        </File.Source>
      </File>
    )
  },
  
  // All-operations generator
  Operations({ operations, options }) {
    const { pluginManager } = useApp<PluginFastMCP>()
    
    return (
      <File baseName="index.ts">
        <File.Source>
          {`// Index of all operations`}
        </File.Source>
      </File>
    )
  }
})
```

--------------------------------

### FastMCP Server Initialization and Tool Registration

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/generated-output.md

Initializes the FastMCP server, registers operations as tools with their parameters and handlers, and starts the server with specified transport configuration. This is the main entry point for running the MCP server.

```typescript
import { FastMCP } from 'fastmcp'
import { addPetHandler } from './petHandlers/addPet.ts'
import { getPetByIdHandler } from './petHandlers/getPetById.ts'
import { AddPetRequest } from '../zod/addPetSchema.ts'
import { z } from "zod"

export const server = new FastMCP({
  name: "Swagger Petstore",
  version: "1.0.0",
})

server.addTool({
  name: "addPet",
  description: "Add a new pet to the store",
  parameters: z.object({ data: AddPetRequest }),
  execute: async (args) => {
    return await addPetHandler(args)
  }
})

// ... more tool registrations ...

// Parse command-line arguments and start server
const args = process.argv.slice(2)
const transportIndex = args.indexOf('--transport')
const transportType = transportIndex > -1 ? args[transportIndex + 1] : 'stdio'

if (transportType === 'httpStream') {
  server.start({ transportType: "httpStream", httpStream: { port: 8080 } })
} else {
  server.start({ transportType: "stdio" })
}
```

--------------------------------

### Example Main Index File: index.ts

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/generated-output.md

The root barrel export file for all handlers and the client. It provides convenient top-level imports for the entire plugin output and is generated if the output barrel type is 'named' or 'all'.

```typescript
export { client } from './client'
export { server } from './server'
export { addPetHandler, getPetByIdHandler } from './petHandlers'
export { storeOrderHandler } from './storeHandlers'
```

--------------------------------

### Running the Server with Bun

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/README.md

Execute the generated server using Bun, the default runtime.

```bash
# With Bun (default)
bun src/gen/fastmcp/server.ts --transport stdio
```

--------------------------------

### GitHub Actions Workflow for FastMCP Generation

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/integration-examples.md

Automates FastMCP code generation on push events that modify OpenAPI specifications or configuration files. Requires checkout, Bun setup, dependency installation, and running the generation script.

```yaml
# .github/workflows/generate-fastmcp.yml
name: Generate FastMCP

on:
  push:
    paths:
      - 'openapi.yaml'
      - 'kubb.config.ts'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - uses: oven-sh/setup-bun@v1
      
      - run: bun install
      
      - run: bun run generate
      
      - name: Commit generated files
        run: |
          git add src/gen
          git commit -m 'chore: regenerate FastMCP code'
          git push

```

--------------------------------

### Build and Test with Bun

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/quick-reference.md

Commands for building plugin distributions, running tests, type checking, and linting your code using Bun.

```bash
# Build plugin distribution
bun build
```

```bash
# Run tests
bun test
```

```bash
# Type checking
bun typecheck
```

```bash
# Lint code
bun lint
```

```bash
# Fix lint issues
bun lint:fix
```

--------------------------------

### List All Available Tools

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/TESTING.md

Execute this command to list all available tools on the FastMCP server. This is useful for understanding the server's capabilities.

```bash
bunx @modelcontextprotocol/inspector --cli bun ./test/generated/fastmcp/server.ts --transport stdio --method tools/list
```

--------------------------------

### Running Server with Bun (stdio)

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/quick-reference.md

Executes the generated server using Bun with the default standard input/output transport.

```bash
# Bun with stdio (default)
bun src/gen/fastmcp/server.ts
```

--------------------------------

### Example Generated Handler with fastmcpGenerator

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/api-reference-generators.md

This example shows a generated TypeScript handler function for an OpenAPI POST operation. It includes imports for types and the client, defines the handler signature, makes an axios client call, and wraps the response in FastMCP's ContentResult format. Ensure necessary types and client are available.

```typescript
import { ContentResult } from 'fastmcp'
import { client } from '../client'
import type { AddPetRequest, AddPet200Response } from '../../types/addPet'

export async function addPetHandler({ data }: { data: AddPetRequest }): Promise<ContentResult> {
  const requestData = data

  const res = await client<AddPet200Response, unknown, AddPetRequest>({
    method: "POST",
    url: `/pet`,
    baseURL: "https://petstore.swagger.io/v2",
    data: requestData,
  })

  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify(res.data)
      }
    ]
  }
}
```

--------------------------------

### List All Available Tools

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/TESTING.md

Use this command to list all available tools for the FastMCP plugin via stdio transport.

```bash
npx @modelcontextprotocol/inspector --cli npx tsx ./test/generated/fastmcp/server.ts --transport stdio --method tools/list
```

--------------------------------

### Testing with Configuration File

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/TESTING.md

Commands to test FastMCP tools using a configuration file, specifying either Bun or Node.js server.

```bash
# Using Bun config
bunx @modelcontextprotocol/inspector --cli --config mcp.json --server petstore-bun --method tools/list
```

```bash
# Using Node.js config
npx @modelcontextprotocol/inspector --cli --config mcp.json --server petstore-node --method tools/list
```

--------------------------------

### PluginFastMCP Type Hierarchy

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/architecture.md

Outlines the type hierarchy starting from PluginFastMCP, detailing its properties and their types.

```markdown
PluginFastMCP (from PluginFactoryOptions)
├── options: Options (user-provided config)
├── resolvedOptions: ResolvedOptions (processed config)
├── generators: Generator<PluginFastMCP>[] (code generators)
└── hooks: buildStart() → void

Options
├── importStyle: ImportStyle
├── runtime: 'bun' | 'node'
├── output: Output<Oas>
├── client: ClientConfig
├── group: Group
├── exclude: Exclude[]
├── include: Include[]
├── transformers: { name?: (name, type) => string }
└── generators: Generator<PluginFastMCP>[]

ResolvedOptions (internal)
├── importStyle: ImportStyle (resolved)
├── tsconfig: TsConfigJsonResolved | null
├── pathsMatcher: (request: string) => string[] | undefined
├── client: ResolvedClientConfig
└── ... (all other options, fully resolved)
```

--------------------------------

### getInfoHandler

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/generated-output.md

Retrieves general information. This handler does not require any parameters and makes a GET request to the /info endpoint.

```APIDOC
## GET /info

### Description
Retrieves general information about the service.

### Method
GET

### Endpoint
/info

### Parameters
This endpoint does not accept any parameters.

### Response
#### Success Response (200)
- **content** (Array<{ type: 'text', text: string }>) - The result of the operation, typically JSON-stringified response data.
```

--------------------------------

### Running Server with Bun (HTTP Stream)

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/quick-reference.md

Executes the generated server using Bun with the HTTP stream transport on port 8080.

```bash
# Bun with HTTP stream
bun src/gen/fastmcp/server.ts --transport httpStream --port 8080
```

--------------------------------

### Node.js Runtime Configuration

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/configuration.md

Configure FastMCP to use the Node.js runtime with npx and tsx. This requires Node.js and tsx to be installed.

```typescript
runtime: 'node'
```

```json
{
  "fastmcpServers": {
    "api-stdio": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "src/gen/fastmcp/server.ts"]
    }
  }
}
```

```bash
npx tsx src/gen/fastmcp/server.ts --transport stdio
```

--------------------------------

### Basic Plugin Configuration

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/README.md

Configure the plugin with a basic output path.

```typescript
pluginFastMCP({
  output: { path: './fastmcp' },
})
```

--------------------------------

### Get Info Handler with No Parameters

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/generated-output.md

This handler is for requests that do not require any input parameters. It directly calls the client with a fixed URL.

```typescript
export async function getInfoHandler(
  {}: {}
): Promise<ContentResult> {
  const res = await client<GetInfo200Response>({
    method: "GET",
    url: `/info`,
  })
  // ...
}
```

--------------------------------

### Generate FastMCP Server

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/TESTING.md

Use this command to generate your FastMCP server. This is the first step before testing.

```bash
bun x kubb generate
```

--------------------------------

### Example tsconfig.json for CommonJS / Legacy Mode

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/README.md

This configuration is for CommonJS or older Node.js module systems. It disables explicit extension requirements for imports.

```json
{
  "compilerOptions": {
    "module": "commonjs",
    "moduleResolution": "node",
    "baseUrl": "."
  }
}
```

--------------------------------

### Automatic TypeScript Configuration Detection

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/configuration.md

FastMCP automatically detects and uses your tsconfig.json for TypeScript integration. No explicit configuration is needed for basic setup.

```typescript
// No config needed - automatic
pluginFastMCP()
```

--------------------------------

### Run Pre-Release Checks with Bun

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/RELEASING.md

Execute these commands to ensure the code is linted, type-checked, tested, and built successfully before proceeding with the release.

```bash
bun lint
```

```bash
bun typecheck
```

```bash
bun test
```

```bash
bun build
```

--------------------------------

### listPetsHandler

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/generated-output.md

Lists pets, potentially with filtering or sorting options. It expects query parameters for filtering and makes a GET request to the /pets endpoint.

```APIDOC
## GET /pets

### Description
Retrieves a list of pets.

### Method
GET

### Endpoint
/pets

### Parameters
#### Query Parameters
- **queryParams** (ListPetsQueryParams) - Required - Parameters for filtering and sorting the list of pets.

### Response
#### Success Response (200)
- **content** (Array<{ type: 'text', text: string }>) - The result of the operation, typically JSON-stringified response data.
```

--------------------------------

### TypeScript JSX Support Configuration

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/configuration.md

FastMCP automatically enables JSX support if detected in your tsconfig.json. This example shows 'react-jsx' which is common for React components.

```json
{
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}
```

--------------------------------

### TypeScript Module Resolution Configuration

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/configuration.md

FastMCP respects module resolution settings from your tsconfig.json. This example shows 'node16' module and moduleResolution with verbatimModuleSyntax enabled.

```json
{
  "compilerOptions": {
    "module": "node16",
    "moduleResolution": "node16",
    "verbatimModuleSyntax": true
  }
}
```

--------------------------------

### Initialize FastMCP Client

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/README.md

Instantiate a FastMCP client with a server configuration and a list of available tools. This client can then be used to call specific tools.

```typescript
import { FastMCPClient } from 'fastmcp/client'
import { server } from './server'

const client = new FastMCPClient({
  server: server,
  tools: ['addPet', 'getPetById', 'placeOrder']
})

const result = await client.callTool('addPet', {
  // pet data
})
```

--------------------------------

### Plugin Configuration with Manual importStyle Override

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/README.md

Example of configuring the fastmcp plugin to manually set the import style, overriding automatic detection from tsconfig.json.

```typescript
pluginFastMCP({
  importStyle: 'ts-extensions-allowed', // Force .ts extensions
  // or
  importStyle: 'no-extension-ok', // No extensions for bundler
  output: { path: './fastmcp' },
})
```

--------------------------------

### Overriding Auto-Detected Import Style

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/advanced-patterns.md

Manually set the import style if the automatic detection is not suitable for your project setup. This ensures consistent import behavior.

```typescript
pluginFastMCP({
  importStyle: 'ts-extensions-allowed',
  // ... other options
})
```

--------------------------------

### server.ts

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/generated-output.md

Main FastMCP server file that instantiates the server and registers all tools, serving as the entry point for running the FastMCP server.

```APIDOC
## server.ts

### Description
Main FastMCP server file that instantiates the server and registers all tools.

Purpose: Entry point for running the FastMCP server as an MCP server.

### Exports
- `server` - FastMCP server instance

### Generated When
Always generated as part of the serverGenerator

### Structure
1. Imports all handler functions from grouped handler files
2. Imports all Zod validation schemas
3. Creates FastMCP server instance with API info
4. Registers each operation as a tool with parameters and handler
5. Parses command-line arguments for transport configuration
6. Starts server with stdio or httpStream transport

### Example Content
```typescript
import { FastMCP } from 'fastmcp'
import { addPetHandler } from './petHandlers/addPet.ts'
import { getPetByIdHandler } from './petHandlers/getPetById.ts'
import { AddPetRequest } from '../zod/addPetSchema.ts'
import { z } from "zod"

export const server = new FastMCP({
  name: "Swagger Petstore",
  version: "1.0.0",
})

server.addTool({
  name: "addPet",
  description: "Add a new pet to the store",
  parameters: z.object({ data: AddPetRequest }),
  execute: async (args) => {
    return await addPetHandler(args)
  }
})

// ... more tool registrations ...

// Parse command-line arguments and start server
const args = process.argv.slice(2)
const transportIndex = args.indexOf('--transport')
const transportType = transportIndex > -1 ? args[transportIndex + 1] : 'stdio'

if (transportType === 'httpStream') {
  server.start({ transportType: "httpStream", httpStream: { port: 8080 } })
} else {
  server.start({ transportType: "stdio" })
}
```
```

--------------------------------

### Path Resolution Strategy

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/architecture.md

Details the step-by-step process for resolving import paths, including alias matching and extension appending.

```text
1. Check if import is special (e.g., 'fastmcp' npm package)
   → Return as-is
         ↓
2. Use pathsMatcher to resolve aliases
   Example: '@utils' → './src/utils'
         ↓
3. Determine if relative or absolute
   → Relative paths can have extensions
   → Absolute/npm packages cannot
         ↓
4. Append extension based on importStyle
   - 'needs-js-extension': .js
   - 'ts-extensions-allowed': .ts or .tsx
   - 'no-extension-ok': (none)
         ↓
5. Fallback: Check file existence if uncertain
   Try: .ts, .js, .tsx
```

--------------------------------

### getPetHandler

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/generated-output.md

Retrieves information about a specific pet using its ID. It expects the petId in the path parameters and makes a GET request to the /pet/{petId} endpoint.

```APIDOC
## GET /pet/{petId}

### Description
Retrieves details for a specific pet.

### Method
GET

### Endpoint
/pet/{petId}

### Parameters
#### Path Parameters
- **petId** (string) - Required - The unique identifier of the pet.

### Response
#### Success Response (200)
- **content** (Array<{ type: 'text', text: string }>) - The result of the operation, typically JSON-stringified response data.
```

--------------------------------

### Extract Base Directory from File Path

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/api-reference-utils.md

Use this helper to get the parent directory of a given file path. Useful for resolving relative imports.

```typescript
getBaseDirFromContext('/project/src/handlers/petHandlers/addPet.ts')
// → '/project/src/handlers/petHandlers'

getBaseDirFromContext('/project/client.ts')
// → '/project'
```

```typescript
const handlerDir = getBaseDirFromContext(fastmcp.file.path)
const resolvedPath = resolveImportPath('../client', options, handlerDir)
```

--------------------------------

### Generated Imports with Path Aliases

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/advanced-patterns.md

Example of how generated imports utilize the configured path aliases. The plugin resolves these aliases to their actual file paths during the build.

```typescript
// Generated handler with automatic alias resolution
import type { PetRequest, PetResponse } from '@api/types'
import { client } from '@utils/http/client'
```

--------------------------------

### Plugin Configuration with Custom Client

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/README.md

Configure the plugin with a custom client import path and base URL.

```typescript
pluginFastMCP({
  client: {
    importPath: './my-client',
    baseURL: 'https://api.example.com',
  },
})
```

--------------------------------

### Run fastmcp server with Bun

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/integration-examples.md

Use Bun to run the fastmcp server. Supports stdio and HTTP stream transports.

```bash
# Recommended way to run with Bun
bun src/gen/fastmcp/server.ts

# With stdio transport (default)
bun src/gen/fastmcp/server.ts --transport stdio

# With HTTP stream transport on custom port
bun src/gen/fastmcp/server.ts --transport httpStream --port 9000
```

--------------------------------

### Example tsconfig.json for ESM with Extensions

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/README.md

This configuration is suitable for Node.js 16+ using ESM. It enables path alias resolution and requires .js extensions for imports.

```json
{
  "compilerOptions": {
    "module": "node16",
    "moduleResolution": "node16",
    "verbatimModuleSyntax": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

--------------------------------

### Run FastMCP Server with httpStream Transport

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/generated-output.md

Start the FastMCP server using the httpStream transport on a specified port. This is useful for network-based communication where stdio is not feasible.

```bash
bun fastmcp/server.ts --transport httpStream --port 9000
```

--------------------------------

### Run the Generated FastMCP Server

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/README.md

Navigate to the generated server directory and run the server using tsx.

```bash
cd src/gen/fastmcp
npx tsx server.ts
```

--------------------------------

### Publish Stable Version to NPM

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/RELEASING.md

Use either `bun release` or `pnpm publish` to publish the stable version of the package to NPM. Ensure you are logged in to NPM.

```bash
bun release
```

```bash
pnpm publish --no-git-check
```

--------------------------------

### Using Faker-Generated Data with MSW

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/MOCK_TESTING.md

Utilize default, seeded Faker-generated responses for API requests. This snippet demonstrates intercepting a GET request for a pet by ID.

```typescript
import { getPetByIdHandler } from './test/generated/mocks/handlers/index.ts'

// Use default faker-generated response (seeded for consistency)
server.use(getPetByIdHandler())

// Makes request - returns realistic fake pet data
const response = await fetch('http://petstore.swagger.io/v2/pet/123')
```

--------------------------------

### Import Path Resolution with No Extensions (CommonJS/Bundler)

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/generated-output.md

Example of import statements when no file extensions are used, typical for CommonJS modules or bundler configurations that handle module resolution.

```typescript
import { client } from '../client'
import { addPetHandler } from './petHandlers/addPet'
import type { AddPetRequest } from '../../types/addPet'
```

--------------------------------

### Import Path Resolution with ESM Extensions (.js)

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/generated-output.md

Example of import statements when using ESM with file extensions. Ensure your TypeScript configuration supports resolving these extensions.

```typescript
import { client } from '../client.js'
import { addPetHandler } from './petHandlers/addPet.js'
import type { AddPetRequest } from '../../types/addPet.js'
```

--------------------------------

### Handler Imports with Nested Aliases

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/advanced-patterns.md

Example of handler imports that correctly resolve using nested path aliases. Ensures that components and hooks from various directories are accessible.

```typescript
import { useApi } from '@hooks/useApi'
import { Button } from '@components/common/Button'
```

--------------------------------

### Running Server with Node.js (stdio)

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/_autodocs/quick-reference.md

Executes the generated server using Node.js (via tsx) with the standard input/output transport.

```bash
# Node.js with stdio
npx tsx src/gen/fastmcp/server.ts --transport stdio
```

--------------------------------

### Generate FastMCP Server with Kubb

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/README.md

Generate the FastMCP server using the Kubb CLI with a specified configuration file.

```bash
kubb generate --config kubb.config.ts
```

--------------------------------

### FastMCP Handler for Add Pet Operation

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/README.md

Example of a generated handler function for the 'addPet' operation. It uses the FastMCP client to make a POST request and returns the result.

```typescript
import { CallToolResult } from 'fastmcp/types'
import { client } from 'fastmcp/client'

export const addPetHandler = async (params: AddPetRequest): Promise<CallToolResult> => {
  const res = await client<AddPet200Response>('/pet', {
    method: 'POST',
    params,
    // ... generated client code
  })
  
  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify(res.data)
      }
    ]
  }
}
```

--------------------------------

### Running Mock API Tests

Source: https://github.com/beshkenadze/kubb-plugin-fastmcp/blob/main/MOCK_TESTING.md

Commands to execute mock API tests and generate new mocks. Use `bun run test:mock` for mock tests and `bun run kubb` to regenerate mocks.

```bash
# Run mock API tests
bun run test:mock

# Run all tests
bun run test:all

# Generate new mocks after OpenAPI changes
bun run kubb
```