Metadata-Version: 2.4
Name: und-mcp
Version: 0.2.0
Summary: A small local MCP wrapper exposing the und public API (/api/v1) as Claude tools.
Author: Up Next Data
License: MIT
Project-URL: Homepage, https://www.upnextdata.com
Keywords: mcp,und,api
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp==2.3.0
Requires-Dist: httpx==0.28.1
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Dynamic: license-file

# und-mcp

A small, local **Model Context Protocol (MCP)** wrapper that exposes the **und
public API** as tools you can call from **Claude Desktop** or **Claude Code**.

It runs **on your machine** over **stdio**. It holds **your** API key, makes
**read-only** `GET` calls to the und public API, and returns the results to
Claude. It contains no business logic beyond mapping each named tool to a single
API request.

## What it does

The wrapper exposes two tools:

| Tool | What it returns |
|------|-----------------|
| `run_test(limit, offset)` | Your key's identity plus a project-scoped sample of `und_master_summary` rows (filtered to your key's project). Use it to confirm your key works and to see exactly what your key's project can read. |
| `download_all_in_one(start_date, end_date)` | Downloads the all-in-one sales CSV for an inclusive date range to a local file (default ~/Downloads/und-mcp) and returns the path, size, and line count. The CSV body is never returned to Claude; read the file to inspect it. |

`run_test` maps to `GET {UND_API_URL}/api/v1/test`. The `/test` endpoint
returns a **project-scoped sample of `und_master_summary`** — specifically,
`und_master_summary` rows filtered by your key's project name (its `vendor`
field). Keys are project-scoped, **including `rep` projects**: a `rep` key does
**not** automatically reach the vendors it is associated with, so it may return
no rows. The `limit` argument is capped at 200 server-side; `offset` paginates
the sample.

`download_all_in_one` maps to `GET {UND_API_URL}/api/v1/all_in_one` with
`start_date` and `end_date` query parameters: both are inclusive ISO dates in
`YYYY-MM-DD` form. A malformed date, a reversed range (`end_date` before
`start_date`), and any non-ISO form are rejected locally **before** any request
goes out. The maximum range width is enforced server-side (it is configurable
there), and a too-wide range comes back as a sanitized 422 hint rather than a
raw server message. The response is streamed straight to disk as it arrives,
so large ranges are safe — the CSV body is never buffered in memory and never
returned as tool content. The filename is derived only from the validated
dates, and an existing file is never overwritten (a `-1`, `-2`, ... suffix is
added instead); the summary returned to Claude is the file path plus its byte
and line counts.

More data tools will be added in a later release as the API grows.

## API documentation (for clients and AI tools)

The API publishes an **auto-generated OpenAPI spec** at
`{UND_API_URL}/api/v1/docs/openapi.json` (public, no key required; Swagger UI
at `/api/v1/docs/ui`, ReDoc at `/api/v1/docs/redoc`). The spec is generated
from the server code, so it is the **single source of truth** for the
endpoints, their query parameters (including the `limit`/`offset` pagination
contract), and the request/response schemas. **Clients and AI tools should
consume that document** to learn the API's shapes instead of guessing or
relying on prose documentation: fetch it at `{UND_API_URL}/api/v1/docs/openapi.json`,
and treat the error envelope there (`{"error", "status"}` with fixed
server-defined messages) as the complete set of error responses.

## Prerequisites

- **Python 3.11+**
- An **und API key** (`und_...`) scoped to your project — **vendor or
  `rep`**. **Ask the und team to issue one for you.** Keys are project-scoped:
  the API only ever returns data your key's project is authorized to read.
- The **confirmed und API host** (the base URL, e.g. an `https://...` host).
  **Ask the und team for the confirmed HTTPS host** and set it via
  `UND_API_URL` or `config.toml` **before using a real key** — the wrapper has
  **no default host** and will not start on a key alone.

## Quickstart (no Python experience needed)

This path is for **non-technical clients** — it needs **no Python knowledge**
and no pre-existing Python setup. The `uv` tool installs and runs the wrapper
for you, so you can skip straight to configuring Claude.

**1. Install [uv](https://docs.astral.sh/uv/)** with the official one-liner
for your platform:

macOS / Linux:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Windows (PowerShell):

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**2. Configure Claude Desktop.** Edit
`claude_desktop_config.json` (on macOS:
`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "und": {
      "command": "uvx",
      "args": ["und-mcp"],
      "env": {
        "UND_API_URL": "https://api.example.com",
        "UND_API_KEY": "und_..."
      }
    }
  }
}
```

Both values are **required** — a key without `UND_API_URL` will not start the
server. The `UND_API_URL` value above is an obvious **placeholder**
(`api.example.com` is a reserved domain, **not** a live host) — **obtain the
confirmed und API host from the und team and replace the placeholder before
using a real key**.

**3. Restart Claude Desktop.** You'll see the `und` server and its
`run_test` and `download_all_in_one` tools available.

You never install `und-mcp` yourself in this path: when Claude Desktop starts
the server, `uvx` **automatically downloads `und-mcp` from PyPI** into an
isolated, **cached** environment and runs it. The **first start is slower and
needs internet**; later starts **reuse the local cache**.

If the `und` server does not appear after restart, Claude Desktop may not find
the `uvx` command — **GUI apps do not inherit your shell `PATH`**. Run
`which uvx` in a terminal and use the **printed absolute path** as the
`"command"` value in the config above.

## Installation

Two supported paths install the `und-mcp` command (both pin `mcp==2.3.0` +
`httpx==0.28.1`):

**Recommended — install with `pipx`:**

```bash
pipx install und-mcp
```

(`pipx` needs a **Python 3.11+** interpreter available to it — see
Prerequisites.)

**Zero-install — run with `uvx`:**

```bash
uvx und-mcp
```

To run a newly published version, use `uvx und-mcp@latest` — plain `uvx und-mcp` reuses uv's cached environment (`pipx` users instead run `pipx upgrade und-mcp`).

`uvx` fetches and runs the wrapper on demand, installing nothing permanent
(it is what the Quickstart uses via Claude Desktop's `args`).

### Installing from source

If you **already have a repo checkout** of this project (contributors), you
can instead install from source as a fallback:

```bash
# from this directory
pip install .
```

## Configuration

Provide **both** your key **and** your API base URL — the URL is **required
and has no default**, so a key alone will not start the wrapper; the download
directory (below) is **optional** and has a default. Two ways (values may also
be mixed: any value that is missing or blank in the environment is read from
the file):

**Environment variables**:

- `UND_API_KEY` — **required.** Your `und_...` key.
- `UND_API_URL` — **required** (and nonblank, well-formed). The confirmed und
  API host: an `https://` URL (a normal URL path is fine). For **local
  testing only**, `http://` is accepted **only** for loopback hosts
  (`http://localhost[:PORT]`, `http://127.0.0.1[:PORT]`, `http://[::1][:PORT]`).
  Non-loopback `http://`, other schemes, embedded `user:pass@` credentials,
  and malformed hosts or ports are rejected with a clear error **before** the
  server starts or any request goes out.
- `UND_MCP_DOWNLOAD_DIR` — **optional.** The absolute directory downloaded
  CSVs are written to. Defaults to `~/Downloads/und-mcp` and is created on
  first use. It must be an absolute path — a relative path is rejected with a
  clear error **before** the server starts.

**Deliberately unsupported URL forms** — three valid-but-unusual URLs are
rejected by design (safe over-strictness: rejected before the server starts,
with the same clear error that never echoes the URL): trailing-dot FQDNs (`https://api.example.com.`), expanded or
zero-compressed IPv6 loopback
literals other than `[::1]` (e.g. `http://[0:0:0:0:0:0:0:1]`), and
IPv4-mapped IPv6 hosts (`https://[::ffff:127.0.0.1]`). A raw space inside the
URL path **is** accepted — the HTTP client percent-encodes it.

**Or a config file** at `~/.config/und-mcp/config.toml`:

```toml
api_url = "https://api.example.com"   # required; PLACEHOLDER -- replace with the confirmed host before use
api_key = "und_..."                   # required
download_dir = "/Users/you/Downloads/und-mcp"   # optional; absolute path; default ~/Downloads/und-mcp
```

The `api_url` value above is an obvious **placeholder** (`api.example.com` is
a reserved domain, **not** a live host) — **replace it with the confirmed und
API host before use**.

Environment variables take precedence over the file. If a value is missing or
blank in the environment, the file is consulted as a **fallback** for that
value. Only when **all three** values (`UND_API_URL`, `UND_API_KEY`, and
`UND_MCP_DOWNLOAD_DIR`) are set to nonblank values is the file not read at
all. Only when a **required** value is **still** missing or blank **after
both sources are checked** does the wrapper exit with a clear error message
(it never logs your key, and it never echoes the
supplied URL in an error either). A resolved URL that fails validation —
e.g. non-loopback `http://` — exits with the same kind of clear error,
**before** the server is constructed or any request is made.

> **⚠️ There is no default API host, and non-local hosts must use HTTPS.**
> The wrapper accepts `https://` URLs for any host, and `http://` **only** for
> loopback hosts (`localhost`, `127.0.0.1`, `[::1]`). Note that **HTTPS does
> not verify host ownership**: it only proves the connection reached a host
> with a valid certificate for that name. Before you supply a **real API
> key**, **obtain the confirmed und API host (HTTPS) from the und team** and
> confirm it matches what you set in `UND_API_URL` (env or `config.toml`) —
> using a real key before the host is confirmed risks sending it to the wrong
> place. The **loopback `http://` exception is for local testing only**: it
> works with **any** key, so use it against a local stand-in, never as a
> substitute for the confirmed host.

> **The config file holds a plaintext secret.** `config.toml` stores your key
> in **plaintext** on disk. Keep it private: restrict its permissions (e.g.
> `chmod 600`), and never commit it, sync it to a shared or cloud location, or
> share it. The same care applies to any environment you export the key into.

## Claude Desktop

Edit `claude_desktop_config.json` (on macOS:
`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "und": {
      "command": "und-mcp",
      "env": {
        "UND_API_URL": "https://api.example.com",
        "UND_API_KEY": "und_..."
      }
    }
  }
}
```

Both values are **required** — a key without `UND_API_URL` will not start the
server. The `UND_API_URL` value above is an obvious **placeholder**
(`api.example.com` is a reserved domain, **not** a live host) — **obtain the
confirmed und API host from the und team and replace the placeholder before
using a real key**.

Restart Claude Desktop. You'll see the `und` server and its `run_test` and
`download_all_in_one` tools available.

## Claude Code

Register the stdio server. **Options go before the `--` separator; everything
after the `--` is the command Claude Code launches (and its arguments) — not a
Claude flag:**

```bash
# if installed with pipx
claude mcp add --transport stdio und-mcp -- und-mcp

# zero-install alternative (uvx fetches and runs it on demand)
claude mcp add --transport stdio und-mcp -- uvx und-mcp
```

Claude Code hands the server its **key and API URL** in one of two ways
(both are required; any value that is missing or blank in the environment is
read from the file):

- **Local config file (recommended).** Create `~/.config/und-mcp/config.toml`
  with **both** `api_url` and `api_key`, as shown in
  [Configuration](#configuration). The wrapper reads it automatically, so the
  key never appears in a shell command, your shell history, or a project file.
- **Explicitly configured environment.** Pass repeatable `--env KEY=VALUE`
  flags **before** the `--`:

  ```bash
  claude mcp add --transport stdio \
    --env UND_API_URL="<confirmed API host>" \
    --env UND_API_KEY="<paste key here>" \
    und-mcp -- und-mcp
  ```

  Don't paste a real key into a shell command like this: it is stored verbatim
  in the saved MCP config and also remains in your shell history. If you prefer
  the environment, set `UND_API_URL` / `UND_API_KEY` in your shell profile or
  in the environment you launch Claude Code from, and register the server with
  no `--env` flags.

Whichever way you choose, the value ends up stored in **plaintext** on disk
(the config file, or the saved MCP config), so treat that file as a secret and
keep it private.

## Auditable by design

A live API key sits next to this code, so it's built to be read in a few
minutes:

- **stdio only** — no HTTP/`serve` mode, no OAuth, no listening socket.
- **No telemetry, no background calls** — the only network activity is the
  explicit `GET` your tool triggers, on demand, and the only local effect is
  writing a downloaded CSV into your configured download directory.
- **Read-only** — both tools are read-only `GET`s; no write/delete endpoints.
- **Error-sanitizing** — API error responses are mapped to short, actionable
  messages; arbitrary server error bodies are never echoed back to Claude.
- **Proxy-immune** — the HTTP client is built with `trust_env=False`, so
  proxy/netrc settings in the environment cannot redirect requests.
- **~640 lines** of plain Python: `config.py`, `client.py`, `server.py`.

## SDK version note

The MCP Python SDK is in fast flux. This wrapper is pinned to **`mcp==2.3.0`**
(the v2 line, where `FastMCP` was renamed to `MCPServer`). If you upgrade the
`mcp` SDK or Claude and the tools stop appearing, you may need a corresponding
`und-mcp` bump. Keep the pinned version in `pyproject.toml` as your reference.

## Troubleshooting

- **`UND_API_URL is not set`** — the URL is required and has no default; a
  key alone will not start the server. Obtain the confirmed und API host from
  the und team, set `UND_API_URL` (env or `api_url` in `config.toml`), then
  restart Claude. For local testing, an explicit loopback HTTP URL such as
  `http://127.0.0.1:PORT` works.
- **`UND_API_KEY is not set`** — set the key (env or `config.toml`), then
  restart Claude.
- **`UND_API_URL is invalid ...`** — the URL failed validation. Only
  `https://` is accepted for non-local hosts; `http://` only for loopback
  hosts (`localhost`, `127.0.0.1`, `[::1]`, optional port); embedded
  `user:pass@` credentials and malformed hosts or ports are rejected. Set an
  `https://` URL to the confirmed und API host (or a loopback `http://` URL
  for local testing), then restart Claude.
- **`rejected the key (401/403)`** from a tool — your key is invalid, revoked,
  or expired. Ask the und team to reissue it.
- **`Rate limited by the und API (429)...`** — you hit the API rate limit; if
  the server sent a numeric `Retry-After`, the tool tells Claude the wait
  duration before retrying.
- **`rejected the request parameters (422)`** from `download_all_in_one` — the
  und API rejected the date range. Narrow the range (or use two smaller ranges
  and concatenate the files); the maximum width is configured server-side by
  the und team.
- **`Could not create the download directory ...`** — set `UND_MCP_DOWNLOAD_DIR`
  (or `download_dir` in `config.toml`) to a writable absolute directory path,
  then retry.
- **No tools listed** — check the SDK version note above.
- **No `und` server after restart (Quickstart)** — `uvx` must be findable by
  Claude Desktop, which does **not** inherit your shell `PATH`. Run
  `which uvx` and use the printed **absolute path** as `"command"`. The first
  start also **needs internet** (`uvx` downloads the wrapper from PyPI).

## Running the tests

Install the wrapper (with the test extra) **into the Python environment you
will run the tests with**, then run the suite from that same environment.
Quote the editable test-extra argument so the shell does not glob `.[test]`:

```bash
# from this directory
python -m pip install -e '.[test]'
python -m pytest tests -q
```

The stdio end-to-end tests resolve the **`und-mcp` console script from the
`sysconfig` scripts directory of the very Python environment running pytest**
(`bin` on POSIX, `Scripts` on Windows, including the Windows `.exe` launcher)
and spawn it as a subprocess. There is **no** hard-coded venv path and **no**
fallback to an unrelated `und-mcp` on `PATH`: the console script must belong to
the environment running the tests. Run the suite with whichever environment has
the wrapper and its test dependencies installed, e.g. from the repository root:

```bash
env PYTHONDONTWRITEBYTECODE=1 wrapper/.venv/bin/python -m pytest -q -p no:cacheprovider wrapper/tests
```

If `und-mcp` is not installed in the environment that runs the tests, the
suite fails up front with a clear, actionable error telling you to install it
(`python -m pip install -e '.[test]'`), instead of a confusing spawn error
mid-test.

The suite drives the real entry point over an actual stdio channel against an
ephemeral `127.0.0.1` HTTP server, with a synthetic key — no real API, no
network access beyond loopback.
