bring-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- bring_mcp-0.1.0/.env.example +22 -0
- bring_mcp-0.1.0/.gitattributes +1 -0
- bring_mcp-0.1.0/.github/dependabot.yml +14 -0
- bring_mcp-0.1.0/.github/workflows/ci.yml +29 -0
- bring_mcp-0.1.0/.github/workflows/release.yml +64 -0
- bring_mcp-0.1.0/.gitignore +21 -0
- bring_mcp-0.1.0/AGENTS.md +144 -0
- bring_mcp-0.1.0/CLAUDE.md +1 -0
- bring_mcp-0.1.0/Dockerfile +12 -0
- bring_mcp-0.1.0/LICENSE +21 -0
- bring_mcp-0.1.0/PKG-INFO +195 -0
- bring_mcp-0.1.0/README.md +171 -0
- bring_mcp-0.1.0/SECURITY.md +25 -0
- bring_mcp-0.1.0/compose.yml +31 -0
- bring_mcp-0.1.0/deploy/apache/bring-mcp.conf +23 -0
- bring_mcp-0.1.0/deploy/caddy/Caddyfile +14 -0
- bring_mcp-0.1.0/docs/deploy.md +102 -0
- bring_mcp-0.1.0/pyproject.toml +53 -0
- bring_mcp-0.1.0/server.json +39 -0
- bring_mcp-0.1.0/src/bring_mcp/__init__.py +0 -0
- bring_mcp-0.1.0/src/bring_mcp/__main__.py +21 -0
- bring_mcp-0.1.0/src/bring_mcp/auth.py +280 -0
- bring_mcp-0.1.0/src/bring_mcp/bring_client.py +179 -0
- bring_mcp-0.1.0/src/bring_mcp/server.py +122 -0
- bring_mcp-0.1.0/src/bring_mcp/staples.py +50 -0
- bring_mcp-0.1.0/src/bring_mcp/store.py +46 -0
- bring_mcp-0.1.0/src/bring_mcp/tools.py +215 -0
- bring_mcp-0.1.0/tests/test_auth.py +183 -0
- bring_mcp-0.1.0/tests/test_client.py +122 -0
- bring_mcp-0.1.0/tests/test_server.py +87 -0
- bring_mcp-0.1.0/tests/test_tools.py +159 -0
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Copy to .env (chmod 600) and fill in. Never commit .env.
|
|
2
|
+
|
|
3
|
+
# Bring! account
|
|
4
|
+
BRING_EMAIL=
|
|
5
|
+
BRING_PASSWORD=
|
|
6
|
+
# List used when a tool is called without a list name (default: the first list)
|
|
7
|
+
# BRING_DEFAULT_LIST=Shopping
|
|
8
|
+
|
|
9
|
+
# --- Remote server only (claude.ai connector) ---
|
|
10
|
+
|
|
11
|
+
# Password asked on the OAuth page when adding the connector (20+ characters)
|
|
12
|
+
# Generate one with: openssl rand -base64 30
|
|
13
|
+
MCP_PASSWORD=
|
|
14
|
+
|
|
15
|
+
# Public base URL of the server (your reverse proxy vhost), without trailing slash
|
|
16
|
+
PUBLIC_URL=https://bring.example.com
|
|
17
|
+
|
|
18
|
+
# Optional
|
|
19
|
+
# PORT=8765
|
|
20
|
+
# LISTEN_HOST=127.0.0.1
|
|
21
|
+
# OAuth redirect URIs a client may register (comma-separated). Default: claude.ai's callback.
|
|
22
|
+
# ALLOWED_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
* text=auto eol=lf
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
version: 2
|
|
2
|
+
updates:
|
|
3
|
+
- package-ecosystem: pip
|
|
4
|
+
directory: /
|
|
5
|
+
schedule:
|
|
6
|
+
interval: weekly
|
|
7
|
+
- package-ecosystem: docker
|
|
8
|
+
directory: /
|
|
9
|
+
schedule:
|
|
10
|
+
interval: weekly
|
|
11
|
+
- package-ecosystem: github-actions
|
|
12
|
+
directory: /
|
|
13
|
+
schedule:
|
|
14
|
+
interval: weekly
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
pull_request:
|
|
6
|
+
|
|
7
|
+
permissions:
|
|
8
|
+
contents: read
|
|
9
|
+
|
|
10
|
+
jobs:
|
|
11
|
+
test:
|
|
12
|
+
runs-on: ubuntu-latest
|
|
13
|
+
strategy:
|
|
14
|
+
matrix:
|
|
15
|
+
python: ["3.12", "3.13"]
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
18
|
+
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
|
|
19
|
+
with:
|
|
20
|
+
python-version: ${{ matrix.python }}
|
|
21
|
+
- run: pip install -e ".[dev]"
|
|
22
|
+
- run: ruff check .
|
|
23
|
+
- run: pytest -q
|
|
24
|
+
|
|
25
|
+
docker:
|
|
26
|
+
runs-on: ubuntu-latest
|
|
27
|
+
steps:
|
|
28
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
29
|
+
- run: docker build -t bring-mcp .
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Push a tag vX.Y.Z (matching the version in pyproject.toml) to publish the
|
|
2
|
+
# package on PyPI, then the server on the MCP Registry (registry.modelcontextprotocol.io).
|
|
3
|
+
# PyPI uses trusted publishing (no token): add this workflow as a trusted
|
|
4
|
+
# publisher on pypi.org, environment "pypi". The registry uses GitHub OIDC.
|
|
5
|
+
name: Release
|
|
6
|
+
|
|
7
|
+
on:
|
|
8
|
+
push:
|
|
9
|
+
tags: ["v*"]
|
|
10
|
+
|
|
11
|
+
permissions:
|
|
12
|
+
contents: read
|
|
13
|
+
|
|
14
|
+
jobs:
|
|
15
|
+
pypi:
|
|
16
|
+
runs-on: ubuntu-latest
|
|
17
|
+
environment: pypi
|
|
18
|
+
permissions:
|
|
19
|
+
id-token: write
|
|
20
|
+
steps:
|
|
21
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
22
|
+
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
|
|
23
|
+
with:
|
|
24
|
+
python-version: "3.13"
|
|
25
|
+
- name: Check the tag matches the package version
|
|
26
|
+
run: |
|
|
27
|
+
version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
|
|
28
|
+
test "v$version" = "$GITHUB_REF_NAME" || { echo "tag $GITHUB_REF_NAME != pyproject version $version"; exit 1; }
|
|
29
|
+
- run: pip install -e ".[dev]" build
|
|
30
|
+
- run: ruff check .
|
|
31
|
+
- run: pytest -q
|
|
32
|
+
- run: python -m build
|
|
33
|
+
- uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
|
|
34
|
+
|
|
35
|
+
mcp-registry:
|
|
36
|
+
needs: pypi
|
|
37
|
+
runs-on: ubuntu-latest
|
|
38
|
+
permissions:
|
|
39
|
+
id-token: write
|
|
40
|
+
env:
|
|
41
|
+
MCP_PUBLISHER_VERSION: v1.8.9
|
|
42
|
+
steps:
|
|
43
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
44
|
+
- uses: sigstore/cosign-installer@756fe2d284c7292c4e9b62c8a28f1e5629c59532 # v4.1.3
|
|
45
|
+
- name: Download and verify mcp-publisher
|
|
46
|
+
run: |
|
|
47
|
+
set -euo pipefail
|
|
48
|
+
archive="mcp-publisher_linux_amd64.tar.gz"
|
|
49
|
+
base_url="https://github.com/modelcontextprotocol/registry/releases/download/${MCP_PUBLISHER_VERSION}"
|
|
50
|
+
curl --fail --location --silent --show-error --output "$archive" "$base_url/$archive"
|
|
51
|
+
curl --fail --location --silent --show-error --output "$archive.sigstore.json" "$base_url/$archive.sigstore.json"
|
|
52
|
+
cosign verify-blob \
|
|
53
|
+
--bundle "$archive.sigstore.json" \
|
|
54
|
+
--certificate-identity "https://github.com/modelcontextprotocol/registry/.github/workflows/release.yml@refs/tags/${MCP_PUBLISHER_VERSION}" \
|
|
55
|
+
--certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
|
|
56
|
+
"$archive"
|
|
57
|
+
tar xzf "$archive" mcp-publisher
|
|
58
|
+
- name: Set the version in server.json
|
|
59
|
+
run: |
|
|
60
|
+
version="${GITHUB_REF_NAME#v}"
|
|
61
|
+
jq --arg v "$version" '.version = $v | .packages[].version = $v' server.json > server.tmp
|
|
62
|
+
mv server.tmp server.json
|
|
63
|
+
- run: ./mcp-publisher login github-oidc
|
|
64
|
+
- run: ./mcp-publisher publish
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Secrets and runtime data: never commit
|
|
2
|
+
.env
|
|
3
|
+
data/
|
|
4
|
+
*.sqlite
|
|
5
|
+
*.sqlite-journal
|
|
6
|
+
|
|
7
|
+
# Python
|
|
8
|
+
.venv/
|
|
9
|
+
__pycache__/
|
|
10
|
+
*.py[cod]
|
|
11
|
+
*.egg-info/
|
|
12
|
+
build/
|
|
13
|
+
dist/
|
|
14
|
+
.pytest_cache/
|
|
15
|
+
.ruff_cache/
|
|
16
|
+
|
|
17
|
+
# Editors / OS
|
|
18
|
+
.vscode/
|
|
19
|
+
.idea/
|
|
20
|
+
.DS_Store
|
|
21
|
+
Thumbs.db
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
Notes for coding agents (and humans) working on this repository. The README covers
|
|
4
|
+
what the project does and how to set it up; this file covers what to keep in mind
|
|
5
|
+
when changing it.
|
|
6
|
+
|
|
7
|
+
## Layout
|
|
8
|
+
|
|
9
|
+
- `src/bring_mcp/tools.py`: every tool and prompt, plus `INSTRUCTIONS`. `register()`
|
|
10
|
+
adds them to any `MCPServer`; it is the only place tools are defined.
|
|
11
|
+
- `src/bring_mcp/bring_client.py`: wrapper around bring-api (login, lists by name,
|
|
12
|
+
catalog names, recipe parser) and the name-matching helpers (`normalize`,
|
|
13
|
+
`find`, `merge_spec`).
|
|
14
|
+
- `src/bring_mcp/__main__.py`: local stdio server (`bring-mcp`).
|
|
15
|
+
`src/bring_mcp/server.py`: remote HTTP server for claude.ai (OAuth, audit log).
|
|
16
|
+
- `src/bring_mcp/auth.py`: OAuth provider (password page, lockout, redirect
|
|
17
|
+
allowlist). Ported from proton-mcp's `remote/auth.py`: a security fix in one
|
|
18
|
+
probably applies to the other.
|
|
19
|
+
- `src/bring_mcp/store.py`: SQLite key-value store (OAuth clients/tokens, staples).
|
|
20
|
+
`src/bring_mcp/staples.py`: staples, and the cron command `python -m bring_mcp.staples`.
|
|
21
|
+
- `deploy/`: example reverse-proxy configs. `docs/deploy.md`: the full server guide.
|
|
22
|
+
|
|
23
|
+
## Commands
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
pip install -e ".[dev]"
|
|
27
|
+
pytest
|
|
28
|
+
ruff check .
|
|
29
|
+
docker build -t bring-mcp .
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Tests need no Bring account and no network: `tests/test_tools.py` runs the tools
|
|
33
|
+
against a `FakeClient`, `tests/test_client.py` fakes `bring_api.Bring` including
|
|
34
|
+
its private attributes. `server.py` reads its configuration at import time, so
|
|
35
|
+
`tests/test_server.py` imports it in a subprocess.
|
|
36
|
+
|
|
37
|
+
## Releasing
|
|
38
|
+
|
|
39
|
+
Bump `version` in `pyproject.toml`, commit, then push a tag `vX.Y.Z` with the same
|
|
40
|
+
version. `.github/workflows/release.yml` checks the tag matches, runs the tests,
|
|
41
|
+
publishes to PyPI (trusted publishing, environment `pypi`), then publishes
|
|
42
|
+
`server.json` to the MCP Registry as `io.github.vdeabreu/bring-mcp` (GitHub OIDC). The
|
|
43
|
+
registry checks ownership through the `mcp-name:` comment at the top of the
|
|
44
|
+
README: keep it.
|
|
45
|
+
|
|
46
|
+
## Invariants: don't break these
|
|
47
|
+
|
|
48
|
+
- **Bounded, single-line inputs.** Item names, specs and list names go through the
|
|
49
|
+
`ItemName` / `Spec` / `ListArg` types in `tools.py` (no control characters,
|
|
50
|
+
length limits), and a call takes at most `MAX_ITEMS` items. Use them for any new
|
|
51
|
+
argument.
|
|
52
|
+
- **No account-level tools.** The server reads and edits list items and staples
|
|
53
|
+
only. Don't add tools that delete lists, share them, invite users or change
|
|
54
|
+
account settings.
|
|
55
|
+
- **Annotations stay honest.** Read tools are `readOnlyHint`; `remove_items` and
|
|
56
|
+
`set_staples_list` are `destructiveHint`, so clients can ask before running them.
|
|
57
|
+
- **Recipe pages are untrusted.** `fetch_recipe` passes the URL to Bring's parser
|
|
58
|
+
(the server never downloads the page itself), accepts `http(s)` only and returns
|
|
59
|
+
only ingredient names and specs. `INSTRUCTIONS` tell the model not to follow text
|
|
60
|
+
from recipe pages; keep it that way.
|
|
61
|
+
- **Errors are readable, internals aren't.** Bring and lookup errors
|
|
62
|
+
(`BringException`, `ValueError`) become a `ToolError` with a short message the
|
|
63
|
+
model can act on (e.g. the list of available lists). Any other exception is logged
|
|
64
|
+
with its traceback and reported as a generic message.
|
|
65
|
+
- **Shared lists are untrusted too.** Item names come from everyone the list is
|
|
66
|
+
shared with; `INSTRUCTIONS` tell the model to treat them as data.
|
|
67
|
+
- **Private data directory.** `Store` creates the directory 0700 and the SQLite
|
|
68
|
+
file 0600: it holds OAuth tokens.
|
|
69
|
+
- **Remote hardening.** The HTTP server refuses a non-loopback `LISTEN_HOST` unless
|
|
70
|
+
`ALLOW_NON_LOOPBACK_LISTEN=true` (`_check_listen_host`); `MCP_PASSWORD` must be
|
|
71
|
+
20+ characters; OAuth registration only accepts the claude.ai callback URLs; the
|
|
72
|
+
login page sends anti-framing headers. Every tool call is logged with its
|
|
73
|
+
arguments (shopping items aren't sensitive enough to hide).
|
|
74
|
+
|
|
75
|
+
## Bring and bring-api behaviour (learned the hard way)
|
|
76
|
+
|
|
77
|
+
- **bring-api hides what we need.** The catalog translations, the list locale and
|
|
78
|
+
the translate function are name-mangled private attributes
|
|
79
|
+
(`_Bring__translations`, `_Bring__locale`, `_Bring__translate`). That's why
|
|
80
|
+
bring-api is pinned in `pyproject.toml`: before bumping it, check these still
|
|
81
|
+
exist and run the tests.
|
|
82
|
+
- **Catalog keys are Swiss German.** Bring identifies catalog items by their de-CH
|
|
83
|
+
name (`BRING_DEFAULT_LOCALE`), so there is no translation table for de-CH: for a
|
|
84
|
+
de-CH list, the catalog is the table's keys. The recipe parser returns these keys
|
|
85
|
+
too, hence `_to_list_language()`.
|
|
86
|
+
- **Names are in the list's language both ways.** `get_list` returns items
|
|
87
|
+
translated to the list's language, and `batch_update_list` translates `itemId`
|
|
88
|
+
back to the catalog key. So always send names in the list's language, spelled
|
|
89
|
+
as in the catalog (`catalog_name()`): a name that doesn't match exactly is stored
|
|
90
|
+
as a custom item, without icon or section.
|
|
91
|
+
- **Matching is ours.** Bring doesn't deduplicate "tomate" and "Tomates".
|
|
92
|
+
`normalize()` ignores case, accents, œ/æ and a final s/x on words longer than 3
|
|
93
|
+
letters; `find()` uses it to merge with existing items.
|
|
94
|
+
- **One operation, three effects.** `ADD` with an existing item's `uuid` replaces
|
|
95
|
+
its spec (that's how `update_item` and merging work). `COMPLETE` moves an item to
|
|
96
|
+
"recently bought"; `REMOVE` works on both sections.
|
|
97
|
+
- **Sessions.** Login is lazy (first tool call), so the server starts without
|
|
98
|
+
network. bring-api refreshes the access token by itself; when the refresh token
|
|
99
|
+
expires it raises `BringAuthException`, and `BringClient._call()` logs in again
|
|
100
|
+
once. A failed login itself is never retried (wrong credentials would double the
|
|
101
|
+
attempts on every call and risk a rate limit on the Bring account). List settings (locales) are loaded at login: a list created later uses the
|
|
102
|
+
account locale until the next login.
|
|
103
|
+
- **Accounts** must sign in with email and password; Google/Apple sign-in accounts
|
|
104
|
+
need a password set in the Bring app first.
|
|
105
|
+
- **de-CH only accounts.** bring-api loads no translation table for de-CH, so the
|
|
106
|
+
catalog comes from the `articles.de-CH.json` file bring-api ships.
|
|
107
|
+
|
|
108
|
+
## MCP SDK notes (mcp 2.3.0)
|
|
109
|
+
|
|
110
|
+
- The server class is `mcp.server.mcpserver.MCPServer`. `Tool` fields are
|
|
111
|
+
snake_case (`input_schema`, `annotations.read_only_hint`).
|
|
112
|
+
- `Annotated[..., Field(...)]` parameters become JSON Schema constraints and are
|
|
113
|
+
validated before the tool runs (a bad argument is a `ToolError`).
|
|
114
|
+
- A tool returning `dict` has no output schema: `call_tool()` gives
|
|
115
|
+
`structured_content=None` and the JSON in `content[0].text` (see the `call`
|
|
116
|
+
helper in `tests/test_tools.py`).
|
|
117
|
+
|
|
118
|
+
## Deployment notes
|
|
119
|
+
|
|
120
|
+
- Unlike proton-mcp, the container uses a normal Docker network, not the host
|
|
121
|
+
network: it only talks to the internet, and the host network would let it reach
|
|
122
|
+
other loopback services (such as Proton Mail Bridge on the same host). So in
|
|
123
|
+
`compose.yml` it listens on 0.0.0.0 inside the container, the port is published
|
|
124
|
+
on `127.0.0.1` only, and `FORWARDED_ALLOW_IPS` trusts Docker's default pool
|
|
125
|
+
(172.16.0.0/12) because requests come from the Docker gateway. Never `"*"`: uvicorn
|
|
126
|
+
then takes the *leftmost* `X-Forwarded-For` value, which the client controls, so
|
|
127
|
+
anyone could forge the address in "wrong password from ..." log lines.
|
|
128
|
+
- The reverse proxy should target `127.0.0.1:8765`, not `localhost` (Docker
|
|
129
|
+
doesn't publish the port on `::1`).
|
|
130
|
+
- Rebuilding the container keeps OAuth tokens (`data/bring-mcp.sqlite`), so
|
|
131
|
+
claude.ai stays connected. Raising the password rules (e.g. the 20-character
|
|
132
|
+
minimum) stops the server from starting until `.env` is updated.
|
|
133
|
+
|
|
134
|
+
## Conventions
|
|
135
|
+
|
|
136
|
+
- Python 3.12+, ruff with line length 120. Code, docs and tool descriptions in
|
|
137
|
+
English; the model answers in the user's language anyway.
|
|
138
|
+
- Tool docstrings are what the model reads: keep them accurate and short.
|
|
139
|
+
- Add a test with each change, especially for name matching, input validation and
|
|
140
|
+
anything that reads bring-api's private attributes.
|
|
141
|
+
- Dependencies and the Docker base image are pinned (image by digest, actions by
|
|
142
|
+
SHA). Dependabot opens the update PRs.
|
|
143
|
+
- Keep the repo generic: no personal domains, IPs or host names (use
|
|
144
|
+
`bring.example.com`).
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
@AGENTS.md
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Base image pinned by digest (the tag is on the FROM line); Dependabot proposes updates.
|
|
2
|
+
FROM python:3.15-slim@sha256:65a65fc7b30b06cb6df4930fd4650697cb23f4c2698ab81fc87e4b031bc36928
|
|
3
|
+
WORKDIR /app
|
|
4
|
+
COPY pyproject.toml README.md ./
|
|
5
|
+
COPY src ./src
|
|
6
|
+
RUN pip install --no-cache-dir "uvicorn==0.54.0" . \
|
|
7
|
+
&& useradd -u 1000 -m app && mkdir /data && chown app /data
|
|
8
|
+
USER app
|
|
9
|
+
ENV DATA_DIR=/data PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1
|
|
10
|
+
EXPOSE 8765
|
|
11
|
+
HEALTHCHECK --interval=60s --timeout=5s CMD python -c "import os, urllib.request; urllib.request.urlopen(f'http://127.0.0.1:{os.environ.get(\"PORT\", \"8765\")}/health')"
|
|
12
|
+
CMD ["python", "-m", "bring_mcp.server"]
|
bring_mcp-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Victor De Abreu
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
bring_mcp-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: bring-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: MCP server for Bring! shopping lists (local stdio or remote claude.ai connector)
|
|
5
|
+
Project-URL: Homepage, https://github.com/vdeabreu/bring-mcp
|
|
6
|
+
Project-URL: Issues, https://github.com/vdeabreu/bring-mcp/issues
|
|
7
|
+
Author: Victor De Abreu
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: bring,claude,groceries,mcp,mcp-server,recipes,shopping-list
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Topic :: Home Automation
|
|
16
|
+
Requires-Python: >=3.12
|
|
17
|
+
Requires-Dist: bring-api==1.1.2
|
|
18
|
+
Requires-Dist: mcp==2.3.0
|
|
19
|
+
Requires-Dist: uvicorn>=0.30
|
|
20
|
+
Provides-Extra: dev
|
|
21
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
22
|
+
Requires-Dist: ruff>=0.6; extra == 'dev'
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
|
|
25
|
+
# bring-mcp
|
|
26
|
+
|
|
27
|
+
[](https://pypi.org/project/bring-mcp/)
|
|
28
|
+
[](https://github.com/vdeabreu/bring-mcp/actions/workflows/ci.yml)
|
|
29
|
+
[](https://github.com/vdeabreu/bring-mcp/blob/main/LICENSE)
|
|
30
|
+
|
|
31
|
+
<!-- mcp-name: io.github.vdeabreu/bring-mcp -->
|
|
32
|
+
|
|
33
|
+
An [MCP](https://modelcontextprotocol.io) server that gives Claude (or any MCP
|
|
34
|
+
client) access to your **[Bring!](https://www.getbring.com)** shopping lists.
|
|
35
|
+
|
|
36
|
+
- **Lists**: read, add (with quantities), update, check off and remove items.
|
|
37
|
+
Names are matched against the Bring catalog, so items get their section and icon.
|
|
38
|
+
- **Recipes**: extract the ingredients of a recipe page with Bring's own parser,
|
|
39
|
+
then add them in one go.
|
|
40
|
+
- **Staples**: keep a list of items you buy every week and add the missing ones,
|
|
41
|
+
from Claude or from cron (no LLM involved).
|
|
42
|
+
- Runs **locally** for Claude Desktop (stdio), or **remotely** as a claude.ai
|
|
43
|
+
custom connector (streamable HTTP + OAuth).
|
|
44
|
+
|
|
45
|
+
> Unofficial project, not affiliated with or endorsed by Bring! Labs AG. It uses
|
|
46
|
+
> [bring-api](https://github.com/miaucl/bring-api), an unofficial client of the
|
|
47
|
+
> Bring! API, which may change without notice.
|
|
48
|
+
|
|
49
|
+
## Why this one
|
|
50
|
+
|
|
51
|
+
Other Bring! MCP servers map the API call by call (load list, save item, remove
|
|
52
|
+
item...). This one gives the model tools shaped like the tasks you ask for:
|
|
53
|
+
|
|
54
|
+
- **"Add what I need for this recipe"**: Bring's own recipe parser extracts the
|
|
55
|
+
ingredients of a page in your list's language, and flags pantry items (salt,
|
|
56
|
+
oil) so the model can ask before adding them.
|
|
57
|
+
- **"Add 2 more litres of milk"**: an item already on the list gets its quantity
|
|
58
|
+
merged instead of replaced, and names are matched against the Bring catalog
|
|
59
|
+
(case, accents, simple plurals), so items land in the right section with their icon.
|
|
60
|
+
- **Weekly staples**: keep the list of things you always buy and add the missing
|
|
61
|
+
ones in one call, or from cron without any LLM.
|
|
62
|
+
- **Works in claude.ai on the web and on your phone**, not only in Claude Desktop:
|
|
63
|
+
a remote mode with OAuth, Docker and reverse-proxy configs, and a full
|
|
64
|
+
[deployment guide](https://github.com/vdeabreu/bring-mcp/blob/main/docs/deploy.md).
|
|
65
|
+
|
|
66
|
+
## Tools
|
|
67
|
+
|
|
68
|
+
| Tool | What it does |
|
|
69
|
+
| --- | --- |
|
|
70
|
+
| `list_lists` | Names of your Bring lists. |
|
|
71
|
+
| `get_list` | Items to buy and recently bought items. |
|
|
72
|
+
| `add_items` | Add items with an optional spec (`"6"`, `"500 g"`, `"organic"`). An item already on the list gets its spec merged (`1 L + 2 L`). |
|
|
73
|
+
| `update_item` | Replace the spec of an item. |
|
|
74
|
+
| `complete_items` | Check items off (they move to "recently bought"). |
|
|
75
|
+
| `remove_items` | Remove items. |
|
|
76
|
+
| `fetch_recipe` | Ingredients of a recipe URL, in the list's language, with a `pantry` flag (salt, oil...). Adds nothing by itself. |
|
|
77
|
+
| `get_staples_list` / `set_staples_list` | Read or replace your staples. |
|
|
78
|
+
| `add_staples` | Add the staples that aren't on the list yet. |
|
|
79
|
+
|
|
80
|
+
Every tool takes an optional `list` (name, case-insensitive); without it, the
|
|
81
|
+
server uses `BRING_DEFAULT_LIST`, or your first list.
|
|
82
|
+
|
|
83
|
+
Prompts: `add_recipe`, `clean_up_list`, `weekly_shopping`.
|
|
84
|
+
|
|
85
|
+
## Local setup (Claude Desktop)
|
|
86
|
+
|
|
87
|
+
Requirements: [uv](https://docs.astral.sh/uv/) (or Python 3.12+) and a Bring!
|
|
88
|
+
account that signs in with an email and password (if you use Google or Apple
|
|
89
|
+
sign-in, set a password in the Bring app).
|
|
90
|
+
|
|
91
|
+
Add the server to `claude_desktop_config.json`. Open it from Claude Desktop →
|
|
92
|
+
Settings → Developer → Edit Config, or directly:
|
|
93
|
+
|
|
94
|
+
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
95
|
+
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
96
|
+
- Linux: `~/.config/Claude/claude_desktop_config.json`
|
|
97
|
+
|
|
98
|
+
```json
|
|
99
|
+
{
|
|
100
|
+
"mcpServers": {
|
|
101
|
+
"bring": {
|
|
102
|
+
"command": "uvx",
|
|
103
|
+
"args": ["bring-mcp"],
|
|
104
|
+
"env": {
|
|
105
|
+
"BRING_EMAIL": "you@example.com",
|
|
106
|
+
"BRING_PASSWORD": "your-bring-password",
|
|
107
|
+
"BRING_DEFAULT_LIST": "Shopping"
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Fully quit and restart Claude Desktop after editing the file.
|
|
115
|
+
|
|
116
|
+
Without uv: `pip install bring-mcp`, then use `"command": "bring-mcp"` (the full
|
|
117
|
+
path to that script if it isn't on your `PATH`) and no `args`.
|
|
118
|
+
|
|
119
|
+
### Configuration
|
|
120
|
+
|
|
121
|
+
| Variable | Default | |
|
|
122
|
+
| --- | --- | --- |
|
|
123
|
+
| `BRING_EMAIL` | (required) | Bring account email |
|
|
124
|
+
| `BRING_PASSWORD` | (required) | Bring account password |
|
|
125
|
+
| `BRING_DEFAULT_LIST` | *(first list)* | List used when a tool gets no `list` |
|
|
126
|
+
| `DATA_DIR` | `~/.bring-mcp` | Where the SQLite file (staples, and OAuth tokens in remote mode) is kept |
|
|
127
|
+
|
|
128
|
+
The config file holds your Bring password: keep it readable by you only.
|
|
129
|
+
|
|
130
|
+
## Remote setup (claude.ai connector)
|
|
131
|
+
|
|
132
|
+
`python -m bring_mcp.server` (or `bring-mcp-remote`) serves the same tools over
|
|
133
|
+
streamable HTTP, behind a single-user OAuth password page, for claude.ai on the
|
|
134
|
+
web and mobile. A Dockerfile and compose file are included, plus Apache and Caddy
|
|
135
|
+
configs that only let Anthropic's IP ranges reach `/mcp`.
|
|
136
|
+
|
|
137
|
+
See **[docs/deploy.md](https://github.com/vdeabreu/bring-mcp/blob/main/docs/deploy.md)** for the full guide (Docker, reverse
|
|
138
|
+
proxy, claude.ai, weekly staples).
|
|
139
|
+
|
|
140
|
+
## Security
|
|
141
|
+
|
|
142
|
+
- **What's at stake.** Your Bring password gives full access to your Bring
|
|
143
|
+
account; this server can read and change your lists. It has no tool to
|
|
144
|
+
delete lists, change account settings or invite people.
|
|
145
|
+
- **Recipe pages are untrusted.** `fetch_recipe` asks Bring's servers to parse the
|
|
146
|
+
page (this server never downloads it) and returns only ingredient names and
|
|
147
|
+
quantities. The server instructions still tell the model not to follow text
|
|
148
|
+
found there. Only `http(s)` URLs are accepted.
|
|
149
|
+
- **Inputs are bounded.** Item names and specs are single-line and length-limited,
|
|
150
|
+
and a call handles at most 100 items. `remove_items` and `set_staples_list` carry
|
|
151
|
+
the MCP `destructiveHint`, so clients can ask before running them.
|
|
152
|
+
- **Remote mode**:
|
|
153
|
+
- OAuth with a 20+ character password, a lockout after 5 failures, and tokens
|
|
154
|
+
stored in SQLite.
|
|
155
|
+
- Only claude.ai's callback can be registered as redirect URI, and the number of
|
|
156
|
+
clients is capped.
|
|
157
|
+
- The password page says which client asks and can't be framed by another site.
|
|
158
|
+
- `/mcp` is restricted to Anthropic's outbound IPs by the reverse proxy.
|
|
159
|
+
- The server refuses to listen on a public address, every tool call is logged,
|
|
160
|
+
and the container is read-only and unprivileged.
|
|
161
|
+
- **Remote mode, known limits:**
|
|
162
|
+
- The lockout is global: anyone can make *new* logins wait 15 minutes by failing
|
|
163
|
+
5 times. Tokens already issued keep working.
|
|
164
|
+
- Anyone can add your server URL as a connector in *their own* claude.ai account
|
|
165
|
+
and send you the resulting authorization link. If you type your password, their
|
|
166
|
+
account gets access. Only type it right after clicking *Connect* yourself.
|
|
167
|
+
|
|
168
|
+
Keep `.env` and `claude_desktop_config.json` private. To report a vulnerability,
|
|
169
|
+
see [SECURITY.md](https://github.com/vdeabreu/bring-mcp/blob/main/SECURITY.md).
|
|
170
|
+
|
|
171
|
+
## Limitations
|
|
172
|
+
|
|
173
|
+
- Catalog matching relies on bring-api's translation tables, read through private
|
|
174
|
+
attributes; bring-api is pinned for that reason.
|
|
175
|
+
- Name matching ignores case, accents and a final `s`/`x`; it doesn't know other
|
|
176
|
+
plurals or synonyms.
|
|
177
|
+
- Item photos, list sharing, notifications and loyalty cards are not supported.
|
|
178
|
+
|
|
179
|
+
## Development
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
git clone https://github.com/vdeabreu/bring-mcp && cd bring-mcp
|
|
183
|
+
pip install -e ".[dev]"
|
|
184
|
+
pytest
|
|
185
|
+
ruff check .
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Tests don't need a Bring account: they cover the tools against a fake list
|
|
189
|
+
(merging, catalog names, list lookup, staples), input validation, re-login after
|
|
190
|
+
an expired session, and the OAuth flow (redirect allowlist, client cap, lockout,
|
|
191
|
+
security headers, startup checks).
|
|
192
|
+
|
|
193
|
+
## License
|
|
194
|
+
|
|
195
|
+
[MIT](https://github.com/vdeabreu/bring-mcp/blob/main/LICENSE)
|