Hello MCP Agents Project

This project demonstrates building and orchestrating multiple agents using the openai-agents-python library and exposing functionality through the Model Context Protocol (MCP) using mcp-sdk.

The core functionality involves a pipeline:

1. Search: Finds public events (exhibitions, sports, concerts) in a specified city using web search.
2. Classify: Determines the likely target audience groups for each found event.
3. Compose: Generates tailored push notification text for each event and its corresponding audience group, encouraging taxi usage.

This pipeline is orchestrated by a "Conductor" agent, which is exposed as a tool via an MCP server (conductor_server.py). The project also includes a simpler MCP server (hello_mcp_server.py) with a basic greeting tool.

Project Structure

.
├── conductor_server.py   # MCP server exposing the main event pipeline tool
├── search_agent.py       # Agent responsible for searching events
├── classify_agent.py     # Agent responsible for classifying event audiences
├── compose_agent.py      # Agent responsible for composing push notifications
├── hello_mcp_server.py   # Simple MCP server with a greeting tool
├── main.py               # Example client-side usage (currently shows hello_agent usage)
├── pyproject.toml        # Project metadata and dependencies
├── README.md             # This file
├── tests/                # Directory for tests (currently basic)
│   └── test_server.py
├── .env.example          # Example environment variable file
└── .gitignore            # Git ignore file (optional but recommended)

Dependencies

This project uses Python and manages dependencies using uv and pyproject.toml.

Key dependencies include:

• openai-agents-python: For creating and running agents.
• mcp-sdk: For creating MCP servers and clients.
• pydantic: For data validation and structuring agent outputs.
• pytest: For running tests.
• uv: For package management and running tasks.
• click: For command-line interfaces (used by mcp-sdk).
• rich: For potentially richer console output (used by mcp-sdk).

Setup and Installation

1. Clone the repository (if applicable):

   git clone <your-repo-url>
   cd <your-repo-directory>
   

2. Ensure uv is installed: Follow the installation instructions at https://github.com/astral-sh/uv.

3. Create a virtual environment and install dependencies:

   uv venv  # Creates a .venv directory
   uv sync  # Installs dependencies from pyproject.toml and uv.lock
   

   • Alternatively, activate the environment first: source .venv/bin/activate

4. Environment Variables:

   • Copy the example environment file: cp .env.example .env
   • Edit the .env file and add any necessary API keys or configuration (e.g., OPENAI_API_KEY if using OpenAI models directly with the agents library).

Running the Servers

You can run the MCP servers using uv run. The agents library often requires environment variables like OPENAI_API_KEY to be set, which uv run usually handles if they are in your .env file.

• Run the Conductor Event Pipeline Server:

  uv run python conductor_server.py
  

  This will start the MCP server defined in conductor_server.py, making the run_event_pipeline tool available (typically via stdio).

• Run the Simple Greeting Server:

  uv run python hello_mcp_server.py
  

  Or using the mcp command provided by mcp-sdk (if installed globally or via uv run):

  uv run mcp run hello_mcp_server.py
  

  This starts the simpler server with the greeting tool.

Usage

The primary way to interact with the core functionality is by connecting an MCP client (like another agent configured with MCPServerStdio) to the conductor_server.py process. The client can then call the run_event_pipeline tool, providing a city name.

The main.py file currently demonstrates how to run the hello_agent which connects to the hello_mcp_server.py. You can adapt main.py or create a new client script to connect to and use the conductor_server.py.

Testing

Run tests using pytest via uv:

uv run pytest

Basic tests are located in the tests/ directory.

Contributing

Please refer to the contribution guidelines if you wish to contribute (add link if available).

License

Specify your project's license here (e.g., MIT License). Add a LICENSE file if needed.