SimpleLocalize MCP Server

Instructions

Implementation Reference

• main.py:44-93 (handler)

  The handler function decorated with @mcp.tool() that implements the create_translation_keys tool. It validates input, calls the SimpleLocalize API to create bulk translation keys, and handles responses and errors.

  @mcp.tool()
  async def create_translation_keys(keys: List[dict]) -> str:
      """Create translation keys in bulk for a project.
      
      This endpoint allows you to create multiple translation keys at once. You can create up to 100 translation keys in a single request.
      Each key must have a 'key' field, and optionally can include 'namespace' and 'description' fields.
      
      Args:
          keys: List of dictionaries containing key information with fields:
              - key (required): Translation key (max 500 chars)
              - namespace (optional): Namespace for the key (max 128 chars)
              - description (optional): Description for translators (max 500 chars)
      """
      # Validate and clean input
      cleaned_keys = []
      for key_info in keys:
          if not key_info.get("key"):
              raise ValueError("Each key must have a 'key' field")
              
          cleaned_key = {
              "key": key_info["key"]
          }
          
          # Only include optional fields if they exist
          if "namespace" in key_info:
              cleaned_key["namespace"] = key_info["namespace"]
          if "description" in key_info:
              cleaned_key["description"] = key_info["description"]
              
          cleaned_keys.append(cleaned_key)
  
      if len(cleaned_keys) > 100:
          raise ValueError("Maximum 100 keys allowed per request")
  
      try:
          result = await make_simplelocalize_request(
              "POST",
              "/api/v1/translation-keys/bulk",
              {"translationKeys": cleaned_keys}
          )
          
          if "failures" in result.get("data", {}):
              failures = result["data"]["failures"]
              if failures:
                  return f"Some keys failed to create: {failures}"
          
          return f"Successfully created {len(cleaned_keys)} translation keys"
      except SimpleLocalizeError as e:
          return str(e)

• main.py:45-56 (schema)

  Type hints and docstring defining the input schema (List[dict] with key, optional namespace, description) and output (str response message).

  async def create_translation_keys(keys: List[dict]) -> str:
      """Create translation keys in bulk for a project.
      
      This endpoint allows you to create multiple translation keys at once. You can create up to 100 translation keys in a single request.
      Each key must have a 'key' field, and optionally can include 'namespace' and 'description' fields.
      
      Args:
          keys: List of dictionaries containing key information with fields:
              - key (required): Translation key (max 500 chars)
              - namespace (optional): Namespace for the key (max 128 chars)
              - description (optional): Description for translators (max 500 chars)
      """

• main.py:44-44 (registration)

  The @mcp.tool() decorator registers the function as an MCP tool.

  @mcp.tool()

• main.py:19-43 (helper)

  Helper function used by the tool to make authenticated HTTP requests to the SimpleLocalize API.

  async def make_simplelocalize_request(method: str, endpoint: str, json_data: dict | None = None) -> dict[str, Any]:
      """Make a request to the SimpleLocalize API with proper error handling."""
      headers = {
          "X-SimpleLocalize-Token": SIMPLELOCALIZE_API_KEY,
          "Content-Type": "application/json"
      }
      
      url = f"{SIMPLELOCALIZE_API_BASE}{endpoint}"
      
      async with httpx.AsyncClient() as client:
          try:
              if method.upper() == "POST":
                  response = await client.post(url, headers=headers, json=json_data, timeout=30.0)
              elif method.upper() == "PATCH":
                  response = await client.patch(url, headers=headers, json=json_data, timeout=30.0)
              elif method.upper() == "GET":
                  response = await client.get(url, headers=headers, timeout=30.0)
              else:
                  raise ValueError(f"Unsupported HTTP method: {method}")
              
              response.raise_for_status()
              return response.json()
          except httpx.HTTPError as e:
              raise SimpleLocalizeError(f"SimpleLocalize API error: {str(e)}")