wunder-mobility-mcp 0.3.0

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 seven 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.
search_snowflake_docs(query)	"What tables store rental data in the Snowflake warehouse?" — full-text search across Snowflake data-warehouse metadata.
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).

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

---

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 (and 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

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

---

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: read-only API docs search, public and unauthenticated, docs fetched live on startup.
• v0.2 (current): Snowflake data-warehouse documentation search — operators can discover tables, columns, and enum meanings for SQL building without leaving their AI assistant.
• v1.0: tools that call the live Wunder API directly (e.g. create_test_booking), gated by a customer API key.