Metadata-Version: 2.5
Name: familybugle-mcp
Version: 0.2.0
Summary: Stdio bridge to the hosted Family Bugle MCP connector, for hosts that can only launch a command.
Project-URL: Homepage, https://familybugle.com
Project-URL: MCP Reference, https://familybugle.com/ai/reference/mcp
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: mcp<2,>=1.0.0
Description-Content-Type: text/markdown

# familybugle-mcp

A stdio bridge to the hosted Family Bugle MCP connector, for hosts that can
only launch a command.

**Most hosts do not need this.** Claude, ChatGPT and Cursor all connect to a
remote MCP server directly, and connecting to `https://familybugle.com/mcp`
is the better path: fewer moving parts, nothing to install, nothing to keep
up to date. Reach for this package only when your host cannot do that.

## What it does

It forwards. `tools/list`, `tools/call`, prompts and resources all go
straight to the hosted connector and come back untouched, so this package
exposes exactly what production exposes — 15 catalog tools that need no
account, and 8 account tools behind OAuth 2.1.

That is a deliberate design rather than a shortcut. Until v0.2.0 this package
was a second implementation of the catalog against the public REST API, and
it drifted: four of its five tool names no longer existed on the server, so
the package ran fine and called nothing. A bridge has no second copy to fall
behind.

## Install

No installation required:

```sh
uvx familybugle-mcp
```

### Claude Desktop

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

### Cursor

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

## Signing in

The 15 catalog tools work anonymously. The 8 account tools — profile,
children, digest and email preferences — need a signed-in user, and this
bridge does not run an OAuth flow of its own.

If your host supports remote MCP, connect to `https://familybugle.com/mcp`
directly and sign in there; the hosted connector prompts for sign-in when a
conversation first reaches an account tool.

Otherwise, set a Supabase access token and the bridge sends it upstream:

```sh
FAMILYBUGLE_TOKEN="<access token>" uvx familybugle-mcp
```

Without it the account tools refuse, which is the server's own behaviour
rather than anything this package adds.

**The token is read once at startup and never refreshed.** A Supabase access
token lasts about an hour; after that the account tools fail until you restart
the command with a fresh one. The bridge holds no refresh token and cannot ask
for one. If your host can reach the remote connector, sign in there instead —
it handles this for you.

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `FAMILYBUGLE_MCP_URL` | `https://familybugle.com/mcp` | Connector URL to bridge to |
| `FAMILYBUGLE_TOKEN` | unset | Optional bearer token for the account tools |

## Tool reference

The current tool list is whatever the connector answers, and is documented at
<https://familybugle.com/ai/reference/mcp>.

## Development

```sh
uv run pytest -q
uv run ruff check src tests
```

## License

MIT
