wunder-mobility-mcp 0.1.1

MCP server exposing the Wunder Mobility public API documentation

Wunder Mobility MCP

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

This is a Model Context Protocol (MCP) 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.

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 runs the package directly from PyPI — no Python environment setup, no cloning.

Install uv if you don't have it:

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
# or: brew install uv
# or: winget install astral-sh.uv                  # Windows

Claude Code:

claude mcp add wunder-api uvx wunder-mobility-mcp

Cursor — add to your MCP settings (~/.cursor/mcp.json or via Settings → MCP):

{
  "mcpServers": {
    "wunder-api": {
      "command": "uvx",
      "args": ["wunder-mobility-mcp"]
    }
  }
}

Windsurf — add to ~/.codeium/windsurf/mcp_config.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.

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

Claude Code:

claude mcp add wunder-api "$(pwd)/.venv/bin/wunder-mobility-mcp"

Cursor:

{
  "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:

claude mcp add wunder-api --transport http https://mcp.wundermobility.services/mcp

Cursor / Windsurf / other clients:

{
  "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 — 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

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

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.

---

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:

   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:

   claude mcp remove wunder-api
   claude mcp add wunder-api /opt/homebrew/bin/uvx wunder-mobility-mcp
   

   Cursor / Windsurf / other JSON configs:

   {
     "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 (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.