atlas_mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

atlas_mcp is a standalone Python toolkit for AI-powered search and conversation over FHIR R4 clinical documents, accessible via MCP (Model Context Protocol). It provides 15+ MCP tools for agent queries, document retrieval, session management, and embeddings ingestion. The MCP interface is the delivery mechanism — the value is the full healthcare AI stack underneath (hybrid search, cross-encoder reranking, multi-agent workflow, PII masking, medical API integrations).

Requires Python 3.11+, PostgreSQL 14+ with pgvector, and an LLM provider (Ollama default). Designed to be cloned, configured via .env, and run immediately.

Commands

# Run server (stdio transport for Claude Desktop/Cursor)
python server.py

# Run server (HTTP transport)
python server.py --transport streamable-http --port 8000

# Run all tests (134 tests, no external services needed)
.venv/bin/python -m pytest

# Run a specific test file
.venv/bin/python -m pytest tests/test_session/test_in_memory_store.py

# Run tests matching a pattern
.venv/bin/python -m pytest -k "query_classifier"

# Run tests for a module
.venv/bin/python -m pytest tests/test_agent/

# Install dependencies
pip install -r requirements.txt

# Database setup
psql -U postgres -d hc_ai -f scripts/setup_db.sql

Note: Use .venv/bin/python — the project venv has all dependencies including pytest.

Architecture

The server entry point is server.py, which creates a FastMCP instance, registers tool groups, and runs via stdio or HTTP (uvicorn).

Core Modules

• agent/ — LangGraph multi-agent workflow: Query → Classifier → Researcher → Validator → Response. graph.py defines the state machine, config.py handles LLM provider abstraction (Ollama/OpenAI/Anthropic/Bedrock), query_classifier.py detects query type (medical/conversational/mixed). pii_masker/ provides PII detection via local regex or AWS Comprehend Medical.