Update MCP types to align with what Claude Code expects

[dicksontsai]

Compare against the Typescript SDK

export type McpStdioServerConfig = {
  type?: 'stdio' // Optional for backwards compatibility
  command: string
  args?: string[]
  env?: Record<string, string>
}

export type McpSSEServerConfig = {
  type: 'sse'
  url: string
  headers?: Record<string, string>
}

export type McpHttpServerConfig = {
  type: 'http'
  url: string
  headers?: Record<string, string>
}

export type McpServerConfig = McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig

[claude]

Claude finished @dicksontsai's task —— View job

---

Code Review Complete ✅

Todo List:

• Read and analyze the modified src/claude_code_sdk/types.py file
• Compare Python types against provided TypeScript reference types
• Review code quality and best practices
• Check for potential bugs or issues
• Assess performance considerations
• Evaluate security concerns
• Review test coverage implications
• Provide comprehensive feedback

---

Review Summary

The MCP types update successfully aligns the Python SDK with the TypeScript SDK reference. The implementation is well-structured and follows Python typing best practices.

✅ Code Quality & Best Practices

Excellent alignment with TypeScript reference:

• Correctly uses TypedDict classes for structured config objects
• Proper use of NotRequired for optional fields (equivalent to TypeScript's ?)
• Literal types used appropriately for discriminated union
• Modern Python union syntax (|) used consistently
• Clear docstrings for each config type

Strong typing implementation:

# Perfect mapping from TypeScript optional fields
type: NotRequired[Literal["stdio"]]  # TypeScript: type?: 'stdio'
args: NotRequired[list[str]]         # TypeScript: args?: string[]

✅ Potential Issues Analysis

No bugs identified. The implementation correctly mirrors the TypeScript types:

• Discriminated union: Properly implemented with type field as discriminator
• Optional fields: All optional fields from TypeScript correctly marked with NotRequired
• Type consistency: dict[str, str] correctly maps to Record<string, string>

✅ Performance Considerations

Minimal performance impact:

• TypedDict has negligible runtime overhead compared to regular dicts
• Union types resolved at type-check time, no runtime cost
• Structure is lightweight and appropriate for configuration objects

✅ Security Considerations

No security concerns:

• No dynamic code execution or eval usage
• Type definitions are purely declarative
• Configuration fields are properly typed to prevent injection issues

🔍 Test Coverage Implications

Recommendation: Consider adding tests to verify:

# Example test cases to consider
def test_mcp_stdio_config():
    config: McpStdioServerConfig = {"command": "python", "args": ["-m", "server"]}
    assert config["command"] == "python"

def test_mcp_server_config_union():
    # Test that union type accepts all variants
    stdio_config: McpServerConfig = {"command": "python"}
    sse_config: McpServerConfig = {"type": "sse", "url": "https://example.com"}
    # etc.

✨ Overall Assessment

LGTM! This PR successfully achieves its goal of aligning Python MCP types with the TypeScript SDK. The implementation is:

• Accurate: Perfect 1:1 mapping with TypeScript reference
• Idiomatic: Uses appropriate Python typing constructs
• Maintainable: Clear structure and documentation
• Future-proof: Uses modern Python typing features

Recommendation: ✅ Approve and merge

---