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