# MCP with RAG Demo

This demonstration project shows how to implement a Model Context Protocol (MCP) server with Retrieval-Augmented Generation (RAG) capabilities. The demo allows AI models to interact with a knowledge base, search for information, and add new documents.

## Features

- MCP server with tool and resource support
- RAG implementation (with fallback to in-memory storage)
- Client example for interacting with the MCP server
- Support for both SSE (HTTP) and stdio communication modes
- Simple prompt templates

## Prerequisites

- Python 3.8+
- pip (Python package manager)

## Installation

1. Clone the repository:

```bash
git clone <repository-url>
cd mcp-demo
```

2. Create a virtual environment:

```bash
python -m venv mcp-env
source mcp-env/bin/activate  # On Windows: mcp-env\Scripts\activate
```

3. Install the required dependencies:

```bash
pip install -r requirements.txt
```

## Project Structure

```
mcp-demo/
├── server.py           # Main MCP server implementation
├── client_example.py   # Example client to interact with the server
├── requirements.txt    # Project dependencies
├── sample_data.txt     # Sample data available as a resource
├── tools/
│   ├── __init__.py     # Package initialization
│   └── rag_tools.py    # RAG tools implementation
└── README.md           # This readme file
```

## Running the Demo

### Step 1: Start the MCP Server

You can run the MCP server in two different modes:

#### Option A: SSE (HTTP) Mode

This mode allows the server to accept connections over HTTP using Server-Sent Events (SSE):

```bash
python server.py --sse
```

By default, the server will listen on `0.0.0.0:8000`. You can customize the host and port:

```bash
python server.py --sse --host 127.0.0.1 --port 9000
```

#### Option B: stdio Mode

This mode allows the server to communicate through standard input/output:

```bash
python server.py --stdio
```

### Step 2: Run the Client Example

After the server is up and running, open a new terminal window (keeping the server running in the first one):

#### Connecting to an SSE Server

```bash
# Make sure your virtual environment is activated
source mcp-env/bin/activate  # On Windows: mcp-env\Scripts\activate

# Run the client with SSE mode
python client_example.py --sse http://localhost:8000
```

The client will automatically append "/sse" to the URL if it's not already present.

#### Connecting via stdio

```bash
# Make sure your virtual environment is activated
source mcp-env/bin/activate  # On Windows: mcp-env\Scripts\activate

# Run the client with stdio mode
python client_example.py --stdio --command python --args "server.py --stdio"
```

You can customize the command and arguments as needed.

## What the Client Example Does

The client example demonstrates several key operations:

1. **Lists available tools, resources, and prompts** from the MCP server
2. **Calls the echo tool** to verify basic communication
3. **Adds documents to the knowledge base** with metadata
4. **Searches the knowledge base** using the RAG system
5. **Reads a sample resource** from the server

## Available MCP Tools

The following tools are available in this demo:

- `echo`: A simple tool that echoes back the provided message
- `add`: A tool that adds two numbers together
- `add_document`: Adds a document to the knowledge base
- `rag_search`: Searches the knowledge base for information related to a query
- `list_documents`: Lists all documents in the knowledge base

## Available MCP Resources

- `sample://data`: Provides access to the sample data in sample_data.txt

## Available MCP Prompts

- `greeting`: A simple greeting prompt template

## Customizing the Demo

### Adding New Tools

To add new tools, modify the `server.py` file:

```python
@mcp.tool()
def your_tool_name(param1: type, param2: type) -> return_type:
    """Tool description"""
    # Tool implementation
    return result
```

### Adding New Resources

To add new resources, modify the `server.py` file:

```python
@mcp.resource("resource://pattern")
def your_resource_function() -> str:
    """Resource description"""
    # Resource implementation
    return "Resource content"
```

### Adding New Prompts

To add new prompt templates, modify the `server.py` file:

```python
@mcp.prompt()
def your_prompt_name(param1: str, param2: str) -> str:
    """Prompt description"""
    return f"""
    Your prompt template text with {param1} and {param2} parameters.
    """
```

## Troubleshooting

### Client Connection Issues

If you get a "Connection refused" error when running the client:

1. Make sure the server is actually running in another terminal window
2. Check that you're using the correct URL (default is http://localhost:8000)
3. Ensure the server is listening on the expected interface (0.0.0.0 to accept external connections)
4. Try specifying the server URL explicitly: `python client_example.py --sse http://localhost:8000`

### Server Endpoint Issues

The MCP server exposes an SSE (Server-Sent Events) endpoint at `/sse`. When connecting with the client:

- The full URL should be `http://localhost:8000/sse`
- The client will automatically append `/sse` if it's missing from your specified URL

### Debug Mode

If you encounter issues, you can enable debug mode for more verbose output:

```bash
python client_example.py --sse http://localhost:8000 --debug
```

### Common Issues

**Import errors with client connection**

If you see import errors when running the client example, make sure you have installed all the required dependencies:

```bash
pip install mcp-sdk
```

**Package not found or version mismatch**

If you're experiencing import errors or version compatibility issues, try installing a specific version of the MCP package:

```bash
pip install mcp-sdk>=1.0.0
```

## License

This project is provided as an example implementation and is available under the MIT License.

## Setup

1. Install the required dependencies:
   ```bash
   pip install -r requirements.txt
   ```

2. Create a `.env` file:
   ```bash
   cp .env.example .env
   ```

3. Edit the `.env` file and add your OpenAI API key:
   ```
   OPENAI_API_KEY=your_api_key_here
   ```

   You can also configure other options in the `.env` file:
   - `MCP_SERVER_URL`: The URL of the MCP server (default: http://localhost:3000)
   - `DEBUG`: Enable debug mode (default: false)

## Usage

Run the demo with:

```bash
python openai_example.py
```

You can override the settings in the `.env` file by using command-line arguments:

```bash
python openai_example.py --api-key YOUR_API_KEY --server-url http://your-server-url
```

## Environment Variables

The following environment variables can be set in the `.env` file:

- `OPENAI_API_KEY`: Your OpenAI API key (required)
- `MCP_SERVER_URL`: The URL of the MCP server (optional)
- `DEBUG`: Enable debug mode (optional)

## Command-line Arguments

- `--api-key`: Your OpenAI API key (overrides the .env file)
- `--server-url`: The URL of the MCP server (overrides the .env file)
- `--debug`: Enable debug mode (overrides the .env file)

# MCP OpenAI Example

This example demonstrates how to use the Model Control Protocol (MCP) with OpenAI's API.

## Setup

1. Install the required dependencies:
   ```
   pip install -r requirements.txt
   ```

2. Create a `.env` file based on the `.env.example` template:
   ```
   cp .env.example .env
   ```

3. Edit the `.env` file and add your OpenAI API key:
   ```
   OPENAI_API_KEY=your_api_key_here
   ```

## Running the Example

Run the example script:

```
python openai_example.py
```

You can also specify options directly:

```
python openai_example.py --api-key your_api_key_here --server-url http://localhost:3000 --debug
```

## What the Example Does

1. Loads environment variables from the `.env` file
2. Configures the OpenAI client with your API key
3. Lists available models
4. Creates a chat completion with a simple prompt

## Environment Variables

- `OPENAI_API_KEY`: Your OpenAI API key (required)
- `MCP_SERVER_URL`: URL of the MCP server (optional, defaults to http://localhost:3000)
- `DEBUG`: Enable debug logging (optional, defaults to false)