Loading ToolBench
Markdown Spec MCP Server - provides tools for managing, searching, and indexing markdown specification files with semantic search capabilities
MarkdownSpecs is a well-structured spec exploration server with clear naming conventions and generally good parameter descriptions. 8 tools total, all read-only except index_specs. Tool names follow verb_noun pattern (list_, read_, search_, get_, index_). Most parameters have type definitions and descriptions. Strengths: consistent error handling pattern (_get_safe_path), security-conscious path validation, parameter descriptions are present and actionable (context lines, recursive flags). Weaknesses: output schemas are not explicitly documented (tool responses return {status, data} but structure of 'data' varies by tool and is not formally specified), some descriptions lack depth about return value structure, no documentation of what fields are in the output objects, missing enum constraints on some parameters (e.g., what values can appear in tag searches?). All tools are explicitly defined with @mcp.tool decorator, so registration is proper.
Generates a table of contents from the markdown headings in a file.
Indexes all specs for semantic search. This process can take a while depending on the number of specs.
Lists specs in a given directory relative to the base path, including their last modified timestamp. The base path can be set using the 'SPECS_DIR' environment variable, otherwise it defaults to the current working directory.
Reads the content and metadata of a spec file relative to the base path. The base path can be set using the 'SPECS_DIR' environment variable, otherwise it defaults to the current working directory.
Searches for specs with a specific tag in their frontmatter.
Searches for a keyword within a specific markdown file and returns matching lines with surrounding context.
Searches for a keyword in all markdown files in the specs directory and returns matching lines with surrounding context.
Output schemas are not formally documented. Tools return {status, data: <object>} but the structure of 'data' varies by tool (list of objects vs single object vs tree) and is not specified. Callers and LLMs must infer structure from code or trial-and-error.
Lack of result limits and pagination. search_specs, search_by_tag, and semantic_search can return unbounded results. If a spec directory has 10K markdown files and 1K match a keyword, all 1K results are returned, risking context window overflow. No pagination (limit/offset) is documented.
Missing dependency hints. semantic_search description does not state that index_specs must be called first. LLMs may not know the correct sequence or may call semantic_search on an empty/uninitialized index.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 8 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 45 | - | v1 |
Performs a semantic search over the indexed specs.
Parameter constraints not specified. n_results in semantic_search has no documented min/max. query in semantic_search has no length limits. tag in search_by_tag has no format specification (case sensitivity, allowed characters).
Error messages in tool implementation are informative (e.g., 'Absolute paths are not allowed', 'Access to paths outside of the specs directory is not allowed'), but error responses are returned as {status: 'error', error: string}. MCP clients expect structured error reporting with error codes; the current free-text error approach requires LLM parsing.