mcp-to-ai-sdk: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is mcp-to-ai-sdk, a CLI tool that generates Vercel AI SDK wrappers for Model Context Protocol (MCP) tools. It connects to MCP servers, discovers their tools, and generates type-safe TypeScript wrappers that can be used with the Vercel AI SDK.

Development Commands

# Build the CLI
npm run build

# Run the CLI directly (after building)
npm run dev <MCP_URL_OR_PATH>

# Test the built CLI
node dist/mcp-tools-cli.js https://mcp.grep.app

Architecture

Core Components

Main CLI File (mcp-tools-cli.ts)

• Single-file CLI that handles all generation logic
• Contains functions for connecting to MCP servers (HTTP/SSE/Stdio transports)
• Generates three types of files for each MCP server

Generated Code Architecture The CLI generates a directory structure like mcps/mcp.grep.app/ with:

1. client.ts - Shared MCP client with lazy connection

   • Uses singleton pattern with connection promise deduplication
   • Handles all transports: StreamableHTTP (default), SSE, or Stdio
   • Single persistent connection shared across all tools

2. {toolName}.ts - Individual tool implementations

   • Each exports a {toolName}ToolWithClient factory function
   • Takes a client getter function as parameter for dependency injection
   • Uses json-schema-to-zod for automatic schema conversion

3. index.ts - Convenience exports

   • Domain-based naming (e.g., mcpGrepTools for mcp.grep.app)
   • Two export patterns: default client and custom client injection
   • Individual tool re-exports for granular imports

Key Design Patterns

Tool Factory Pattern: Tools are generated as factory functions that accept a client getter, enabling both default shared client usage and custom client injection.

Domain-based Naming: Export names are generated from MCP URLs (e.g., mcp.grep.app → mcpGrep) with intelligent TLD and prefix stripping.