# 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 **25+ healthcare 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**
```bash
pip install hacs-utils
```
## 🚀 **Quick Start**
### **Start MCP Server**
```bash
# Via HACS setup
python setup.py --mode local
# MCP server runs on http://localhost:8000
curl http://localhost:8000/
```
### **Use Healthcare Tools**
```python
import requests
def use_tool(tool_name, arguments):
"""Call HACS MCP tools"""
response = requests.post('http://localhost:8000/', 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**
```python
# 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**
```python
# Generate assessment template
template = use_tool("create_clinical_template", {
"template_type": "assessment",
"focus_area": "cardiology",
"complexity_level": "comprehensive"
})
```
## ⚙️ **Configuration**
### **Environment Variables**
```bash
# 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**
```python
# MCP server automatically starts with HACS setup
# Provides healthcare tools via JSON-RPC
# No additional configuration needed
```
## 🧠 **LangGraph Integration**
The optional LangGraph agent provides AI workflows with clinical memory:
```bash
# 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**
```bash
# 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**
```python
# 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](../../LICENSE) for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "hacs-utils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Solano Todeschini <solanovisitor@gmail.com>",
"keywords": "agents, ai, anthropic, crewai, healthcare, langchain, langgraph, mcp, model-context-protocol, openai, pinecone, qdrant, utils",
"author": null,
"author_email": "Solano Todeschini <solanovisitor@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/37/36/678ea4c83753d9b0e18b9773084fcdeaf30d4b78ef3e07b41bfa27c695a5/hacs_utils-0.4.1.tar.gz",
"platform": null,
"description": "# HACS Utils\n\n**MCP server and essential utilities for Healthcare Agent Communication Standard**\n\nProvides the Model Context Protocol server and core utilities for healthcare AI agent integration.\n\n## \ud83c\udf10 **MCP Server**\n\nThe core HACS MCP server provides **25+ healthcare tools** via JSON-RPC:\n\n- **Port**: 8000 (default)\n- **Protocol**: Model Context Protocol (MCP)\n- **Interface**: JSON-RPC 2.0\n- **Tools**: Healthcare-specific operations\n\n### **Tool Categories**\n- \ud83d\udd0d **Resource Discovery** - Explore healthcare resources and schemas\n- \ud83d\udccb **Record Management** - Full CRUD for clinical records\n- \ud83e\udde0 **Memory Management** - Clinical memory and context\n- \u2705 **Validation & Schema** - Data validation and schema tools\n- \ud83c\udfa8 **Advanced Tools** - LLM optimization and versioning\n- \ud83d\udcda **Knowledge Management** - Clinical guidelines and protocols\n\n## \ud83d\udd17 **Core Integrations**\n\n### **Database Storage**\n- **PostgreSQL** - Primary database with healthcare schema\n- **pgvector** - Vector storage for clinical embeddings\n- **Migration Support** - Automated schema management\n\n### **LLM Providers**\n- **Anthropic Claude** - Healthcare-optimized AI (recommended)\n- **OpenAI GPT** - General purpose AI models\n- **Environment-based** - Auto-configuration from API keys\n\n### **Agent Frameworks**\n- **LangGraph** - AI agent workflows with memory\n- **MCP Protocol** - Standard tool calling interface\n\n## \ud83d\udce6 **Installation**\n\n```bash\npip install hacs-utils\n```\n\n## \ud83d\ude80 **Quick Start**\n\n### **Start MCP Server**\n```bash\n# Via HACS setup\npython setup.py --mode local\n\n# MCP server runs on http://localhost:8000\ncurl http://localhost:8000/\n```\n\n### **Use Healthcare Tools**\n```python\nimport requests\n\ndef use_tool(tool_name, arguments):\n \"\"\"Call HACS MCP tools\"\"\"\n response = requests.post('http://localhost:8000/', json={\n \"jsonrpc\": \"2.0\",\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": tool_name,\n \"arguments\": arguments\n },\n \"id\": 1\n })\n return response.json()\n\n# List all available tools\ntools = use_tool(\"tools/list\", {})\nprint(f\"Available tools: {len(tools['result']['tools'])}\")\n\n# Create patient record\npatient = use_tool(\"create_hacs_record\", {\n \"resource_type\": \"Patient\",\n \"resource_data\": {\n \"full_name\": \"Sarah Johnson\",\n \"birth_date\": \"1985-03-15\",\n \"gender\": \"female\"\n }\n})\n```\n\n## \ud83c\udfe5 **Healthcare Workflow Integration**\n\n### **Clinical Memory Management**\n```python\n# Store clinical memory\nmemory_result = use_tool(\"create_memory\", {\n \"content\": \"Patient reports significant improvement in symptoms after medication adjustment\",\n \"memory_type\": \"episodic\",\n \"importance_score\": 0.9,\n \"tags\": [\"medication_response\", \"symptom_improvement\"]\n})\n\n# Search memories\nsearch_result = use_tool(\"search_memories\", {\n \"query\": \"medication adjustment outcomes\",\n \"memory_type\": \"episodic\",\n \"limit\": 5\n})\n```\n\n### **Clinical Templates**\n```python\n# Generate assessment template\ntemplate = use_tool(\"create_clinical_template\", {\n \"template_type\": \"assessment\",\n \"focus_area\": \"cardiology\",\n \"complexity_level\": \"comprehensive\"\n})\n```\n\n## \u2699\ufe0f **Configuration**\n\n### **Environment Variables**\n```bash\n# Database\nDATABASE_URL=postgresql://hacs:password@localhost:5432/hacs\n\n# LLM Provider (choose one)\nANTHROPIC_API_KEY=sk-ant-... # Recommended for healthcare\nOPENAI_API_KEY=sk-... # Alternative\n\n# Vector Store\nVECTOR_STORE=pgvector # Recommended for healthcare compliance\n\n# Organization\nHACS_ORGANIZATION=your_health_system\nHEALTHCARE_SYSTEM_NAME=Your Health System\n```\n\n### **MCP Server Configuration**\n```python\n# MCP server automatically starts with HACS setup\n# Provides healthcare tools via JSON-RPC\n# No additional configuration needed\n```\n\n## \ud83e\udde0 **LangGraph Integration**\n\nThe optional LangGraph agent provides AI workflows with clinical memory:\n\n```bash\n# Start LangGraph agent (optional)\ncd apps/hacs_developer_agent\nuv run langgraph dev\n\n# Agent runs on http://localhost:8001\n# Automatically connects to MCP tools\n```\n\n## \ud83d\udcca **Performance**\n\n- **MCP Tools**: <200ms average response time\n- **Memory Search**: <100ms for semantic queries\n- **Record Operations**: <50ms for CRUD operations\n- **Tool Discovery**: <10ms for tool listing\n\n## \ud83d\udd10 **Security Features**\n\n- **Actor-based Security** - Role-based access control\n- **Audit Trails** - Complete operation logging\n- **Session Management** - Secure authentication\n- **Healthcare Compliance** - HIPAA-aware design\n\n## \ud83d\udee0\ufe0f **Development**\n\n### **Health Checks**\n```bash\n# Check MCP server\ncurl http://localhost:8000/\n\n# List available tools\ncurl -X POST -H \"Content-Type: application/json\" \\\n -d '{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}' \\\n http://localhost:8000/\n```\n\n### **Custom Tool Development**\n```python\n# Tools are implemented in hacs_utils/mcp/tools.py\n# Follow MCP protocol standards\n# Focus on healthcare-specific functionality\n```\n\n## \ud83d\udcc4 **License**\n\nApache-2.0 License - see [LICENSE](../../LICENSE) for details.",
"bugtrack_url": null,
"license": "MIT",
"summary": "External service integrations, utilities, and MCP server for HACS",
"version": "0.4.1",
"project_urls": {
"Changelog": "https://github.com/solanovisitor/hacs-ai/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/solanovisitor/hacs-ai/blob/main/docs/",
"Homepage": "https://github.com/solanovisitor/hacs-ai",
"Issues": "https://github.com/solanovisitor/hacs-ai/issues",
"Repository": "https://github.com/solanovisitor/hacs-ai"
},
"split_keywords": [
"agents",
" ai",
" anthropic",
" crewai",
" healthcare",
" langchain",
" langgraph",
" mcp",
" model-context-protocol",
" openai",
" pinecone",
" qdrant",
" utils"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e6104a09adcc7368656e954c84f4177fa9c1acef80fa70493bce6055faf6d3f5",
"md5": "c122ce66a82e154ee5df178d51cfe589",
"sha256": "9aab27eece2a0812724543f3342c49c735a0efe8a3df6619b36141e3ed6d7d98"
},
"downloads": -1,
"filename": "hacs_utils-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c122ce66a82e154ee5df178d51cfe589",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 127554,
"upload_time": "2025-08-10T16:57:26",
"upload_time_iso_8601": "2025-08-10T16:57:26.491558Z",
"url": "https://files.pythonhosted.org/packages/e6/10/4a09adcc7368656e954c84f4177fa9c1acef80fa70493bce6055faf6d3f5/hacs_utils-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3736678ea4c83753d9b0e18b9773084fcdeaf30d4b78ef3e07b41bfa27c695a5",
"md5": "69a94e7279c67062cb941e6fe6f64b5d",
"sha256": "7565543ed836329193b964bd2b019bc04824e83806e317cc09fbf07a06fd44d3"
},
"downloads": -1,
"filename": "hacs_utils-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "69a94e7279c67062cb941e6fe6f64b5d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 109411,
"upload_time": "2025-08-10T16:57:28",
"upload_time_iso_8601": "2025-08-10T16:57:28.102962Z",
"url": "https://files.pythonhosted.org/packages/37/36/678ea4c83753d9b0e18b9773084fcdeaf30d4b78ef3e07b41bfa27c695a5/hacs_utils-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-10 16:57:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "solanovisitor",
"github_project": "hacs-ai",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hacs-utils"
}
JSON
