Lessons

LESSON

Local-only knowledge base. Aggregates problems 鈫?root causes 鈫?solutions from DEVLOG.md. Intentionally not tracked by git (configured via .git/info/exclude, never via .gitignore).

Conventions:

• Grouped by category (## <Category>), newest lesson at the top of each.
• Entry format: Problem / Root cause / Solution / How to avoid / Related.
• Slugs are stable IDs 鈥?never rename an old slug, only add "Superseded by".

See .trae/skills/devlog/references/categories.md for the canonical category list.

---

MCP

2026-07-20 mcp-client-request-timeout-string-code

• Problem: Trae IDE reported mcp error: command error: invalid type: string "REQUEST_TIMEOUT", expected i32 at line 1 column 80 when an ssh_execute call timed out, giving no useful information about where the timeout occurred.
• Root cause: Trae's Rust MCP client generates a JSON-RPC error whose code is the string "REQUEST_TIMEOUT" on timeout, violating the JSON-RPC spec that requires error.code to be an integer. The installed mcp Python SDK (1.27.1) does serialize httpx.codes.REQUEST_TIMEOUT as integer 408, so the malformed response originates from the client side, not our server.
• Solution: Add server-side timeout and heartbeat logs so the real hang point can be identified independently of the client's broken error message.
• How to avoid: For long-running tool calls, always log [cmd-start], periodic [cmd-heartbeat], and [cmd-done] / [cmd-timeout] / [cmd-error] events around the blocking SSH execution. Do not rely solely on MCP client error messages for timeout diagnosis.
• Related:
  • DEVLOG.md → ## [2026-07-20] Add execution timeout and heartbeat logging

---

Security

2026-06-28 mcp-tool-every-path-must-validate

• Problem: The ssh_connect MCP tool's optional command parameter executed arbitrary commands without any security validation, audit logging, or dangerous-command confirmation — a complete bypass of the security framework.
• Root cause: The command parameter was added as a convenience feature before the security framework existed. When the security framework was later added to ssh_execute (_handle_execute), the parallel path in _handle_connect was overlooked. MCP tools with multiple parameters can hide execution paths that bypass the main handler.
• Solution: Add command_validator.validate_command() before every command execution, regardless of which MCP tool handler triggers it. Log blocked attempts to the audit trail. Connection success should still be returned even when the command is blocked.
• How to avoid: When adding a new parameter to an existing MCP tool that can execute commands, always route the execution through the same validation path. Review all session.execute_command() call sites for security gaps.
• Related:
  • DEVLOG.md → ## [2026-06-28] Fix ssh_connect command bypassing security validation

---

Index

(to be generated once the file has more than ~10 lessons)

---