Encoding MCP Server

Instructions

Implementation Reference

• encoding_mcp/file_operations.py:99-149 (handler)

  Core handler function that executes the tool logic: validates encoding, ensures directory exists, creates empty file with appropriate encoding (including BOM for utf-8-bom), and returns success/error message.

  def create_empty_file(file_path: str, encoding: str = "utf-8-bom") -> str:
      """
      Create an empty file with specified encoding.
      
      Args:
          file_path: File path
          encoding: Encoding (default: utf-8-bom)
          
      Returns:
          str: Result message
      """
      try:
          # Validate encoding
          if not validate_encoding(encoding):
              supported = ", ".join(SUPPORTED_ENCODINGS.keys())
              return f"Unsupported encoding: {encoding}. Supported: {supported}"
          
          # Create directory
          dir_result = ensure_directory(file_path)
          if "failed" in dir_result.lower() or "permission" in dir_result.lower():
              return dir_result
          
          # Create empty file by encoding
          if encoding == "utf-8-bom":
              with open(file_path, 'wb') as f:
                  f.write(UTF8_BOM)  # Write BOM only
          elif encoding == "utf-8":
              with open(file_path, 'w', encoding='utf-8', newline='\n') as f:
                  pass  # Empty file
          elif encoding == "cp949":
              with open(file_path, 'w', encoding='cp949') as f:
                  pass  # Empty file
          elif encoding == "euc-kr":
              with open(file_path, 'w', encoding='euc-kr') as f:
                  pass  # Empty file
          elif encoding == "ascii":
              with open(file_path, 'w', encoding='ascii') as f:
                  pass  # Empty file
          
          encoding_info = get_encoding_info(encoding)
          return f"Empty file created successfully: {file_path} ({encoding_info['name']})"
      
      except PermissionError:
          return f"No permission to write file: {file_path}"
      except FileNotFoundError:
          return f"Invalid file path: {file_path}"
      except OSError as e:
          return f"File system error: {str(e)}"
      except Exception as e:
          return f"Unexpected error creating file: {str(e)}"

• encoding_mcp/server.py:130-153 (registration)

  Registers the create_empty_file tool in the MCP server list_tools, including name, description, and input schema definition.

  Tool(
      name="create_empty_file",
      description="Create an empty file with specified encoding. Creates only an empty file so Agent can fill in content.",
      inputSchema={
          "type": "object",
          "properties": {
              "file_name": {
                  "type": "string",
                  "description": "File name to create (e.g., hello.cpp, test.h)"
              },
              "directory_path": {
                  "type": "string", 
                  "description": "Absolute path of directory to create file in"
              },
              "encoding": {
                  "type": "string",
                  "description": "File encoding",
                  "enum": ["utf-8-bom", "utf-8", "cp949", "euc-kr", "ascii"],
                  "default": "utf-8-bom"
              }
          },
          "required": ["file_name", "directory_path"]
      }
  ),

• encoding_mcp/server.py:223-247 (handler)

  MCP server call_tool dispatcher handler specifically for create_empty_file: constructs full file_path, calls the core function, formats response with icon and message.

  if name == "create_empty_file":
      file_name = arguments.get("file_name", "")
      directory_path = arguments.get("directory_path", "")
      encoding = arguments.get("encoding", "utf-8-bom")
      
      # Combine file name and directory path
      file_path = os.path.join(directory_path, file_name)
      
      result = create_empty_file(file_path, encoding)
      
      # Select icon based on result
      if "successfully" in result.lower() or "success" in result.lower():
          icon = "✅"
      elif "permission" in result.lower() or "failed" in result.lower() or "error" in result.lower():
          icon = "❌"
      else:
          icon = "⚠️"
      
      return [
          types.TextContent(
              type="text",
              text=f"{icon} Create empty file\n\n{result}\n\n💡 Agent can use write tool to fill in content."
          )
      ]

• encoding_mcp/server.py:133-152 (schema)

  Input schema definition for the create_empty_file tool, specifying parameters file_name, directory_path (required), and optional encoding.

  inputSchema={
      "type": "object",
      "properties": {
          "file_name": {
              "type": "string",
              "description": "File name to create (e.g., hello.cpp, test.h)"
          },
          "directory_path": {
              "type": "string", 
              "description": "Absolute path of directory to create file in"
          },
          "encoding": {
              "type": "string",
              "description": "File encoding",
              "enum": ["utf-8-bom", "utf-8", "cp949", "euc-kr", "ascii"],
              "default": "utf-8-bom"
          }
      },
      "required": ["file_name", "directory_path"]
  }

• encoding_mcp/file_operations.py:74-97 (helper)

  Helper function used by create_empty_file to ensure the target directory exists before file creation.

  def ensure_directory(file_path: str) -> str:
      """
      Check if file's directory exists and create it if needed.
      
      Args:
          file_path: File path
          
      Returns:
          str: Success message or error message
      """
      dir_path = os.path.dirname(file_path)
      if not dir_path:
          return "Directory path not required."
      
      if os.path.exists(dir_path):
          return "Directory already exists."
      
      try:
          os.makedirs(dir_path, exist_ok=True)
          return f"Directory created: {dir_path}"
      except PermissionError:
          return f"No permission to create directory: {dir_path}"
      except OSError as e:
          return f"Directory creation failed: {dir_path} - {str(e)}"