Metadata-Version: 2.4
Name: familybugle-mcp
Version: 0.1.0
Summary: Model Context Protocol server for Park City Families — plug Family Bugle into Claude Desktop, Cursor, or any MCP-compatible client.
Project-URL: Homepage, https://familybugle.com/ai
Project-URL: API Reference, https://familybugle.com/ai/reference
Project-URL: Repository, https://github.com/park-city-families/familybugle-mcp
License: MIT
Keywords: activities,claude,families,mcp,model-context-protocol,park-city
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: httpx>=0.26.0
Requires-Dist: mcp<2,>=1.0.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

# familybugle-mcp

Model Context Protocol server for Park City Families — plug Family Bugle into Claude Desktop, Cursor, or any MCP-compatible client.

```
Claude: "Find ski camps for my 7-year-old in Park City"
→ calls search("ski camps", type="activity", filters={age: 7})
→ returns Youth Ski Camp, Basin Rec Snowsports, Park City Mountain Kids Camp
→ "Here are three ski camps available this winter..."
```

## Install

No installation required. Use `uvx` to run directly:

```bash
uvx familybugle-mcp
```

Or install permanently:

```bash
pip install familybugle-mcp
```

## Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "familybugle": {
      "command": "uvx",
      "args": ["familybugle-mcp"],
      "env": {
        "FAMILYBUGLE_API_KEY": "fb_live_YOUR_KEY_HERE"
      }
    }
  }
}
```

Restart Claude Desktop after saving. You'll see "familybugle" in the tools panel.

## Cursor

Add to `.cursor/mcp.json` in your project root, or `~/.cursor/mcp.json` globally:

```json
{
  "mcpServers": {
    "familybugle": {
      "command": "uvx",
      "args": ["familybugle-mcp"],
      "env": {
        "FAMILYBUGLE_API_KEY": "fb_live_YOUR_KEY_HERE"
      }
    }
  }
}
```

## API Key

The server works without a key (public tier: 100 requests/hour). For higher limits, get a free key:

1. Sign in at [familybugle.com/account](https://familybugle.com/account) — Developer tab
2. Click **Create API key**, copy the `fb_live_...` value
3. Paste into the `env.FAMILYBUGLE_API_KEY` field in your config

See [familybugle.com/ai](https://familybugle.com/ai) for rate limit details.

## The 3 Tools

| Tool | What it does |
|------|-------------|
| `search` | Search activities and providers by keyword. Optional filters: age, category, location, date range, price. Returns up to 10 compact results. |
| `get` | Fetch full details for a specific activity or provider by id. Use after `search` to get the complete record. |
| `ask` | Ask a natural-language question about Park City family life. Returns an answer with source citations. |

**Combined tool schemas < 1500 tokens** — designed to be lean so you don't burn context budget just loading the server.

## Example prompts

```
"Find indoor activities for a 4-year-old this weekend"
"What daycares are available in Old Town Park City?"
"When is spring break and what camps are available?"
"Compare ski lessons for ages 6-10"
"What's the price range for swimming lessons?"
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `FAMILYBUGLE_API_KEY` | (none) | API key for authenticated tier |
| `FAMILYBUGLE_API_URL` | `https://familybugle.com` | Override API base URL (for local dev) |

## Local development

Point at a local backend:

```json
{
  "mcpServers": {
    "familybugle": {
      "command": "uvx",
      "args": ["familybugle-mcp"],
      "env": {
        "FAMILYBUGLE_API_URL": "http://localhost:8000"
      }
    }
  }
}
```

## Links

- [Developer hub](https://familybugle.com/ai) — MCP config, API docs, key management
- [Interactive API reference](https://familybugle.com/ai/reference) — try every endpoint in the browser
- [Family Bugle](https://familybugle.com) — the full site for Park City families
- [GitHub](https://github.com/park-city-families/familybugle-mcp) — source code
