fix: retry on transient HTTP errors (503/502/504/429) with debug logging

[Copilot]

renderMermaid calls against mcp.mermaidchart.com intermittently throw HTTPStatusError: Server error '503 Service Temporarily Unavailable', causing tool invocations to fail hard with no recovery path.

Changes

src/utils/retry.ts — new withRetry<T> utility

• Retries an async function up to maxAttempts (default 3) on transient HTTP errors
• Default retryable set: 503, 502, 504, 429
• Detects retryable errors via status/statusCode property and word-boundary regex on the error message (catches stringified errors like "Server error '503 Service Temporarily Unavailable'")
• Exponential back-off with configurable base delay (default 500 ms)
• Logs a warn with attempt/total and error message before each retry

export async function withRetry<T>(
  fn: () => Promise<T>,
  options: RetryOptions = {},  // maxAttempts, delayMs, exponential, retryableStatusCodes
): Promise<T>

src/server.ts

• Wraps renderMermaid in withRetry({ maxAttempts: 3, delayMs: 500 })
• Adds Logger.info before each render (logs outputType + theme) for trace correlation
• Adds Logger.error in the catch block so all tool failures surface with full error details

src/utils/index.ts

• Re-exports withRetry

Original prompt

This pull request addresses the issue described in #35, where users sometimes experience a 503 server error ('Service Temporarily Unavailable') while using the mermaid mcp. The error might be related to server infrastructure, load balancing, or other hosting configuration issues. Attached is the reported screenshot in the issue description. The exact cause must be pinpointed by observing patterns of occurrences—time, traffic, etc. Changes include implementing failover handling or retries on receiving specific HTTP status codes such as 503 and logging for debugging information when the error occurs.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: 解决

Assistant: The issue titled "Server error '503 Service Temporarily Unavailable'" in the repository hustcc/mcp-mermaid provides the following details:

Description:

The user and their team occasionally encounter a 503 server error (Service Temporarily Unavailable) while using mermaid mcp. The cause of this issue is unclear, and they are seeking urgent support.

A screenshot of the error is attached:

Status:

• State: Open
• Created: 35 days ago
• Updated: 35 days ago
• Comments: 0
• Assignees: None

---

Would you like me to analyze the issue and suggest potential ways to investigate or resolve it?

User: 直接提 pr 解决

Assistant: A pull request has been initiated to address the issue and resolve the 503 Service Temporarily Unavailable error. Let me know if further adjustments or details are needed.

This pull request was created from Copilot chat.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.