MCP Terminal

Instructions

Implementation Reference

• src/mcp_terminal/tools/file.py:57-120 (handler)

  The core handler function for the 'file_modify' tool. It writes content to a specified file path using one of three modes: overwrite, append, or insert at a position. Handles directory creation, error logging, and returns a structured response.
  @mcp.tool(name="file_modify", description="Writes content to a file") async def file_modify( filepath: str, content: str, mode: WriteMode = WriteMode.OVERWRITE, position: Optional[int] = None, create_dirs: bool = True, ) -> FileOperationResponse: try: # Create directories if they don't exist if create_dirs: directory = os.path.dirname(filepath) if directory and not os.path.exists(directory): os.makedirs(directory) # Handle different write modes details = {"mode": mode} if mode == WriteMode.INSERT: if position is None: raise ValueError( "Position must be specified when using INSERT mode" ) # Read existing content if file exists existing_content = "" if os.path.exists(filepath): with open(filepath, "r", encoding="utf-8") as f: existing_content = f.read() # Insert the new content at the specified position position = min(position, len(existing_content)) new_content = ( existing_content[:position] + content + existing_content[position:] ) details["position"] = position # Write the combined content with open(filepath, "w", encoding="utf-8") as f: f.write(new_content) elif mode == WriteMode.APPEND: # Append to file with open(filepath, "a", encoding="utf-8") as f: f.write(content) else: # OVERWRITE # Overwrite file with open(filepath, "w", encoding="utf-8") as f: f.write(content) return FileOperationResponse( success=True, filepath=filepath, details=details ) except Exception as e: logger.error(f"Error writing to file {filepath}: {e}") return FileOperationResponse( success=False, error=f"Error writing to file: {str(e)}", filepath=filepath, )
• src/mcp_terminal/tools/file.py:31-41 (schema)

  Pydantic model defining the response structure for file operations, including success status, error message, filepath, and details. Used as return type for file_modify.
  class FileOperationResponse(BaseModel): """Response model for file operations.""" success: bool = Field(..., description="Whether the operation was successful") error: Optional[str] = Field( None, description="Error message if the operation failed" ) filepath: str = Field(..., description="Path to the file that was operated on") details: Optional[Dict[str, Any]] = Field( None, description="Additional operation details" )
• src/mcp_terminal/tools/file.py:23-29 (schema)

  Enum defining the write modes supported by the file_modify tool: OVERWRITE, APPEND, INSERT.
  class WriteMode(str, Enum): """Enum representing different file writing modes.""" OVERWRITE = "overwrite" # Overwrite the entire file APPEND = "append" # Append to the end of the file INSERT = "insert" # Insert at a specific position
• src/mcp_terminal/server.py:94-104 (registration)

  In the register_tools method of MCPTerminalServer, the FileTool instance is created and its register_mcp method is called on the FastMCP server instance, which in turn registers the file_modify tool via its decorator.
  terminal_tool = TerminalTool( self.controller_type, whitelist_file=self.whitelist_file, blacklist_file=self.blacklist_file, whitelist_mode=self.whitelist_mode, ) file_tool = FileTool() terminal_tool.register_mcp(self.mcp) file_tool.register_mcp(self.mcp) self.tools["terminal"] = terminal_tool self.tools["file"] = file_tool