# life-agent-mcp

Turn any personal-assistant REST backend into 38 Claude-ready tools over a single MCP server.

## What it is

A thin [Model Context Protocol](https://modelcontextprotocol.io) server built on `FastMCP`. Every tool is a small async function that forwards its arguments to a REST backend (`X-API-Key` auth) and formats the JSON response for Claude. No business logic lives here: the server is pure transport and shaping. It runs over the streamable-http transport, so a single long-lived process serves Claude Desktop, Claude mobile, and Claude Code alike.

The pattern is the point. If you already have a REST API for your own data, wrapping it as MCP tools is mostly this file: one decorated function per capability, two shared `call_api` / `call_api_get` helpers, and an entry point. This repo is a worked example of that pattern across a wide domain surface.

The backend itself is **not** included. The tools reference endpoints like `/api/v1/message/inbound`, `/api/v1/brain/search`, and `/api/v1/social-brand/queue`; you supply a service that answers them. Point `API_URL` at your own backend, or read the tool bodies as a template for wrapping your own.

## Tool catalog

38 tools, grouped by domain.

### General
| Tool | What it does |
|------|--------------|
| `query_agent` | Send a free-form natural-language query, optionally with a domain hint |
| `get_weekly_summary` | Cross-domain weekly digest (brain activity, cron health, stats) |

### Communications
| Tool | What it does |
|------|--------------|
| `check_emails` | Email summary for a timeframe |
| `check_messages` | SMS/text summary for a timeframe |
| `send_text` | Send an SMS via the backend (Twilio) |
| `check_calls` | Call log and voicemail summary |
| `get_communication_summary` | Unified email + SMS + call summary |

### Finance
| Tool | What it does |
|------|--------------|
| `log_expense` | Log an expense with amount, category, description |
| `check_budget` | Budget status, overall or per-category |
| `query_financials` | Natural-language finance questions (spending, net worth, investments) |

### Health
| Tool | What it does |
|------|--------------|
| `log_health_metric` | Record a metric (weight, BP, steps, sleep, …) |
| `check_health_trends` | Trends and recent readings |

### Home & inventory
| Tool | What it does |
|------|--------------|
| `check_inventory` | Search or summarize home inventory |
| `check_maintenance` | Upcoming home maintenance due |

### Infrastructure
| Tool | What it does |
|------|--------------|
| `check_system_health` | CPU/memory/disk/service status |
| `list_cron_status` | Recent cron executions and durations |
| `get_cron_errors` | Recent cron failures |

### Social media
| Tool | What it does |
|------|--------------|
| `create_social_post` | Post across platforms, now / scheduled / draft |
| `check_social_schedule` | Upcoming scheduled posts |

### Social brand management
| Tool | What it does |
|------|--------------|
| `generate_brand_posts` | AI-drafted posts per brand/platform |
| `get_social_queue` | Draft queue awaiting review |
| `approve_post` | Approve a draft and mark it scheduled |
| `reject_post` | Reject a draft with a reason |
| `schedule_post` | Send an approved post to Late for scheduling |
| `get_brand_analytics` | Engagement analytics per platform |
| `sync_social_analytics` | Pull latest engagement data from Late |

### Semantic memory ("brain")
| Tool | What it does |
|------|--------------|
| `capture_thought` | Store a thought/decision/insight; auto-classified |
| `search_brain` | Semantic search over captured entries |
| `list_recent_thoughts` | Browse recent entries chronologically |
| `brain_stats` | Topic/people/action-item patterns over time |
| `get_brain_digest` | Digest of recent activity |

### Contacts
| Tool | What it does |
|------|--------------|
| `get_contact_context` | Profile + recent history for a person |
| `log_contact_interaction` | Record an interaction and capture notes |
| `list_overdue_contacts` | Contacts overdue on their touch goal |

### Saved content
| Tool | What it does |
|------|--------------|
| `summarize_youtube_video` | Transcribe and summarize a YouTube video |
| `save_instagram_video` | Download, transcribe, and store an Instagram video |
| `search_recipes` | Semantic search over saved Instagram transcripts |
| `search_saved_content` | Search all saved content (IG, YT, TikTok, X, Reddit, articles) |

## Quick start

```bash
pip install .

cp .env.example .env      # then edit API_URL and BACKEND_API_KEY

export API_URL=http://localhost:8000
export BACKEND_API_KEY=your-key
export PORT=8001

life-agent-mcp
```

The server listens on `http://0.0.0.0:$PORT` (default `8001`) and speaks the streamable-http MCP transport at the `/mcp` path.

## Connecting Claude

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "life-agent": {
      "type": "streamable-http",
      "url": "http://localhost:8001/mcp"
    }
  }
}
```

### Claude Code

```json
{
  "mcpServers": {
    "life-agent": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    }
  }
}
```

Or via the CLI:

```bash
claude mcp add --transport http life-agent http://localhost:8001/mcp
```

## Docker

```bash
docker build -t life-agent-mcp .

docker run -p 8001:8001 \
  -e API_URL=http://host.docker.internal:8000 \
  -e BACKEND_API_KEY=your-key \
  -e PORT=8001 \
  life-agent-mcp
```

## Configuration

| Variable | Default | Purpose |
|----------|---------|---------|
| `API_URL` | `http://localhost:8000` | Base URL of the REST backend the tools proxy to |
| `BACKEND_API_KEY` | `""` | Sent as `X-API-Key` on every backend request |
| `PORT` | `8001` | Port the MCP server listens on |

## Architecture

```
Claude Desktop / Claude Code
        │  MCP (streamable-http)
        ▼
  life-agent-mcp  ── X-API-Key ──▶  your REST backend
   (this repo)                       (not included)
```

Two helpers, `call_api` (POST) and `call_api_get` (GET), carry the auth header and JSON handling; every tool is a `@mcp.tool()`-decorated coroutine that calls one of them and formats the result. The intelligence — routing, storage, embeddings, integrations — lives in the backend. This layer only defines the tool contracts and the transport.

## Note

This is an extraction of the MCP layer from a personal assistant project, published to demonstrate MCP tool and transport design. It runs against a backend that is not part of this repo, so out of the box it exercises the MCP surface (tool discovery, schemas, streamable-http) rather than returning live data. Every tool listed above maps to real code in `server.py` — nothing here is aspirational.

## License

MIT — see [LICENSE](LICENSE).