An MCP server that acts as an escape guide for AI coding agents, providing structured thinking protocols to help agents unstick themselves without human help.
The server provides 5 tools with explicit schemas and descriptions, but exhibits inconsistencies in schema completeness, parameter validation, and error guidance. Tool naming follows verb_noun conventions (list_, get_) and is clear. Descriptions are present but often generic. Sampling mode introduces complexity that is partially underdocumented. Parameter types are defined via Zod, but several lack detailed constraints. Error handling exists but is minimal. The server would benefit from richer descriptions (50-200 chars per pattern:tool-description), explicit output schema documentation, and recovery guidance for failures.
Scenario tool for when bug fixes always fail
Get prompt template for any scenario (core or extended) with optional mode. Use list_scenarios to discover available scenario IDs.
List all available stuck-agent scenarios with their tier (core/extended). Core scenarios are also directly available as individual tools.
Scenario tool for when logic implementation becomes too complex
Scenario tool for when requirements are missing
Generic scenario tool names (logic-is-too-complex, bug-fix-always-failed, missing-requirements) lack verb prefixes and are hyphenated rather than snake_case. While descriptive, they deviate from LLM-friendly verb_noun convention and reduce clarity when listed alongside get_prompt and list_scenarios.
Parameter 'contextSummary' is marked optional in schema but the description states 'Required for sampling mode'. The actual validation only occurs at runtime in handleScenarioRequest() (line: 'if (!contextSummary)'), not in the schema. This creates a silent contract violation, LLMs cannot infer the conditional requirement from Zod .optional().
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-21 | D | 57 | <=2025-11-25 | v2 |
| 2026-03-09 | F | 8 | - | v1 |
Tool descriptions for core scenario tools (logic-is-too-complex, etc.) are minimal (avg ~45 chars: 'Scenario tool for when...'). Per pattern:tool-description, descriptions should be 10 - 1024 chars and answer WHAT, WHEN, and WHAT IT RETURNS. Current descriptions lack context for LLM selection and do not explain when to use each scenario over another.
Output schema is not documented. The handleScenarioRequest() function returns a union type (StaticToolResult as array of messages vs SamplingToolResult from LLM). LLMs cannot infer the structure of the 'content' field or predict what object shape results from sampling mode. Documentation is missing for the return type of each mode.
Error handling is minimal and non-actionable. When scenario is not found (get_prompt), error is returned as JSON text in content[0].text with isError=true. When contextSummary is missing (sampling mode), error message suggests providing it, but does not explain how to compute a good context summary or offer recovery examples. Per pattern:recovery-guide, errors should guide next steps.
Sampling mode relies on server-initiated MCP Sampling (deprecated as of 2025-06-15, removal planned ~2027-07-28). Code casts to ServerWithSampling and calls serverWithSampling.sampling?.createMessage(). This pattern is being phased out in favor of direct LLM integration. Migration path: collect context and generate questions directly via Anthropic/OpenAI SDK.
'mode' parameter defaults to 'static', but description says 'Default is static for MCP clients that don't support sampling.' This rationale is not relevant to the LLM calling the tool, it suggests server-side fallback logic, not user intent. Describe the default in terms of agent behavior: e.g., 'Use static for fixed guidance or sampling for context-aware questions. Default: static for compatibility.'