Metadata-Version: 2.4
Name: tf-mcp-server
Version: 0.8.2
Summary: MCP server for ToothFairyAI documentation and SDK operations
Author-email: ToothFairyAI <support@toothfairyai.com>
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: fastmcp>=0.4.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-frontmatter>=1.0.0
Requires-Dist: toothfairyai>=0.8.0
Requires-Dist: uvicorn>=0.30.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# ToothFairyAI Documentation MCP Server

A Model Context Protocol (MCP) server that exposes ToothFairyAI documentation, API specifications, and full SDK operations for AI assistants.

## Features 

- **Documentation Resources**: Access 47+ markdown documentation pages
- **API Specifications**: OpenAPI specs for Platform, AI Services, and Voice APIs
- **Full-Text Search**: Search across all documentation and API endpoints
- **Dual Transport Support**: Run as HTTP server (remote) or stdio (local)
- **SDK Integration**: 85+ tools for full workspace management
- **Validation Models**: Pre-validate payloads with Pydantic models before API calls
- **Health Checks**: Built-in `/health` and `/info` endpoints (HTTP mode)

## Quick Start

### Local Development (stdio Mode)

For use with local MCP clients like Claude Code or Claude Desktop:

```bash
cd tf_mcp_server
python -m venv venv
source venv/bin/activate
pip install -e .

# Run with stdio transport
python -m tf_mcp_server.server --stdio
```

### Local Development (SSE Mode)

For testing SSE transport locally:

```bash
cd tf_mcp_server
source venv/bin/activate

# Run with SSE transport (default)
python -m tf_mcp_server.server

# Server available at http://localhost:8000/sse
```

### Docker Deployment

```bash
# From repository root
docker build -t tf-mcp-server -f tf_mcp_server/Dockerfile.full .
docker run -p 8000:8000 tf-mcp-server
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_TRANSPORT` | `http` | Transport type: `stdio` or `http` |
| `MCP_HOST` | `0.0.0.0` | Host to bind the server (HTTP mode only) |
| `MCP_PORT` | `8000` | Port to bind the server (HTTP mode only) |
| `DOCS_PATH` | `docs/tf_docs/docs` | Path to markdown documentation |
| `API_DOCS_PATH` | `docs/api_docs/public` | Path to API documentation |
| `BASE_PATH` | (auto-detected) | Base path to repository root |

## HTTP Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/sse` | GET | SSE endpoint for MCP clients (Claude Code) |
| `/health` | GET | Health check for load balancers |
| `/info` | GET | Server information and stats |

### Health Check Response

```json
{
  "status": "healthy",
  "server": "ToothFairyAI Documentation MCP",
  "docs_loaded": 47,
  "api_specs_loaded": 3
}
```

## Connecting MCP Clients

### Claude Code (CLI) Configuration

To use the ToothFairyAI MCP server with Claude Code:

#### Option 1: Local stdio (Recommended for development)

Run the server locally using stdio transport for the most reliable connection:

**CLI Command**

```bash
claude mcp add toothfairy-docs -- python -m tf_mcp_server.server --stdio
```

**Manual configuration**

Edit your Claude config file (`~/.claude.json`):

```json
{
  "mcpServers": {
    "toothfairy-docs": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "tf_mcp_server.server", "--stdio"],
      "cwd": "/path/to/tooth-fairy-website-1/tf_mcp_server"
    }
  }
}
```

#### Option 2: Remote SSE

Connect to the hosted remote server using SSE:

| Environment | Region | Endpoint | Status |
|-------------|--------|----------|--------|
| Development | AU | `https://mcp.toothfairylab.link/sse` | ✅ Available |
| Production | AU | `https://mcp.toothfairyai.com/sse` | ✅ Available |
| Production | EU | `https://mcp.eu.toothfairyai.com/sse` | ❌ Coming Soon |
| Production | US | `https://mcp.us.toothfairyai.com/sse` | ❌ Coming Soon |

**CLI Command** (example for AU production)

```bash
claude mcp add toothfairy-docs "https://mcp.toothfairyai.com/sse" -t sse
```

**Manual configuration**

```json
{
  "mcpServers": {
    "toothfairy-docs": {
      "type": "sse",
      "url": "https://mcp.toothfairyai.com/sse"
    }
  }
}
```

> **Note**: Use `type: "sse"` for Server-Sent Events transport.

**Verify the connection**

```bash
claude mcp list
```

Or within Claude Code, type `/mcp` to see connected servers.

### Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

#### Local stdio

```json
{
  "mcpServers": {
    "toothfairy-docs": {
      "command": "python",
      "args": ["-m", "tf_mcp_server.server", "--stdio"],
      "cwd": "/path/to/tooth-fairy-website-1/tf_mcp_server"
    }
  }
}
```

#### Remote SSE

```json
{
  "mcpServers": {
    "toothfairy-docs": {
      "url": "https://mcp.toothfairyai.com/sse",
      "transport": "sse"
    }
  }
}
```

## Connection Reliability

### Built-in Keepalive

The MCP server uses FastMCP which includes **automatic SSE pings every 15 seconds** to keep connections alive. This should prevent most idle timeout issues.

### Why Connections May Still Disconnect

If you experience disconnections (e.g., after ~60 minutes), the cause is likely:

1. **AWS ALB idle timeout** - Default 60s, max configurable 4000s (~66 min)
2. **ALB target group settings** - Connection draining may close idle connections
3. **Proxy buffering** - Nginx/CloudFront may buffer SSE responses

### AWS ALB Configuration (Critical for Production)

To prevent disconnections, configure the ALB with these settings:

**Load Balancer Attributes:**
```
idle_timeout.timeout_seconds = 3600  # 1 hour (or higher if needed)
```

**Target Group Settings:**
```
deregistration_delay.timeout_seconds = 300
slow_start.duration_seconds = 0
```

**Listener Rules (if using nginx as reverse proxy):**
```nginx
location / {
    proxy_pass http://ecs-target;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_set_header Host $host;
    
    # CRITICAL: Disable buffering for SSE
    proxy_buffering off;
    proxy_cache off;
    
    # Long timeouts matching ALB idle timeout
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}
```

### Nginx Configuration (for self-hosting)

If deploying behind nginx, use these settings for optimal SSE support:

```nginx
location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_set_header Host $host;
    
    # Critical for SSE streaming - disables buffering
    proxy_buffering off;
    proxy_cache off;
    
    # Match your ALB idle timeout
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}
```

## MCP Tools

This server provides **105 tools** organized into categories:

| Category | Tools | Auth Required |
|----------|-------|---------------|
| Documentation | 10 | No |
| Release Notes | 4 | No |
| Public Utils | 3 | No |
| Agent Management | 6 | Yes |
| Agent Functions | 5 | Yes |
| Authorisations | 5 | Yes |
| Secrets | 2 | Yes |
| Documents | 6 | Yes |
| Entities | 6 | Yes |
| Folders | 6 | Yes |
| Chats | 5 | Yes |
| Prompts | 5 | Yes |
| Members | 4 | Yes |
| Channels | 5 | Yes |
| Connections | 3 | Yes |
| Benchmarks | 5 | Yes |
| Hooks | 5 | Yes |
| Scheduled Jobs | 5 | Yes |
| Sites | 4 | Yes |
| Dictionary | 2 | Yes |
| Request Logs | 2 | Yes |
| Settings | 4 | Yes |
| Billing | 1 | Yes |
| Embeddings | 1 | Yes |

See [TOOLS.md](./TOOLS.md) for complete tool documentation.

## Validation Models

The MCP server uses Pydantic validation models from the ToothFairyAI Python SDK to pre-validate payloads before making API calls. This prevents common errors like:

- Missing required fields (e.g., `interpolation_string` for agents, `custom_prompt_id` for scheduled jobs)
- Invalid field values (e.g., `interpolation_string` must be ≥ 128 characters)
- Type mismatches and invalid enum values

### Available Validation Models

| Model | Required Fields |
|-------|-----------------|
| `AgentCreateModel` | `label`, `mode`, `interpolation_string` (≥128 chars), `goals`, `temperature`, `max_tokens`, `max_history`, `top_k`, `doc_top_k` |
| `AgentFunctionCreateModel` | `name`, `description`, `url` |
| `ScheduledJobCreateModel` | `name`, `agent_id`, `custom_prompt_id`, `schedule` |
| `DocumentCreateModel` | `user_id`, `title`, `doc_type` |
| `PromptCreateModel` | `user_id`, `label`, `prompt_type`, `interpolation_string` |
| `ConnectionCreateModel` | `name` |
| `FolderCreateModel` | `name` (not `label`) |
| `EntityCreateModel` | `user_id`, `label`, `entity_type` |
| `MemberCreateModel` | `user_id` (not `email`) |

### Using Validation in MCP Tools

The MCP tools automatically validate payloads using these models. When validation fails, you'll receive a clear error message:

```
ValidationError: interpolation_string must be at least 128 characters
```

For direct SDK usage:

```python
from toothfairyai.models import AgentCreateModel

agent_data = AgentCreateModel(
    label="Support Agent",
    mode="retriever",
    interpolation_string="You are a helpful assistant..." * 10,  # Min 128 chars
    goals="Help customers",
    temperature=0.7,
    max_tokens=2000,
    max_history=10,
    top_k=10,
    doc_top_k=5
)
```

## MCP Resources

### Documentation

- `toothfairy://docs/list` - List all documentation pages
- `toothfairy://docs/{category}/{slug}` - Get a specific doc page

### API Specifications

- `toothfairy://api/list` - List all API specs
- `toothfairy://api/{name}` - Get OpenAPI spec (platform, ai-services, voice)
- `toothfairy://api/{name}/endpoints` - Get endpoints summary
- `toothfairy://api/integration-guide` - Voice API integration guide

## MCP Prompts

| Prompt | Description |
|--------|-------------|
| `api_usage_guide(endpoint)` | Generate guide for an API endpoint |
| `feature_guide(feature)` | Generate guide for a feature |
| `create_agent(agent_type, use_case)` | Generate agent configuration |

## AWS ECS Deployment (Production)

Deployment is automated via GitHub Actions. The workflow triggers on pushes to `development` branch when changes are made to:
- `tf_mcp_server/**`
- `docs/tf_docs/docs/**`
- `docs/api_docs/public/**`

### GitHub Actions Workflow

See: [.github/workflows/deployMcpServer-dev.yml](../.github/workflows/deployMcpServer-dev.yml)

### Management Commands

```bash
cd tf_mcp_server/aws
./deploy.sh status   # Get service status and endpoint URL
./deploy.sh logs     # View live logs
./deploy.sh destroy  # Delete all resources
```

## Programmatic Access

```python
from mcp import ClientSession
from mcp.client.sse import sse_client

# Use available endpoint
async with sse_client(url="https://mcp.toothfairyai.com/sse") as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        result = await session.call_tool("search_docs", {"query": "agents"})
```

## References

- [FastMCP Documentation](https://gofastmcp.com)
- [MCP Specification](https://modelcontextprotocol.io/)
- [AWS MCP Servers](https://github.com/awslabs/mcp)
- [FastMCP HTTP Deployment](https://gofastmcp.com/deployment/http)

## License

MIT
