Markdown Editor MCP Server

Instructions

Implementation Reference

• src/markdown_editor/tools/edit_tools.py:252-268 (handler)

  Main tool handler: acquires file lock, updates document metadata via Document.update_metadata(), performs atomic file write, updates cache, confirms journal entry. Handles write errors with rollback.

  async def update_metadata(
      self, file_path: str, metadata: Dict[str, Any]
  ) -> Dict[str, Any]:
      abs_path = resolve_path(file_path)
      with FileLock(abs_path):
          doc = self.get_doc(file_path)
          result = doc.update_metadata(metadata)
          if "success" in result:
              try:
                  self._atomic_write(file_path, doc.get_content())
                  self._update_cache_mtime(abs_path)
                  doc.confirm_journal()
              except Exception as e:
                  doc.rollback_last_entry()
                  self.invalidate_cache(file_path)
                  return {"error": f"Failed to write file: {e}"}
      return result

• src/markdown_editor/server.py:330-356 (registration)

  Tool registration in @app.list_tools(): defines name, description, input/output schemas for update_metadata tool.

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

• src/markdown_editor/server.py:330-356 (schema)

  Input/output schema definition for the update_metadata tool, specifying file_path and metadata object.

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

• src/markdown_editor/core/document.py:764-785 (helper)

  Core Document class method: updates metadata dictionary, rebuilds raw content from structure, creates journal entry for undo support.

  def update_metadata(self, new_metadata: Dict[str, Any]) -> Dict[str, Any]:
      """Update YAML metadata"""
      old = deepcopy(self.metadata)
      self.metadata.update(new_metadata)
      self._rebuild_raw_content()
  
      # Create journal entry for undo support
      entry = JournalEntry(
          operation="update_metadata",
          path="metadata",
          old_value=json.dumps(old, ensure_ascii=False),
          new_value=json.dumps(self.metadata, ensure_ascii=False),
          transaction_id=self._transaction_id,
      )
  
      if not self._transaction_active:
          self.journal.append(entry)
          # Note: _save_journal() is NOT called here
          # Caller must call confirm_journal() after successful file write
          self.version += 1
  
      return {"success": True, "old": old, "new": self.metadata}

• src/markdown_editor/server.py:637-643 (registration)

  Dispatch logic in @app.call_tool(): calls the update_document_metadata handler when tool name matches.

  elif name == "update_metadata":
      res = await update_document_metadata(file_path, arguments["metadata"])
      return CallToolResult(
          content=[TextContent(type="text", text="Metadata updated")],
          structuredContent=res,
          isError="error" in res,
      )