ClaudeDesign 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 assumedwrite_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:
-
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.
-
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
.
Next Solana AI Agent: My Deployment Workflow →