---
slug: "brest"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/BSE-dev/Brest-mcp-server@main/README.md"
repo: "https://github.com/BSE-dev/Brest-mcp-server"
source_file: "README.md"
branch: "main"
---
# Brest MCP Server

A robust Model Context Protocol (MCP) server implementation for the Brest region, providing infrastructure for MCP-based interactions with built-in debugging and monitoring capabilities.

## Table of Contents
- [Description](#description)
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Technologies](#technologies)
- [Installation](#installation)
- [Usage](#usage)
  - [Running the Server](#running-the-server)
  - [Using the Client](#using-the-client)
  - [AI Agent Integration](#ai-agent-integration)
- [Development](#development)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)

## Description

**Brest MCP Server** is a server implementation of the Model Context Protocol (MCP) for the Brest region. It provides a robust infrastructure for managing MCP-based interactions and includes an MCP inspector for debugging and monitoring.

The goal of this project is to facilitate the deployment and management of MCP services with a focus on simplicity and reliability.

## Features

- 🚀 **MCP Protocol Implementation**: Full compliance with Model Context Protocol standards
- 🔍 **Built-in Inspector**: Debug and monitor your MCP server with the integrated web interface
- 🤖 **AI Agent Integration**: Support for A2A protocol and agent-to-agent communication
- 🐍 **Python-based**: Built with Python 3.12+ for modern development practices
- 📦 **UV Package Management**: Fast and reliable dependency management
- 🔧 **Development Tools**: Client tools and debugging utilities included

## Prerequisites

Before installing Brest MCP Server, ensure you have:

- **Python 3.12.3** or higher
- **Node.js** (for MCP Inspector)
- **Git** (for cloning the repository)
- **uv** package manager (installation instructions below)

## Technologies

- **Language**: Python 3.12.3 or compatible
- **Dependency Management**: uv
- **Inspector**: MCP Inspector via Node.js (`npx`)
- **Environment**: Virtual environment managed by `uv`
- **Protocol**: Model Context Protocol (MCP) and A2A (Agent-to-Agent)
## Installation

To install and configure Brest MCP Server locally, follow these steps:

1. **Install `uv`** (if not already installed):
    - On Linux/macOS:
        ```bash
        curl -LsSf https://astral.sh/uv/install.sh | sh
        ```
    - On Windows:
        ```powershell
        powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
        ```

2. **Clone the repository**:
    ```bash
    git clone https://github.com/Nijal-AI/Brest-mcp-server.git
    cd Brest-mcp-server
    ```

3. **Create and activate the virtual environment**:
    ```bash
    uv venv
    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
    ```

4. **Install the dependencies**:
    ```bash
    uv sync
    ```

## Usage

### Running the Server

To run the server locally, proceed as follows:

1. **Ensure the virtual environment is activated**:
    ```bash
    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
    ```

2. **Start the server with the MCP Inspector**:
    ```bash
    npx @modelcontextprotocol/inspector uv run brest-mcp
    ```

3. **Access the MCP Inspector in your browser**:
    - Proxy: `http://localhost:3000`
    - Web interface: `http://localhost:5173`

Example output:
```
Starting MCP inspector...
Proxy server listening on port 3000
🔍 MCP Inspector is up and running at http://localhost:5173 🚀
```

### Using the Client

If you want to communicate with an AI agent using the Brest MCP Server, you can use the client provided in the `tools` directory:

```bash
uv run python tools/client.py src/server.py
```

### AI Agent Integration

You can also chat with an AI agent using Brest MCP Server on A2A protocol.

1. **Setup the agent**:
    ```bash
    echo "MCP_TRANSPORT=stdio" > src/.env
    ```

2. **Run the agent**:
    ```bash
    uv run agent
    ```

3. **Use with A2A samples demo** (optional):
    ```bash
    # Setup
    git clone https://github.com/google-a2a/a2a-samples.git
    echo "GOOGLE_API_KEY=your_api_key_here" > a2a-samples/demo/ui/.env

    # Run
    cd a2a-samples/demo/ui
    uv run main.py
    ```
    
    Then navigate to `http://localhost:12000`, go to "Agents" and connect your Brest Expert Agent at `localhost:10030`. You can add other agents if you want, then go to Home and create a new conversation to discuss with your agent(s).

## Development

For developers wishing to contribute or work on advanced features, follow these additional steps:

1. **Ensure the virtual environment is set up and dependencies are installed**:
    ```bash
    uv venv
    uv sync
    ```

2. **Use the MCP Inspector to debug and monitor the server**:
    ```bash
    npx @modelcontextprotocol/inspector uv run brest-mcp
    ```

3. **Refer to the `pyproject.toml` file** for details on dependencies and configurations.

## Troubleshooting

### Common Issues

**Virtual environment activation fails**
- Ensure `uv` is properly installed and in your PATH
- Try recreating the virtual environment: `uv venv --force`

**MCP Inspector not starting**
- Ensure Node.js is installed: `node --version`
- Clear npm cache: `npm cache clean --force`
- Try installing the inspector globally: `npm install -g @modelcontextprotocol/inspector`

**Connection errors with A2A samples**
- Verify your Google API key is correctly set in the `.env` file
- Check that the Brest Expert Agent is running on `localhost:10030`
- Ensure all required ports are available and not blocked by firewall

**Dependencies installation fails**
- Update `uv` to the latest version: `uv self update`
- Clear the cache: `uv cache clean`
- Try installing with verbose output: `uv sync -v`

### Getting Help

If you encounter issues not covered here:
1. Check the [Issues](https://github.com/Nijal-AI/Brest-mcp-server/issues) section on GitHub
2. Review the MCP protocol documentation
3. Create a new issue with detailed error messages and your environment details

## Contributing

Contributions are welcome! To propose changes:

1. **Fork the repository**
2. **Create a feature branch**: `git checkout -b feature/your-feature-name`
3. **Make your changes** and ensure tests pass
4. **Follow the coding standards** defined in the project
5. **Submit a pull request** with a clear description of your changes

Please refer to the [CONTRIBUTING.md](https://github.com/BSE-dev/Brest-mcp-server/blob/HEAD/CONTRIBUTING.md) file for detailed guidelines.

## License

This project is licensed under the MIT License. See the [LICENSE](https://github.com/BSE-dev/Brest-mcp-server/tree/HEAD/LICENSE) file for details.