Metadata-Version: 2.4
Name: wunder-mobility-mcp
Version: 0.1.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
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: uvicorn[standard]>=0.32.0
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 ranked, 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 four tools your assistant can call automatically:

| Tool | What your assistant uses it for |
|---|---|
| `search_api_docs(query)` | *"Find the right endpoint or guide for this flow"* — full-text search across all guides and OpenAPI specs. |
| `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."* — returns the raw OpenAPI operation object. |
| `get_guide(slug)` | *"Explain how authentication works."* — returns the full markdown guide. |

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

Docs are pulled **live from GitHub** on every startup and cached locally — so your assistant always has the current API, not a stale snapshot.

---

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

### Option C — hosted URL (no local install at all)

Point your client at our hosted server — nothing to install or run locally.

**Claude Code:**
```bash
claude mcp add wunder-api --transport http https://mcp.wundermobility.services/mcp
```

**Cursor / Windsurf / other clients:**
```json
{
  "mcpServers": {
    "wunder-api": {
      "url": "https://mcp.wundermobility.services/mcp"
    }
  }
}
```

---

## 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 live in [`Wunder-Mobility/public-api-docs`](https://github.com/Wunder-Mobility/public-api-docs) — a public GitHub repo. On every server startup, this MCP downloads the latest tarball from that repo and caches it locally. 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 run       # start HTTP server on http://localhost:8080/mcp
```

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

### Project structure

```
src/wunder_mcp/
  docs_source.py   # fetches & caches the docs tarball from GitHub
  catalog.py       # builds the in-memory guide + endpoint catalog
  docs_links.py    # parses toc.json and builds Stoplight deep-link URLs
  openapi.py       # loads and indexes OpenAPI specs
  search.py        # BM25 search index
  server.py        # MCP tool definitions (FastMCP)
  app.py           # HTTP entrypoint (uvicorn)
  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`.

---

## Deploying your own hosted instance

The server runs on AWS Lambda behind a Function URL. See `template.yaml` for the SAM definition.

**Prerequisites:** AWS CLI, SAM CLI (`brew install aws-sam-cli`), Python 3.12.

```bash
sam build
sam deploy --guided   # first time; saves config to samconfig.toml
sam build && sam deploy   # subsequent deploys
```

Doc changes don't require a redeploy — the Lambda fetches the latest docs on every cold start.

---

## Roadmap

- **v0.1 (current):** read-only docs search, public and unauthenticated, docs fetched live on startup.
- **v0.2:** per-tenant API key auth + usage telemetry.
- **v1.0:** tools that call the live Wunder API directly (e.g. `create_test_booking`), gated by a customer API key.
