MediFinderBot/medifinder-mcp

MedifinderMCP Server

An MCP (Model Context Protocol) server for medicine inventory queries, designed to work with AI assistants like Claude.

Overview

The MedifinderMCP Server provides tools and resources for querying a medicine inventory database through the Model Context Protocol (MCP). It allows AI assistants and other clients to:

• Search for medicines by name or location
• Check medicine availability at different healthcare facilities
• Get stock information for specific medicines
• View statistics on medicine availability by region
• Analyze stock status across the healthcare system

Database Schema

The application uses a normalized database schema:

Region
  - region_id (PK)
  - name
  - code
  - created_at
  - updated_at

MedicalCenter
  - center_id (PK)
  - code
  - name
  - region_id (FK -> Region)
  - category
  - reporter_name
  - institution_type
  - reporter_type
  - address
  - latitude
  - longitude
  - created_at
  - updated_at

ProductType
  - type_id (PK)
  - code
  - name
  - description
  - created_at
  - updated_at

Product
  - product_id (PK)
  - code
  - name
  - type_id (FK -> ProductType)
  - description
  - dosage_form
  - strength
  - created_at
  - updated_at

Inventory
  - inventory_id (PK)
  - center_id (FK -> MedicalCenter)
  - product_id (FK -> Product)
  - current_stock
  - avg_monthly_consumption
  - accumulated_consumption_4m
  - measurement
  - last_month_consumption
  - last_month_stock
  - status_indicator
  - cpma_12_months_ago
  - cpma_24_months_ago
  - cpma_36_months_ago
  - accumulated_consumption_12m
  - report_date
  - status
  - created_at
  - updated_at

User
  - user_id (PK)
  - phone_number
  - name
  - preferred_location
  - created_at
  - updated_at

SearchHistory
  - search_id (PK)
  - user_id (FK -> User)
  - product_query
  - location_query
  - search_radius
  - results_count
  - created_at

Project Structure

medifinder-mcp/
├── app/
│   ├── __init__.py
│   ├── config.py            # Configuration management
│   ├── db/
│   │   ├── __init__.py
│   │   ├── connection.py    # Database connection handling
│   │   └── queries.py       # SQL queries
│   ├── models/
│   │   ├── __init__.py
│   │   ├── base.py          # Base model with timestamp fields
│   │   ├── region.py        # Region model
│   │   ├── medical_center.py # Medical center model
│   │   ├── product_type.py  # Product type model
│   │   ├── product.py       # Product model
│   │   ├── inventory.py     # Inventory model
│   │   ├── user.py          # User model
│   │   └── search_history.py # Search history model
│   ├── mcp/
│   │   ├── __init__.py
│   │   ├── server.py        # MCP server setup
│   │   ├── tools.py         # Tool implementations
│   │   ├── resources.py     # Resource implementations
│   │   └── prompts.py       # Prompt templates
│   └── utils/
│       ├── __init__.py
│       └── helpers.py       # Helper functions
├── main.py                  # Application entry point
├── requirements.txt         # Dependencies
└── README.md                # Documentation

MCP Features

Tools

• search_medicines: Search for medicines by name or location
• get_medicine_locations: Find locations where a medicine is available
• get_medicine_stock: Get stock information for a specific medicine
• get_regional_statistics: Get medicine statistics by region
• get_medicine_status: Get overall medicine statistics
• diagnose_database: Check database connectivity and content
• troubleshoot_connection: Detailed database connection diagnostics
• create_database_schema: Create database tables based on models

Resources

• product://{id}: Get product details by ID
• stock://{name}: Get stock information for a product by name
• locations://{region}: Get medical centers in a specific region
• statistics://stock: Get overall stock statistics
• statistics://regions: Get regional statistics

Prompts

• medicine_search_prompt: Template for searching medicines by name
• medicine_availability_prompt: Template for checking medicine availability
• medicine_statistics_prompt: Template for analyzing medicine statistics
• regional_availability_prompt: Template for analyzing regional medicine availability

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/medifinder-mcp.git
   cd medifinder-mcp
   

2. Create a virtual environment and install dependencies:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   

3. Set up environment variables by creating a .env file:

   DB_HOST=localhost
   DB_PORT=5432
   DB_NAME=medifinderbot
   DB_USER=your_user
   DB_PASSWORD=your_password
   DEBUG=True
   ENV=development
   SERVER_NAME=MedifinderMCP
   SERVER_VERSION=1.0.0
   MCP_SERVER_NAME=MedifinderMCP
   MCP_SERVER_DESCRIPTION=MCP server for medicine inventory queries
   MAX_SEARCH_RESULTS=50
   SEARCH_SIMILARITY_THRESHOLD=0.3
   

4. Create the database:

   # Connect to PostgreSQL
   psql -U postgres
   
   # Create database and user
   CREATE DATABASE medifinderbot;
   CREATE USER your_user WITH PASSWORD 'your_password';
   GRANT ALL PRIVILEGES ON DATABASE medifinderbot TO your_user;
   
   # Exit PostgreSQL
   \q
   

5. Initialize the database schema: After starting the server, use the create_database_schema tool to create the tables.

Usage

Running the Server Locally

You can run the MCP server directly:

python main.py

Using MCP Inspector

For development and testing, the MCP Inspector provides a convenient way to interact with the server:

1. Install MCP CLI:

   pip install mcp[cli]
   

2. Run the server in development mode:

   python -m mcp dev main.py
   

3. The MCP Inspector will open in your browser, allowing you to:

   • Test tools and resources
   • View the output of diagnostic tools
   • Experiment with different queries

Integration with Claude Desktop

To use the server with Claude Desktop:

1. Create a batch file for reliable startup (run-mcp-server.bat):

   @echo off
   cd /d %~dp0
   call venv\Scripts\activate.bat
   python main.py
   

2. Install the server in Claude Desktop:

   mcp install run-mcp-server.bat -f .env
   

3. Alternatively, edit Claude Desktop's config file manually:

   {
     "mcpServers": {
       "MedifinderMCP": {
         "command": "C:\\path\\to\\project\\venv\\Scripts\\python.exe",
         "args": ["C:\\path\\to\\project\\main.py"],
         "env": {
           "DB_HOST": "localhost",
           "DB_PORT": "5432",
           "DB_NAME": "medifinderbot",
           "DB_USER": "your_user",
           "DB_PASSWORD": "your_password",
           "DEBUG": "True",
           "ENV": "development",
           "SERVER_NAME": "MedifinderMCP",
           "SERVER_VERSION": "1.0.0",
           "MCP_SERVER_NAME": "MedifinderMCP",
           "MCP_SERVER_DESCRIPTION": "MCP server for medicine inventory queries",
           "MAX_SEARCH_RESULTS": "50",
           "SEARCH_SIMILARITY_THRESHOLD": "0.3"
         }
       }
     }
   }
   

4. In Claude Desktop, select the MedifinderMCP server from the servers dropdown to enable it for your conversation.

Troubleshooting

Common Issues

1. Database Connection Issues:

   • Use the troubleshoot_connection tool to diagnose connection problems
   • Verify your database credentials in the .env file
   • Ensure PostgreSQL is running on the specified port

2. Missing Tables:

   • Use the create_database_schema tool to create the database tables
   • Check logs for any errors during schema creation

3. Empty Results:

   • If queries return no results, there might not be any data in your tables
   • You need to import data into the tables using your data ingestion process

4. Session Binding Errors:

   • If you see "Instance is not bound to a Session" errors, ensure model instances are converted to dictionaries within active sessions
   • See how this is handled in the queries.py file for examples

5. Missing Dependencies:

   • Run pip install -r requirements.txt to ensure all dependencies are installed
   • Common missing dependencies are: mcp, python-dotenv, psycopg2-binary

Diagnostic Tools

When troubleshooting, use these built-in diagnostic tools:

1. diagnose_database: Checks if:

   • The database connection works
   • Tables exist
   • Tables contain data

2. troubleshoot_connection: Provides detailed information about:

   • Database connection settings
   • Connection errors
   • Table structure
   • Recommended fixes

3. create_database_schema: Creates the database tables and provides:

   • List of created tables
   • Any errors that occurred
   • Test record creation results

License

Contributors

• Lenin Carrasco - Initial work