HACS Utils

MCP server and essential utilities for Healthcare Agent Communication Standard

Provides the Model Context Protocol server and core utilities for healthcare AI agent integration.

🌐 MCP Server

The core HACS MCP server provides 42+ Hacs Tools via JSON-RPC:

• Port: 8000 (default)
• Protocol: Model Context Protocol (MCP)
• Interface: JSON-RPC 2.0
• Tools: Healthcare-specific operations

Tool Categories

• 🔍 Resource Discovery - Explore healthcare resources and schemas
• 📋 Record Management - Full CRUD for clinical records
• 🧠 Memory Management - Clinical memory and context
• ✅ Validation & Schema - Data validation and schema tools
• 🎨 Advanced Tools - LLM optimization and versioning
• 📚 Knowledge Management - Clinical guidelines and protocols

🔗 Core Integrations

Database Storage

• PostgreSQL - Primary database with healthcare schema
• pgvector - Vector storage for clinical embeddings
• Migration Support - Automated schema management

LLM Providers

• Anthropic Claude - Healthcare-optimized AI (recommended)
• OpenAI GPT - General purpose AI models
• Environment-based - Auto-configuration from API keys

Agent Frameworks

• LangGraph - AI agent workflows with memory
• MCP Protocol - Standard tool calling interface

📦 Installation

pip install hacs-utils

🚀 Quick Start

Start MCP Server

# Start MCP server
python -m hacs_utils.mcp.cli

# Configure server URL
export HACS_MCP_SERVER_URL=http://127.0.0.1:8000

# Verify server is running
curl $HACS_MCP_SERVER_URL

Use Hacs Tools

import requests

def use_tool(tool_name, arguments):
    """Call HACS MCP tools"""
    import os
    server_url = os.getenv('HACS_MCP_SERVER_URL', 'http://127.0.0.1:8000')
    response = requests.post(server_url, json={
        "jsonrpc": "2.0",
        "method": "tools/call",
        "params": {
            "name": tool_name,
            "arguments": arguments
        },
        "id": 1
    })
    return response.json()

# List all available tools
tools = use_tool("tools/list", {})
print(f"Available tools: {len(tools['result']['tools'])}")

# Create patient record
patient = use_tool("create_hacs_record", {
    "resource_type": "Patient",
    "resource_data": {
        "full_name": "Sarah Johnson",
        "birth_date": "1985-03-15",
        "gender": "female"
    }
})

🏥 Healthcare Workflow Integration

Clinical Memory Management

# Store clinical memory
memory_result = use_tool("create_memory", {
    "content": "Patient reports significant improvement in symptoms after medication adjustment",
    "memory_type": "episodic",
    "importance_score": 0.9,
    "tags": ["medication_response", "symptom_improvement"]
})

# Search memories
search_result = use_tool("search_memories", {
    "query": "medication adjustment outcomes",
    "memory_type": "episodic",
    "limit": 5
})

Clinical Templates

# Generate assessment template
template = use_tool("create_clinical_template", {
    "template_type": "assessment",
    "focus_area": "cardiology",
    "complexity_level": "comprehensive"
})

⚙️ Configuration

Environment Variables

# Database
DATABASE_URL=postgresql://hacs:password@localhost:5432/hacs

# LLM Provider (choose one)
ANTHROPIC_API_KEY=sk-ant-...  # Recommended for healthcare
OPENAI_API_KEY=sk-...         # Alternative

# Vector Store
VECTOR_STORE=pgvector  # Recommended for healthcare compliance

# Organization
HACS_ORGANIZATION=your_health_system
HEALTHCARE_SYSTEM_NAME=Your Health System

MCP Server Configuration

# MCP server automatically starts with HACS setup
# Provides Hacs Tools via JSON-RPC
# No additional configuration needed

🧠 LangGraph Integration

The optional LangGraph agent provides AI workflows with clinical memory:

# Start LangGraph agent (optional)
cd apps/hacs_developer_agent
uv run langgraph dev

# Agent runs on http://localhost:8001
# Automatically connects to MCP tools

📊 Performance

• MCP Tools: <200ms average response time
• Memory Search: <100ms for semantic queries
• Record Operations: <50ms for CRUD operations
• Tool Discovery: <10ms for tool listing

🔐 Security Features

• Actor-based Security - Role-based access control
• Audit Trails - Complete operation logging
• Session Management - Secure authentication
• Healthcare Compliance - HIPAA-aware design

🛠️ Development

Health Checks

# Check MCP server
curl http://localhost:8000/

# List available tools
curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
  http://localhost:8000/

Custom Tool Development

# Tools are implemented in hacs_utils/mcp/tools.py
# Follow MCP protocol standards
# Focus on healthcare-specific functionality

📄 License

Apache-2.0 License - see LICENSE for details.