Markdown Editor MCP Server

Instructions

Implementation Reference

• src/markdown_editor/server.py:496-512 (handler)

  Handler logic for the 'search_tools' tool. It extracts the query, fetches all available tools using list_tools(), filters tools whose name or description contains the query (case-insensitive), and returns a CallToolResult with the list of relevant tool names.
  if name == "search_tools": query = arguments.get("query", "").lower() all_tools = await list_tools() relevant = [ t.name for t in all_tools if query in t.name or (t.description and query in t.description.lower()) ] return CallToolResult( content=[ TextContent( type="text", text=f"Relevant tools: {', '.join(relevant)}" ) ], structuredContent={"tools": relevant}, isError=False, )
• src/markdown_editor/server.py:44-76 (schema)

  Input and output schema definition for the 'search_tools' tool, registered within the list_tools() function. Input requires a 'query' string; output provides an array of matching tool names.
  Tool( name="search_tools", title="Search Tools", description="Scalability feature: find the right tool for your complex task among all available tools.", inputSchema={ "type": "object", "properties": { "query": { "type": "string", "description": "Description of the operation you want to perform", "examples": [ "find paragraphs", "replace text", "move section", "delete element", "list files", ], } }, "required": ["query"], "additionalProperties": False, }, outputSchema={ "type": "object", "properties": { "tools": { "type": "array", "description": "List of relevant tool names", "items": {"type": "string"}, } }, }, ),
• src/markdown_editor/server.py:36-488 (registration)

  Registration of the 'search_tools' tool via the @app.list_tools() decorator on the list_tools() function, which returns a list of all Tool objects including search_tools.
  @app.list_tools() async def list_tools() -> list[Tool]: """ Returns the complete list of tools available in the server. Adheres to the 2025 Scaling Standard for MCP. """ return [ # --- SCALING & DISCOVERY (2025 Standard) --- Tool( name="search_tools", title="Search Tools", description="Scalability feature: find the right tool for your complex task among all available tools.", inputSchema={ "type": "object", "properties": { "query": { "type": "string", "description": "Description of the operation you want to perform", "examples": [ "find paragraphs", "replace text", "move section", "delete element", "list files", ], } }, "required": ["query"], "additionalProperties": False, }, outputSchema={ "type": "object", "properties": { "tools": { "type": "array", "description": "List of relevant tool names", "items": {"type": "string"}, } }, }, ), # --- NAVIGATION & STRUCTURE --- Tool( name="get_document_structure", title="Get Document Structure", description="Parses the Markdown file and returns a tree of headings and elements. Use this first to navigate.", inputSchema={ "type": "object", "properties": { "file_path": { "type": "string", "description": "Absolute path to the .md file", "examples": ["/path/to/document.md", "./README.md"], }, "depth": { "type": "integer", "description": "Maximum depth of headings to return", "default": 2, "examples": [2, 3, 5], }, }, "required": ["file_path"], "additionalProperties": False, }, outputSchema={ "type": "object", "properties": { "structure": { "type": "array", "description": "Tree of document elements", } }, }, ), Tool( name="search_text", title="Search Text in Document", description="Performs a semantic search for text strings and returns their structural paths.", inputSchema={ "type": "object", "properties": { "file_path": { "type": "string", "examples": ["./document.md", "/path/to/file.md"], }, "query": { "type": "string", "description": "String to search for", "examples": ["TODO", "urgent", "deadline"], }, }, "required": ["file_path", "query"], "additionalProperties": False, }, outputSchema={ "type": "object", "properties": { "results": { "type": "array", "description": "List of matching elements with their paths", } }, }, ), Tool( name="get_context", title="Get Element Context", description="Returns the target element along with its immediate neighbors (before and after).", inputSchema={ "type": "object", "properties": { "file_path": {"type": "string", "examples": ["./document.md"]}, "path": { "type": "string", "description": "Path to the element (e.g., 'Intro > paragraph 1')", "examples": ["Introduction > paragraph 2", "Conclusion"], }, }, "required": ["file_path", "path"], "additionalProperties": False, }, outputSchema={ "type": "object", "properties": { "target": {"type": "object", "description": "The target element"}, "before": { "type": "object", "description": "Element before target", }, "after": {"type": "object", "description": "Element after target"}, }, }, ), # --- CONTENT EDITING --- Tool( name="read_element", title="Read Specific Element", description="Fetches the full content of a specific block by its path.", inputSchema={ "type": "object", "properties": { "file_path": {"type": "string", "examples": ["./document.md"]}, "path": { "type": "string", "examples": ["Features > list 1", "Introduction"], }, }, "required": ["file_path", "path"], "additionalProperties": False, }, outputSchema={ "type": "object", "properties": { "element": { "type": "object", "description": "The requested element", }, "content": {"type": "string", "description": "Element content"}, }, }, ), Tool( name="replace_content", title="Replace Block Content", description="Overwrites the content of a specific block. Maintains document structure.", inputSchema={ "type": "object", "properties": { "file_path": {"type": "string", "examples": ["./document.md"]}, "path": { "type": "string", "examples": [ "Introduction > paragraph 1", "Conclusion", "Features > list 2", ], }, "new_content": { "type": "string", "examples": ["Updated paragraph text", "New content here"], }, }, "required": ["file_path", "path", "new_content"], "additionalProperties": False, }, outputSchema={ "type": "object", "properties": {"success": {"type": "boolean"}}, }, ), Tool( name="insert_element", title="Insert New Element", description="Inserts a new block (heading, paragraph, etc.) relative to an existing one.", inputSchema={ "type": "object", "properties": { "file_path": {"type": "string", "examples": ["./document.md"]}, "path": { "type": "string", "description": "Reference path", "examples": ["Introduction", "Features > paragraph 2"], }, "element_type": { "type": "string", "enum": [ "heading", "paragraph", "list", "code_block", "blockquote", ], "examples": ["paragraph", "heading"], }, "content": { "type": "string", "examples": ["New paragraph content", "## New Section"], }, "where": { "type": "string", "enum": ["before", "after"], "default": "after", "examples": ["after", "before"], }, "heading_level": { "type": "integer", "default": 1, "examples": [1, 2, 3], }, }, "required": ["file_path", "path", "element_type", "content"], "additionalProperties": False, }, outputSchema={ "type": "object", "properties": {"success": {"type": "boolean"}}, }, ), Tool( name="move_element", title="Move Structural Block", description="Moves an element (and its children) to a new location in the document.", inputSchema={ "type": "object", "properties": { "file_path": {"type": "string", "examples": ["./document.md"]}, "source_path": { "type": "string", "examples": ["Old Section", "Introduction > paragraph 2"], }, "target_path": { "type": "string", "examples": ["Conclusion", "Features"], }, "where": { "type": "string", "enum": ["before", "after"], "default": "after", "examples": ["after", "before"], }, }, "required": ["file_path", "source_path", "target_path"], "additionalProperties": False, }, outputSchema={ "type": "object", "properties": {"success": {"type": "boolean"}}, }, ), Tool( name="delete_element", title="Delete Block", description="Removes a block from the document.", inputSchema={ "type": "object", "properties": { "file_path": {"type": "string", "examples": ["./document.md"]}, "path": { "type": "string", "examples": [ "Introduction > paragraph 3", "Old Section", "Deprecated > list 1", ], }, }, "required": ["file_path", "path"], "additionalProperties": False, }, outputSchema={ "type": "object", "properties": {"success": {"type": "boolean"}}, }, ), Tool( name="update_metadata", title="Update YAML Metadata", description="Modifies the document's Frontmatter.", inputSchema={ "type": "object", "properties": { "file_path": { "type": "string", "examples": ["./document.md", "./blog/post.md"], }, "metadata": { "type": "object", "examples": [ {"status": "published", "tags": ["mcp", "ai"]}, {"author": "John Doe", "date": "2025-12-27"}, ], }, }, "required": ["file_path", "metadata"], "additionalProperties": False, }, outputSchema={ "type": "object", "properties": {"success": {"type": "boolean"}}, }, ), Tool( name="undo", title="Undo Last Changes", description="Reverts the last N operations on the document.", inputSchema={ "type": "object", "properties": { "file_path": {"type": "string", "examples": ["./document.md"]}, "count": {"type": "integer", "default": 1, "examples": [1, 2, 5]}, }, "required": ["file_path"], "additionalProperties": False, }, outputSchema={ "type": "object", "properties": { "success": {"type": "boolean"}, "reverted_count": { "type": "integer", "description": "Number of operations reverted", }, }, }, ), # --- FILE SYSTEM --- Tool( name="list_directory", title="List Directory", description="Lists files and folders in the workspace.", inputSchema={ "type": "object", "properties": { "path": { "type": "string", "default": ".", "examples": [".", "./docs", "/path/to/directory"], } }, "additionalProperties": False, }, outputSchema={ "type": "object", "properties": { "items": { "type": "array", "description": "List of directory entries", "items": { "type": "object", "properties": { "name": {"type": "string"}, "is_dir": {"type": "boolean"}, "size": {"type": "integer"}, "path": {"type": "string"}, }, }, } }, }, ), Tool( name="create_file", title="Create File", inputSchema={ "type": "object", "properties": { "path": { "type": "string", "examples": ["./new_document.md", "./notes/todo.md"], }, "content": { "type": "string", "default": "", "examples": ["# New Document\n\nContent here", ""], }, }, "required": ["path"], "additionalProperties": False, }, outputSchema={ "type": "object", "properties": { "success": {"type": "boolean"}, "path": {"type": "string"}, "size": {"type": "integer"}, }, }, ), Tool( name="create_directory", title="Create Directory", inputSchema={ "type": "object", "properties": { "path": { "type": "string", "examples": ["./new_folder", "./docs/archive"], } }, "required": ["path"], "additionalProperties": False, }, outputSchema={ "type": "object", "properties": { "success": {"type": "boolean"}, "path": {"type": "string"}, }, }, ), Tool( name="delete_item", title="Delete File/Folder", inputSchema={ "type": "object", "properties": { "path": { "type": "string", "examples": ["./old_file.md", "./temp_folder"], } }, "required": ["path"], "additionalProperties": False, }, outputSchema={ "type": "object", "properties": { "success": {"type": "boolean"}, "path": {"type": "string"}, }, }, ), ]