Claude Design Sync: A Deep Dive into Protocol Archaeology

Using an LLM agent to sync files from Claude Design to a local disk is essentially using a supercomputer as a glorified cp command. I tracked a single project sync that burned through 665,000 tokens just to move bytes from point A to point B. Since moving files isn't a reasoning task, paying that "token tax" is absurd.

To fix this, I decided to build a CLI that handles clone, pull, and push operations directly via the API, bypassing the model's context entirely. The catch? The Design API is undocumented.

Reverse-Engineering the Protocol

Since the endpoint is an MCP server, the transport layer (JSON-RPC) is predictable, but the tool definitions are a black box. I had to treat this like archaeology: call the endpoint, observe the response, and document the behavior.

The biggest trap in this process is relying on mocks. If you build a mock based on a guess, your tests will pass, but you're just verifying your own assumptions. I hit three specific walls where my assumptions failed:

• Return Types: I assumed write_files returned a list. It actually returns a map keyed by path.
• Error Handling: I expected "access denied" to be a tool-level error inside a 200 response. It's actually a hard HTTP 403.
• Binary Detection: I thought the server checked file extensions. It actually inspects the bytes; a .txt file full of NULs is treated as binary.

To prevent this, I implemented a "live test" suite. While mocks handle logic, the actual protocol facts are verified against the real server. If the API changes, the tests go red immediately.

Ensuring Data Integrity

Once you remove the LLM from the loop, you're building a sync engine, and sync engines are notorious for data loss. I focused on two main safeguards for this AI workflow:

1. Atomic Writes: Every file is written to a temporary location and then renamed. This prevents half-written files if the process crashes, which would otherwise look like a local edit and lead to accidental overwrites.
2. Byte-Level Conflict Resolution: I ignored timestamps and etags entirely. If the bytes differ on both ends, it's a conflict. Period.

For those looking to implement similar logic or explore the underlying structure, here is the conceptual prompt logic I used to map out the initial tool capabilities:

Act as a protocol analyst. I will provide you with a series of JSON-RPC requests and responses from an undocumented MCP server. 
Your goal is to:
1. Identify the exact schema of the tool arguments.
2. Map the possible return types (List vs Map).
3. Distinguish between transport-level errors (HTTP codes) and application-level errors.
4. Flag any discrepancies between the filename extension and the server's content-type detection.

Current observation: [Insert JSON trace here]

By treating the API as a living organism rather than a static document, I turned a 665k token expense into a simple one-line summary: pulled 103, unchanged 0, binary 6.