rmiranda-dev/caregiving-mcp

Caregiving MCP Server

A FastAPI-based MCP (Model Context Protocol) server that provides caregiving resources from AARP.org through Server-Sent Events (SSE).

Features

• MCP-over-SSE: Streaming endpoint at /sse for real-time tool execution
• Two MCP Tools:
  • search_caregiving(query, limit=5): Search caregiving articles on AARP.org
  • fetch_article(url): Fetch and extract article content (limited to AARP caregiving domain)
• Bearer Token Authentication: Optional token-based auth via MCP_TOKEN environment variable
• Health Check: Simple / endpoint returning service status
• Content Capping: Article text automatically capped at ~20k characters

Quick Start

1. Create Virtual Environment

# Windows PowerShell
python -m venv venv
.\venv\Scripts\activate

# Linux/Mac
python3 -m venv venv
source venv/bin/activate

2. Install Dependencies

pip install -r requirements.txt

3. Run the Server

Basic (No Authentication):

python main.py

With Authentication:

# Windows PowerShell
$env:MCP_TOKEN="your-secret-token"
python main.py

# Linux/Mac
export MCP_TOKEN="your-secret-token"
python main.py

Custom Port:

# Windows PowerShell
$env:PORT="3000"
python main.py

# Linux/Mac
export PORT=3000
python main.py

The server will be available at http://localhost:8000 (or your custom port)

API Endpoints

Health Check

GET /

Returns:

{
  "status": "healthy",
  "service": "caregiving-mcp",
  "version": "1.0.0"
}

MCP-over-SSE Endpoint

POST /sse
Authorization: Bearer your-secret-token (if MCP_TOKEN is set)

This endpoint handles MCP protocol messages over Server-Sent Events.

MCP Tools

search_caregiving

Search for caregiving articles on AARP.org.

Parameters:

• query (string, required): Search query
• limit (integer, optional): Maximum results (default: 5)

Returns: JSON with search results including titles, URLs, and snippets

fetch_article

Fetch and extract content from AARP caregiving articles.

Parameters:

• url (string, required): Article URL (must be from https://www.aarp.org/caregiving/)

Returns: Article content as formatted text (capped at ~20k characters)

Security

• URLs for fetch_article are restricted to https://www.aarp.org/caregiving/ domain
• Optional bearer token authentication for the /sse endpoint
• HTTPX client configured with 30-second timeout to prevent hanging requests

Dependencies

• FastAPI: Modern web framework for building APIs
• uvicorn: ASGI server for running FastAPI
• httpx: Async HTTP client for web scraping
• selectolax: Fast HTML parser for content extraction
• fastmcp: Lightweight MCP protocol implementation with SSE support

Development

To run in development mode with auto-reload:

uvicorn main:app --reload --port 8000

Example MCP Client Usage

import httpx

async def test_mcp_tools():
    async with httpx.AsyncClient() as client:
        # Health check
        response = await client.get("http://localhost:8000/")
        print(response.json())
        
        # Connect to SSE endpoint
        headers = {"Authorization": "Bearer your-secret-token"}  # if auth enabled
        async with client.stream("POST", "http://localhost:8000/sse", headers=headers) as response:
            async for line in response.aiter_lines():
                print(line)

License

MIT License - Feel free to use and modify as needed.