clover-mcp 0.1.1__tar.gz

clover_mcp-0.1.1/.env.example

@@ -0,0 +1,24 @@
+# ── Required ─────────────────────────────────────────────────────────────────
+CLOVER_MERCHANT_ID=your_merchant_id_here
+CLOVER_ACCESS_TOKEN=your_access_token_here
+
+# ── Region (na | eu | la) — default: na ──────────────────────────────────────
+CLOVER_REGION=na
+
+# ── Sandbox mode (true | false) — default: false ─────────────────────────────
+# Set true to use apisandbox.dev.clover.com instead of production
+CLOVER_SANDBOX=false
+
+# ── Auth mode (token | oauth_refresh) — default: token ───────────────────────
+# token       → static access token; operator regenerates manually when it expires
+# oauth_refresh → server auto-refreshes using OAuth refresh token (v1 production)
+CLOVER_AUTH_MODE=token
+
+# ── OAuth refresh fields (required only when AUTH_MODE=oauth_refresh) ─────────
+# CLOVER_REFRESH_TOKEN=your_refresh_token
+# CLOVER_OAUTH_CLIENT_ID=your_oauth_client_id
+# CLOVER_OAUTH_CLIENT_SECRET=your_oauth_client_secret
+
+# ── Token store path (oauth_refresh mode only) ────────────────────────────────
+# Default: ~/.config/clover-mcp/tokens.json (created with 0600 permissions)
+# CLOVER_TOKEN_STORE=~/.config/clover-mcp/tokens.json

clover_mcp-0.1.1/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default owner for everything — required reviewer on protected branches.
+* @SBolivarLoL

clover_mcp-0.1.1/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  # Python dependencies (pyproject.toml)
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      python-deps:
+        patterns: ["*"]
+
+  # GitHub Actions — keeps SHA-pinned actions current
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      actions:
+        patterns: ["*"]

clover_mcp-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Create virtual environment
+        run: uv venv --python ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: uv run ruff check src/ tests/
+
+      - name: Format check (ruff)
+        run: uv run ruff format --check src/ tests/
+
+      - name: Type check (mypy)
+        run: uv run mypy src/clover_mcp/
+
+      - name: Test (pytest)
+        run: uv run pytest tests/ -v --tb=short

clover_mcp-0.1.1/.github/workflows/codeql.yml

@@ -0,0 +1,31 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1" # weekly, Monday 06:00 UTC
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: Analyze (python)
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write # upload CodeQL results
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@dd903d2e4f5405488e5ef1422510ee31c8b32357 # v3
+        with:
+          languages: python
+          queries: security-extended
+
+      - name: Perform CodeQL analysis
+        uses: github/codeql-action/analyze@dd903d2e4f5405488e5ef1422510ee31c8b32357 # v3

clover_mcp-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+# Tag-triggered. Push a vX.Y.Z tag to build artifacts, create a GitHub Release,
+# and publish to PyPI via trusted publishing (OIDC — no token stored in the repo).
+# PyPI publish requires a one-time "trusted publisher" setup on PyPI for this
+# repo + workflow. See RELEASING.md.
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write # create the GitHub Release
+  id-token: write # PyPI trusted publishing (OIDC)
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
+
+      - name: Verify tag matches package version
+        run: |
+          PKG=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          TAG="${GITHUB_REF_NAME#v}"
+          if [ "$PKG" != "$TAG" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match pyproject version $PKG" >&2
+            exit 1
+          fi
+          echo "Releasing version $PKG"
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2
+        with:
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+          generate_release_notes: true
+          fail_on_unmatched_files: true
+
+      # Requires a PyPI trusted publisher configured for this repo + workflow.
+      # Until that's set up this step fails without affecting the GitHub Release above.
+      - name: Publish to PyPI (trusted publishing)
+        run: uv publish

clover_mcp-0.1.1/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*.egg
+
+# uv
+.uv/
+uv.lock
+
+# env / secrets
+.env
+.env.*
+!.env.example
+*.json
+!docs/*.json
+
+# token store
+~/.config/clover-mcp/
+
+# test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db

clover_mcp-0.1.1/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.1] — unreleased
+### Added
+- Legal & disclaimer section: nominative trademark / not-affiliated notice,
+  AS-IS no-warranty statement, and operator responsibilities (Clover terms,
+  data-protection, least-privilege tokens).
+- PyPI publishing from the release workflow via trusted publishing (OIDC).
+### Fixed
+- Release workflow attaches only the wheel + sdist (glob narrowed from `dist/*`).
+
+## [0.1.0] — 2026-06-21 (GitHub release)
+### Added
+- 11 read tools: `get_merchant_info`, `get_sales_summary`, `list_payments`,
+  `list_orders`, `get_order`, `list_open_orders`, `list_items`, `get_item`,
+  `list_low_stock_items`, `search_customers`, `get_customer`.
+- 3 safe write tools: `create_customer` (idempotency dup-check, `dry_run`),
+  `set_item_price_cents`, `set_item_stock_quantity` (optimistic-lock pre-check,
+  bounds, `dry_run`, absolute set — not a delta).
+- Two auth modes: static `token` and `oauth_refresh` (single-use refresh-token
+  rotation, 0600 token store, refresh-on-401).
+- MCP tool annotations (`readOnlyHint` / `destructiveHint` / `idempotentHint` /
+  `openWorldHint`) on all 14 tools.
+- Allowlist response shaping (no card / PII / PIN leakage), 90-day windowing,
+  currency-aware money formatting, startup permission self-check.
+- Sandbox-verified endpoint audit ([docs/endpoints.md](docs/endpoints.md)).
+
+### Out of scope (by design)
+- Refunds, voids, payment capture, charge creation, record deletes.
+- Employee/shift tools (planned v1.1), multi-merchant hosted mode + MCP-level
+  OAuth 2.1 (planned v2).
+
+[Unreleased]: https://github.com/SBolivarLoL/clover-mcp-server/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/SBolivarLoL/clover-mcp-server/releases/tag/v0.1.0

clover_mcp-0.1.1/CLAUDE.md

@@ -0,0 +1,112 @@
+# CLAUDE.md — Development Guidelines for clover-mcp
+
+This file defines the coding principles and best practices that every contributor (human or AI) must follow in this project.
+
+---
+
+## Principles
+
+### 1. KISS — Keep It Simple, Stupid
+
+Prefer the simplest solution that correctly solves the problem. Complexity is a liability.
+
+- A new function should do one thing and do it clearly.
+- If you find yourself explaining what a block of code does, simplify it first.
+- Avoid abstractions until they are earned by repetition (see DRY below). A premature abstraction is worse than a copy.
+- When two implementations both work, the shorter one wins — unless clarity suffers.
+
+**Applied here:** `resolve_base_url()` in `config.py` is a single dict lookup, not a class hierarchy. `_pick()` in `shaping.py` is three lines. Keep new helpers at that level.
+
+---
+
+### 2. DRY — Don't Repeat Yourself
+
+Every piece of knowledge has a single authoritative home. Duplication is the root of maintenance bugs.
+
+- If the same logic appears in two tools, extract a shared helper in `src/clover_mcp/` (formatting, shaping, windowing, etc.).
+- Region → base-URL mapping lives **only** in `config.resolve_base_url()`. Never hardcode a hostname elsewhere.
+- Allowlist field names live **only** in `shaping.py`. Never re-list them in a tool or a test.
+- Shared test fixtures live **only** in `tests/conftest.py`.
+
+**Red flag:** if you copy-paste a block and change one variable, that is a signal to parameterise, not to paste.
+
+---
+
+### 3. SOLID Principles — The Core of OOP
+
+Applied pragmatically to this Python/async codebase:
+
+| Principle | What it means here |
+|---|---|
+| **S** — Single Responsibility | Each module has one job: `config.py` loads config, `client.py` sends HTTP, `shaping.py` projects responses, `windowing.py` splits date ranges. Don't blur those lines. |
+| **O** — Open/Closed | Add new Clover resources by adding a new file under `tools/` and registering it in `server.py`. Do not modify `client.py` or `shaping.py` to accommodate a specific tool's quirks. |
+| **L** — Liskov Substitution | Not deeply relevant in a mostly-functional codebase, but: if you subclass `CloverClient`, the subclass must be a drop-in replacement — do not weaken the contract. |
+| **I** — Interface Segregation | Keep tool signatures narrow. A tool that only reads inventory should not accept payment-related parameters. Pass only what is needed. |
+| **D** — Dependency Inversion | Tools depend on `CloverClient` (the abstraction), not on `httpx` directly. Tests inject a mock-backed client — not the real network. Never import `httpx` inside a tool file. |
+
+---
+
+### 4. Separation of Concerns (SoC)
+
+Each layer of the stack is responsible for exactly one concern. Do not let concerns leak across layers.
+
+| Layer | Its concern | Must NOT do |
+|---|---|---|
+| `config.py` | Read env, validate, resolve URLs | Make HTTP calls |
+| `auth.py` | Token lifecycle, file storage, refresh | Business logic |
+| `client.py` | HTTP transport, retries, pagination | Know about Clover resources |
+| `shaping.py` | Allowlist projection, PII removal | Know about tools or auth |
+| `windowing.py` | Date chunking, ms conversion | Know about HTTP or tools |
+| `formatting.py` | Money and time display | Know about the API |
+| `tools/*.py` | Orchestrate a user-facing action | Duplicate HTTP logic or shaping |
+| `server.py` | Register tools with FastMCP, run | Implement business logic directly |
+| `tests/` | Verify behaviour | Call real network or read `.env` |
+
+If you find yourself importing `httpx` in a tool file, or importing `fastmcp` in `client.py`, that is a SoC violation — stop and refactor.
+
+---
+
+## Best Practices
+
+### 1. Write Clean and Readable Code
+
+- **Name things after what they are**, not what they do to get there. `shape_customer()` not `strip_and_flatten_customer_dict()`.
+- **No abbreviations** beyond universally understood ones (`id`, `ts`, `ms`, `mId`). Write `merchant_id`, not `mid` or `m`.
+- **One concept per line.** Avoid chaining more than two method calls on a single expression.
+- **No magic numbers.** `max_days=90`, `MAX_PRICE_CENTS = 100_000_000` — name every constant.
+- **Comments explain WHY, not WHAT.** The code says what; a comment earns its place only when the reasoning is non-obvious (e.g. "Clover returns 200 with empty body on some PUTs").
+- **Keep functions short.** If a function doesn't fit on one screen, it has more than one responsibility.
+
+---
+
+### 2. Follow Design Principles & Architecture
+
+- **Module boundaries are real.** Before adding code to a file, ask: is this the right module? Resist the urge to add a "quick fix" in the wrong layer.
+- **The endpoint audit gate is a design constraint.** No tool ships until its endpoint row in `docs/endpoints.md` is verified against the Clover sandbox. Do not skip this.
+- **Write tools as thin orchestrators.** A tool function should: validate inputs → call `client.*` → run output through the appropriate `shaping.*` function → return a clean dict. Nothing more.
+- **No global mutable state** beyond the module-level `_client` in `server.py` and the asyncio lock in `auth.py`. Both are intentional and documented.
+- **Async all the way down.** All I/O — HTTP calls, file reads in `auth.py` — must be non-blocking. Do not call `open()` or `requests` in an `async def` function.
+- **Write tools is a privilege, not a default.** Any new write tool must have: explicit ID parameter, expected-current-value pre-check, `dry_run` support, input bounds, and a description that starts with "Modifies merchant data."
+
+---
+
+### 3. Always Do Testing
+
+- **Every tool gets a test file** in `tests/tools/test_<tool_name>.py` with at minimum: one happy-path test and one error-path test (rotate through 401, 403, 404, 429).
+- **Contract tests are first-class.** `tests/contract/` tests cover the guarantees that would silently break if a module drifts: region resolution, window splitting, shaping allowlist (PII/card/PIN leak prevention), money formatting.
+- **Use `respx` to mock `httpx`.** Tests must never make real network calls. Use `conftest.py` fixtures — do not re-create the mock router in each test.
+- **The allowlist test is a security gate.** `test_shaping_allowlist.py` must pass before any shaping change merges. Add new banned field names to `BANNED_KEYS` whenever a new sensitive Clover field is discovered.
+- **Coverage floors:** `client.py`, `auth.py`, `windowing.py`, `formatting.py`, `shaping.py`, `config.py` ≥ 85%; tool modules ≥ 60%.
+- **CI must be green before merging** — ruff lint, ruff format, mypy strict (on core modules), and pytest.
+
+---
+
+### 4. Validate User Input and Implement Graceful Error Handling
+
+- **Validate at the boundary.** Tool parameters are the system boundary. Validate there — not inside `client.py` or `shaping.py`.
+- **Fail fast and loudly on config errors.** `load_config()` raises a `RuntimeError` listing every missing variable before the server starts. Never silently default a required value.
+- **Surface Clover errors verbatim.** Do not paraphrase a 403 or 404 — pass through Clover's original message so the operator can act on it.
+- **Write tools require pre-checks.** Before any `PUT` or `POST`, verify the current state matches what the caller expects (`expected_current_price_cents`, `expected_current_quantity`). Fail with a diff, not silently.
+- **Never retry non-idempotent writes on 5xx.** A retry on a `PUT /items/{id}` or `POST /customers` may duplicate the action. Reads get one retry; writes surface the error immediately.
+- **Bound all numeric inputs.** Price: `0 ≤ price_cents ≤ 100_000_000`. Stock: `0 ≤ quantity ≤ 1_000_000`. Reject out-of-range values before the HTTP call.
+- **Log to stderr only.** The stdio MCP transport uses stdout for the protocol. Any print or logging must go to stderr. Never log token values, customer PII, or card data.

clover_mcp-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikel Diaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clover_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: clover-mcp
+Version: 0.1.1
+Summary: MCP server for the Clover POS REST API — sales, inventory, orders, customers, and employees for small businesses
+Author-email: Mikel Diaz <mikeldev62@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,anthropic,clover,mcp,pos,small-business
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# clover-mcp
+
+MCP server for the Clover POS REST API — gives AI assistants (Claude, Cursor, etc.) read and safe-write access to a Clover merchant's sales, inventory, orders, and customers.
+
+> **Status:** v1 candidate — 14 tools, both auth modes, 152 tests. Single-merchant, local (stdio). See [docs/endpoints.md](docs/endpoints.md) for the sandbox-verified endpoint contracts.
+
+> ⚠️ **Independent project — not affiliated with, endorsed by, or sponsored by Clover Network, LLC or Fiserv, Inc.** "Clover" is a trademark of its respective owner and is used here only nominatively to describe interoperability. Provided **as is**, without warranty — see [Legal & disclaimer](#legal--disclaimer).
+
+## What it can do
+
+- Sales summaries and payment reports
+- Inventory lookups and low-stock alerts
+- Order history and open-order inspection
+- Customer search and creation
+- Safe writes: update item prices, set stock quantities, create customers
+
+**What it cannot do (by design):** process refunds, capture payments, void charges, delete records. Those stay in the Clover dashboard. Employee/shift reporting and a multi-merchant hosted mode are planned (v1.1 / v2).
+
+## Tools
+
+| Tool | Kind | Notes |
+|---|---|---|
+| `get_merchant_info` | read | name, currency, timezone, country |
+| `get_sales_summary` | read | aggregated window (see [Sales summary semantics](#sales-summary-semantics)) |
+| `list_payments` | read | SUCCESS payments in a window |
+| `list_orders` / `get_order` / `list_open_orders` | read | order history + detail |
+| `list_items` / `get_item` / `list_low_stock_items` | read | inventory + stock |
+| `search_customers` / `get_customer` | read | cards never returned |
+| `create_customer` | write | additive; idempotency dup-check + `dry_run` |
+| `set_item_price_cents` | write | optimistic-lock pre-check, bounds, `dry_run` |
+| `set_item_stock_quantity` | write | absolute (not delta), pre-check, `dry_run` |
+
+Every tool carries MCP behaviour annotations (`readOnlyHint` / `destructiveHint` / `idempotentHint`) so clients can parallelize reads and prompt before writes.
+
+## Install
+
+```bash
+uvx clover-mcp   # coming soon after PyPI publish
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/SBolivarLoL/clover-mcp-server
+cd clover-mcp-server
+uv pip install -e .
+```
+
+## Configuration
+
+Copy `.env.example` to `.env` and fill in your values:
+
+```bash
+cp .env.example .env
+```
+
+Required:
+
+| Variable | Description |
+|---|---|
+| `CLOVER_MERCHANT_ID` | Your Clover merchant ID |
+| `CLOVER_ACCESS_TOKEN` | Your Clover API access token |
+
+Optional:
+
+| Variable | Default | Description |
+|---|---|---|
+| `CLOVER_REGION` | `na` | `na`, `eu`, or `la` |
+| `CLOVER_SANDBOX` | `false` | `true` to use the Clover sandbox |
+| `CLOVER_AUTH_MODE` | `token` | `token` or `oauth_refresh` |
+
+### Auth modes
+
+- **`token`** — paste a static access token. Works for sandbox and single-merchant production use. If the token expires, regenerate it in the Clover Developer Dashboard.
+- **`oauth_refresh`** — supply a refresh token + OAuth client credentials; the server auto-refreshes on expiry and persists the new token pair to `CLOVER_TOKEN_STORE` (default: `~/.config/clover-mcp/tokens.json`, mode 0600). Clover refresh tokens are single-use, so the rotated pair is written back after each refresh.
+
+> **Use a least-privilege token.** Grant only the permission scopes the tools you actually use require (see the table below). A read-only deployment needs no `*_W` scopes at all. Don't reuse a production token in sandbox or vice versa.
+
+## Claude Desktop setup
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "clover": {
+      "command": "uvx",
+      "args": ["clover-mcp"],
+      "env": {
+        "CLOVER_MERCHANT_ID": "your_merchant_id",
+        "CLOVER_ACCESS_TOKEN": "your_token",
+        "CLOVER_REGION": "na"
+      }
+    }
+  }
+}
+```
+
+## Cursor setup
+
+Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):
+
+```json
+{
+  "mcpServers": {
+    "clover": {
+      "command": "uvx",
+      "args": ["clover-mcp"],
+      "env": {
+        "CLOVER_MERCHANT_ID": "your_merchant_id",
+        "CLOVER_ACCESS_TOKEN": "your_token"
+      }
+    }
+  }
+}
+```
+
+## Required Clover permissions
+
+Your token must have the following Clover permission scopes:
+
+| Permission | Used by |
+|---|---|
+| `MERCHANT_R` | `get_merchant_info` |
+| `ORDERS_R` | `list_orders`, `get_order`, `list_open_orders`, `get_sales_summary` |
+| `PAYMENTS_R` | `list_payments`, `get_sales_summary` |
+| `INVENTORY_R` | `list_items`, `get_item`, `list_low_stock_items` |
+| `INVENTORY_W` | `set_item_price_cents`, `set_item_stock_quantity` |
+| `CUSTOMERS_R` | `search_customers`, `get_customer` |
+| `CUSTOMERS_W` | `create_customer` |
+
+Read scopes (`*_R`) are probed at startup; the server reports any missing ones and exits. Write scopes (`*_W`) are **not** probed (a probe would mutate data) — a missing write scope surfaces as a 403 the first time you call that tool. Permission changes on a Clover app require the merchant to reinstall the app.
+
+## Sales summary semantics
+
+`get_sales_summary` makes the accounting explicit so the LLM can explain it:
+
+- **Gross** = sum of `result=SUCCESS` payment amounts. `FAIL`/`AUTH`/uncaptured `PRE_AUTH` are excluded.
+- **Voids and refunds are reported separately** (`void_count`, `refund_count`, `refund_amount`) — never silently netted into `payment_count`.
+- **Tips and taxes** are broken out as their own line items.
+- **Service charges** are summed from orders (Clover does not expose them on payments) and reported as `service_charges_collected` — requires `ORDERS_R`.
+- **Offline payments** are included; a `note` flags the window when any are present.
+- **Currency** comes from the merchant record, never defaulted.
+- Windows longer than 90 days are split and concatenated transparently.
+
+## Development
+
+```bash
+uv pip install -e ".[dev]"
+pytest
+ruff check src/
+mypy src/clover_mcp/
+```
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for the vulnerability disclosure policy.
+
+## Legal & disclaimer
+
+> This is not legal advice. The notes below describe the project's intent and the
+> operator's responsibilities.
+
+- **Not affiliated.** This is an independent, community project. It is **not**
+  affiliated with, endorsed by, or sponsored by Clover Network, LLC or Fiserv, Inc.
+  "Clover" and related marks are trademarks of their respective owners and are used
+  here only **nominatively** — to state that this software interoperates with the
+  Clover REST API. No Clover logos or branding are used.
+- **No warranty / no liability.** The software is provided **"AS IS"** under the
+  [MIT License](LICENSE), without warranty of any kind. The authors are not liable
+  for any claim, damage, or loss arising from its use — including incorrect data,
+  unintended writes, downtime, or API changes outside the authors' control.
+- **You operate it; you're responsible.** You run this server with **your own**
+  Clover account and API credentials. You are solely responsible for: complying
+  with Clover's developer/API terms and trademark-usage policy; safeguarding your
+  tokens; and meeting any data-protection (e.g. GDPR/CCPA) and tax obligations for
+  data you access. The write tools **modify live merchant data** — test in the
+  sandbox first and use least-privilege tokens.
+- **No card data, no payments.** The server never handles payment card data (the
+  shaping layer blocks it) and deliberately cannot capture payments, refund, or
+  void. It is **not** a PCI-DSS solution.
+- **Third-party API.** This project only calls Clover's public REST API using the
+  operator's credentials; it bundles no Clover SDK or proprietary code. Clover may
+  change or restrict its API at any time, which may break functionality.
+
+## License
+
+MIT — see [LICENSE](LICENSE).