borghei/Claude-Skills / engineering/mcp-server-builder
mcp-server-builder
VerifiedBuilds MCP servers: OpenAPI-to-tool conversion, tool and schema linting, TypeScript or Python scaffolds, transports. Use when exposing an API to AI agents, building a tool server, or reviewing MCP tool definitions.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.5 KB |
| assets/flawed_tools.json | config | 410 B |
| assets/sample_openapi.json | config | 1.8 KB |
| references/server-implementation.md | markdown | 9.7 KB |
| references/streaming-batch-and-computer-use.md | markdown | 11.0 KB |
| references/testing-and-troubleshooting.md | markdown | 5.8 KB |
| references/tool-schema-design.md | markdown | 2.4 KB |
| references/transport-and-deployment.md | markdown | 1.8 KB |
| scripts/openapi_converter.pyexecutable | script | 14.3 KB |
| scripts/server_scaffolder.pyexecutable | script | 11.4 KB |
| scripts/tool_linter.pyexecutable | script | 13.1 KB |
| scripts/tool_schema_linter.py | script | 11.1 KB |
references/streaming-batch-and-computer-use.md
View on GitHub# Streaming, Batch, and Computer-Use Tool Design
Read this when a tool runs long enough to need progress, when it wraps screen/browser/desktop
actions, or when callers process many items at once. These three patterns share one root concern:
keep the conversation efficient and predictable while the work itself is slow, stateful, or risky.
The guidance here is conceptual and model-agnostic. MCP transports and SDKs evolve, so reason about
the *capabilities* below (progress, cancellation, partial results) rather than memorizing exact
field names. Confirm the precise wire format against your SDK version before implementing.
---
## 1. Streaming and Progress for Long-Running Tools
### When a tool needs streaming or progress
Default to a single request/response. Add progress or streaming only when one of these is true:
- The call routinely exceeds a few seconds (builds, crawls, large queries, multi-step automation).
- The result is naturally incremental (log tails, search hits arriving over time, generated chunks).
- A human or agent benefits from seeing intermediate state to decide whether to keep waiting.
If a tool finishes in well under a second, streaming adds complexity for no benefit — return once.
### Progress updates
MCP lets a long call emit progress notifications while the final result is still pending. Treat
progress as *advisory UX*, not as the result:
- **Carry a stable correlation handle.** Tie each progress update to the originating call so a client
can route it to the right place when several tools run concurrently.
- **Report fraction or step, plus a short label.** "3/10 repositories scanned" is more useful to an
agent than a raw percentage with no unit.
- **Send a known total when you have one.** When the total is unknown (streaming an open-ended feed),
send monotonic counts and say so, rather than faking a denominator.
- **Throttle.** Coalesce updates to a sane cadence (e.g., a few per second at most). Flooding the
channel with thousands of ticks wastes tokens and can starve the actual result.
- **Never put load-bearing data only in progress.** The final response must stand alone; a client
that ignored every progress update should still get a complete, correct result.
### Chunking incremental results
When the payload itself is large or arrives over time:
- Stream **semantically whole units** (a complete log line, one search hit, one record), never bytes
split mid-token. A consumer should be able to act on each chunk without buffering the whole stream.
- Make each chunk **self-describing** — include enough identity (index, id, offset) that an
interrupted stream can be resumed or de-duplicated.
- Mark the **terminal chunk** explicitly (an end/complete signal). Don't make clients infer completion
from a timeout.
- Decide up front whether order matters. If chunks can arrive out of order, stamp them with a sequence
number; if order is guaranteed by the transport, document that you rely on it.
### Cancellation and timeouts
Long tools must be interruptible, or a single stuck call can hang an agent indefinitely.
- **Honor cancellation.** MCP supports cancelling an in-flight request; wire it through to the
underlying work (abort the HTTP request, kill the subprocess, close the cursor). Cancellation that
only stops *reporting* but lets the job run on is a resource leak.
- **Set an internal deadline.** Don't rely solely on the client to time out. Cap the operation and
return a clear "timed out after N s, partial results included" response instead of hanging.
- **Make cancellation safe.** If the work mutates state, define what a cancelled call leaves behind —
ideally nothing (transactional) or a clearly-reported partial state. See idempotency below.
- **Clean up on disconnect.** If the client goes away mid-stream, release the subprocess, file handle,
or browser session. Orphaned automation sessions are a common leak in computer-use servers.
---
## 2. Wrapping Computer-Use / Browser / Desktop Actions
Some MCP servers expose *actions on a live surface* — a browser tab, a desktop, a VM — rather than a
pure API. (For building the automation engine itself, see the `computer-use-automation` skill; this
section is about the MCP boundary around it.) These tools are stateful, slow, and often irreversible,
so they need extra discipline.
### Action granularity
Pick a level of granularity that is expressive but not chatty:
- **Too fine** ("move mouse 10px", "press key A") forces the agent into long, fragile click-by-click
sequences and burns turns. Avoid raw primitive-per-call as the *only* interface.
- **Too coarse** ("accomplish this goal") hides what actually happened and makes failures
undebuggable.
- **Prefer intent-level actions** that map to one user-meaningful step: `navigate(url)`,
`click(target)`, `type_text(target, text)`, `read_page()`, `take_screenshot()`. Offer a batched
"do these steps" action (see §3) for known sequences so the agent isn't forced into a round-trip per
keystroke.
- Give actions a **stable way to name targets** (role + accessible name, a selector, or a labeled
element from a prior read) rather than only raw pixel coordinates, which break across viewports.
### Returning screenshots and state
The agent cannot see the screen; the tool's response *is* its eyes. After an action, return enough to
ground the next decision:
- **Current observable state** — a screenshot and/or a structured/text snapshot (accessibility tree,
visible text, URL, focused element). Structured text is cheaper and more reliable than an image when
it suffices; reserve screenshots for when layout/visual state actually matters.
- **What changed** — new URL, dialog appeared, element count, error banner — so the agent isn't forced
to diff two screenshots.
- **Identity for follow-up** — element references the next call can reuse, so the agent doesn't
re-scrape the page each step.
- Keep images **right-sized**: downscale to legible-but-small, and don't return a full-resolution
screenshot after every trivial action. Let the agent request a screenshot explicitly when needed.
### Safety gates for destructive or sensitive actions
Live-surface actions can spend money, send messages, delete data, or leak credentials. Build the gate
into the tool, not just the prompt:
- **Separate read from write.** Navigation/reading is low-risk; submitting forms, purchasing, sending,
or deleting is not. Don't bundle an irreversible action into an innocuous-looking read tool.
- **Require explicit confirmation or a dry-run for irreversible steps.** A `confirm: true` (or a
preceding `dry_run` that returns *what would happen*) forces the agent — and any human-in-the-loop —
to commit deliberately. Default to the safe path.
- **Scope and allowlist.** Constrain which domains, files, or apps the server can touch. A computer-use
server with unbounded reach is a standing security risk.
- **Never echo secrets.** Redact passwords, tokens, and card numbers from screenshots, page dumps, and
logs. Treat any returned state as something the model and transcript will see.
- **Make actions observable and reversible where possible.** Log every action; prefer flows that can
be undone or that stage changes before a final commit.
---
## 3. Batch-Friendly Tool Design
A tool that handles exactly one item forces an agent into N chatty round-trips to process N items —
slow, token-expensive, and error-prone. Design tools so the common "do this to many things" case is
one call.
### Accept arrays
- **Let the primary input take a list.** `delete_records(ids: [...])` beats N calls to
`delete_record(id)`. Accept a single-element list rather than maintaining two tools.
- **Keep per-item structure explicit.** A batch of objects (each with its own fields) is clearer than
parallel arrays the caller must keep aligned.
- **Bound the batch.** Document and enforce a max items / max payload per call so one request can't
blow past timeouts or memory. Reject oversized batches with a clear message telling the caller to
split.
- Don't force batching where it makes no sense — a singleton "get current user" stays singular. Batch
the operations that are genuinely repeated.
### Idempotency
Batches make retries likely (a partial failure, a timeout, a cancelled stream), so repeated calls must
be safe:
- **Prefer idempotent operations** keyed by a stable id, so re-running a batch doesn't double-apply.
- **Support client-supplied operation keys** (an idempotency token per item) when the action creates
something, so a retry recognizes already-done work instead of duplicating it.
- State idempotency guarantees in the tool description — the agent decides retry behavior based on them.
### Partial-failure results
The biggest design trap: a 100-item batch where item 37 fails. Do **not** fail the whole call or you
force the agent to re-do the 99 that worked.
- **Return a per-item result list**, each entry carrying the item's id, a success/failure status, and
its output or error. The agent can then retry only the failures.
- **Use a summary + details shape**: counts of succeeded/failed up top, per-item detail below, so the
agent can branch on the summary without parsing everything.
- **Make errors actionable per item** — which item, why, and whether retrying could help (transient vs.
permanent) — rather than one opaque top-level error.
- **Don't silently drop items.** Every input item should appear in the output (success or failure) so
the caller can reconcile.
### Pagination for list/read tools
The mirror image of batching: a tool that *returns* many items must page, or it floods the context and
risks truncation.
- **Page large result sets** with a limit plus a cursor/offset; return a `next_cursor` (or
`has_more`) so the agent knows whether to continue.
- **Cap and document the default page size.** Never return an unbounded list "because the dataset is
usually small" — datasets grow.
- **Prefer opaque cursors** over offset where the underlying data shifts, to avoid skips/duplicates.
- **Support server-side filtering and field selection** so the agent can narrow results instead of
paging through everything — fewer tokens, fewer round-trips.
- Echo enough context (total count if cheap, current cursor) for the agent to reason about progress.
---
## Quick Checklist
- [ ] Long tools (>~ a few seconds) emit throttled progress with a stable correlation handle.
- [ ] Streamed results are whole units, self-describing, and end with an explicit terminal signal.
- [ ] Cancellation aborts the real work and cleans up sessions; an internal deadline caps runtime.
- [ ] Computer-use actions are intent-level, return current state (text-first, screenshots when needed).
- [ ] Destructive/sensitive actions require confirm/dry-run, are scoped to an allowlist, and redact secrets.
- [ ] Repeated operations accept a bounded array; ops are idempotent or take an idempotency key.
- [ ] Batch tools return per-item success/failure, never a single all-or-nothing error.
- [ ] List/read tools paginate with a documented cap and a cursor, plus filtering to narrow results.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |