client.py

Overview

The client.py file provides an asynchronous client interface to interact with the RAGFlow server using Server-Sent Events (SSE). It establishes an SSE connection, initializes a client session, lists available tools on the server, and calls a specific tool with provided arguments. This file is designed as a runnable script that demonstrates how to connect to the RAGFlow backend, authenticate (if needed), and perform requests to the server in an asynchronous event-driven manner.

Detailed Description

Imports

• ClientSession from mcp.client.session: Represents a session for interacting with RAGFlow server tools.

• sse_client from mcp.client.sse: Provides an asynchronous SSE client context manager for connecting to the server's SSE endpoint.

• anyio.run: Used to run the asynchronous main() function in a suitable event loop.

main() - Asynchronous Entry Point

async def main():

Purpose:

The main coroutine is the primary entry point for this client example. It handles connecting to the server via SSE, creating a client session, initializing communication, listing available tools, and invoking a tool with specified arguments.

Functionality:

• Opens an asynchronous SSE connection to the RAGFlow server at http://localhost:9382/sse.

• Creates a ClientSession with the two streams obtained from the SSE connection.

• Calls initialize() on the session to prepare the session for use.

• Calls list_tools() to retrieve the list of tools available on the server.

• Calls a specific tool "ragflow_retrieval" with a question and dataset/document IDs.

• Prints the tool list and the response from the tool call.

• Catches and prints any exceptions during the process.

Parameters:

• None

Returns:

• None (runs asynchronously and prints outputs)

Usage Example:

To run the client script, simply execute:

python client.py

This will connect to the local RAGFlow server SSE endpoint, list tools, and call the retrieval tool with a sample query.

Implementation Details and Notes

• Authentication:
  The example includes commented-out code snippets demonstrating how to add authentication headers to the SSE connection:

  • Using an api_key header for "host" mode access.

  • Using an Authorization header with a Bearer token, as per OAuth 2.1 Section 5 requirements.

  The active example uses no authentication headers, assuming an open or local environment.

• SSE Client Usage:
  The sse_client context manager yields a tuple of two async streams, which are passed to the ClientSession. This establishes bidirectional communication over SSE.

• ClientSession:
  The session handles protocol-level communication with the server, including initialization, tool listing, and tool invocation.

• Tool Invocation:
  call_tool is used to invoke a named tool on the server, passing JSON-serializable arguments. The response is dumped via model_dump() to print the returned data.

• Error Handling:
  A broad exception handler prints any errors encountered during connection or calls, useful for debugging connection or protocol issues.

Interaction with Other System Components

• mcp.client.session.ClientSession
  Manages the client-side session lifecycle and communication protocol with RAGFlow tools.

• mcp.client.sse.sse_client
  Provides the underlying SSE connection management to the RAGFlow backend.

• RAGFlow Server
  This client connects to the RAGFlow server's SSE endpoint to send commands and receive responses asynchronously.

• Authentication Systems
  Supports integration with API key-based or OAuth 2.1 Bearer token authentication for secure access.

Classes and Functions in this file

This file defines only one top-level asynchronous function:

No classes are defined in this file; it primarily serves as a usage example and entry point.

Visual Diagram: Class and Function Structure

classDiagram
    class client.py {
        <<module>>
        +async main()
    }
    ClientSession <.. client.py : uses
    sse_client <.. client.py : uses

Summary

The client.py file provides a minimal but functional asynchronous client example for connecting to the RAGFlow server via SSE, authenticating if necessary, listing available tools, and invoking a tool with arguments. It demonstrates usage patterns for ClientSession and sse_client abstractions and serves as a foundation or reference for building clients that interact with RAGFlow servers in an event-driven manner.

If you want to extend this client, consider:

• Adding command-line argument parsing for server URL, API keys, and tool parameters.

• Implementing richer error handling and retries.

• Integrating with UI or other application layers for interactive use.