Metadata-Version: 2.4
Name: und-mcp
Version: 0.1.1
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 one tool in v1:

| 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. |

`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.

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` tool 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. 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.

**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
```

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 **both** `UND_API_URL` and `UND_API_KEY` are set to
nonblank values is the file not read at all. Only when a 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` tool
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.
- **Read-only** — 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.
- **~150 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.
- **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.
