db-retrieval-bot

Retrieval-Bot MCP Agent Demo

May 2023 - Matthew Draper

Overview

This repository demonstrates the 'Retrieval-Bot' data retrieval agent as outlined in the accompanying documentation. The demo runs the MCP agent on Python 3.1X with a React-based front-end interface. Windows users must have the Windows Subsystem for Linux installed to run the MCP client, as the asyncio package has critical components that are not implemented on Windows machines.

This demonstration utilizes claude-3-5-sonnet-20241022 via the Anthropic API. The API key should be stored in /mcp-client/.env. Please note you'll need to supply your own API key.

Prerequisites

• Python 3.1X
• Node.js (latest version)
• Windows Subsystem for Linux (for Windows users only)

Installation & Setup

1. Python Environment Setup

Ensure Python 3.1X and the latest Node.js version are installed on your device. Open a WSL/Linux Bash terminal, create a virtual environment, and install the required packages:

cd mcp-client

# Create a virtual environment
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate

# Install required packages (terminal should now show "(venv)" prefix)
pip install -r requirements.txt

2. Running the MCP Client & Server

Navigate to the mcp-client subdirectory and start the MCP Client & Server:

uvicorn main:app --reload

You should see output similar to:

INFO: Will watch for changes in these directories: ['/your-path/retrieval-bot/mcp-client']
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [501] using StatReload
INFO: Started server process [503]
INFO: Waiting for application startup.
2023-05-14 10:09:07,139 - MCPClient - INFO - Connected to MCP server
Processing request of type ListToolsRequest
2023-05-14 10:09:07,144 - MCPClient - INFO - Available tools: ['retrieval_parrot', 'get_records_by_id', 'get_records_by_date_range_and_category', 'get_records_by_date_range_and_department', 'get_records_by_date_range_and_user', 'get_summary_statistics']
INFO: Application startup complete.

3. Starting the Front-End

With the MCP Client & Server running in one terminal window, open another terminal (Windows or Linux). Start the front-end application using the following commands:

cd frontend
npm install
npm install axios
npm start

4. Database Construction (If Required)

If the dataset data/records.db is not present in your distribution, you'll need to run the utility script to create it:

cd utils
python3 create_db.py

System Architecture

MCP Client (/mcp-client)

This directory contains core components of the MCP agent system:

• mcp_client.py: Contains the MCP client code for connecting to the MCP server, processing submitted prompts, calling the language model for tool selection, executing tools, and returning system responses.

• main.py: Performs two primary functions:

  1. Sets up an MCPClient instance that connects to the MCP server
  2. Implements the Web API layer using FastAPI to handle prompt requests

When /mcp-client/main.py is executed via uvicorn, it initializes the MCP Client, MCP Server, and Web API. Changing the language model in production would only require modifications to the ask_llm() function in /mcp-client/mcp_client.py.

MCP Server (/mcp-server)

• main.py: Contains all tools accessible to the MCP Client. Most tools invoke methods from a DataService() instance.

• The DataService class (defined in utils/data_service.py) includes the methods which connect to the SQLite database and execute the SQL queries to retrieve the requested data.

Frontend (/frontend)

• A React application structured with components in frontend/components/src/components/.

• API communication is handled through frontend/components/src/services/api.js, which forwards user requests to the Python FastAPI endpoint, which then communicates with the MCP Client.

Example Usage

Retrieval-Bot demonstrates how an MCP agent can provide a secure, lightweight solution to data retrieval challenges. The system uses a simple database (data/records.db) to simulate data retrieval operations.

Sample Queries

The following example prompts demonstrate Retrieval-Bot's current capabilities:

1. "Show me all records with ID 12345"

2. "Get all records between 2024-01-01 and 2024-04-30 in the MARKETING category"

3. "What records were created between 2023-06-01 and 2023-12-31 in the RESEARCH department?"

4. "Find records for user 300 between January 1st 2024 and March 31st 2024"

5. "What's the summary of records created in January 2025 for the Spain region and what was their total value?"

The first four queries return downloadable CSV files containing the requested data, while the fifth query returns a text response with additional commentary.

Troubleshooting

Common Issues

• Connection Errors: If you encounter connection issues with the MCP server, ensure all services are running in the correct order and that port 8000 is not being used by another application.

• Database Access Problems: Verify that data/records.db has proper read/write permissions and is not locked by another process.

• API Key Errors: If you encounter authentication failures, check that the API key in the .env file is valid and properly formatted.

Environment-Specific Issues

• WSL Users: If experiencing file system permission issues, ensure WSL is properly configured with access to your Windows directories.

  You may have to construct the python virtual environment at a higher directory level than the installed repository (i.e create the venv in C:/)

• Node.js Version Conflicts: If npm reports dependency conflicts, try using Node.js version 16.x or later.

Support and Contact

For any further questions or contributions, please open an issue on this repository.