Bluesky Social MCP

Instructions

Args:
    ctx: MCP context
    handle: User handle to resolve (e.g. "user.bsky.social")

Returns:
    Resolved DID information

Implementation Reference

• server.py:666-699 (handler)

  The primary handler function for the 'resolve_handle' MCP tool. It uses the authenticated Bluesky client to resolve the given handle to a DID and returns the result in a standardized dictionary format.

  @mcp.tool()
  def resolve_handle(
      ctx: Context,
      handle: str,
  ) -> Dict:
      """Resolve a handle to a DID.
  
      Args:
          ctx: MCP context
          handle: User handle to resolve (e.g. "user.bsky.social")
  
      Returns:
          Resolved DID information
      """
      try:
          bluesky_client = get_authenticated_client(ctx)
  
          resolved = bluesky_client.resolve_handle(handle)
  
          # Convert the response to a dictionary
          if hasattr(resolved, "model_dump"):
              resolved_data = resolved.model_dump()
          else:
              resolved_data = resolved
  
          return {
              "status": "success",
              "handle": handle,
              "did": resolved_data.get("did"),
          }
      except Exception as e:
          error_msg = f"Failed to resolve handle: {str(e)}"
          return {"status": "error", "message": error_msg}

• server.py:49-77 (helper)

  Helper function used by the resolve_handle tool (and others) to obtain an authenticated Bluesky Client instance from environment variables via the login() function.

  def get_authenticated_client(ctx: Context) -> Client:
      """Get an authenticated client, creating it lazily if needed.
  
      Args:
          ctx: MCP context
  
      Returns:
          Authenticated Client instance
  
      Raises:
          ValueError: If credentials are not available
      """
      app_context = ctx.request_context.lifespan_context
  
      # If we already have a client, return it
      if app_context.bluesky_client is not None:
          return app_context.bluesky_client
  
      # Try to create a new client by calling login again
      client = login()
      if client is None:
          raise ValueError(
              "Authentication required but credentials not available. "
              "Please set BLUESKY_IDENTIFIER and BLUESKY_APP_PASSWORD environment variables."
          )
  
      # Store it in the context for future use
      app_context.bluesky_client = client
      return client

• server.py:22-46 (helper)

  Supporting login function that authenticates the Bluesky Client using environment variables, called by get_authenticated_client.

  def login() -> Optional[Client]:
      """Login to Bluesky API and return the client.
  
      Authenticates using environment variables:
      - BLUESKY_IDENTIFIER: The handle (username)
      - BLUESKY_APP_PASSWORD: The app password
      - BLUESKY_SERVICE_URL: The service URL (defaults to "https://bsky.social")
  
      Returns:
          Authenticated Client instance or None if credentials are not available
      """
      handle = os.environ.get("BLUESKY_IDENTIFIER")
      password = os.environ.get("BLUESKY_APP_PASSWORD")
      service_url = os.environ.get("BLUESKY_SERVICE_URL", "https://bsky.social")
  
      if not handle or not password:
          return None
  
      # This is helpful for debugging.
      # print(f"LOGIN {handle=} {service_url=}", file=sys.stderr)
  
      # Create and authenticate client
      client = Client(service_url)
      client.login(handle, password)
      return client