Insert New Element
insert_elementAdds new headings, paragraphs, lists, or other content blocks to Markdown documents at specified locations relative to existing elements.
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 |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| success | No |
Implementation Reference
- Core implementation of the insert_element tool logic within the EditTool class. Handles path resolution, file locking, document insertion (before/after), atomic file writing, cache updates, and journal confirmation/rollback on errors.
async def insert( self, file_path: str, path: str, element_type: str, content: str, where: str = "after", heading_level: int = 1, ) -> Dict[str, Any]: abs_path = resolve_path(file_path) with FileLock(abs_path): 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: 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 - Top-level async handler function for the insert_element MCP tool, delegating to the singleton EditTool instance's insert method.
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 ) - src/markdown_editor/server.py:227-273 (registration)Registration of the insert_element tool in the MCP server's list_tools() response, including detailed input and output schemas.
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"}}, }, ), - Input schema definition for the insert_element tool, specifying parameters, types, enums, defaults, and requirements.
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, }, - src/markdown_editor/server.py:601-614 (handler)Dispatch handler in the MCP server's call_tool method that invokes the insert_element function with parsed arguments and returns the result.
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 CallToolResult( content=[TextContent(type="text", text="Element inserted")], structuredContent=res, isError="error" in res, )