Medicos MCP

Medicos MCP Backend

Python MCP server backend for the Hospital Medicine Reminder app.

Overview

• Protocol: Model Context Protocol (MCP), Python implementation

• Responsibilities:

  • Expose controlled tools for Firebase, OCR/parsing, medical intelligence, scheduling, notifications, adherence, and governance.

  • Enforce ArmorIQ intent checks and auditing for all sensitive operations.

  • Persist all application data in Firebase (Firestore + Storage) and send notifications via FCM.

High-Level Layout

• mcp_server/

  • main.py – MCP server entrypoint and tool registration.

  • config.py – Environment-driven configuration (Firebase, ArmorIQ, LLM, etc.).

  • firebase_client.py – Firebase Admin SDK initialization and helpers.

  • armor_iq_client.py – ArmorIQ REST client for policy.check_intent and audit.log.

  • llm_client.py – Wrapper for LLM provider(s) used by parsing/medical/scheduling tools.

  • models/ – Pydantic models for tool inputs/outputs and shared context.

  • tools/ – Implementation of MCP tools, grouped by namespace.

Runtime Expectations

• Python 3.10+ recommended.

• MCP client (e.g. orchestrator agent) connects to this server over stdio or another supported transport.

• The server is designed to run on your VPS, separate from the Flutter app and hospital dashboard.

Environment Variables

The server is configured via environment variables (all optional defaults documented in config.py):

• MEDICOS_ENV – dev or prod (default: dev).

• MEDICOS_FIREBASE_PROJECT_ID – Firebase project ID.

• MEDICOS_FIREBASE_CREDENTIALS_FILE – Path to Firebase service account JSON (if not using ADC).

• MEDICOS_ARMORIQ_API_KEY – API key for ArmorIQ (SDK handles endpoints internally based on MEDICOS_ENV).

• MEDICOS_LLM_PROVIDER – LLM provider identifier (e.g. openai, anthropic).

• MEDICOS_LLM_API_KEY – API key for the chosen LLM provider.

You can also use a local .env file in the repository root during development; see notes in config.py.

Getting Started

Option 1: Virtual Environment (Development)

Setup:

./setup.sh          # Creates venv and installs dependencies
source .venv/bin/activate

Or manually:

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

Configure Environment:

1. Copy env.example to .env and fill in your values:

   cp env.example .env
   # Edit .env with your actual values

2. Place your Firebase service account JSON in ./credentials/firebase-service-account.json

Run the Server:

python -m mcp_server.main

Option 2: Docker Compose (Production/VPS)

Prerequisites:

• Docker and Docker Compose installed

• Firebase service account JSON file

Setup:

1. Create credentials directory and add Firebase service account:

   mkdir -p credentials
   cp /path/to/your/firebase-service-account.json credentials/

2. Create .env file:

   cp env.example .env
   # Edit .env with your actual values

3. Build and run:

   docker-compose build
   docker-compose up -d
   docker-compose logs -f mcp-server

Stop the container:

docker-compose down

Docker Configuration:

• The container runs as a non-root user (mcpuser)

• Firebase credentials are mounted read-only from ./credentials/

• Environment variables can be set in .env or docker-compose.yml

• The server runs over stdio (for MCP clients that support it)

Transport Modes

The MCP server supports two transport modes:

1. Stdio Transport (Default)

For direct process-to-process communication (e.g., Cursor, Claude Desktop):

{
  "mcpServers": {
    "medicos": {
      "command": "python",
      "args": ["-m", "mcp_server.main"],
      "env": {
        "MEDICOS_FIREBASE_PROJECT_ID": "...",
        "MEDICOS_TRANSPORT": "stdio"
      }
    }
  }
}

2. HTTP Transport (Reverse Proxy)

For deployment behind a reverse proxy (e.g., mcp.p1ng.me):

1. Set environment variable:

   MEDICOS_TRANSPORT=http
   MEDICOS_SERVER_PORT=8000

2. Run the server:

   python -m mcp_server.main
   # Server listens on http://0.0.0.0:8000

3. Configure reverse proxy (using Caddy, nginx, or similar):

   • Point mcp.p1ng.me to your VPS

   • Proxy /mcp/stream and /mcp/message to http://localhost:8000

   • Set up SSL/TLS certificates

4. Connect clients to: https://mcp.p1ng.me/mcp/stream

Troubleshooting

• Import errors: Make sure dependencies are installed (pip install -e .)

• Firebase errors: Verify service account JSON path and permissions

• ArmorIQ errors: Check base URL and API key

• LLM errors: Verify API key and provider name

• Docker issues: Ensure credentials directory exists and contains valid JSON