Metadata-Version: 2.4
Name: wunder-mobility-mcp
Version: 0.6.0
Summary: MCP server exposing the Wunder Mobility public API documentation
Author: Wunder Mobility
License: MIT
Project-URL: Homepage, https://github.com/Wunder-Mobility/public-api-mcp
Project-URL: Documentation, https://docs.wundermobility.services
Project-URL: Bug Tracker, https://github.com/Wunder-Mobility/public-api-mcp/issues
Keywords: mcp,wunder,mobility,api,documentation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi>=2024.0.0
Requires-Dist: fastmcp>=3.3.1
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: pyyaml>=6.0.2
Provides-Extra: dev
Requires-Dist: pytest>=8.3.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Dynamic: license-file

# Wunder Mobility MCP

> **Give your AI coding assistant live knowledge of the Wunder Mobility API.**

This is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that puts the full Wunder Mobility public API documentation — every guide, every endpoint, every request/response schema — directly inside your AI assistant.

Instead of copy-pasting docs or hoping your assistant's training data is up to date, you can just ask:

> *"What endpoints do I need to build a payment flow for my users?"*
> *"Show me the full spec for creating a booking."*
> *"How does vehicle discovery work in the User API?"*

…and get back cited answers with deep-links straight to [docs.wundermobility.services](https://docs.wundermobility.services/).

Works with **Claude Code**, **Cursor**, **Windsurf**, **VS Code with Copilot**, and any other MCP-compatible client.

---

## What it does

The MCP server exposes twelve tools your assistant can call automatically. It reads like a book: the list first, then the outline of one document, then one section. For an exact code or name, a finder lists every place it appears.

| Tool | What your assistant uses it for |
|---|---|
| `list_guides()` | *"What is documented at all?"* — every guide with its group and a one-line description. The start for any question about a concept, a rule, a flow or an error code. |
| `get_guide_outline(slug)` | *"What sections does the Error Codes guide have?"* — the guide's table of contents: section id, title, level and size in tokens. |
| `get_guide_section(slug, section_id)` | *"Show me the section on rental errors."* — one section, word for word, with the guide title, the section path and the link. |
| `list_tags(api)` | *"What areas does the Operations API have?"* — the tag names to narrow `list_endpoints` with, and how many endpoints each holds. |
| `list_endpoints(api, tag?)` | *"What endpoints exist in the User API under Payments?"* — browse by API namespace and tag. |
| `get_endpoint_spec(operation_id)` | *"Give me the exact request/response schema for this endpoint."* — the OpenAPI operation with its schema references expanded, so the field names are there. |
| `find_in_api_docs(text, limit?)` | *"Where does `R256` appear?"* — every place an exact text appears, in a fixed order: endpoints whose id, path, summary or description holds it, then guide sections, then endpoints that hold it only in their request or response fields. No ranking. At most 50 places per call (`limit`); `truncated` is true when there are more. |
| `list_snowflake_tables()` | *"What tables are documented in the Snowflake warehouse?"* — lists every documented table with primary key and description. |
| `get_snowflake_table(name)` | *"Show me the columns, types, and descriptions for the bookings table."* — returns the table's primary key, description, and full field list (case-insensitive name lookup). |
| `list_data_guides()` | *"How is a KPI defined?"* — the Snowflake data guides (KPI definitions, reporting how-tos, the data inventory) with their size. |
| `get_data_guide(slug)` | *"Show me the KPI report documentation."* — one data guide, in full. |
| `find_in_data_docs(text, limit?)` | *"Which tables have a `branch_id` column?"* — every place an exact text appears, in a fixed order: tables (with the notes on their pages), then fields table by table, then data guides. No ranking. At most 50 places per call (`limit`); `truncated` is true when there are more. |

Every result includes a deep-link so you (or your assistant) can open the same content in a browser.

Docs are pulled **live from the public Wunder docs sites** ([api.docs.wundermobility.services](https://api.docs.wundermobility.services) and [data.docs.wundermobility.services](https://data.docs.wundermobility.services)) on every startup and cached locally — so your assistant always has the current API and data-warehouse schema, not a stale snapshot. The fetch is unauthenticated and never committed.

---

## Install

### Option A — `uvx` (recommended, no cloning needed)

[`uvx`](https://docs.astral.sh/uv/) runs the package directly from PyPI — no Python environment setup, no cloning.

**Install `uv` if you don't have it:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
# or: brew install uv
# or: winget install astral-sh.uv                  # Windows
```

**Claude Code:**
```bash
claude mcp add wunder-api uvx wunder-mobility-mcp
```

**Cursor** — add to your MCP settings (`~/.cursor/mcp.json` or via *Settings → MCP*):
```json
{
  "mcpServers": {
    "wunder-api": {
      "command": "uvx",
      "args": ["wunder-mobility-mcp"]
    }
  }
}
```

**Windsurf** — add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
  "mcpServers": {
    "wunder-api": {
      "command": "uvx",
      "args": ["wunder-mobility-mcp"]
    }
  }
}
```

**Any client that accepts a command:** use `uvx` as the command and `["wunder-mobility-mcp"]` as the args.

On first start, the server fetches the latest docs from GitHub (~5–10s) and caches them locally. Every subsequent start is instant.

### Option B — clone and run

If you'd rather run from source:

**Prerequisites:** Python 3.12+, git.

```bash
git clone https://github.com/Wunder-Mobility/public-api-mcp.git
cd public-api-mcp
make install
```

**Claude Code:**
```bash
claude mcp add wunder-api "$(pwd)/.venv/bin/wunder-mobility-mcp"
```

**Cursor:**
```json
{
  "mcpServers": {
    "wunder-api": {
      "command": "/path/to/public-api-mcp/.venv/bin/wunder-mobility-mcp"
    }
  }
}
```

Replace `/path/to/public-api-mcp` with your actual clone path (`pwd` inside the repo).

---

## Verify it's working

Once connected, open your assistant and try:

- *"Search the Wunder API docs for payment flow"*
- *"List all endpoints in the Wunder operations API"*
- *"Get the guide for user authentication"*

You should see the tools being called and results coming back with Stoplight links.

---

## How docs stay current

The docs are published to the public GitHub Pages site [api.docs.wundermobility.services](https://api.docs.wundermobility.services) (and [data.docs.wundermobility.services](https://data.docs.wundermobility.services) for the Snowflake data docs). On every server startup, this MCP mirrors the latest raw docs from those sites — driven by each site's `toc.json` — and caches them locally. No authentication, no manual sync, no stale snapshots.

**To get the latest docs locally:** restart your MCP server (or restart your editor). The cache lives at:

| OS | Cache path |
|---|---|
| macOS | `~/Library/Caches/wunder-mobility-mcp/public-api-docs` |
| Linux | `~/.cache/wunder-mobility-mcp/public-api-docs` |
| Windows | `%LOCALAPPDATA%\wunder-mobility-mcp\Cache\public-api-docs` |

---

## Development

```bash
make install   # create .venv, install package + dev deps
make test      # run the test suite (requires network on first run)
```

> `make test` fetches live docs from the public docs sites on the first run (~10s). Subsequent runs use the local cache.

### Project structure

```
src/wunder_mcp/
  docs_source.py   # mirrors & caches the raw docs from the public Pages sites
  catalog.py       # builds the in-memory guide + endpoint catalog
  guide_tree.py    # a guide's table of contents: its sections and the text of each
  find.py          # exact-text finder (no ranking) over the API docs and the data docs
  docs_links.py    # parses toc.json and builds Stoplight deep-link URLs
  openapi.py       # loads and indexes OpenAPI specs
  server.py        # MCP tool definitions (FastMCP)
  stdio.py         # stdio entrypoint
```

### Publishing a new version

1. Bump `version` in `pyproject.toml`
2. Commit and tag: `git tag v0.x.x && git push --tags`
3. The `publish.yml` workflow builds and uploads to PyPI automatically via trusted publishing

**One-time PyPI setup** (before the first publish): go to [pypi.org](https://pypi.org) → your project → Publishing → add a trusted publisher with owner `Wunder-Mobility`, repo `public-api-mcp`, workflow `publish.yml`, environment `pypi`.

---

## Troubleshooting

### `Failed to reconnect to wunder-api: ENOENT`

**What it means:** Your AI client tried to restart the `wunder-api` server process but couldn't find the `uvx` executable. This happens because desktop apps and some editors launch with a minimal PATH that doesn't include the directory where Homebrew or uv installed `uvx`.

**Fix — use the absolute path to `uvx`:**

1. Find where `uvx` lives on your machine:
   ```bash
   which uvx
   ```
   Common locations:
   - macOS (Apple Silicon / Homebrew): `/opt/homebrew/bin/uvx`
   - macOS (Intel / Homebrew): `/usr/local/bin/uvx`
   - Linux: `~/.local/bin/uvx`

2. Re-register the server using that full path:

   **Claude Code:**
   ```bash
   claude mcp remove wunder-api
   claude mcp add wunder-api /opt/homebrew/bin/uvx wunder-mobility-mcp
   ```

   **Cursor / Windsurf / other JSON configs:**
   ```json
   {
     "mcpServers": {
       "wunder-api": {
         "command": "/opt/homebrew/bin/uvx",
         "args": ["wunder-mobility-mcp"]
       }
     }
   }
   ```
   Replace `/opt/homebrew/bin/uvx` with the output of `which uvx`.

---

## Roadmap

- **v0.1:** read-only API docs search, public and unauthenticated, docs fetched live on startup.
- **v0.2:** Snowflake data-warehouse documentation search — operators can discover tables, columns, and enum meanings for SQL building without leaving their AI assistant.
- **v0.6 (current):** read the docs by table of contents (list, outline, one section) with an exact-text finder for codes and names. Both word-match searches (`search_guides_and_endpoints`, `search_snowflake_docs`) and `get_guide` are removed.
- **v1.0:** tools that call the live Wunder API directly (e.g. `create_test_booking`), gated by a customer API key.
