What is the best way to verify a fix for an SDK bug?

Use the guide's verification strategy: verify the immediate return value, simulate the SDK's internal serialization logic, and then test the full end-to-end workflow.

How do I find the root cause of an SDK error if it's hidden?

The guide recommends checking full error tracebacks in logs/errors.log and using grep to find specific serialization or type errors that user-facing messages might hide.

Why am I getting JSON serialization errors with MCP servers?

This typically happens when the SDK fails to strip non-serializable objects (like Server instances). This guide helps you verify identification keys like 'type=sdk' so the internal stripping logic triggers correctly.

Why does TypedDict matter for debugging the Claude SDK?

TypedDict is not enforced at runtime in Python. If your keys are slightly off, the error won't happen at the assignment but much later inside the SDK's internal processing logic.

Claude SDK Debugger

Name: Claude SDK Debugger
Author: WarrenZhu050413

byWarrenZhu050413

•

API開発

Diagnoses and resolves complex Claude Agent SDK errors, TypedDict contract mismatches, and MCP server serialization failures.

概要

This skill provides a comprehensive framework for debugging internal Claude Agent SDK issues and Model Context Protocol (MCP) server configurations. It moves beyond superficial error messages by teaching developers how to interpret full tracebacks, locate SDK source code within virtual environments, and verify internal processing logic. By focusing on runtime TypedDict contracts and JSON serialization patterns, it helps resolve cryptic 'not JSON serializable' errors and parameter mismatches that often occur when building custom Claude integrations.

主な機能

Step-by-step patching checklist for SDK internal bug fixes
MCP server configuration and serialization troubleshooting
TypedDict contract verification and mapping strategies
5 GitHub stars
Traceback analysis for deep-stack SDK error identification
SDK source code inspection workflows for local environments

ユースケース

Debugging internal SDK processing failures during agent initialization
Resolving runtime TypedDict mismatches in ClaudeAgentOptions
Fixing 'Object of type Server is not JSON serializable' errors in MCP setups

概要

主な機能

Step-by-step patching checklist for SDK internal bug fixes
MCP server configuration and serialization troubleshooting
TypedDict contract verification and mapping strategies
5 GitHub stars
Traceback analysis for deep-stack SDK error identification
SDK source code inspection workflows for local environments

ユースケース

Debugging internal SDK processing failures during agent initialization
Resolving runtime TypedDict mismatches in ClaudeAgentOptions
Fixing 'Object of type Server is not JSON serializable' errors in MCP setups