What I Built
DevDocs Navigator is a CLI agent that helps developers navigate multi-version API documentation. It connects to a Sanity Context MCP knowledge base of structured API docs and answers questions that keyword search simply can't — like generating ordered migration plans that respect breaking change dependencies, or explaining why a 409 error in v2 becomes a 422 in v3.
The agent is built with the Claude SDK (TypeScript) and connects to Sanity Context via MCP. It queries a knowledge base of structured PayFlow API documentation spanning 3 major versions.
Repo: github.com/suraj16thjan/devdocs-navigator
Sanity Project ID: oqa25u7d
Why Structure Matters Here
Developer documentation is one of the best examples of content where structure is the entire point. Consider this question:
"I'm on PayFlow API v1 and need to get to v3. What do I do?"
A keyword search finds pages mentioning "v1", "v3", and "migration" — maybe even the right pages. But it can't tell you:
- JWT auth must be implemented first — every v3 endpoint requires it, so nothing else works until this is done
- Multi-currency amounts depend on JWT auth — you can't test the new amount format without v3 access
- Webhook signature changes depend on JWT auth too — re-registering webhooks requires v3 API calls
- Subscription event renames depend on the webhook signature change — the new event names only fire on v3 webhook registrations
- The webhook envelope format change (from v1→v2) must happen AFTER renaming charges to payments — the new event types reference "payment" objects
That ordering isn't in any single document. It emerges from the relationships between documents: breaking changes reference which other breaking changes they depend on, migration paths link to the breaking changes they address in a specific order, and endpoints track which version introduced and deprecated them.
This is exactly what Sanity Context enables — structured content where the relationships are first-class data, not implicit context a reader has to reconstruct.
The Content Model
The knowledge base contains 32 structured documents across 5 schema types:
API Versions (3 documents)
Each version tracks its status (stable/deprecated/sunset), release date, sunset date, and key highlights.
Endpoints (12 documents)
Each endpoint records its HTTP method, path, which version introduced it, which version deprecated it, what replaced it (a reference to another endpoint document), auth requirements, rate limits, parameters (with version-specific additions/removals), and version-specific behavior notes.
Breaking Changes (9 documents)
This is where the structure shines. Each breaking change records:
- Severity (critical/major/minor)
- Affected endpoints (references to endpoint documents)
- Affected categories (payments, webhooks, etc.)
- Migration steps (ordered)
- Dependencies — references to other breaking changes that must be applied first
- Before/after code examples
The dependency chain between breaking changes is what makes the agent's migration plans correct and ordered. For example:
bc-v3-jwt-auth (no dependencies)
↳ bc-v3-multi-currency (depends on JWT auth)
↳ bc-v3-webhook-signatures (depends on JWT auth)
↳ bc-v3-subscription-events (depends on webhook signatures)
↳ bc-v3-idempotency-uuid (depends on JWT auth)
Migration Paths (3 documents)
Pre-computed migration guides (v1→v2, v2→v3, v1→v3) with ordered steps, each referencing the relevant breaking change. The v1→v3 path is particularly interesting — it combines and reorders steps from both incremental paths, noting where changes can be collapsed (e.g., skip the v2 amount format and go straight to multi-currency).
Error Codes (5 documents)
Each error code has version-specific behavior — the same error code can return different HTTP status codes, different response body structures, and have different root causes depending on the API version. For example:
| Error | v1 | v2 | v3 |
|---|---|---|---|
IDEMPOTENCY_CONFLICT |
Not supported | HTTP 409, any string key | HTTP 422 (changed!), UUID v4 required |
AUTH_INVALID |
API key only | API key or OAuth, detailed error | JWT only, specific sub-codes |
CURRENCY_MISMATCH |
Doesn't exist | Doesn't exist | HTTP 422, shows expected vs received |
How the Agent Works
The agent uses a standard MCP client-server architecture:
User Question
↓
Claude (with MCP tools)
↓
Sanity Context MCP Server
↓
Knowledge Base (structured PayFlow docs)
↓
Grounded Answer
- On startup, the agent connects to the Sanity Context MCP endpoint and discovers available tools
- User asks a question
- Claude receives the question along with the MCP tools from the knowledge base
- Claude calls the appropriate tools to query the structured content
- Tool results come back with the structured data — including references, dependencies, and version-specific fields
- Claude synthesizes the answer, respecting the structure (dependency ordering, version applicability, etc.)
Example Interactions
"What changed between v2 and v3?"
The agent queries breaking changes introduced in v3, finds 5 of them, and presents them in dependency order — not alphabetical, not by severity, but by the order you'd need to apply them. It notes that JWT auth is the critical first step since everything else depends on it.
"I'm getting a 429 after upgrading to v2, what's different?"
The agent queries the RATE_LIMIT_EXCEEDED error code and surfaces the version-specific behavior: v1 had a hard cap at 100/min with X-RateLimit-* headers, while v2 uses 60/min sustained with burst to 120 and IETF RateLimit-* headers. It also notes the Retry-After header is now available.
"How do I migrate webhooks from v1 to v3?"
This is where dependency chains matter. The agent traces:
- First apply
bc-v2-charges-renamed(charges → payments) - Then
bc-v2-webhook-format(flat → envelope, depends on step 1) - Then
bc-v3-jwt-auth(needed for v3 webhook registration) - Then
bc-v3-webhook-signatures(SHA-1 → SHA-256, depends on step 3) - Then
bc-v3-subscription-events(event renames, depends on step 4)
No keyword search could produce this ordered sequence. It requires traversing the dependency graph in the structured content.
Tech Stack
- Content: Sanity Studio v3 with TypeScript schemas
- Knowledge Base: Sanity Context with GROQ dataset binding
-
Agent: Node.js + Claude SDK (
@anthropic-ai/sdk) + MCP SDK (@modelcontextprotocol/sdk) - Transport: Streamable HTTP / SSE to Sanity Context MCP endpoint
What I'd Do Differently
If I had more time, I'd:
- Add a web UI with interactive migration checklists
- Support real API documentation (Stripe, Twilio) instead of a fictional API
- Add a "diff my code" feature where you paste your integration code and the agent identifies which breaking changes affect it
- Enable auto-refresh so the knowledge base stays in sync as docs change
The Structured Content Advantage
The core insight: developer documentation is inherently relational. An endpoint exists in some versions but not others. A breaking change affects specific endpoints and depends on other breaking changes being applied first. An error code behaves differently across versions. Migration is an ordered graph traversal, not a text search.
Sanity Context makes these relationships queryable through MCP, which means an AI agent can reason about them — generating correct migration plans, version-aware error explanations, and dependency-ordered change lists that no amount of keyword searching could produce.
Top comments (0)