MCP server implementation for markdownlint that validates markdown content against markdownlint rules
Two tools with basic schemas and descriptions, but significant gaps in parameter documentation and output schema clarity. The 'validate' tool has a reasonable description (145 chars, within baseline 34-392 range) but the 'config' parameter lacks a description entirely. The 'rules' tool description is adequate (127 chars) but provides no output schema documentation. No parameter descriptions for the 'config' object properties. Error handling exists but lacks recovery guidance. No tool annotations (readOnlyHint, idempotentHint). Naming is acceptable (verb-based: 'validate', 'rules') but generic. Output is JSON-stringified text rather than structured objects, forcing LLM parsing.
Returns the available markdownlint rules and their configurations. Each rule includes its default settings and description.
Validates markdown content against markdownlint rules. Checks for common markdown style and formatting issues. Returns validation results including any errors found. Can be configured with custom markdownlint rules.
Output schema not documented. Tools return JSON-stringified text in a generic 'text' field rather than structured objects. LLMs must parse unstructured output, wasting tokens and increasing hallucination risk.
Parameter 'config' in validate tool has no description. LLMs cannot infer what configuration options are valid or how to structure the object. Violates pattern:tool-description requirement.
No tool annotations (readOnlyHint, idempotentHint). Both tools are read-only and idempotent but this is not declared in the tool definition, forcing LLMs to infer safety properties.
Error messages lack recovery guidance. Generic 'Invalid arguments' and 'Unknown tool' errors do not tell the LLM what to do next or how to self-correct.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 50 | 2026-07-28+ | v2 |
No output schema documentation. The validate tool returns a ValidationResult object but the schema is not visible in the tool definition. LLMs cannot plan downstream operations without knowing the response structure.