mcp-restful-wrapper 0.1.0__tar.gz

mcp_restful_wrapper-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.3
+Name: mcp-restful-wrapper
+Version: 0.1.0
+Summary: Automatically convert RESTful APIs (Swagger 2.0 / OpenAPI 3.0) into MCP Servers
+Keywords: mcp,openapi,swagger,restful,api,model-context-protocol
+Author: lixw
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: fastmcp>=3.4.2
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pyyaml>=6.0
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/alvinlee518/mcp-restful-wrapper
+Project-URL: Repository, https://github.com/alvinlee518/mcp-restful-wrapper
+Project-URL: Issues, https://github.com/alvinlee518/mcp-restful-wrapper/issues
+Description-Content-Type: text/markdown
+
+# MCP RESTful Wrapper
+
+将 RESTful API（Swagger 2.0 / OpenAPI 3.0）自动转换为 MCP Server。每个 API 端点变成一个 MCP Tool。
+
+## 快速开始
+
+### 1. 在 Claude Desktop / Cursor / Claude Code 中使用
+
+编辑配置文件（Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`）：
+
+**从 PyPI 安装（推荐）：**
+
+```json
+{
+  "mcpServers": {
+    "petstore": {
+      "command": "uvx",
+      "args": ["mcp-restful-wrapper"],
+      "env": {
+        "API_SPEC_URL": "https://petstore3.swagger.io/api/v3/openapi.json",
+        "API_BASE_URL": "https://petstore3.swagger.io/api/v3",
+        "API_TAGS": "pet,store"
+      }
+    }
+  }
+}
+```
+
+**本地开发（未发布时）：**
+
+```json
+{
+  "mcpServers": {
+    "petstore": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--project", "/path/to/mcp-restful-wrapper",
+        "mcp-restful-wrapper"
+      ],
+      "env": {
+        "API_SPEC_URL": "https://petstore3.swagger.io/api/v3/openapi.json",
+        "API_BASE_URL": "https://petstore3.swagger.io/api/v3",
+        "API_TAGS": "pet,store"
+      }
+    }
+  }
+}
+```
+
+> 将 `/path/to/mcp-restful-wrapper` 替换为本项目的实际路径。
+
+配置完成后，Claude 就能直接调用 Petstore 的 API 了：
+
+- `findPetsByStatus(status="available")` → 查询可用宠物
+- `getPetById(petId=1)` → 查询宠物详情
+- `addPet(name="Buddy", ...)` → 创建宠物
+
+### 2. 在终端中使用
+
+```bash
+# PyPI 版本
+API_SPEC_URL=https://petstore3.swagger.io/api/v3/openapi.json \
+API_BASE_URL=https://petstore3.swagger.io/api/v3 \
+API_TAGS=pet \
+uvx mcp-restful-wrapper
+
+# 本地开发
+API_SPEC_URL=https://petstore3.swagger.io/api/v3/openapi.json \
+API_BASE_URL=https://petstore3.swagger.io/api/v3 \
+API_TAGS=pet \
+uv run mcp-restful-wrapper
+```
+
+### 3. 带认证的 API
+
+```json
+{
+  "mcpServers": {
+    "my-api": {
+      "command": "uvx",
+      "args": ["mcp-restful-wrapper"],
+      "env": {
+        "API_SPEC_URL": "https://your-api.example.com/openapi.json",
+        "API_BASE_URL": "https://your-api.example.com",
+        "API_TOKEN": "your-bearer-token"
+      }
+    }
+  }
+}
+```
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `API_SPEC_URL` | OpenAPI/Swagger 文档地址 | **必填** |
+| `API_BASE_URL` | 后端 API 地址 | **必填** |
+| `API_TOKEN` | Bearer Token 认证 | 空 |
+| `API_TAGS` | Tag 白名单，逗号分隔，**OR** 逻辑（匹配任一 tag 即保留） | 全部 |
+| `API_METHODS` | HTTP 方法白名单，逗号分隔 | 全部 |
+| `API_PATHS` | 路径正则白名单（如 `^/api/v1/`） | 全部 |
+| `LOG_LEVEL` | 日志级别（`INFO` 记录请求 URL，`DEBUG` 记录请求头和 body） | `WARNING` |
+
+### 过滤示例
+
+```bash
+# 只要 GET 请求
+API_METHODS=GET
+
+# 只要 pet 或 store 相关的端点
+API_TAGS=pet,store
+
+# 只要 /api/v1/ 开头的路径
+API_PATHS=^/api/v1/
+
+# 组合使用：pet tag 下的 GET 和 POST
+API_TAGS=pet
+API_METHODS=GET,POST
+```
+
+## 开发
+
+```bash
+uv sync                                    # 安装依赖
+uv run mcp-restful-wrapper                 # 运行
+uv run pytest tests/ -v                    # 运行测试
+uv run pytest tests/ --cov=mcp_restful_wrapper  # 覆盖率
+```
+
+## 示例代码
+
+| 文件 | 说明 |
+|------|------|
+| [`examples/agent_usage.py`](examples/agent_usage.py) | Agent 中使用 — 连接 MCP Server、列出 tools、调用 tools |
+| [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json) | Claude Desktop 配置模板 |
+
+```bash
+uv run python examples/agent_usage.py
+```

mcp_restful_wrapper-0.1.0/README.md

@@ -0,0 +1,140 @@
+# MCP RESTful Wrapper
+
+将 RESTful API（Swagger 2.0 / OpenAPI 3.0）自动转换为 MCP Server。每个 API 端点变成一个 MCP Tool。
+
+## 快速开始
+
+### 1. 在 Claude Desktop / Cursor / Claude Code 中使用
+
+编辑配置文件（Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`）：
+
+**从 PyPI 安装（推荐）：**
+
+```json
+{
+  "mcpServers": {
+    "petstore": {
+      "command": "uvx",
+      "args": ["mcp-restful-wrapper"],
+      "env": {
+        "API_SPEC_URL": "https://petstore3.swagger.io/api/v3/openapi.json",
+        "API_BASE_URL": "https://petstore3.swagger.io/api/v3",
+        "API_TAGS": "pet,store"
+      }
+    }
+  }
+}
+```
+
+**本地开发（未发布时）：**
+
+```json
+{
+  "mcpServers": {
+    "petstore": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--project", "/path/to/mcp-restful-wrapper",
+        "mcp-restful-wrapper"
+      ],
+      "env": {
+        "API_SPEC_URL": "https://petstore3.swagger.io/api/v3/openapi.json",
+        "API_BASE_URL": "https://petstore3.swagger.io/api/v3",
+        "API_TAGS": "pet,store"
+      }
+    }
+  }
+}
+```
+
+> 将 `/path/to/mcp-restful-wrapper` 替换为本项目的实际路径。
+
+配置完成后，Claude 就能直接调用 Petstore 的 API 了：
+
+- `findPetsByStatus(status="available")` → 查询可用宠物
+- `getPetById(petId=1)` → 查询宠物详情
+- `addPet(name="Buddy", ...)` → 创建宠物
+
+### 2. 在终端中使用
+
+```bash
+# PyPI 版本
+API_SPEC_URL=https://petstore3.swagger.io/api/v3/openapi.json \
+API_BASE_URL=https://petstore3.swagger.io/api/v3 \
+API_TAGS=pet \
+uvx mcp-restful-wrapper
+
+# 本地开发
+API_SPEC_URL=https://petstore3.swagger.io/api/v3/openapi.json \
+API_BASE_URL=https://petstore3.swagger.io/api/v3 \
+API_TAGS=pet \
+uv run mcp-restful-wrapper
+```
+
+### 3. 带认证的 API
+
+```json
+{
+  "mcpServers": {
+    "my-api": {
+      "command": "uvx",
+      "args": ["mcp-restful-wrapper"],
+      "env": {
+        "API_SPEC_URL": "https://your-api.example.com/openapi.json",
+        "API_BASE_URL": "https://your-api.example.com",
+        "API_TOKEN": "your-bearer-token"
+      }
+    }
+  }
+}
+```
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `API_SPEC_URL` | OpenAPI/Swagger 文档地址 | **必填** |
+| `API_BASE_URL` | 后端 API 地址 | **必填** |
+| `API_TOKEN` | Bearer Token 认证 | 空 |
+| `API_TAGS` | Tag 白名单，逗号分隔，**OR** 逻辑（匹配任一 tag 即保留） | 全部 |
+| `API_METHODS` | HTTP 方法白名单，逗号分隔 | 全部 |
+| `API_PATHS` | 路径正则白名单（如 `^/api/v1/`） | 全部 |
+| `LOG_LEVEL` | 日志级别（`INFO` 记录请求 URL，`DEBUG` 记录请求头和 body） | `WARNING` |
+
+### 过滤示例
+
+```bash
+# 只要 GET 请求
+API_METHODS=GET
+
+# 只要 pet 或 store 相关的端点
+API_TAGS=pet,store
+
+# 只要 /api/v1/ 开头的路径
+API_PATHS=^/api/v1/
+
+# 组合使用：pet tag 下的 GET 和 POST
+API_TAGS=pet
+API_METHODS=GET,POST
+```
+
+## 开发
+
+```bash
+uv sync                                    # 安装依赖
+uv run mcp-restful-wrapper                 # 运行
+uv run pytest tests/ -v                    # 运行测试
+uv run pytest tests/ --cov=mcp_restful_wrapper  # 覆盖率
+```
+
+## 示例代码
+
+| 文件 | 说明 |
+|------|------|
+| [`examples/agent_usage.py`](examples/agent_usage.py) | Agent 中使用 — 连接 MCP Server、列出 tools、调用 tools |
+| [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json) | Claude Desktop 配置模板 |
+
+```bash
+uv run python examples/agent_usage.py
+```

mcp_restful_wrapper-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "mcp-restful-wrapper"
+version = "0.1.0"
+description = "Automatically convert RESTful APIs (Swagger 2.0 / OpenAPI 3.0) into MCP Servers"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "lixw"},
+]
+keywords = ["mcp", "openapi", "swagger", "restful", "api", "model-context-protocol"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "fastmcp>=3.4.2",
+    "httpx>=0.28.1",
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/alvinlee518/mcp-restful-wrapper"
+Repository = "https://github.com/alvinlee518/mcp-restful-wrapper"
+Issues = "https://github.com/alvinlee518/mcp-restful-wrapper/issues"
+
+[project.scripts]
+mcp-restful-wrapper = "mcp_restful_wrapper.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.10.9,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=7.1.0",
+]

mcp_restful_wrapper-0.1.0/src/mcp_restful_wrapper/__init__.py

@@ -0,0 +1,5 @@
+"""MCP RESTful Wrapper — convert OpenAPI/Swagger specs into MCP Servers."""
+
+from mcp_restful_wrapper._version import __version__
+
+__all__ = ["__version__"]

mcp_restful_wrapper-0.1.0/src/mcp_restful_wrapper/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

mcp_restful_wrapper-0.1.0/src/mcp_restful_wrapper/cli.py

@@ -0,0 +1,88 @@
+"""CLI entry point for mcp-restful-wrapper."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+from mcp_restful_wrapper.logging import setup_logging
+
+
+def main() -> None:
+    """Entry point: fetch spec, convert if needed, build and run MCP server."""
+
+    setup_logging()
+
+    # 1. Read environment variables
+    spec_url = os.environ.get("API_SPEC_URL")
+    if not spec_url:
+        print("Error: API_SPEC_URL environment variable is required.", file=sys.stderr)
+        sys.exit(1)
+
+    base_url = os.environ.get("API_BASE_URL")
+    if not base_url:
+        print("Error: API_BASE_URL environment variable is required.", file=sys.stderr)
+        sys.exit(1)
+
+    token = os.environ.get("API_TOKEN")
+    tags_str = os.environ.get("API_TAGS")
+    methods_str = os.environ.get("API_METHODS")
+    paths_pattern = os.environ.get("API_PATHS")
+
+    # Parse filter values
+    tags = {t.strip() for t in tags_str.split(",") if t.strip()} if tags_str else None
+    methods = (
+        {m.strip().upper() for m in methods_str.split(",") if m.strip()}
+        if methods_str
+        else None
+    )
+
+    # 2. Fetch the spec
+    from mcp_restful_wrapper.spec_fetcher import fetch_spec
+
+    print(f"Fetching spec from {spec_url}...", file=sys.stderr)
+    try:
+        spec = asyncio.run(fetch_spec(spec_url))
+    except Exception as e:
+        print(f"Error: Failed to fetch spec: {e}", file=sys.stderr)
+        sys.exit(1)
+    print(
+        f"Spec loaded: {spec.get('info', {}).get('title', 'Unknown')}", file=sys.stderr
+    )
+
+    # 3. Convert Swagger 2.0 → OpenAPI 3.0 if needed
+    from mcp_restful_wrapper.spec_converter import (
+        convert_swagger_to_openapi,
+        is_swagger_2,
+    )
+
+    if is_swagger_2(spec):
+        print("Detected Swagger 2.0, converting to OpenAPI 3.0...", file=sys.stderr)
+        spec = convert_swagger_to_openapi(spec)
+
+    # 4. Build and run the MCP server (filtering via RouteMap inside)
+    from mcp_restful_wrapper.server import build_server
+
+    server_name = spec.get("info", {}).get("title", "RESTful API Server")
+    print(
+        f"Filters: tags={tags or 'all'}, methods={methods or 'all'}, "
+        f"paths={paths_pattern or 'all'}",
+        file=sys.stderr,
+    )
+
+    try:
+        mcp = build_server(
+            spec,
+            base_url=base_url,
+            token=token,
+            name=server_name,
+            tags=tags,
+            methods=methods,
+            paths=paths_pattern,
+        )
+    except Exception as e:
+        print(f"Error: Failed to build MCP server: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Starting MCP server: {server_name}", file=sys.stderr)
+    mcp.run(transport="stdio", show_banner=False)

mcp_restful_wrapper-0.1.0/src/mcp_restful_wrapper/logging.py

@@ -0,0 +1,48 @@
+"""Logging configuration for mcp-restful-wrapper."""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from logging.handlers import RotatingFileHandler
+
+LOGGER_NAME = "mcp_restful_wrapper"
+LOG_DIR = os.path.join(os.path.expanduser("~"), ".mcp_restful_wrapper")
+os.makedirs(LOG_DIR, exist_ok=True)
+LOG_FILE = os.path.join(LOG_DIR, "mcp_requests.log")
+
+
+def setup_logging() -> logging.Logger:
+    """Configure logging based on LOG_LEVEL environment variable.
+
+    Sets up two handlers:
+    - RotatingFileHandler: writes to mcp_requests.log (10MB × 5 backups)
+    - StreamHandler: writes to stderr
+
+    Returns:
+        Configured logger instance.
+    """
+    log_level = os.environ.get("LOG_LEVEL", "WARNING").upper()
+    level = getattr(logging, log_level, logging.WARNING)
+    log_format = "%(asctime)s %(levelname)s %(message)s"
+
+    logger = logging.getLogger(LOGGER_NAME)
+    logger.setLevel(level)
+
+    # File handler: rotating log file for request/response records
+    file_handler = RotatingFileHandler(
+        LOG_FILE,
+        maxBytes=10 * 1024 * 1024,
+        backupCount=5,
+        encoding="utf-8",
+    )
+    file_handler.setFormatter(logging.Formatter(log_format))
+    logger.addHandler(file_handler)
+
+    # Stderr handler: console output
+    stderr_handler = logging.StreamHandler(sys.stderr)
+    stderr_handler.setFormatter(logging.Formatter(log_format))
+    logger.addHandler(stderr_handler)
+
+    return logger

mcp_restful_wrapper-0.1.0/src/mcp_restful_wrapper/server.py

@@ -0,0 +1,160 @@
+"""Build and run the MCP server from an OpenAPI specification."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi.routing import MCPType, RouteMap
+
+from mcp_restful_wrapper._version import __version__ as _version
+from mcp_restful_wrapper.logging import LOGGER_NAME
+
+logger = logging.getLogger(LOGGER_NAME)
+
+
+async def log_request(request: httpx.Request):
+    """Log outgoing HTTP request details."""
+    body = (
+        request.content.decode("utf-8", errors="replace")
+        if request.content
+        else "(no body)"
+    )
+    logger.info(
+        "[REQUEST] %s %s\n  Headers: %s\n  Body: %s",
+        request.method,
+        request.url,
+        dict(request.headers),
+        body,
+    )
+
+
+async def log_response(response: httpx.Response):
+    """Log incoming HTTP response details."""
+    # Read body if not already consumed
+    try:
+        await response.aread()
+    except Exception:
+        pass
+    body = (
+        response.content.decode("utf-8", errors="replace")
+        if response.content
+        else "(no body)"
+    )
+    logger.info(
+        "[RESPONSE] %s %s\n  Status: %d\n  Body: %s",
+        response.request.method if response.request else "?",
+        response.url,
+        response.status_code,
+        body,
+    )
+
+
+def build_server(
+    spec: dict[str, Any],
+    base_url: str | None = None,
+    token: str | None = None,
+    name: str = "RESTful API Server",
+    tags: set[str] | None = None,
+    methods: set[str] | None = None,
+    paths: str | None = None,
+) -> FastMCP:
+    """Build a FastMCP server from an OpenAPI specification.
+
+    Args:
+        spec: The OpenAPI 3.x specification dict.
+        base_url: Base URL for the API.
+        token: Bearer token for API authentication.
+        name: Name for the MCP server.
+        tags: Set of tag names to include (OR logic — match ANY).
+        methods: Set of HTTP methods to include (case-insensitive).
+        paths: Regex pattern to match against path strings.
+
+    Returns:
+        A configured FastMCP server instance.
+    """
+    headers: dict[str, str] = {
+        "X-Requested-From": f"MCP/{_version}",
+    }
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    # Build httpx client
+    client_kwargs: dict[str, Any] = {
+        "headers": headers,
+        "timeout": 30.0,
+        "follow_redirects": True,
+        "event_hooks": {
+            "request": [log_request],
+            "response": [log_response],
+        },
+    }
+    if base_url:
+        client_kwargs["base_url"] = base_url
+
+    client = httpx.AsyncClient(**client_kwargs)
+
+    # Build RouteMaps for filtering
+    route_maps = _build_route_maps(tags, methods, paths)
+
+    # Create MCP server from OpenAPI spec
+    mcp = FastMCP.from_openapi(
+        openapi_spec=spec,
+        client=client,
+        name=name,
+        route_maps=route_maps,
+        validate_output=False,
+    )
+
+    return mcp
+
+
+def _build_route_maps(
+    tags: set[str] | None,
+    methods: set[str] | None,
+    paths: str | None,
+) -> list[RouteMap]:
+    """Build RouteMap list for filtering endpoints.
+
+    Strategy:
+    - If tags specified: one RouteMap per tag (OR logic), matched first.
+    - If no tags: one RouteMap matching all (filtered by methods/paths).
+    - Final catch-all EXCLUDE rule drops everything unmatched.
+    """
+    route_maps: list[RouteMap] = []
+
+    # Normalize methods to uppercase list, or "*" for all
+    allowed_methods: list[str] | str = "*"
+    if methods:
+        allowed_methods = [m.upper() for m in methods]
+
+    # Path pattern
+    pattern = paths or r".*"
+
+    if tags:
+        # OR logic: one RouteMap per tag — first match wins
+        for tag in tags:
+            route_maps.append(
+                RouteMap(
+                    methods=allowed_methods,
+                    pattern=pattern,
+                    tags={tag},
+                    mcp_type=MCPType.TOOL,
+                )
+            )
+    else:
+        # No tag filter: accept all routes matching methods/paths
+        route_maps.append(
+            RouteMap(
+                methods=allowed_methods,
+                pattern=pattern,
+                mcp_type=MCPType.TOOL,
+            )
+        )
+
+    # Catch-all: exclude everything not matched above
+    route_maps.append(RouteMap(mcp_type=MCPType.EXCLUDE))
+
+    return route_maps

mcp_restful_wrapper-0.1.0/src/mcp_restful_wrapper/spec_converter.py

@@ -0,0 +1,564 @@
+"""Convert Swagger 2.0 specifications to OpenAPI 3.0 format."""
+
+from __future__ import annotations
+
+import copy
+import re
+from typing import Any
+
+
+def is_swagger_2(spec: dict[str, Any]) -> bool:
+    """Check if a spec is Swagger 2.0."""
+    return "swagger" in spec and str(spec["swagger"]).startswith("2")
+
+
+def convert_swagger_to_openapi(spec: dict[str, Any]) -> dict[str, Any]:
+    """Convert a Swagger 2.0 specification to OpenAPI 3.0 format.
+
+    Args:
+        spec: A Swagger 2.0 specification dict.
+
+    Returns:
+        A new dict in OpenAPI 3.0 format.
+    """
+    spec = copy.deepcopy(spec)
+    result: dict[str, Any] = {"openapi": "3.0.3"}
+
+    # 1. Info (pass through, fill in required fields)
+    info = spec.get("info", {})
+    if not isinstance(info, dict):
+        info = {}
+    info.setdefault("title", "API")
+    info.setdefault("version", "1.0.0")
+    # Clean up empty nested objects that fail validation
+    if isinstance(info.get("license"), dict) and "name" not in info["license"]:
+        info["license"] = {"name": "Unknown"}
+    result["info"] = info
+
+    # 2. Servers: host + basePath + schemes → servers[].url
+    result["servers"] = _convert_servers(spec)
+
+    # 3. Paths
+    result["paths"] = _convert_paths(spec)
+
+    # 4. Components
+    components = _convert_components(spec)
+    if components:
+        result["components"] = components
+
+    # 5. Security (pass through, rewrite $refs)
+    if "security" in spec:
+        result["security"] = spec["security"]
+
+    # 6. Tags (pass through)
+    if "tags" in spec:
+        result["tags"] = spec["tags"]
+
+    # 7. External docs (pass through)
+    if "externalDocs" in spec:
+        result["externalDocs"] = spec["externalDocs"]
+
+    return result
+
+
+def _convert_servers(spec: dict[str, Any]) -> list[dict[str, str]]:
+    """Convert host/basePath/schemes to OpenAPI 3.0 servers array."""
+    host = spec.get("host", "")
+    base_path = spec.get("basePath", "")
+    schemes = spec.get("schemes", ["https"])
+
+    if not host:
+        return []
+
+    servers = []
+    for scheme in schemes:
+        url = f"{scheme}://{host}{base_path}".rstrip("/")
+        servers.append({"url": url})
+
+    return servers
+
+
+def _convert_paths(spec: dict[str, Any]) -> dict[str, Any]:
+    """Convert all paths and their operations."""
+    paths: dict[str, Any] = {}
+    global_consumes = spec.get("consumes", ["application/json"])
+    global_produces = spec.get("produces", ["application/json"])
+
+    for path_key, path_item in spec.get("paths", {}).items():
+        new_path_item: dict[str, Any] = {}
+
+        # Path-level parameters (shared by all operations)
+        if "parameters" in path_item:
+            new_params = []
+            for param in path_item["parameters"]:
+                converted = _convert_parameter(param)
+                if converted:
+                    new_params.append(converted)
+            if new_params:
+                new_path_item["parameters"] = new_params
+
+        # Convert each HTTP method operation
+        http_methods = {"get", "post", "put", "delete", "patch", "head", "options"}
+        for method in http_methods:
+            if method not in path_item:
+                continue
+
+            operation = path_item[method]
+            new_op = _convert_operation(
+                operation, global_consumes, global_produces
+            )
+            new_path_item[method] = new_op
+
+        paths[path_key] = new_path_item
+
+    return paths
+
+
+def _convert_operation(
+    operation: dict[str, Any],
+    global_consumes: list[str],
+    global_produces: list[str],
+) -> dict[str, Any]:
+    """Convert a single Swagger 2.0 operation to OpenAPI 3.0."""
+    new_op: dict[str, Any] = {}
+
+    # Pass-through fields
+    for field in ("tags", "summary", "description", "operationId", "deprecated",
+                  "security"):
+        if field in operation:
+            new_op[field] = operation[field]
+
+    # External docs
+    if "externalDocs" in operation:
+        new_op["externalDocs"] = operation["externalDocs"]
+
+    consumes = operation.get("consumes", global_consumes)
+    produces = operation.get("produces", global_produces)
+
+    # Separate parameters: regular params vs body/formData
+    parameters = operation.get("parameters", [])
+    regular_params = []
+    body_params = []
+    form_params = []
+
+    for param in parameters:
+        param = _resolve_ref_param(param)
+        location = param.get("in", "")
+        if location == "body":
+            body_params.append(param)
+        elif location == "formData":
+            form_params.append(param)
+        else:
+            converted = _convert_parameter(param)
+            if converted:
+                regular_params.append(converted)
+
+    # Set parameters (path, query, header, cookie)
+    if regular_params:
+        new_op["parameters"] = regular_params
+
+    # Set requestBody from body or formData params
+    request_body = _build_request_body(body_params, form_params, consumes)
+    if request_body:
+        new_op["requestBody"] = request_body
+
+    # Convert responses
+    if "responses" in operation:
+        new_op["responses"] = _convert_responses(operation["responses"], produces)
+    else:
+        new_op["responses"] = {"200": {"description": "Successful response"}}
+
+    return new_op
+
+
+def _convert_parameter(param: dict[str, Any]) -> dict[str, Any] | None:
+    """Convert a Swagger 2.0 parameter to OpenAPI 3.0 format.
+
+    In Swagger 2.0, type/format/enum/items are inline on the parameter.
+    In OpenAPI 3.0, they're nested under a 'schema' key.
+    """
+    param = _resolve_ref_param(param)
+
+    # If it's still a $ref after resolution, pass through as-is
+    if "$ref" in param:
+        return param
+
+    location = param.get("in", "")
+
+    # Skip body and formData — handled separately
+    if location in ("body", "formData"):
+        return None
+
+    new_param: dict[str, Any] = {
+        "name": param["name"],
+        "in": location,
+    }
+
+    if param.get("description"):
+        new_param["description"] = param["description"]
+    if param.get("required"):
+        new_param["required"] = param["required"]
+    # Path params are always required in OpenAPI 3.0
+    if location == "path":
+        new_param["required"] = True
+
+    # Build the schema from inline type fields
+    schema = _extract_schema_from_swagger_param(param)
+    if schema:
+        new_param["schema"] = schema
+
+    # Convert collectionFormat to style/explode
+    if "collectionFormat" in param:
+        style, explode = _convert_collection_format(param["collectionFormat"])
+        if style:
+            new_param["style"] = style
+        new_param["explode"] = explode
+
+    # Allow empty values → not directly supported in 3.0, skip
+    # allowEmptyValue is deprecated in 3.0
+
+    return new_param
+
+
+def _extract_schema_from_swagger_param(param: dict[str, Any]) -> dict[str, Any]:
+    """Extract a JSON Schema from inline Swagger 2.0 parameter type fields."""
+    schema: dict[str, Any] = {}
+
+    for field in ("type", "format", "enum", "minimum", "maximum",
+                  "minLength", "maxLength", "pattern", "default",
+                  "minItems", "maxItems", "uniqueItems"):
+        if field in param:
+            schema[field] = param[field]
+
+    # Swagger 2.0 type: "file" → OpenAPI 3.0 type: "string", format: "binary"
+    if schema.get("type") == "file":
+        schema["type"] = "string"
+        schema["format"] = "binary"
+
+    # Handle array items
+    if "items" in param:
+        schema["items"] = _convert_schema_object(param["items"])
+
+    return schema
+
+
+def _resolve_ref_param(param: dict[str, Any]) -> dict[str, Any]:
+    """If param has a $ref, return the ref path rewritten for OpenAPI 3.0."""
+    if "$ref" in param:
+        ref = param["$ref"]
+        # #/parameters/Name → #/components/parameters/Name
+        new_ref = _rewrite_ref(ref)
+        return {"$ref": new_ref}
+    return param
+
+
+def _build_request_body(
+    body_params: list[dict[str, Any]],
+    form_params: list[dict[str, Any]],
+    consumes: list[str],
+) -> dict[str, Any] | None:
+    """Build an OpenAPI 3.0 requestBody from Swagger 2.0 body/formData params."""
+    if body_params:
+        # Use the first body parameter's schema
+        body = body_params[0]
+        schema = body.get("schema", {})
+        schema = _convert_schema_object(schema)
+
+        # Build content map from consumes
+        content_types = _resolve_content_types(consumes, is_body=True)
+        content: dict[str, Any] = {}
+        for ct in content_types:
+            content[ct] = {"schema": schema}
+
+        request_body: dict[str, Any] = {"content": content}
+        if body.get("description"):
+            request_body["description"] = body["description"]
+        if body.get("required"):
+            request_body["required"] = True
+
+        return request_body
+
+    if form_params:
+        # Build schema from formData parameters
+        properties: dict[str, Any] = {}
+        required: list[str] = []
+
+        for param in form_params:
+            prop_schema = _extract_schema_from_swagger_param(param)
+            if param.get("description"):
+                prop_schema["description"] = param["description"]
+            properties[param["name"]] = prop_schema
+            if param.get("required"):
+                required.append(param["name"])
+
+        schema: dict[str, Any] = {"type": "object", "properties": properties}
+        if required:
+            schema["required"] = required
+
+        # Determine content type for form data
+        has_file = any(p.get("type") == "file" for p in form_params)
+        content_type = "multipart/form-data" if has_file else "application/x-www-form-urlencoded"
+
+        return {
+            "content": {
+                content_type: {"schema": schema}
+            }
+        }
+
+    return None
+
+
+def _convert_responses(
+    responses: dict[str, Any],
+    produces: list[str],
+) -> dict[str, Any]:
+    """Convert Swagger 2.0 responses to OpenAPI 3.0 format."""
+    new_responses: dict[str, Any] = {}
+
+    for status_code, response in responses.items():
+        new_resp: dict[str, Any] = {}
+
+        if "$ref" in response:
+            # Rewrite $ref for responses
+            new_resp["$ref"] = _rewrite_ref(response["$ref"])
+            new_responses[status_code] = new_resp
+            continue
+
+        new_resp["description"] = response.get("description", "")
+
+        # Convert response schema to content
+        if "schema" in response:
+            schema = _convert_schema_object(response["schema"])
+            content_types = _resolve_content_types(produces)
+            content: dict[str, Any] = {}
+            for ct in content_types:
+                content[ct] = {"schema": schema}
+            new_resp["content"] = content
+
+        # Convert headers
+        if "headers" in response:
+            new_headers: dict[str, Any] = {}
+            for header_name, header_def in response["headers"].items():
+                new_header: dict[str, Any] = {}
+                if header_def.get("description"):
+                    new_header["description"] = header_def["description"]
+                schema = _extract_schema_from_swagger_param(header_def)
+                if schema:
+                    new_header["schema"] = schema
+                new_headers[header_name] = new_header
+            new_resp["headers"] = new_headers
+
+        new_responses[status_code] = new_resp
+
+    return new_responses
+
+
+def _convert_components(spec: dict[str, Any]) -> dict[str, Any]:
+    """Convert top-level Swagger 2.0 definitions to OpenAPI 3.0 components."""
+    components: dict[str, Any] = {}
+
+    # definitions → components.schemas
+    if "definitions" in spec:
+        schemas: dict[str, Any] = {}
+        for name, schema in spec["definitions"].items():
+            schemas[name] = _convert_schema_object(schema)
+        components["schemas"] = schemas
+
+    # parameters → components.parameters
+    if "parameters" in spec:
+        params: dict[str, Any] = {}
+        for name, param in spec["parameters"].items():
+            converted = _convert_parameter(param)
+            if converted:
+                params[name] = converted
+        if params:
+            components["parameters"] = params
+
+    # responses → components.responses
+    global_produces = spec.get("produces", ["application/json"])
+    if "responses" in spec:
+        resps: dict[str, Any] = {}
+        for name, response in spec["responses"].items():
+            resps[name] = _convert_responses({name: response}, global_produces)[name]
+        if resps:
+            components["responses"] = resps
+
+    # securityDefinitions → components.securitySchemes
+    if "securityDefinitions" in spec:
+        schemes: dict[str, Any] = {}
+        for name, scheme in spec["securityDefinitions"].items():
+            schemes[name] = _convert_security_scheme(scheme)
+        if schemes:
+            components["securitySchemes"] = schemes
+
+    return components
+
+
+def _convert_schema_object(schema: dict[str, Any]) -> dict[str, Any]:
+    """Recursively convert a Swagger 2.0 schema object to OpenAPI 3.0.
+
+    Handles $ref rewriting and nested schema objects.
+    """
+    if not isinstance(schema, dict):
+        return schema
+
+    result: dict[str, Any] = {}
+
+    for key, value in schema.items():
+        if key == "$ref" and isinstance(value, str):
+            if value.startswith("#/"):
+                result["$ref"] = _rewrite_ref(value)
+            else:
+                # Non-standard $ref (e.g., Springfox Java types)
+                resolved = _resolve_java_type_ref(value)
+                result.update(resolved)
+        elif key == "items" and isinstance(value, dict):
+            result["items"] = _convert_schema_object(value)
+        elif key in ("properties",) and isinstance(value, dict):
+            result[key] = {
+                k: _convert_schema_object(v) for k, v in value.items()
+            }
+        elif key == "additionalProperties" and isinstance(value, dict):
+            result[key] = _convert_schema_object(value)
+        elif key in ("allOf", "anyOf", "oneOf") and isinstance(value, list):
+            result[key] = [_convert_schema_object(item) for item in value]
+        else:
+            result[key] = value
+
+    return result
+
+
+def _rewrite_ref(ref: str) -> str:
+    """Rewrite Swagger 2.0 $ref paths to OpenAPI 3.0 paths."""
+    replacements = [
+        (r"^#/definitions/", "#/components/schemas/"),
+        (r"^#/parameters/", "#/components/parameters/"),
+        (r"^#/responses/", "#/components/responses/"),
+    ]
+    for pattern, replacement in replacements:
+        ref = re.sub(pattern, replacement, ref)
+    return ref
+
+
+# Mapping of common Java/Springfox type names to OpenAPI schemas
+_JAVA_TYPE_MAP = {
+    "LocalDate": {"type": "string", "format": "date"},
+    "LocalDateTime": {"type": "string", "format": "date-time"},
+    "LocalTime": {"type": "string", "format": "time"},
+    "Instant": {"type": "string", "format": "date-time"},
+    "ZonedDateTime": {"type": "string", "format": "date-time"},
+    "OffsetDateTime": {"type": "string", "format": "date-time"},
+    "BigDecimal": {"type": "number"},
+    "BigInteger": {"type": "integer"},
+    "UUID": {"type": "string", "format": "uuid"},
+    "URI": {"type": "string", "format": "uri"},
+    "URL": {"type": "string", "format": "uri"},
+    "MultipartFile": {"type": "string", "format": "binary"},
+}
+
+
+def _resolve_java_type_ref(ref: str) -> dict[str, Any]:
+    """Resolve a non-standard $ref (e.g., Springfox Java type) to an OpenAPI schema.
+
+    Handles refs like: Error-ModelName{namespace='java.time', name='LocalDate'}
+    """
+    # Extract the type name from Springfox format
+    match = re.search(r"name='(\w+)'", ref)
+    type_name = match.group(1) if match else ""
+
+    if type_name in _JAVA_TYPE_MAP:
+        return dict(_JAVA_TYPE_MAP[type_name])
+
+    # Unknown Java type — fall back to string
+    return {"type": "string"}
+
+
+def _convert_security_scheme(scheme: dict[str, Any]) -> dict[str, Any]:
+    """Convert a Swagger 2.0 security scheme to OpenAPI 3.0."""
+    new_scheme: dict[str, Any] = {}
+
+    scheme_type = scheme.get("type", "")
+
+    if scheme_type == "basic":
+        new_scheme["type"] = "http"
+        new_scheme["scheme"] = "basic"
+    elif scheme_type == "apiKey":
+        new_scheme["type"] = "apiKey"
+        new_scheme["name"] = scheme.get("name", "")
+        new_scheme["in"] = scheme.get("in", "header")
+    elif scheme_type == "oauth2":
+        new_scheme["type"] = "oauth2"
+        flows = _convert_oauth2_flows(scheme)
+        if flows:
+            new_scheme["flows"] = flows
+    else:
+        new_scheme = scheme
+
+    if scheme.get("description"):
+        new_scheme["description"] = scheme["description"]
+
+    return new_scheme
+
+
+def _convert_oauth2_flows(scheme: dict[str, Any]) -> dict[str, Any]:
+    """Convert Swagger 2.0 OAuth2 flow types to OpenAPI 3.0 flow names."""
+    flow_type = scheme.get("flow", "")
+    flow: dict[str, Any] = {}
+
+    if scheme.get("scopes"):
+        flow["scopes"] = scheme["scopes"]
+
+    # Map old flow names to new
+    flow_name_map = {
+        "implicit": "implicit",
+        "password": "password",
+        "application": "clientCredentials",
+        "accessCode": "authorizationCode",
+    }
+    flow_name = flow_name_map.get(flow_type, flow_type)
+
+    # Map URLs
+    if scheme.get("authorizationUrl"):
+        flow["authorizationUrl"] = scheme["authorizationUrl"]
+    if scheme.get("tokenUrl"):
+        flow["tokenUrl"] = scheme["tokenUrl"]
+
+    return {flow_name: flow}
+
+
+def _resolve_content_types(
+    consumes: list[str], *, is_body: bool = False
+) -> list[str]:
+    """Resolve content types from Swagger 2.0 consumes/produces list.
+
+    Returns a list of valid content types for OpenAPI 3.0.
+    """
+    if not consumes:
+        return ["application/json"]
+
+    result = []
+    for ct in consumes:
+        # Skip form-related types for body params (they belong to formData)
+        if is_body and ct in (
+            "multipart/form-data",
+            "application/x-www-form-urlencoded",
+        ):
+            continue
+        result.append(ct)
+
+    return result or ["application/json"]
+
+
+def _convert_collection_format(
+    fmt: str,
+) -> tuple[str | None, bool]:
+    """Convert Swagger 2.0 collectionFormat to OpenAPI 3.0 style/explode."""
+    mapping = {
+        "csv": ("form", False),
+        "ssv": ("spaceDelimited", False),
+        "tsv": ("pipeDelimited", False),  # closest approximation
+        "pipes": ("pipeDelimited", False),
+        "multi": ("form", True),
+    }
+    style, explode = mapping.get(fmt, (None, False))
+    return style, explode

mcp_restful_wrapper-0.1.0/src/mcp_restful_wrapper/spec_fetcher.py

@@ -0,0 +1,55 @@
+"""Fetch and parse OpenAPI/Swagger specifications from URLs."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+
+async def fetch_spec(url: str) -> dict[str, Any]:
+    """Fetch an API specification from a URL and parse it as JSON or YAML.
+
+    Args:
+        url: The URL to fetch the specification from.
+
+    Returns:
+        The parsed specification as a dictionary.
+
+    Raises:
+        httpx.HTTPStatusError: If the HTTP request fails.
+        ValueError: If the response cannot be parsed as JSON or YAML.
+    """
+    async with httpx.AsyncClient(timeout=30, follow_redirects=True) as client:
+        response = await client.get(url)
+        response.raise_for_status()
+
+    content_type = response.headers.get("content-type", "")
+    text = response.text
+
+    # Try JSON first
+    if "json" in content_type or url.endswith(".json"):
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            pass
+
+    # Fall back to YAML
+    try:
+        import yaml
+
+        result = yaml.safe_load(text)
+        if isinstance(result, dict):
+            return result
+    except Exception:
+        pass
+
+    # Last resort: try JSON again (some servers return JSON with wrong content-type)
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        raise ValueError(
+            f"Failed to parse spec from {url} as JSON or YAML. "
+            f"Content-Type: {content_type}"
+        )