insert_element
Adds new headings, paragraphs, lists, code blocks, or blockquotes before or after existing elements in Markdown documents using hierarchical paths for structured editing.
Instructions
Inserts a new block (heading, paragraph, etc.) relative to an existing one.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| path | Yes | Reference path | |
| element_type | Yes | ||
| content | Yes | ||
| where | No | after | |
| heading_level | No |
Implementation Reference
- The primary handler function for the 'insert_element' tool, exporting the async interface called from server.py's dispatch.async def insert_element(file_path: str, path: str, element_type: str, content: str, where: str = "after", heading_level: int = 1): return await _instance.insert(file_path, path, element_type, content, where, heading_level)
- Core helper method in EditTool class implementing the insertion logic: loads document, inserts before/after reference path, and persists changes to disk.async def insert(self, file_path: str, path: str, element_type: str, content: str, where: str = "after", heading_level: int = 1) -> Dict[str, Any]: doc = self.get_doc(file_path) if where == "before": result = doc.insert_before(path, element_type, content, heading_level) else: result = doc.insert_after(path, element_type, content, heading_level) if "success" in result: with open(file_path, 'w', encoding='utf-8') as f: f.write(doc.get_content()) return result
- Input and output schema definitions for the 'insert_element' tool, specifying parameters, types, enums, examples, and required fields.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"} } }
- src/markdown_editor/server.py:232-278 (registration)Registration of the 'insert_element' tool within the server's list_tools() method, advertised to MCP clients.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"} } } ),
- src/markdown_editor/server.py:566-568 (registration)Dispatch registration in the call_tool() method, routing 'insert_element' calls to the handler with argument extraction.elif name == "insert_element": res = await insert_element(file_path, arguments["path"], arguments["element_type"], arguments["content"], arguments.get("where", "after"), arguments.get("heading_level", 1)) return {"content": [TextContent(type="text", text="Element inserted")], "structuredContent": res, "isError": "error" in res}