MCP server that makes remote markdown files available as mcp resources
The server has one tool (get_markdown_content) with a clear action verb, solid schema with proper Zod validation, and good error handling patterns. However, the tool description is verbose and partially duplicative (encourages users to use resources instead), and the parameter descriptions, while present, lack concrete formatting constraints or examples that would guide LLM calls. The schema is well-structured with optional field handling, but the output format is underspecified, callers must infer the response structure from implementation rather than from explicit documentation. The tool includes proper annotations (readOnlyHint, idempotentHint, etc.), which is a strong positive. Error responses include actionable context (file not found, fetch failures), meeting the recovery-guide pattern. No critical security issues detected.
Fetches the markdown content from the remote source and makes it available via this tool. Use the `file` parameter to specify the markdown file to fetch. If not specified, the index file will be fetched. Please use the markdown resources instead if possible.
Tool description is verbose (180+ chars) and contains meta-advice ('Please use the markdown resources instead') that should not be in the description. The description should focus on what the tool does and when to use it, not redirect users elsewhere.
Parameter 'file' lacks concrete format guidance. Description says 'The markdown file to fetch. If empty, fetches the index file.' but does not specify: expected format (with or without .md extension?), valid character restrictions, length limits, or examples. The implementation strips .md if present, but this logic is not exposed in the parameter description.
Output schema is not documented. The code returns {content: [{type: 'text', text: string}]} or {isError: true, content: [...]} but no formal schema or response structure is provided in tool metadata. LLMs must reverse-engineer the output shape from the tool name and description.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | C | 61 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 42 | - | v1 |
The tool has two distinct response structures (success vs error) with different field presence (isError flag). No documentation clarifies when each is returned or how the LLM should handle the isError field. This ambiguity invites misinterpretation.