SDK Configuration Validator

Validates Claude Agent SDK project configuration, environment setup, and dependencies.

Use when...

• User mentions "validate SDK setup", "check SDK configuration", or "SDK not working"

• User reports SDK initialization errors or import failures

• User asks "is my SDK project configured correctly?"

• User requests "troubleshoot SDK issues" or "debug SDK setup"

• Before starting SDK development work in a new project

• After installing SDK dependencies to verify correctness

Capabilities

• Validates TypeScript/Python SDK configuration files

• Checks SDK version compatibility and dependencies

• Verifies environment variable setup (.env files)

• Validates project structure and required files

• Generates validation reports with actionable fixes

• Provides configuration templates for common setups

Usage

Basic Validation

Validate TypeScript SDK setup

bash scripts/validate-typescript.sh /path/to/project

Validate Python SDK setup

bash scripts/validate-python.sh /path/to/project

Check SDK version compatibility

bash scripts/check-sdk-version.sh /path/to/project

Environment Validation

Validate .env file setup

bash scripts/validate-env-setup.sh /path/to/project

Generate Templates

Copy environment template

cp templates/.env.example.template /path/to/project/.env.example

Copy TypeScript config

cp templates/tsconfig-sdk.json /path/to/project/tsconfig.json

Copy Python config

cp templates/pyproject-sdk.toml /path/to/project/pyproject.toml

Validation Workflow

• Detect Project Type: Check for package.json (TS) or pyproject.toml (Python)

• Run Configuration Validation: Execute appropriate validation script

• Check Dependencies: Verify SDK package is installed with correct version

• Validate Environment: Check .env files for required variables

• Generate Report: Create validation report with findings and fixes

• Apply Fixes: Offer to apply recommended configuration changes

Common Issues Detected

• Wrong package name (anthropic-agent-sdk instead of claude-agent-sdk ) ⚠️

• Missing SDK dependency in package.json/requirements.txt

• Incorrect TypeScript compiler options for SDK

• Missing required environment variables (ANTHROPIC_API_KEY)

• Missing FastMCP Cloud API key when using MCP servers

• Wrong MCP transport type ("sse" instead of "http" for FastMCP Cloud) ⚠️

• SDK version incompatibility with Node/Python version

• Missing configuration files (tsconfig.json, .env)

• Incorrect module resolution settings

• Missing async/await pattern in Python code

Exit Codes

• 0: All validations passed

• 1: Configuration errors found (see report)

• 2: Critical errors (missing SDK, invalid structure)

Examples

See examples/ directory for sample validation reports and common fix patterns.