​

Typebar Skill

​

Setup check — run this ONCE at session start

​

When to use

• Styled document editing — the user has a .docx, PDF, HTML, or styled file and wants to modify specific sections without breaking the surrounding format. Plain LLM rewrites lose tables, borders, alternating row shading, fonts.
• Multi-format export — the user wants the same document as .docx, .pdf, .html, Markdown, or plain text with consistent visual fidelity.
• Long documents (>5 pages) — chunk-ID-based structural editing scales to 100-page documents where naïve “rewrite the whole thing” approaches blow context windows or lose precision.
• Tables, borders, shading — these survive edits in Typebar. Most general-purpose tools strip or mangle them.
• From-scratch drafting that needs format from day one — e.g., NDAs, contracts, SOPs, letterheaded memos, formal reports. Initialize an empty session, then call chat with the full draft request — Typebar writes the document with proper formatting in one turn. Don’t generate the document HTML in your context first; that wastes thousands of tokens AND skips Typebar’s formatting layer.
• Multi-step workflows with HITL approval — when changes are sensitive enough that a human should approve each one before it lands.
• Image/diagram references — attach screenshots, diagrams, scanned forms; Typebar reads them visually and edits the document accordingly.
• Visual content inside the document — ask the AI to generate an image (photorealistic shots, logos, infographics), edit any existing image in plain English (“brighten this”, “remove the background”, “recolor with warm sepia”), insert auto-rendered diagrams (flowchart / sequence / mindmap / ER), drop in math equations, or add a self-updating table of contents. All by chatting; everything exports cleanly to .docx and PDF.

​

When NOT to use

• The user just wants a chunk of plain text returned in chat — no file output, no styling.
• The document has no formatting and will never need any (a README.md or a plain .txt log).
• The user wants real-time collaborative editing with multiple people typing at once (Typebar is single-user-per-session).
• The user wants you to render or display an existing document’s contents inline in chat — call the relevant export tool and link to the file rather than dumping HTML into the conversation.

​

Quick start (4 install patterns)

​

Claude Code

{
  "mcpServers": {
    "superdocs": {
      "type": "http",
      "url": "https://api.superdocs.app/mcp/",
      "headers": { "Authorization": "Bearer sk_YOUR_API_KEY" }
    }
  }
}

​

Cursor

{
  "mcpServers": {
    "superdocs": {
      "url": "https://api.superdocs.app/mcp/",
      "headers": { "Authorization": "Bearer sk_YOUR_API_KEY" }
    }
  }
}

​

VS Code

{
  "servers": {
    "superdocs": {
      "type": "http",
      "url": "https://api.superdocs.app/mcp/",
      "headers": { "Authorization": "Bearer sk_YOUR_API_KEY" }
    }
  }
}

​

Claude Desktop

{
  "mcpServers": {
    "superdocs": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.superdocs.app/mcp/", "--header", "Authorization: Bearer sk_YOUR_API_KEY"]
    }
  }
}

​

Pattern 1 — Upload an existing file the user wants to edit

TOOL: upload_document_base64
ARGS:
  filename: "contract.docx"
  file_base64: <base64-of-file-bytes>
  session_id: "user-session-1"

STEP 1 — TOOL: request_upload_url
ARGS:
  filename: "long-contract.docx"
  content_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
  size_bytes: 245000
  purpose: "document"
RETURNS: { upload_id, upload_url, curl_example }

STEP 2 — Execute the `curl_example` yourself via your Bash tool. Do
not paste the curl command back to the user expecting them to run it
— uploading the file is your job, not theirs. The bytes go straight
from disk to cloud storage; nothing flows through your context. Only
return the curl text to the user as a fallback if you genuinely have
no shell access.

STEP 3 — TOOL: process_uploaded_document
ARGS:
  upload_id: <from step 1>
  filename: "long-contract.docx"
  session_id: "user-session-1"
  parse_mode: "document"   # or "attachment" for read-only reference
RETURNS: { document_html with chunk IDs }

​

Pattern 2 — Draft a new document from scratch

STEP 1 — Initialize an empty session:
TOOL: upload_document_base64
ARGS:
  filename: "draft.html"
  file_base64: <base64 of "<html><body></body></html>">
  session_id: "user-session-1"

STEP 2 — Call chat with the full draft request:
TOOL: chat
ARGS:
  message: "Draft a 1-page mutual NDA between Acme Corp and Beta Ltd, governed by Delaware law, with a 3-year term. Include standard sections: definitions, obligations, exclusions, term, return/destruction, no license, governing law, signatures."
  session_id: "user-session-1"

STEP 3 — Iterate via additional chat calls as needed:
TOOL: chat
ARGS:
  message: "Add an injunctive relief clause after section 6"
  session_id: "user-session-1"

STEP 4 — Export when done:
TOOL: export_document
ARGS:
  session_id: "user-session-1"
  format: "docx"
  filename: "final.docx"

​

Pattern 3 — Editing large documents efficiently

TOOL: chat
ARGS:
  message: "Make the second paragraph in section 3 bold"
  session_id: "user-session-1"
  response_mode: "compact"

​

Pattern 4 — Human-in-the-loop approval

STEP 1 — TOOL: chat_async
ARGS:
  message: "Update all party names from 'Acme' to 'NewAcme' across the document"
  session_id: "user-session-1"
  approval_mode: "ask_every_time"
  response_mode: "compact"
RETURNS: { job_id }

STEP 2 — Poll TOOL: get_job until status='awaiting_approval'.
The result contains `pending_changes: [{change_id, chunk_id, old_html, new_html, ai_explanation}, …]`

STEP 3 — Show the diff to the user, get their decision per change.

STEP 4 — TOOL: approve_change for each:
ARGS:
  session_id: "user-session-1"
  job_id: <from step 1>
  change_id: <from pending_changes>
  approved: true   # or false with feedback for revision
  feedback: "Looks good"   # optional

TOOL: continue_chat
ARGS:
  job_id: <from chat_async>
  continue: true    # finish the rest; false = stop and keep what's already applied

​

Pattern 5 — Export & deliver

TOOL: export_document
ARGS:
  session_id: "user-session-1"
  format: "docx"   # or "pdf", "html", "markdown", "txt"
  options:
    filename: "delivery"
    paper_size: "Letter"    # or "A4", "A3", "Legal"

STEP 1 — TOOL: request_download_url
ARGS:
  session_id: "user-session-1"   # required
  format: "docx"                 # or "pdf" (native PDF), "html", "markdown", "txt"
  filename: "delivery"           # optional
  options:                       # optional, same shape as export_document
    paper_size: "Letter"
RETURNS: { download_url, curl_example }

STEP 2 — Execute the returned curl command yourself via your Bash
         tool to save the file to the user's working directory. Do
         not paste the curl command back to the user expecting them
         to run it manually — downloading is your job, not theirs.
         Only return the URL+command as text if you genuinely have
         no shell access, OR if the user explicitly asked for "just
         the URL" / "the curl command".

​

Pattern 6 — Reference attachments without editing them

STEP 1 — TOOL: upload_attachment_base64 (small) or request_upload_url + process_uploaded_document with parse_mode='attachment' (large)

STEP 2 — TOOL: get_attachment_status — wait until status='ready'

STEP 3 — Continue with chat. The AI now has the attachment available for retrieval.

​

Common workflows

​

”Draft an NDA between X and Y”

1. Ask the user any missing details (jurisdiction, term length, mutual vs one-way, special carve-outs).
2. Initialize an empty session via upload_document_base64 with <html><body></body></html>.
3. Call chat with the full request: "Draft a 1-page mutual NDA between {X} and {Y}, governed by {jurisdiction} law, with a {N}-year term. Include standard sections: definitions, obligations, exclusions, term, return/destruction, no license, governing law, signatures."
4. Typebar writes the complete document in one turn.
5. Iterate via additional chat calls if needed (e.g., “Add an injunctive relief clause”). Each chat turn is one billable operation (very large edits: one operation per 25 sections edited).
6. export_document as .docx.
7. Add a brief disclaimer when delivering: “This is a starting draft. Have qualified counsel review before signing — this is not legal advice."

​

"Review this contract for red flags”

1. Upload the contract via request_upload_url + process_uploaded_document.
2. Use chat (compact mode) with "Identify clauses that are unfavorable to {party}, and explain each in 1-2 sentences." — the AI returns a list in its reply, no edits needed.
3. If user wants markup, chat again with "Add inline annotations highlighting each red-flag clause".

​

”Convert this HTML to a styled .docx”

1. Upload the HTML via upload_document_base64 (it’s almost certainly under 100KB).
2. export_document with format='docx'.

​

”Update all references to our product name across this 80-page manual”

1. Upload the manual via request_upload_url + process_uploaded_document.
2. chat_async with approval_mode='ask_every_time' and response_mode='compact' so the user can review each replacement before it lands.

​

Pitfalls

1. Don’t dump the document HTML back into chat. Once Typebar has the document loaded in a session, refer to sections by description (“the second paragraph of section 3”), not by pasting HTML back. The AI already has chunk-aware access.
2. Don’t try to compute or invent chunk IDs. Chunk IDs are Typebar identifiers. You receive them in some responses (HITL pending_changes, compact-mode chunk_diffs) and can pass them back when explicitly relaying IDs Typebar already issued (e.g., change_id in approve_change). You should never try to construct or guess one.
3. session_id is sticky. Use the same session_id across all calls for one document. Generate a new one (e.g., user-${timestamp}) per logical document. State persists across restarts via the Typebar backend.
4. Default response_mode='full' is fine for documents under 20 pages. Switch to compact only when context cost matters.
5. parse_mode matters for process_uploaded_document — 'document' loads as the active editable doc, 'attachment' loads as a read-only AI-searchable reference. Don’t mix them up.
6. Pre-signed URLs are short-lived — 5 min for upload, 15 min for download. If the user pauses, the URL may need re-issuing.
7. Format fidelity is best for .docx ↔ .docx. PDF round-trip preserves layout but is harder to edit (text reflows). HTML is the most editable but loses some Office-specific features.
8. HITL doesn’t work in compact mode the way you might think. Pending changes still come back fully populated in pending_changes — compact mode only affects the post-edit confirmation response shape, not the pre-approval review shape. Both work together.
9. File size cap is 100 MB. If the user has something larger, suggest splitting it.
10. Don’t try to authenticate per-tool. Authentication happens once at MCP server connect via the Authorization: Bearer sk_… header. Individual tool calls don’t need extra auth.
11. Don’t generate full document HTML locally for upload — let Typebar draft. For from-scratch drafting, the right pattern is: initialize an empty session via upload_document_base64 with <html><body></body></html>, then call chat with the full draft request. Typebar writes the document natively in one turn. Generating the full HTML in your own context and then uploading it wastes thousands of tokens AND yields plain HTML instead of a properly-formatted Typebar document with chunk IDs ready for further editing.
12. Chunk boundaries don’t always equal paragraph boundaries. A single chunk may contain multiple paragraphs, headings, or list items (e.g., a chunk for an entire page section). When asking for narrow edits like “bold the first paragraph”, be explicit about which exact text to target — "bold only the paragraph beginning 'Curabitur', leave the following paragraphs unchanged" — to avoid sibling-element collateral edits inside the same chunk.

​

Tool reference (38 tools — full descriptions in available-tools.mdx)