# AlayaCare MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) **server** that bridges the AlayaCare home care platform with AI agents — including N8N AI Agent workflows powered by Claude or GPT.

## Architecture

```
N8N Workflow
  └── AI Agent Node (LLM: Claude / GPT)
        └── MCP Client Node  ← built into N8N
              └── AlayaCare MCP Server  ← this project
                    └── AlayaCare REST API (basic auth)
```

## Tools exposed to the AI agent

| Tool | What it answers |
|---|---|
| `list_psws` | Who are all the active PSWs and where do they live? |
| `get_psw` | Details on a specific PSW |
| `list_clients` | Who are all the active clients and where are their service addresses? |
| `get_client` | Details on a specific client |
| `get_visits` | What visits are scheduled in a date range? |
| `get_psw_schedule` | What is a specific PSW's full schedule? |
| `get_psw_utilization` | Which PSWs are over/under-utilized? |
| `find_nearest_clients` | Which clients live closest to a given PSW? |
| `find_nearest_psw_for_client` | Which PSWs live closest to a given client? |
| `analyze_schedule_travel` | What are the travel distances between a PSW's visits on a given day? |

## Prerequisites

- Node.js 18+
- An AlayaCare account with API access enabled
- Basic auth credentials (username + password) for the AlayaCare API
- Addresses in AlayaCare must have **latitude/longitude** populated for geo tools to work (use a geocoding step or AlayaCare's built-in geocoding if available)

## Setup

```bash
# 1. Clone and install
git clone https://github.com/deathracr/alayacare-mcp.git
cd alayacare-mcp
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env with your AlayaCare credentials

# 3. Build
npm run build

# 4. Run
npm start
```

## Configuration (`.env`)

```env
# Your AlayaCare instance URL
ALAYACARE_BASE_URL=https://yourcompany.alayacare.com

# Basic auth credentials
ALAYACARE_USERNAME=your_api_username
ALAYACARE_PASSWORD=your_api_password

# Transport mode: "stdio" for N8N stdio node, "sse" for HTTP
MCP_TRANSPORT=stdio

# Port — only used when MCP_TRANSPORT=sse
MCP_PORT=3000
```

## Connecting to N8N

### Option A: SSE transport (recommended for N8N cloud / remote)

1. Run the server with `MCP_TRANSPORT=sse` on a host reachable by N8N
2. In N8N, add an **MCP Client** node
3. Set the SSE URL to `http://your-server:3000/sse`

### Option B: stdio transport (N8N self-hosted, same machine)

1. Run with `MCP_TRANSPORT=stdio` (default)
2. In N8N MCP node, choose **stdio** and point to `node /path/to/dist/index.js`

## Example questions your AI agent can answer

- *"Which PSWs are under-utilized this week?"*
- *"Find the 5 clients closest to PSW #42."*
- *"Show me all missed visits in the last 7 days."*
- *"How many hours is Sarah Johnson scheduled for next week?"*
- *"Which PSW lives closest to client #107?"*
- *"Analyze the travel efficiency of PSW #15's schedule for tomorrow."*

## Important notes

**Geocoding**: The distance-based tools (`find_nearest_clients`, `find_nearest_psw_for_client`, `analyze_schedule_travel`) require that addresses in AlayaCare have `latitude` and `longitude` fields populated. If your AlayaCare instance stores only street addresses, you will need to run a geocoding step to enrich the data.

**API endpoint paths**: AlayaCare API paths are configured in `src/alayacare/client.ts`. If your instance uses different URL patterns, update the paths in `getEmployees`, `getPatients`, and `getVisits`.

**Rate limiting**: The client paginates automatically (100 records per page). For large datasets, consider adding caching.