Markdown Editor MCP Server

Instructions

Implementation Reference

• src/markdown_editor/tools/edit_tools.py:276-277 (handler)

  The primary handler function for the 'get_document_structure' tool. It delegates to the singleton EditTool instance's get_structure method.

  async def get_document_structure(file_path: str, depth: Optional[int] = None):
      return await _instance.get_structure(file_path, depth)

• src/markdown_editor/server.py:78-109 (schema)

  Schema definition in list_tools(), specifying input (file_path required, depth optional) and output (structure array).

  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",
              }
          },
      },
  ),

• src/markdown_editor/server.py:557-564 (registration)

  Registration and dispatch logic in @app.call_tool(): invokes the handler and formats the CallToolResult.

  if name == "get_document_structure":
      res = await get_document_structure(file_path, arguments.get("depth", 2))
      result = {"structure": res}
      return CallToolResult(
          content=[TextContent(type="text", text=json.dumps(result, ensure_ascii=False, indent=2))],
          structuredContent=result,
          isError=False,
      )

• src/markdown_editor/tools/edit_tools.py:137-142 (helper)

  Helper method in EditTool class implementing the core logic: loads cached Document and calls its get_structure method.

  async def get_structure(
      self, file_path: str, depth: Optional[int] = None
  ) -> List[dict]:
      doc = self.get_doc(file_path)
      return doc.get_structure(depth=depth)