Markdown Editor MCP Server

Instructions

Implementation Reference

• src/markdown_editor/tools/edit_tools.py:147-168 (handler)

  Core handler logic for replacing content in a Markdown document element. Performs path resolution, file locking, content replacement via Document.replace, atomic file write, cache update, and error handling with rollback.

  async def replace(
      self, file_path: str, path: str, new_content: str
  ) -> Dict[str, Any]:
      abs_path = resolve_path(file_path)
      with FileLock(abs_path):
          doc = self.get_doc(file_path)
          result = doc.replace(path, new_content)
          if "success" in result:
              try:
                  self._atomic_write(file_path, doc.get_content())
                  self._update_cache_mtime(abs_path)
                  # Confirm journal only after successful file write
                  doc.confirm_journal()
              except Exception as e:
                  # Rollback journal entry on write failure
                  doc.rollback_last_entry()
                  self.invalidate_cache(file_path)
                  return {"error": f"Failed to write file: {e}"}
          # Remove internal field from result
          result.pop("_pending_entry", None)
      return result

• src/markdown_editor/tools/edit_tools.py:284-285 (handler)

  Async wrapper function that serves as the direct MCP tool handler, delegating to the EditTool instance's replace method.

  async def replace_content(file_path: str, path: str, new_content: str):
      return await _instance.replace(file_path, path, new_content)

• src/markdown_editor/server.py:197-225 (schema)

  JSON Schema definitions for input parameters (file_path, path, new_content) and output (success boolean) of the replace_content tool.

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

• src/markdown_editor/server.py:15-26 (registration)

  Imports the replace_content tool handler along with other edit tools for use in the MCP server.

  from .tools.edit_tools import (
      get_document_structure,
      read_element,
      replace_content,
      insert_element,
      delete_element,
      undo_changes,
      search_in_document,
      get_element_context,
      move_document_element,
      update_document_metadata,
  )

• src/markdown_editor/server.py:591-599 (registration)

  Dispatch logic in call_tool that routes replace_content tool calls to the handler function.

  elif name == "replace_content":
      res = await replace_content(
          file_path, arguments["path"], arguments["new_content"]
      )
      return CallToolResult(
          content=[TextContent(type="text", text="Content replaced")],
          structuredContent=res,
          isError="error" in res,
      )