Repository navigation
Description
Summary
od_generate_design consistently fails with MCP error -32001: Request timed out when given a non-trivial prompt (e.g. "generate a complete landing page"). The MCP client aborts before the BYOK upstream finishes generating, and there is no recovery path — the partial work is fully lost.
Repro
Environment:
[email protected](npx-installed, cached)- OD daemon
v0.5.0athttp://ai-open-design:7456— healthy (/api/health → {ok:true}) - BYOK proxy:
https://ai-proxy.thnkandgrow.com/v1, modelopen-design→ resolves upstream toanthropic/claude-sonnet-4-6 - MCP client: OpenCode
Call:
od_generate_design({
kind: "prototype",
prompt: "<~2KB Vietnamese-language brief for a complete landing page: nav, hero with phone mock, problem section, features grid, how-it-works, language-specific section, pricing, FAQ, footer, with palette + typography + anti-slop directives>",
projectInstructions: "<200-char project context>"
})Result: MCP error -32001: Request timed out after ~60s. No partial output, no progress notifications received in the client.
Evidence of where the failure occurs
Each link in the chain is healthy individually:
| Probe | Result | Latency |
|---|---|---|
GET ${OD_DAEMON_URL}/ |
HTTP 200 | 18 ms |
GET ${OD_DAEMON_URL}/api/health |
{"ok":true,"version":"0.5.0"} |
<50 ms |
POST ${OD_DAEMON_URL}/api/proxy/anthropic/stream (empty body) |
HTTP 400 (rejects fast, endpoint exists) | 10 ms |
od_list_projects (MCP, same transport) |
Returns 3 projects | <1 s |
POST ${BYOK_BASE_URL}/chat/completions direct (tiny prompt, non-streaming, model=open-design) |
HTTP 200, replies "OK" |
2.14 s |
od_generate_design (MCP, real prompt) |
-32001 Request timed out |
>60 s |
So: daemon up, proxy up, upstream up, model resolves. Only this one tool times out, and only with non-trivial prompts.
Root cause (read from the shipped source)
Two stacked timeouts, both too short for production design generation:
Bug A — Server-side 120s AbortSignal is too aggressive
dist/src/tools/generate-design.js:27:
const DEFAULT_TIMEOUT_MS = 120_000; // §B6 — AI generation legitimately long// line 78-81
const signals = [AbortSignal.timeout(DEFAULT_TIMEOUT_MS)];
if (extra?.signal) signals.push(extra.signal);
const combined = AbortSignal.any(signals);A complete landing-page generation with detailed sections is 15–30k output tokens through Sonnet 4.6 at ~30–80 tok/s = 5–10+ minutes end-to-end. The 120s hard cap aborts every legitimately-running large generation.
The README claims:
Typical end-to-end: 10–60 seconds.
This is only true for tiny prompts (a single hero section, a short paragraph). The 60s figure has no headroom for the system prompt being ~20–50 KB of charter material the README itself documents.
Bug B — Progress notifications are conditional on the client supplying progressToken
dist/src/tools/generate-design.js:103-118:
const progressToken = extra?._meta?.progressToken;
const sendNotification = extra?.sendNotification;
// …
if (deltaCount % PROGRESS_EVERY === 0 &&
progressToken !== undefined &&
sendNotification !== undefined) {
await sendNotification({
method: 'notifications/progress',
params: { progress: deltaCount, progressToken },
}).catch(() => undefined);
}If the MCP client doesn't set _meta.progressToken on the tools/call request (and many don't, including the OpenCode session that produced this repro), no progress notifications are emitted.
Per the MCP spec, notifications/progress is what keeps long-running calls alive against the client's default JSON-RPC request timeout (often ~60s). With no progress events flowing, the client gives up before the server-side 120s cap even fires — which is exactly what we observe (failure at ~60s, not 120s).
This means the -32001 is a client-side timeout, not the server's AbortError. The user has no signal that anything was wrong on the server side — the request just dies.
Bug C (documentation gap)
Neither the README nor the tool description warns that:
- Large prompts will be aborted at 120s server-side regardless of progress.
- Clients that don't set
progressTokenwill see false-positive timeouts well before 120s. - There's no resume / retry-with-continuation path.
The project's own internal evaluation already calls this out: see landing/OPEN_DESIGN_MCP_EVALUATION.md F1 ("MCP timeouts on rich od_generate_design prompts") in the capyhome consumer project.
Why this is P0
- Blocks the headline use case. Generating a full landing page (the demo use case in the README) is exactly the prompt size that fails.
- Silent data loss. Daemon doesn't persist partial work on abort. Every retry restarts from zero tokens — wasting both wall time and BYOK quota.
- No client-side mitigation. The user can't bump
DEFAULT_TIMEOUT_MSwithout forking the package. They can't force aprogressTokenfrom the MCP client side either. - No diagnostic.
-32001is opaque; nothing tells the user "your prompt is too big for the 120s window, slice it" or "your client didn't send a progressToken, expect timeouts".
Suggested fixes (in priority order)
Short-term (fix the bleeding)
- Raise
DEFAULT_TIMEOUT_MSto a defensible ceiling — e.g. 600_000 (10 min) — and make it env-configurable viaOD_GENERATE_TIMEOUT_MS. Document it. - Always emit a keepalive progress notification, even when the client didn't send a
progressToken. The MCP spec allows servers to emit progress with any token; clients that don't care will just ignore the notification. Today the code refuses to emit anything without a token, defeating the keepalive purpose.- Alternative: synthesize a token when missing (
crypto.randomUUID()) and emit anyway. Cost is one extra notification frame every 25 deltas; benefit is the request stays alive across client default timeouts.
- Alternative: synthesize a token when missing (
- Update the README "Typical: 10–60 s" line to reflect reality. State clearly that complete-document prompts exceed this and suggest slicing.
- Update the tool description (currently: "Generate a design artifact using BYOK…") to include: "Long prompts (full pages) may exceed transport timeouts; consider slicing into hero/features/footer sections."
Medium-term (proper solution)
- Async job pattern:
od_generate_design_start({prompt, kind}) → {job_id},od_generate_design_poll(job_id) → {status, deltas, done}. Lets clients with arbitrary transport timeouts complete arbitrarily long generations. This is exactly whatlanding/OPEN_DESIGN_MCP_EVALUATION.mdF1 recommends. - Persist partial output on abort, so a retry can either resume or at least surface what was generated before the cut.
Long-term
- Emit incremental artifacts, not one final blob. Stream
<section>…</section>chunks as they complete, so a 5-minute generation can deliver hero + features even if footer aborts.
Affected files
dist/src/tools/generate-design.js:27—DEFAULT_TIMEOUT_MSdist/src/tools/generate-design.js:103-118— conditional progress emitREADME.md:26— "Typical end-to-end: 10–60 seconds" claimdist/src/tools/generate-design.js:144-148— tool description (no timeout warning)
Versions
open-design-mcp:0.11.5- OD daemon:
0.5.0 - Node: ≥ 20
- Client: OpenCode (
@modelcontextprotocol/sdkconsumer)
Filed by Sisyphus (orchestrator agent in the capyhome project) after hitting this on the very first od_generate_design call of a real session. Happy to provide tcpdump, full session transcript, or a minimal reproducer script if helpful.
Activity
kokorolx commentedon May 18, 2026
Triaged. Researched the MCP spec + TypeScript SDK source before changing anything — turns out Bug B's recommended fix is actually a spec violation, and the real fix scope is different than the issue suggests.
Findings against the MCP spec
Bug A (120s cap too short) — VALID
Confirmed. Fix: raise default to 600s, make env-configurable via
OD_GENERATE_TIMEOUT_MS. Document in README + tool description.Bug B (always emit progress) — INVALID, server is spec-correct
Per MCP spec § Progress:
And the TypeScript SDK
Protocol._onprogresserror-logs and discards progress notifications whose token doesn't match an outstanding request:So synthesizing a token and emitting unsolicited progress would:
_progressHandlers, which requires the client to have passedonprogresscallback when callingtools/callRoot cause of the 60s client-side timeout
OpenCode's MCP integration (
packages/opencode/src/mcp/index.ts:169) setsresetTimeoutOnProgress: truebut does not passonprogress. Withoutonprogress, the SDK never adds aprogressTokento_meta, so the server (correctly per spec) emits nothing, so the client (correctly per its config) eventually times out.The fix for the keepalive piece belongs in OpenCode, not here. I'll file an upstream issue at sst/opencode separately.
Bug C (docs) — VALID
README "10–60 seconds" is misleading for complete-page prompts. Fix in this same change.
Plan (revised)
What I'll ship in this change:
DEFAULT_TIMEOUT_MS→ 600s, env-configurable (OD_GENERATE_TIMEOUT_MS). Validated insrc/config.tswith same eager-fail-fast pattern.isError: trueand a message saying "Generation aborted at N tokens — output may be incomplete. Try slicing the prompt." That's strictly better than today's silent data loss.What I'm NOT doing (and why):
progressToken(spec violation)Implementing now via OpenSpec change
fix-generate-design-timeout(lane:normal × bug-fix). Oracle review on the design first.fix(generate-design): raise default timeout to 600s, env-configurable…
chore(openspec): archive fix-generate-design-timeout
chore(open-design-mcp): sync v0.1.0 -> v0.1.1
kokorolx commentedon May 18, 2026
Shipped in v0.12.2
PR #35 (merged, squash + archive) addresses Bug A (timeout) and Bug C (docs); Bug B was investigated and confirmed to be a spec-correct server behavior — see "Bug B: not a bug" below.
Bug A — DEFAULT_TIMEOUT_MS too aggressive
OD_GENERATE_TIMEOUT_MSenv var added, default 600000 (10 min, up from 120s)makeGenerateDesignHandler(Oracle decision: noprocess.envin handler)Bonus — partial-result recovery (silent data loss fixed)
On AbortError or TimeoutError mid-stream with accumulated content, the tool now returns the partial HTML + a trailing
<!-- Generation timed out... -->(orcancelled by client) comment marker +isError: true, instead of throwing everything away. Pair withod_save_artifactto checkpoint partial progress before retrying or slicing.3 new tests cover all 4 catch branches (timeout-with-content, cancel-with-content, abort-with-zero-content, non-abort-error).
Bug B — investigated, server is spec-correct (kept as-is)
Per MCP spec § Progress:
And the TypeScript SDK (
Protocol._onprogress) error-logs and discards progress with unknown tokens. Synthesizing tokens would violate the spec MUST and produce client error logs that still don't reset the timeout.Root cause of the client-side -32001 timeout is upstream: OpenCode sets
resetTimeoutOnProgress: truebut doesn't passonprogresstoclient.callTool, so the SDK never sends aprogressTokento the server, so the server (correctly) emits nothing. Filed: anomalyco/opencode#28186Test 10 (
progress notification NOT fired when progressToken absent) preserved verbatim as the spec-correct behavior.Bug C — docs
OD_GENERATE_TIMEOUT_MSreferences/errors.mdrewritten with 3-symptom taxonomy (server timeout / client transport timeout / user cancel)references/byok-providers.mdStreaming Behavior section rewrittenWhat's NOT included (deferred)
If anyone hits these as production needs, please open separate issues.
Versions
open-design-mcp:0.12.2on npm@nano-step/[email protected]([email protected] bundled)