yapi-mcp 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

yapi_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""YApi MCP Server - Model Context Protocol adapter for YApi."""
+
+from yapi_mcp.server import main, mcp
+
+__all__ = ["main", "mcp"]

yapi_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for running yapi-mcp as a module: python -m yapi_mcp."""
+
+from yapi_mcp.server import main
+
+if __name__ == "__main__":
+    main()

config.py → yapi_mcp/config.py

@@ -1,48 +1,48 @@
-"""Configuration management for YApi MCP Server."""
-
-from pydantic import Field, HttpUrl
-from pydantic_settings import BaseSettings, SettingsConfigDict
-
-
-class ServerConfig(BaseSettings):
-    """YApi MCP Server configuration loaded from environment variables or .env file."""
-
-    model_config = SettingsConfigDict(
-        env_file=".env",
-        env_file_encoding="utf-8",
-        case_sensitive=False,
-    )
-
-    yapi_server_url: HttpUrl = Field(
-        ...,
-        description="YApi server base URL",
-        examples=["https://yapi.example.com"],
-    )
-
-    yapi_token: str = Field(
-        ...,
-        min_length=1,
-        description="YApi authentication token (_yapi_token cookie)",
-    )
-
-    yapi_uid: str = Field(
-        ...,
-        min_length=1,
-        description="YApi user ID (_yapi_uid cookie)",
-    )
-
-    yapi_cas: str | None = Field(
-        default=None,
-        description="Optional CAS authentication cookie (e.g., ZYBIPSCAS for custom deployments)",
-    )
-
-    @property
-    def cookies(self) -> dict[str, str]:
-        """Return cookies dictionary for YApi API authentication."""
-        cookies = {
-            "_yapi_token": self.yapi_token,
-            "_yapi_uid": self.yapi_uid,
-        }
-        if self.yapi_cas:
-            cookies["ZYBIPSCAS"] = self.yapi_cas
-        return cookies
+"""Configuration management for YApi MCP Server."""
+
+from pydantic import Field, HttpUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class ServerConfig(BaseSettings):
+    """YApi MCP Server configuration loaded from environment variables or .env file."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+    )
+
+    yapi_server_url: HttpUrl = Field(
+        ...,
+        description="YApi server base URL",
+        examples=["https://yapi.example.com"],
+    )
+
+    yapi_token: str = Field(
+        ...,
+        min_length=1,
+        description="YApi authentication token (_yapi_token cookie)",
+    )
+
+    yapi_uid: str = Field(
+        ...,
+        min_length=1,
+        description="YApi user ID (_yapi_uid cookie)",
+    )
+
+    yapi_cas: str | None = Field(
+        default=None,
+        description="Optional CAS authentication cookie (e.g., ZYBIPSCAS for custom deployments)",
+    )
+
+    @property
+    def cookies(self) -> dict[str, str]:
+        """Return cookies dictionary for YApi API authentication."""
+        cookies = {
+            "_yapi_token": self.yapi_token,
+            "_yapi_uid": self.yapi_uid,
+        }
+        if self.yapi_cas:
+            cookies["ZYBIPSCAS"] = self.yapi_cas
+        return cookies

yapi_mcp/server.py

@@ -0,0 +1,185 @@
+"""YApi MCP Server - Main server module with fastmcp."""
+
+import json
+from functools import cache
+from typing import Annotated
+
+import httpx
+from fastmcp import FastMCP
+
+from yapi_mcp.config import ServerConfig
+from yapi_mcp.yapi.client import YApiClient
+from yapi_mcp.yapi.errors import map_http_error_to_mcp
+
+
+class MCPToolError(RuntimeError):
+    """Base exception for MCP tool failures."""
+
+
+class MCPHTTPError(MCPToolError):
+    """Exception raised when YApi returns an HTTP error."""
+
+
+class MCPValidationError(MCPToolError):
+    """Exception raised when tool input validation fails."""
+
+
+class InvalidInterfacePathError(ValueError):
+    """Raised when an interface path does not start with a slash."""
+
+    def __init__(self) -> None:
+        super().__init__("接口路径必须以 / 开头")
+
+
+def _http_error_to_tool_error(error: httpx.HTTPStatusError) -> MCPHTTPError:
+    mcp_error = map_http_error_to_mcp(error)
+    return MCPHTTPError(mcp_error.message)
+
+
+def _wrap_validation_error(error: ValueError) -> MCPValidationError:
+    message = f"参数验证失败: {error!s}"
+    return MCPValidationError(message)
+
+
+def _wrap_tool_error(prefix: str, error: Exception) -> MCPToolError:
+    message = f"{prefix}: {error!s}"
+    return MCPToolError(message)
+
+
+def _ensure_path_starts_with_slash(path: str) -> None:
+    if not path.startswith("/"):
+        raise InvalidInterfacePathError
+
+
+SEARCH_INTERFACES_ERROR = "搜索接口失败"
+GET_INTERFACE_ERROR = "获取接口失败"
+SAVE_INTERFACE_ERROR = "保存接口失败"
+
+
+# Initialize MCP server
+mcp = FastMCP(
+    "YApi MCP Server",
+    version="0.1.0",
+)
+
+
+@cache
+def get_config() -> ServerConfig:
+    """Get or create ServerConfig instance (cached)."""
+    return ServerConfig()
+
+
+# Tool implementations will be added in subsequent tasks (T019-T022)
+
+
+@mcp.tool()
+async def yapi_search_interfaces(
+    project_id: Annotated[int, "YApi 项目 ID"],
+    keyword: Annotated[str, "搜索关键词(匹配接口标题/路径/描述)"],
+) -> str:
+    """在指定 YApi 项目中搜索接口,支持按标题、路径、描述模糊匹配."""
+    config = get_config()
+    try:
+        async with YApiClient(str(config.yapi_server_url), config.cookies) as client:
+            results = await client.search_interfaces(project_id, keyword)
+            # Return JSON string with search results
+            return json.dumps(
+                [result.model_dump(by_alias=True) for result in results],
+                ensure_ascii=False,
+                indent=2,
+            )
+    except MCPToolError:
+        raise
+    except httpx.HTTPStatusError as exc:
+        raise _http_error_to_tool_error(exc) from exc
+    except Exception as exc:
+        prefix = SEARCH_INTERFACES_ERROR
+        raise _wrap_tool_error(prefix, exc) from exc
+
+
+@mcp.tool()
+async def yapi_get_interface(
+    interface_id: Annotated[int, "接口 ID"],
+) -> str:
+    """获取 YApi 接口的完整定义(包括请求参数、响应结构、描述等)."""
+    config = get_config()
+    try:
+        async with YApiClient(str(config.yapi_server_url), config.cookies) as client:
+            interface = await client.get_interface(interface_id)
+            return json.dumps(
+                interface.model_dump(by_alias=True),
+                ensure_ascii=False,
+                indent=2,
+            )
+    except MCPToolError:
+        raise
+    except httpx.HTTPStatusError as exc:
+        raise _http_error_to_tool_error(exc) from exc
+    except Exception as exc:
+        prefix = GET_INTERFACE_ERROR
+        raise _wrap_tool_error(prefix, exc) from exc
+
+
+@mcp.tool()
+async def yapi_save_interface(
+    catid: Annotated[int, "分类 ID (必需)"],
+    project_id: Annotated[int | None, "项目 ID (创建时必需)"] = None,
+    interface_id: Annotated[int | None, "接口 ID (有值=更新,无值=创建)"] = None,
+    title: Annotated[str | None, "接口标题 (创建时必需)"] = None,
+    path: Annotated[str | None, "接口路径 (创建时必需,以/开头)"] = None,
+    method: Annotated[str | None, "HTTP方法 (创建时必需)"] = None,
+    req_body: Annotated[str, "请求参数(JSON字符串)"] = "",
+    res_body: Annotated[str, "响应结构(JSON字符串)"] = "",
+    desc: Annotated[str, "接口描述"] = "",
+    req_body_type: Annotated[str | None, "请求体类型(form/json/raw/file)"] = None,
+    req_body_is_json_schema: Annotated[bool | None, "请求体是否为JSON Schema"] = None,
+    res_body_type: Annotated[str | None, "响应体类型(json/raw)"] = None,
+    res_body_is_json_schema: Annotated[bool | None, "响应体是否为JSON Schema"] = None,
+) -> str:
+    """保存 YApi 接口定义。interface_id 有值则更新,无值则创建新接口。"""
+    config = get_config()
+    try:
+        if path is not None:
+            _ensure_path_starts_with_slash(path)
+
+        async with YApiClient(str(config.yapi_server_url), config.cookies) as client:
+            result = await client.save_interface(
+                catid=catid,
+                project_id=project_id,
+                interface_id=interface_id,
+                title=title,
+                path=path,
+                method=method,
+                req_body=req_body,
+                res_body=res_body,
+                desc=desc,
+                req_body_type=req_body_type,
+                req_body_is_json_schema=req_body_is_json_schema,
+                res_body_type=res_body_type,
+                res_body_is_json_schema=res_body_is_json_schema,
+            )
+            action = result["action"]
+            iface_id = result["interface_id"]
+            message = "接口创建成功" if action == "created" else "接口更新成功"
+            return json.dumps(
+                {"action": action, "interface_id": iface_id, "message": message},
+                ensure_ascii=False,
+            )
+    except MCPToolError:
+        raise
+    except httpx.HTTPStatusError as exc:
+        raise _http_error_to_tool_error(exc) from exc
+    except ValueError as exc:
+        raise _wrap_validation_error(exc) from exc
+    except Exception as exc:
+        prefix = SAVE_INTERFACE_ERROR
+        raise _wrap_tool_error(prefix, exc) from exc
+
+
+def main() -> None:
+    """Entry point for uvx yapi-mcp command."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

{tools → yapi_mcp/tools}/__init__.py

@@ -1 +1 @@
-"""MCP tools implementation."""
+"""MCP tools implementation."""

{yapi → yapi_mcp/yapi}/__init__.py

@@ -1 +1 @@
-"""YApi API client module."""
+"""YApi API client module."""

yapi_mcp/yapi/client.py

@@ -0,0 +1,259 @@
+"""YApi API HTTP client implementation."""
+
+from typing import Any, NoReturn
+
+import httpx
+
+from .models import YApiErrorResponse, YApiInterface, YApiInterfaceSummary
+
+
+def _raise_yapi_api_error(response: httpx.Response, error: YApiErrorResponse) -> NoReturn:
+    message = f"YApi API error: {error.errmsg} (code: {error.errcode})"
+    raise httpx.HTTPStatusError(
+        message,
+        request=response.request,
+        response=response,
+    )
+
+
+class YApiClient:
+    """Async HTTP client for YApi API with cookie-based authentication."""
+
+    def __init__(self, base_url: str, cookies: dict[str, str], timeout: float = 10.0) -> None:
+        """Initialize YApi client.
+
+        Args:
+            base_url: YApi server base URL (e.g., "https://yapi.example.com")
+            cookies: Authentication cookies dict with _yapi_token, _yapi_uid, ZYBIPSCAS
+            timeout: Request timeout in seconds (default: 10.0)
+        """
+        self.base_url = base_url.rstrip("/")
+        self.client = httpx.AsyncClient(
+            base_url=f"{self.base_url}/api",
+            cookies=cookies,
+            timeout=timeout,
+            follow_redirects=True,
+        )
+
+    async def __aenter__(self) -> "YApiClient":
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        """Async context manager exit - close HTTP client."""
+        await self.client.aclose()
+
+    async def close(self) -> None:
+        """Close the HTTP client connection."""
+        await self.client.aclose()
+
+    def _check_response(self, response: httpx.Response) -> None:
+        """Check YApi API response for errors and raise appropriate exceptions.
+
+        Args:
+            response: httpx Response object
+
+        Raises:
+            httpx.HTTPStatusError: For HTTP-level errors (4xx, 5xx)
+        """
+        # First check HTTP status codes
+        response.raise_for_status()
+
+        # Then check YApi API-level errors (errcode != 0)
+        try:
+            data = response.json()
+            if isinstance(data, dict) and "errcode" in data and data["errcode"] != 0:
+                error = YApiErrorResponse(**data)
+                # YApi returns errcode != 0 for business logic errors
+                # Treat these as HTTP-equivalent errors
+                _raise_yapi_api_error(response, error)
+        except (ValueError, KeyError):
+            # Not a JSON response or doesn't have errcode - proceed normally
+            pass
+
+    async def search_interfaces(
+        self, project_id: int, keyword: str
+    ) -> list[YApiInterfaceSummary]:
+        """Search interfaces in a YApi project.
+
+        使用 list_menu 接口获取项目下全量接口，突破 50 条限制。
+        支持按接口标题、路径、描述、分类名进行搜索。
+
+        Args:
+            project_id: YApi project ID
+            keyword: Search keyword (matches title, path, description, category name)
+
+        Returns:
+            List of matching interface summaries
+
+        Raises:
+            httpx.HTTPStatusError: For authentication, permission, or server errors
+        """
+        # 使用 list_menu 接口获取全量接口（无分页限制）
+        response = await self.client.get(
+            "/interface/list_menu",
+            params={"project_id": project_id},
+        )
+        self._check_response(response)
+
+        data = response.json()
+        categories = data.get("data", [])
+
+        # 展开树形结构为扁平列表，同时记录分类名
+        interfaces: list[dict] = []
+        for cat in categories:
+            cat_name = cat.get("name", "")
+            for iface in cat.get("list", []):
+                # 将分类名注入到接口数据中，用于搜索
+                iface["_cat_name"] = cat_name
+                interfaces.append(iface)
+
+        # 客户端关键词过滤（支持分类名搜索）
+        if keyword:
+            keyword_lower = keyword.lower()
+            interfaces = [
+                iface
+                for iface in interfaces
+                if keyword_lower in iface.get("title", "").lower()
+                or keyword_lower in iface.get("path", "").lower()
+                or keyword_lower in iface.get("desc", "").lower()
+                or keyword_lower in iface.get("_cat_name", "").lower()
+            ]
+
+        return [YApiInterfaceSummary(**iface) for iface in interfaces]
+
+    async def get_interface(self, interface_id: int) -> YApiInterface:
+        """Get complete interface definition by ID.
+
+        Args:
+            interface_id: YApi interface ID
+
+        Returns:
+            Complete interface definition
+
+        Raises:
+            httpx.HTTPStatusError: For authentication, not found, or server errors
+        """
+        response = await self.client.get("/interface/get", params={"id": interface_id})
+        self._check_response(response)
+
+        data = response.json()
+        return YApiInterface(**data["data"])
+
+    async def save_interface(
+        self,
+        catid: int,
+        project_id: int | None = None,
+        interface_id: int | None = None,
+        title: str | None = None,
+        path: str | None = None,
+        method: str | None = None,
+        req_body: str = "",
+        res_body: str = "",
+        desc: str = "",
+        req_body_type: str | None = None,
+        req_body_is_json_schema: bool | None = None,
+        res_body_type: str | None = None,
+        res_body_is_json_schema: bool | None = None,
+    ) -> dict[str, Any]:
+        """Save interface definition (create or update).
+
+        If interface_id is provided, update the existing interface.
+        If interface_id is not provided, create a new interface.
+
+        Args:
+            catid: Category ID (required for both create and update)
+            project_id: Project ID (required for create)
+            interface_id: Interface ID (if provided, update; otherwise create)
+            title: Interface title (required for create)
+            path: Interface path, must start with / (required for create)
+            method: HTTP method (required for create)
+            req_body: Request body definition (JSON string, optional)
+            res_body: Response body definition (JSON string, optional)
+            desc: Interface description (optional)
+            req_body_type: Request body type (form, json, raw, file)
+            req_body_is_json_schema: Whether req_body is JSON Schema format
+            res_body_type: Response body type (json, raw)
+            res_body_is_json_schema: Whether res_body is JSON Schema format
+
+        Returns:
+            dict with keys: action ("created" or "updated"), interface_id (int)
+
+        Raises:
+            ValueError: When required parameters are missing for create mode
+            httpx.HTTPStatusError: For validation, permission, or server errors
+        """
+        if interface_id is None:
+            # 创建模式：校验必填参数
+            missing = []
+            if project_id is None:
+                missing.append("project_id")
+            if title is None:
+                missing.append("title")
+            if path is None:
+                missing.append("path")
+            if method is None:
+                missing.append("method")
+            if missing:
+                msg = f"创建接口需要以下参数: {', '.join(missing)}"
+                raise ValueError(msg)
+
+            # 调用创建 API
+            payload: dict[str, Any] = {
+                "project_id": project_id,
+                "catid": catid,
+                "title": title,
+                "path": path,
+                "method": method.upper(),  # type: ignore[union-attr]
+            }
+
+            if req_body:
+                payload["req_body_other"] = req_body
+                payload["req_body_type"] = req_body_type if req_body_type else "json"
+                payload["req_body_is_json_schema"] = (
+                    req_body_is_json_schema if req_body_is_json_schema is not None else True
+                )
+            if res_body:
+                payload["res_body"] = res_body
+                payload["res_body_type"] = res_body_type if res_body_type else "json"
+                payload["res_body_is_json_schema"] = (
+                    res_body_is_json_schema if res_body_is_json_schema is not None else True
+                )
+            if desc:
+                payload["desc"] = desc
+
+            response = await self.client.post("/interface/add", json=payload)
+            self._check_response(response)
+
+            data = response.json()
+            return {"action": "created", "interface_id": int(data["data"]["_id"])}
+
+        # 更新模式
+        payload = {"id": interface_id, "catid": catid}
+
+        if title is not None:
+            payload["title"] = title
+        if path is not None:
+            payload["path"] = path
+        if method is not None:
+            payload["method"] = method.upper()
+        if req_body:
+            payload["req_body_other"] = req_body
+        if res_body:
+            payload["res_body"] = res_body
+        if desc is not None:
+            payload["desc"] = desc
+        # 类型标记参数独立设置（不依赖内容参数）
+        if req_body_type is not None:
+            payload["req_body_type"] = req_body_type
+        if req_body_is_json_schema is not None:
+            payload["req_body_is_json_schema"] = req_body_is_json_schema
+        if res_body_type is not None:
+            payload["res_body_type"] = res_body_type
+        if res_body_is_json_schema is not None:
+            payload["res_body_is_json_schema"] = res_body_is_json_schema
+
+        response = await self.client.post("/interface/up", json=payload)
+        self._check_response(response)
+
+        return {"action": "updated", "interface_id": interface_id}

{yapi → yapi_mcp/yapi}/errors.py

@@ -1,14 +1,33 @@
 """Error mapping from YApi/HTTP errors to MCP errors."""
 
-from typing import Any
+from collections.abc import Mapping, MutableMapping
 
 import httpx
 
+ErrorData = MutableMapping[str, object]
+
+HTTP_STATUS_UNAUTHORIZED = 401
+HTTP_STATUS_NOT_FOUND = 404
+HTTP_STATUS_FORBIDDEN = 403
+HTTP_STATUS_SERVER_ERROR = 500
+HTTP_STATUS_BAD_REQUEST = 400
+
+MCP_CODE_AUTH_FAILED = -32001
+MCP_CODE_NOT_FOUND = -32002
+MCP_CODE_FORBIDDEN = -32003
+MCP_CODE_SERVER_ERROR = -32000
+MCP_CODE_INVALID_PARAMS = -32602
+
 
 class MCPError(Exception):
     """MCP protocol error with error code and optional data."""
 
-    def __init__(self, code: int, message: str, data: Any = None) -> None:
+    def __init__(
+        self,
+        code: int,
+        message: str,
+        data: ErrorData | None = None,
+    ) -> None:
         """Initialize MCP error.
 
         Args:
@@ -21,9 +40,9 @@ class MCPError(Exception):
         self.message = message
         self.data = data
 
-    def to_dict(self) -> dict[str, Any]:
+    def to_dict(self) -> dict[str, object]:
         """Convert to MCP error response dict."""
-        result: dict[str, Any] = {"code": self.code, "message": self.message}
+        result: dict[str, object] = {"code": self.code, "message": self.message}
         if self.data is not None:
             result["data"] = self.data
         return result
@@ -49,49 +68,52 @@ def map_http_error_to_mcp(error: httpx.HTTPStatusError) -> MCPError:
     status_code = error.response.status_code
 
     # Try to extract YApi error details from response
-    error_data: dict[str, Any] = {"http_status": status_code}
+    error_data: ErrorData = {"http_status": status_code}
     try:
         yapi_error = error.response.json()
-        if isinstance(yapi_error, dict):
-            error_data["yapi_error"] = yapi_error
+        if isinstance(yapi_error, Mapping):
+            error_data["yapi_error"] = dict(yapi_error)
     except Exception:
         # If response is not JSON, include response text
         error_data["response_text"] = error.response.text[:200]
 
     # Map HTTP status codes to MCP error codes
-    if status_code == 401:
+    if status_code == HTTP_STATUS_UNAUTHORIZED:
         return MCPError(
-            code=-32001,
+            code=MCP_CODE_AUTH_FAILED,
             message="认证失败: Cookie 无效或过期",
             data=error_data,
         )
-    if status_code == 404:
+    if status_code == HTTP_STATUS_NOT_FOUND:
+        errmsg = error_data.get("yapi_error", {}).get("errmsg", "Resource not found")
         return MCPError(
-            code=-32002,
-            message=f"资源不存在: {error_data.get('yapi_error', {}).get('errmsg', 'Resource not found')}",
+            code=MCP_CODE_NOT_FOUND,
+            message=f"资源不存在: {errmsg}",
             data=error_data,
         )
-    if status_code == 403:
+    if status_code == HTTP_STATUS_FORBIDDEN:
         return MCPError(
-            code=-32003,
+            code=MCP_CODE_FORBIDDEN,
             message="权限不足: 无法操作该项目/接口",
             data=error_data,
         )
-    if status_code >= 500:
+    if status_code >= HTTP_STATUS_SERVER_ERROR:
+        errmsg = error_data.get("yapi_error", {}).get("errmsg", "Internal server error")
         return MCPError(
-            code=-32000,
-            message=f"YApi 服务器错误: {error_data.get('yapi_error', {}).get('errmsg', 'Internal server error')}",
+            code=MCP_CODE_SERVER_ERROR,
+            message=f"YApi 服务器错误: {errmsg}",
             data=error_data,
         )
-    if status_code == 400:
+    if status_code == HTTP_STATUS_BAD_REQUEST:
+        errmsg = error_data.get("yapi_error", {}).get("errmsg", "Bad request")
         return MCPError(
-            code=-32602,
-            message=f"Invalid params: {error_data.get('yapi_error', {}).get('errmsg', 'Bad request')}",
+            code=MCP_CODE_INVALID_PARAMS,
+            message=f"Invalid params: {errmsg}",
             data=error_data,
         )
     # Other 4xx errors
     return MCPError(
-        code=-32602,
+        code=MCP_CODE_INVALID_PARAMS,
         message=f"Invalid params: HTTP {status_code}",
         data=error_data,
     )