wunder-mobility-mcp 0.1.0__tar.gz

wunder_mobility_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Wunder Mobility GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wunder_mobility_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,243 @@
+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.

wunder_mobility_mcp-0.1.0/README.md

@@ -0,0 +1,214 @@
+# 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.

wunder_mobility_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "wunder-mobility-mcp"
+version = "0.1.0"
+description = "MCP server exposing the Wunder Mobility public API documentation"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [{ name = "Wunder Mobility" }]
+license = { text = "MIT" }
+keywords = ["mcp", "wunder", "mobility", "api", "documentation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "certifi>=2024.0.0",
+    "fastmcp>=3.3.1",
+    "platformdirs>=4.0.0",
+    "pyyaml>=6.0.2",
+    "rank-bm25>=0.2.2",
+    "uvicorn[standard]>=0.32.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Wunder-Mobility/public-api-mcp"
+Documentation = "https://docs.wundermobility.services"
+"Bug Tracker" = "https://github.com/Wunder-Mobility/public-api-mcp/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-asyncio>=0.24.0",
+    "httpx>=0.27.0",
+]
+
+[project.scripts]
+wunder-mobility-mcp = "wunder_mcp.stdio:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["src"]

wunder_mobility_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wunder_mobility_mcp-0.1.0/src/wunder_mcp/app.py

@@ -0,0 +1,28 @@
+"""Entrypoint for both local dev (uvicorn) and Lambda (via Lambda Web Adapter).
+
+Local dev:    `python -m wunder_mcp.app`  (serves on http://localhost:8080/mcp)
+Lambda:       Lambda Web Adapter forwards Function URL invocations to this same
+              uvicorn process inside the container.
+"""
+
+from __future__ import annotations
+
+import os
+
+import uvicorn
+
+from .server import build_server
+
+_server = build_server()
+# ASGI app for HTTP/SSE transport at path /mcp.
+app = _server.http_app(path="/mcp")
+
+
+def main() -> None:
+    host = os.environ.get("HOST", "0.0.0.0")
+    port = int(os.environ.get("PORT", "8080"))
+    uvicorn.run(app, host=host, port=port, log_level=os.environ.get("LOG_LEVEL", "info"))
+
+
+if __name__ == "__main__":
+    main()

wunder_mobility_mcp-0.1.0/src/wunder_mcp/catalog.py

@@ -0,0 +1,109 @@
+"""Builds the in-memory catalog of guides + endpoints, ready to serve.
+
+A Catalog is loaded once at module init and reused across all requests.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .docs_links import GuideEntry, endpoint_url, load_toc, to_kebab
+from .openapi import Operation, load_operations
+
+
+@dataclass
+class Guide:
+    """One markdown guide with its rendered Stoplight URL and full body."""
+
+    title: str
+    slug: str
+    file_stem: str  # filename without extension
+    body: str
+    url: str
+
+    @property
+    def search_text(self) -> str:
+        return f"{self.title}\n{self.body}"
+
+
+@dataclass
+class Catalog:
+    """The full set of guides and endpoints, indexed for lookup."""
+
+    guides: list[Guide] = field(default_factory=list)
+    operations: list[Operation] = field(default_factory=list)
+    _guides_by_slug: dict[str, Guide] = field(default_factory=dict)
+    _guides_by_stem: dict[str, Guide] = field(default_factory=dict)
+    _ops_by_id: dict[str, Operation] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self._guides_by_slug = {g.slug: g for g in self.guides}
+        self._guides_by_stem = {g.file_stem: g for g in self.guides}
+        self._ops_by_id = {op.operation_id: op for op in self.operations}
+
+    def guide(self, ref: str) -> Guide | None:
+        return self._guides_by_slug.get(ref) or self._guides_by_stem.get(ref)
+
+    def operation(self, operation_id: str) -> Operation | None:
+        return self._ops_by_id.get(operation_id)
+
+    def operations_for(self, api: str | None = None, tag: str | None = None) -> list[Operation]:
+        results = self.operations
+        if api:
+            results = [op for op in results if op.api == api]
+        if tag:
+            results = [op for op in results if tag in op.tags]
+        return results
+
+
+_HEADING_RE = re.compile(r"^# (.+)$", re.MULTILINE)
+
+
+def _extract_title(file_stem: str, body: str) -> str:
+    match = _HEADING_RE.search(body)
+    if match:
+        return match.group(1).strip()
+    # Fall back to the file stem in Title Case.
+    return file_stem.replace("-", " ").title()
+
+
+def load_catalog(vendor_dir: Path) -> Catalog:
+    docs_dir = vendor_dir / "docs"
+    ref_dir = vendor_dir / "reference"
+    toc_path = vendor_dir / "toc.json"
+
+    if not docs_dir.exists() or not ref_dir.exists() or not toc_path.exists():
+        raise FileNotFoundError(
+            f"Docs not found in {vendor_dir}. Check your network connection or WUNDER_MCP_CACHE_DIR."
+        )
+
+    toc_entries: list[GuideEntry] = load_toc(toc_path)
+    guides: list[Guide] = []
+    seen: set[str] = set()
+    for entry in toc_entries:
+        md_path = docs_dir / entry.filename
+        if not md_path.exists() or entry.slug in seen:
+            continue
+        seen.add(entry.slug)
+        body = md_path.read_text()
+        guides.append(
+            Guide(
+                title=_extract_title(entry.file_stem, body) or entry.title,
+                slug=entry.slug,
+                file_stem=entry.file_stem,
+                body=body,
+                url=entry.url,
+            )
+        )
+
+    operations: list[Operation] = load_operations(ref_dir)
+    return Catalog(guides=guides, operations=operations)
+
+
+def stoplight_endpoint_url(operation: Operation) -> str | None:
+    """Return Stoplight URL for an endpoint, or None if the API namespace is unknown."""
+    if not operation.api:
+        return None
+    return endpoint_url(operation.api, to_kebab(operation.operation_id))