Localizable XStrings MCP Server

Instructions

MCP tool to get all localization keys from xcstrings file.

Args:
    file_path (str): Path to the .xcstrings file

Returns:
    str: List of all keys or error message

Implementation Reference

• src/localizable_xstrings_mcp/server.py:36-54 (handler)

  The main handler function for the 'get_keys_tool' MCP tool. It is decorated with @mcp.tool() which handles both registration and execution. Validates the input file, extracts keys using the helper function, and formats the output as a string.

  @mcp.tool()
  def get_keys_tool(file_path: str) -> str:
      """
      MCP tool to get all localization keys from xcstrings file.
  
      Args:
          file_path (str): Path to the .xcstrings file
  
      Returns:
          str: List of all keys or error message
      """
      try:
          if not validate_xcstrings_file(file_path):
              return f"Error: Invalid file path or not an .xcstrings file: {file_path}"
  
          keys = extract_base_keys(file_path)
          return f"Found {len(keys)} keys:\n" + "\n".join(keys)
      except Exception as e:
          return format_error_message(e, "Failed to get keys")

• src/localizable_xstrings_mcp/xcstrings_tools.py:58-82 (helper)

  Helper function that implements the core logic of extracting all localization keys from the .xcstrings JSON file by loading and parsing the 'strings' dictionary keys.

  def extract_base_keys(file_path: str) -> List[str]:
      """
      Extract all string keys from a Localizable.xcstrings file.
      
      Args:
          file_path (str): Path to the .xcstrings file
          
      Returns:
          List[str]: List of all string keys
          
      Raises:
          FileNotFoundError: If the file doesn't exist
          json.JSONDecodeError: If the file is not valid JSON
          KeyError: If the file doesn't have the expected structure
      """
      if not os.path.exists(file_path):
          raise FileNotFoundError(f"File not found: {file_path}")
      
      with open(file_path, 'r', encoding='utf-8') as f:
          data = json.load(f)
      
      if 'strings' not in data:
          return []
      
      return list(data['strings'].keys())

• src/localizable_xstrings_mcp/utils.py:5-21 (helper)

  Utility helper used by the handler to validate that the input file path exists and ends with .xcstrings extension.

  def validate_xcstrings_file(file_path: str) -> bool:
      """
      Validate if a file exists and has the .xcstrings extension.
      
      Args:
          file_path (str): Path to check
          
      Returns:
          bool: True if valid, False otherwise
      """
      if not os.path.exists(file_path):
          return False
      
      if not file_path.lower().endswith('.xcstrings'):
          return False
      
      return True

• src/localizable_xstrings_mcp/utils.py:44-54 (helper)

  Utility helper used by the handler to format error messages consistently.

  def format_error_message(error: Exception, context: str = "") -> str:
      """
      Format error messages consistently.
      
      Args:
          error (Exception): The exception to format
          context (str): Additional context for the error
          
      Returns:
          str: Formatted error message
      """