Twist MCP Server

Instructions

Implementation Reference

• src/inbox.py:100-122 (handler)

  The handler function that executes the tool logic: archives a specific inbox thread by its ID using the Twist API endpoint 'inbox/archive'.

  def twist_inbox_archive(
      ctx: Context,
      id: int
  ) -> str:
      """Archives a thread.
  
      Args:
          id: The ID of the thread to archive
      """
      token = ctx.request_context.lifespan_context.twist_token
  
      params = {"id": id}
  
      try:
          logger.info(f"Archiving thread with ID: {id}")
  
          result = twist_request("inbox/archive", params=params, token=token, method="POST")
  
          logger.info(f"Successfully archived thread with ID: {id}")
          return f"Successfully archived thread with ID: {id}"
      except Exception as error:
          logger.error(f"Error archiving thread: {error}")
          return f"Error archiving thread: {str(error)}"

• main.py:42-48 (registration)

  Dynamic registration of all functions starting with 'twist_' from src.inbox and src.threads modules as MCP tools using FastMCP.tool() decorator. This registers 'twist_inbox_archive'.

  # Register all tools from tool modules
  for module in [src.inbox, src.threads]:
      for name, func in inspect.getmembers(module, inspect.isfunction):
          if name.startswith('twist_') and func.__module__ == module.__name__:
              logger.info(f"Registering tool: {name}")
              mcp.tool()(func)

• src/api.py:28-64 (helper)

  Helper function used by the handler to make the actual API request to Twist's 'inbox/archive' endpoint.

  def twist_request(endpoint, params=None, token=None, method="GET"):
      """
      Make an API request to Twist.
  
      Args:
          endpoint (str): API endpoint to call (without the base URL)
          params (dict, optional): Dictionary of parameters to include in the request
          token (str, optional): Authentication token (if None, uses the one from get_api_client)
          method (str, optional): HTTP method to use (default: "GET")
  
      Returns:
          dict: Response data as a dictionary
  
      Raises:
          Exception: If the API request fails
      """
      if token is None:
          token = get_api_client()
  
      base_url = "https://api.twist.com/api/v3/"
      headers = {"Authorization": f"Bearer {token}"}
      url = f"{base_url}{endpoint}"
  
      try:
          if method == "GET":
              response = requests.get(url, params=params, headers=headers)
          elif method == "POST":
              response = requests.post(url, data=params, headers=headers)
          else:
              raise ValueError(f"Unsupported HTTP method: {method}")
  
          response.raise_for_status()  # Raise an exception for 4XX/5XX responses
          return response.json()
      except requests.exceptions.RequestException as e:
          logger.error(f"Twist API request failed: {e}")
          raise