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

MIT License

Contributors

• Lenin Carrasco - Initial work