yapi-mcp 0.1.0__py3-none-any.whl

__init__.py

@@ -0,0 +1 @@
+"""YApi MCP Server - Model Context Protocol adapter for YApi."""

config.py

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

server.py

@@ -0,0 +1,148 @@
+"""YApi MCP Server - Main server module with fastmcp."""
+
+import json
+from typing import Annotated
+
+import httpx
+from fastmcp import FastMCP
+
+from config import ServerConfig
+from yapi.client import YApiClient
+from yapi.errors import map_http_error_to_mcp
+
+# Initialize MCP server
+mcp = FastMCP(
+    "YApi MCP Server",
+    version="0.1.0",
+)
+
+
+def get_config() -> ServerConfig:
+    """Get or create ServerConfig instance (lazy loading)."""
+    if not hasattr(get_config, "_instance"):
+        get_config._instance = ServerConfig()
+    return get_config._instance
+
+
+# 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 httpx.HTTPStatusError as e:
+        mcp_error = map_http_error_to_mcp(e)
+        raise Exception(mcp_error.message) from e
+    except Exception as e:
+        raise Exception(f"搜索接口失败: {e!s}") from e
+
+
+@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 httpx.HTTPStatusError as e:
+        mcp_error = map_http_error_to_mcp(e)
+        raise Exception(mcp_error.message) from e
+    except Exception as e:
+        raise Exception(f"获取接口失败: {e!s}") from e
+
+
+@mcp.tool()
+async def yapi_create_interface(
+    project_id: Annotated[int, "项目 ID"],
+    title: Annotated[str, "接口标题"],
+    path: Annotated[str, "接口路径(以 / 开头)"],
+    method: Annotated[str, "HTTP 方法(GET/POST/PUT/DELETE等)"],
+    req_body: Annotated[str, "请求参数(JSON 字符串,可选)"] = "",
+    res_body: Annotated[str, "响应结构(JSON 字符串,可选)"] = "",
+    desc: Annotated[str, "接口描述(可选)"] = "",
+) -> str:
+    """在 YApi 项目中创建新接口定义."""
+    config = get_config()
+    try:
+        # Validate path starts with /
+        if not path.startswith("/"):
+            raise ValueError("接口路径必须以 / 开头")
+
+        async with YApiClient(str(config.yapi_server_url), config.cookies) as client:
+            interface_id = await client.create_interface(
+                project_id, title, path, method, req_body, res_body, desc
+            )
+            return json.dumps(
+                {"interface_id": interface_id},
+                ensure_ascii=False,
+            )
+    except httpx.HTTPStatusError as e:
+        mcp_error = map_http_error_to_mcp(e)
+        raise Exception(mcp_error.message) from e
+    except ValueError as e:
+        raise Exception(f"参数验证失败: {e!s}") from e
+    except Exception as e:
+        raise Exception(f"创建接口失败: {e!s}") from e
+
+
+@mcp.tool()
+async def yapi_update_interface(
+    interface_id: Annotated[int, "接口 ID"],
+    title: Annotated[str | None, "更新的标题"] = None,
+    path: Annotated[str | None, "更新的路径"] = None,
+    method: Annotated[str | None, "更新的 HTTP 方法"] = None,
+    req_body: Annotated[str | None, "更新的请求参数"] = None,
+    res_body: Annotated[str | None, "更新的响应结构"] = None,
+    desc: Annotated[str | None, "更新的描述"] = None,
+) -> str:
+    """增量更新 YApi 接口定义(仅更新提供的字段)."""
+    config = get_config()
+    try:
+        # Validate path if provided
+        if path is not None and not path.startswith("/"):
+            raise ValueError("接口路径必须以 / 开头")
+
+        async with YApiClient(str(config.yapi_server_url), config.cookies) as client:
+            success = await client.update_interface(
+                interface_id, title, path, method, req_body, res_body, desc
+            )
+            return json.dumps(
+                {"success": success, "message": "接口更新成功"},
+                ensure_ascii=False,
+            )
+    except httpx.HTTPStatusError as e:
+        mcp_error = map_http_error_to_mcp(e)
+        raise Exception(mcp_error.message) from e
+    except ValueError as e:
+        raise Exception(f"参数验证失败: {e!s}") from e
+    except Exception as e:
+        raise Exception(f"更新接口失败: {e!s}") from e
+
+
+def main() -> None:
+    """Entry point for uvx yapi-mcp command."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

tools/__init__.py

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

yapi/__init__.py

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

yapi/client.py

@@ -0,0 +1,206 @@
+"""YApi API HTTP client implementation."""
+
+from typing import Any
+
+import httpx
+
+from .models import YApiErrorResponse, YApiInterface, YApiInterfaceSummary
+
+
+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 httpx.HTTPStatusError(
+                    f"YApi API error: {error.errmsg} (code: {error.errcode})",
+                    request=response.request,
+                    response=response,
+                )
+        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.
+
+        Args:
+            project_id: YApi project ID
+            keyword: Search keyword (matches title, path, description)
+
+        Returns:
+            List of interface summaries (max 50 results)
+
+        Raises:
+            httpx.HTTPStatusError: For authentication, permission, or server errors
+        """
+        response = await self.client.post(
+            "/interface/list",
+            json={"project_id": project_id, "q": keyword},
+        )
+        self._check_response(response)
+
+        data = response.json()
+        interfaces = data.get("data", {}).get("list", [])
+
+        # Limit to 50 results as per specification
+        return [YApiInterfaceSummary(**iface) for iface in interfaces[:50]]
+
+    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 create_interface(
+        self,
+        project_id: int,
+        title: str,
+        path: str,
+        method: str,
+        req_body: str = "",
+        res_body: str = "",
+        desc: str = "",
+    ) -> int:
+        """Create a new interface in YApi project.
+
+        Args:
+            project_id: Project ID
+            title: Interface title
+            path: Interface path (must start with /)
+            method: HTTP method (GET, POST, etc.)
+            req_body: Request body definition (JSON string, optional)
+            res_body: Response body definition (JSON string, optional)
+            desc: Interface description (optional)
+
+        Returns:
+            Created interface ID
+
+        Raises:
+            httpx.HTTPStatusError: For validation, permission, or server errors
+        """
+        payload: dict[str, Any] = {
+            "project_id": project_id,
+            "title": title,
+            "path": path,
+            "method": method.upper(),
+        }
+
+        if req_body:
+            payload["req_body_other"] = req_body
+        if res_body:
+            payload["res_body"] = res_body
+        if desc:
+            payload["desc"] = desc
+
+        response = await self.client.post("/interface/add", json=payload)
+        self._check_response(response)
+
+        data = response.json()
+        return int(data["data"]["_id"])
+
+    async def update_interface(
+        self,
+        interface_id: int,
+        title: str | None = None,
+        path: str | None = None,
+        method: str | None = None,
+        req_body: str | None = None,
+        res_body: str | None = None,
+        desc: str | None = None,
+    ) -> bool:
+        """Update an existing interface (partial update).
+
+        Args:
+            interface_id: Interface ID to update
+            title: New title (optional)
+            path: New path (optional)
+            method: New HTTP method (optional)
+            req_body: New request body definition (optional)
+            res_body: New response body definition (optional)
+            desc: New description (optional)
+
+        Returns:
+            True if update succeeded
+
+        Raises:
+            httpx.HTTPStatusError: For validation, permission, not found, or server errors
+        """
+        # Start with interface ID
+        payload: dict[str, Any] = {"id": interface_id}
+
+        # Add only provided fields (partial update)
+        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 is not None:
+            payload["req_body_other"] = req_body
+        if res_body is not None:
+            payload["res_body"] = res_body
+        if desc is not None:
+            payload["desc"] = desc
+
+        response = await self.client.post("/interface/up", json=payload)
+        self._check_response(response)
+
+        return True

yapi/errors.py

@@ -0,0 +1,97 @@
+"""Error mapping from YApi/HTTP errors to MCP errors."""
+
+from typing import Any
+
+import httpx
+
+
+class MCPError(Exception):
+    """MCP protocol error with error code and optional data."""
+
+    def __init__(self, code: int, message: str, data: Any = None) -> None:
+        """Initialize MCP error.
+
+        Args:
+            code: MCP error code (negative integer)
+            message: Human-readable error message
+            data: Optional additional error data
+        """
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.data = data
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to MCP error response dict."""
+        result: dict[str, Any] = {"code": self.code, "message": self.message}
+        if self.data is not None:
+            result["data"] = self.data
+        return result
+
+
+def map_http_error_to_mcp(error: httpx.HTTPStatusError) -> MCPError:
+    """Map HTTP status errors to MCP error codes.
+
+    Error code mapping:
+    - 401 Unauthorized → -32001 (Authentication failed)
+    - 404 Not Found → -32002 (Resource not found)
+    - 403 Forbidden → -32003 (Permission denied)
+    - 500+ Server Error → -32000 (Server error)
+    - 400 Bad Request → -32602 (Invalid params)
+    - Other 4xx → -32602 (Invalid params)
+
+    Args:
+        error: httpx HTTPStatusError exception
+
+    Returns:
+        MCPError with appropriate code and message
+    """
+    status_code = error.response.status_code
+
+    # Try to extract YApi error details from response
+    error_data: dict[str, Any] = {"http_status": status_code}
+    try:
+        yapi_error = error.response.json()
+        if isinstance(yapi_error, dict):
+            error_data["yapi_error"] = 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:
+        return MCPError(
+            code=-32001,
+            message="认证失败: Cookie 无效或过期",
+            data=error_data,
+        )
+    if status_code == 404:
+        return MCPError(
+            code=-32002,
+            message=f"资源不存在: {error_data.get('yapi_error', {}).get('errmsg', 'Resource not found')}",
+            data=error_data,
+        )
+    if status_code == 403:
+        return MCPError(
+            code=-32003,
+            message="权限不足: 无法操作该项目/接口",
+            data=error_data,
+        )
+    if status_code >= 500:
+        return MCPError(
+            code=-32000,
+            message=f"YApi 服务器错误: {error_data.get('yapi_error', {}).get('errmsg', 'Internal server error')}",
+            data=error_data,
+        )
+    if status_code == 400:
+        return MCPError(
+            code=-32602,
+            message=f"Invalid params: {error_data.get('yapi_error', {}).get('errmsg', 'Bad request')}",
+            data=error_data,
+        )
+    # Other 4xx errors
+    return MCPError(
+        code=-32602,
+        message=f"Invalid params: HTTP {status_code}",
+        data=error_data,
+    )

yapi/models.py

@@ -0,0 +1,60 @@
+"""Pydantic models for YApi API data structures."""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class YApiInterface(BaseModel):
+    """YApi interface complete definition from API responses."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: int = Field(..., alias="_id", description="Interface ID")
+    title: str = Field(..., description="Interface title")
+    path: str = Field(..., description="Interface path", examples=["/api/user/login"])
+
+    method: Literal["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"] = Field(
+        ...,
+        description="HTTP method",
+    )
+
+    project_id: int = Field(..., description="Project ID this interface belongs to")
+
+    desc: str | None = Field(None, description="Interface description")
+    req_body_other: str | None = Field(
+        None, description="Request parameters definition (JSON string)"
+    )
+    res_body: str | None = Field(None, description="Response structure definition (JSON string)")
+    status: str | None = Field(None, description="Status code")
+
+    add_time: int | None = Field(None, description="Creation timestamp (Unix epoch)")
+    up_time: int | None = Field(None, description="Last update timestamp (Unix epoch)")
+
+
+class YApiInterfaceSummary(BaseModel):
+    """YApi interface summary from search results."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: int = Field(..., alias="_id", description="Interface ID")
+    title: str = Field(..., description="Interface title")
+    path: str = Field(..., description="Interface path")
+    method: str = Field(..., description="HTTP method")
+
+
+class YApiErrorResponse(BaseModel):
+    """YApi API error response structure."""
+
+    errcode: int = Field(..., description="Error code (non-zero indicates error)")
+    errmsg: str = Field(..., description="Error message")
+
+
+class YApiProject(BaseModel):
+    """YApi project information (optional, for future use)."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: int = Field(..., alias="_id", description="Project ID")
+    name: str = Field(..., description="Project name")
+    desc: str | None = Field(None, description="Project description")

yapi_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,394 @@
+Metadata-Version: 2.4
+Name: yapi-mcp
+Version: 0.1.0
+Summary: Model Context Protocol server for YApi 1.12.0 API management platform
+Author: YApi MCP Team
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic-settings>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# YApi MCP Server
+
+[![CI](https://github.com/YOUR_USERNAME/yapi-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/YOUR_USERNAME/yapi-mcp/actions/workflows/ci.yml)
+[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+基于 [YApi 1.12.0](https://github.com/YMFE/yapi) 接口管理平台的 Model Context Protocol (MCP) 服务器。
+
+使开发者能够在支持 MCP 的 IDE 和编辑器(Claude Code、Cursor 等)中直接搜索、查看、创建和更新 YApi 接口定义,无需离开开发环境。
+
+## 功能特性
+
+- 🔍 **搜索接口**: 通过标题、路径或描述查找 API 端点
+- 📖 **查看定义**: 获取完整的接口规范,包括请求/响应结构
+- ➕ **创建接口**: 向 YApi 项目添加新的 API 定义
+- ✏️ **更新接口**: 修改现有接口配置
+- 🔐 **Cookie 认证**: 基于会话的安全认证
+- ⚡ **异步性能**: 基于 httpx 实现高效的并发操作
+
+## 环境要求
+
+- Python 3.11 或更高版本
+- YApi 1.12.0 实例(可通过 HTTP/HTTPS 访问)
+- 有效的 YApi 认证 cookies
+
+## 安装
+
+### 使用 uvx(推荐)
+
+[uvx](https://github.com/astral-sh/uv) 允许在不管理虚拟环境的情况下运行服务器:
+
+```bash
+# 如果未安装 uv,先安装
+pip install uv
+
+# 本地开发运行
+uvx --from . yapi-mcp
+
+# 或使用 uv run(自动管理虚拟环境)
+uv run yapi-mcp
+```
+
+### 使用 pip
+
+```bash
+# 克隆仓库
+git clone <repository-url>
+cd yapi-mcp
+
+# 安装依赖
+pip install -e .
+
+# 开发环境安装
+pip install -e ".[dev]"
+```
+
+## 配置
+
+### 1. 获取 YApi Cookies
+
+1. 在浏览器中登录 YApi 实例
+2. 打开开发者工具(F12)
+3. 导航到 **Application** → **Cookies**(Chrome) 或 **Storage** → **Cookies**(Firefox)
+4. 复制以下 cookie 值:
+   - `_yapi_token` (必需)
+   - `_yapi_uid` (必需)
+   - `ZYBIPSCAS` (可选，仅某些自定义部署需要)
+
+### 2. 设置环境变量
+
+#### 方式 A: 环境变量
+
+```bash
+# Linux/macOS
+export YAPI_SERVER_URL="https://your-yapi-instance.com"
+export YAPI_TOKEN="your_yapi_token_value"
+export YAPI_UID="your_uid_value"
+# export YAPI_CAS="your_cas_value"  # 可选
+
+# Windows (PowerShell)
+$env:YAPI_SERVER_URL="https://your-yapi-instance.com"
+$env:YAPI_TOKEN="your_yapi_token_value"
+$env:YAPI_UID="your_uid_value"
+# $env:YAPI_CAS="your_cas_value"  # 可选
+```
+
+#### 方式 B: .env 文件
+
+在项目根目录创建 `.env` 文件(从 `.env.example` 复制):
+
+```env
+YAPI_SERVER_URL=https://your-yapi-instance.com
+YAPI_TOKEN=your_yapi_token_value
+YAPI_UID=your_yapi_uid_value
+# YAPI_CAS=your_cas_value  # 可选，仅某些自定义部署需要
+```
+
+**⚠️ 安全提示**: 永远不要将 `.env` 文件提交到版本控制。该文件已在 `.gitignore` 中。
+
+## 使用方法
+
+### 启动服务器
+
+```bash
+# 使用 uvx(推荐)
+uvx --from . yapi-mcp
+
+# 使用 uv run(自动管理虚拟环境)
+uv run yapi-mcp
+
+# 开发模式(支持热重载)
+uvx fastmcp dev src/server.py
+```
+
+服务器将在 stdio 传输上启动,并准备接受 MCP 工具调用。
+
+### 可用的 MCP 工具
+
+#### 1. `yapi_search_interfaces`
+
+在 YApi 项目中搜索接口。
+
+**参数**:
+- `project_id` (int): YApi 项目 ID
+- `keyword` (string): 搜索关键词(匹配标题、路径、描述)
+
+**示例**:
+```json
+{
+  "project_id": 123,
+  "keyword": "login"
+}
+```
+
+**返回**: 接口摘要的 JSON 数组(最多 50 条结果)
+
+#### 2. `yapi_get_interface`
+
+获取完整的接口定义。
+
+**参数**:
+- `interface_id` (int): YApi 接口 ID
+
+**示例**:
+```json
+{
+  "interface_id": 456
+}
+```
+
+**返回**: 包含请求/响应结构的完整接口定义
+
+#### 3. `yapi_create_interface`
+
+在 YApi 项目中创建新接口。
+
+**参数**:
+- `project_id` (int): 项目 ID
+- `title` (string): 接口标题
+- `path` (string): 接口路径(必须以 `/` 开头)
+- `method` (string): HTTP 方法(GET、POST、PUT、DELETE 等)
+- `req_body` (string, 可选): 请求参数(JSON 字符串)
+- `res_body` (string, 可选): 响应结构(JSON 字符串)
+- `desc` (string, 可选): 接口描述
+
+**示例**:
+```json
+{
+  "project_id": 123,
+  "title": "用户登录",
+  "path": "/api/user/login",
+  "method": "POST",
+  "req_body": "{\"username\": \"string\", \"password\": \"string\"}",
+  "res_body": "{\"token\": \"string\"}",
+  "desc": "用户认证接口"
+}
+```
+
+**返回**: `{"interface_id": <新接口ID>}`
+
+#### 4. `yapi_update_interface`
+
+更新现有接口(增量更新)。
+
+**参数**:
+- `interface_id` (int): 要更新的接口 ID
+- `title` (string, 可选): 新标题
+- `path` (string, 可选): 新路径
+- `method` (string, 可选): 新 HTTP 方法
+- `req_body` (string, 可选): 新请求参数
+- `res_body` (string, 可选): 新响应结构
+- `desc` (string, 可选): 新描述
+
+**示例**:
+```json
+{
+  "interface_id": 456,
+  "title": "用户登录 V2"
+}
+```
+
+**返回**: `{"success": true, "message": "接口更新成功"}`
+
+### 错误处理
+
+服务器将 HTTP/YApi 错误映射到 MCP 错误码:
+
+| HTTP 状态码 | MCP 错误码 | 描述 |
+|-------------|-----------|------|
+| 401 | -32001 | 认证失败(无效/过期的 cookies) |
+| 404 | -32002 | 资源不存在 |
+| 403 | -32003 | 权限不足 |
+| 500+ | -32000 | YApi 服务器错误 |
+| 400 | -32602 | 参数无效 |
+
+## IDE 集成
+
+### Claude Code
+
+添加到你的 `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "yapi": {
+      "command": "uvx",
+      "args": ["--from", "/path/to/yapi-mcp", "yapi-mcp"],
+      "env": {
+        "YAPI_SERVER_URL": "https://your-yapi-instance.com",
+        "YAPI_TOKEN": "your_token",
+        "YAPI_UID": "your_uid"
+      }
+    }
+  }
+}
+```
+
+> **注意**: 如果你的 YApi 部署需要额外的 CAS 认证，添加 `"YAPI_CAS": "your_cas_value"` 到 `env` 中。
+
+### Cursor / 其他 MCP 客户端
+
+参考你的 IDE 的 MCP 服务器配置文档。服务器默认使用 stdio 传输。
+
+## 开发
+
+### 运行测试
+
+```bash
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行所有测试
+pytest
+
+# 运行并显示覆盖率
+pytest --cov=src --cov-report=term-missing
+
+# 运行特定测试文件
+pytest tests/test_config.py
+```
+
+### 代码质量
+
+```bash
+# 格式化代码
+ruff format
+
+# 代码检查
+ruff check
+
+# 自动修复检查问题
+ruff check --fix
+```
+
+### 项目结构
+
+```
+yapi-mcp/
+├── src/
+│   ├── server.py          # MCP 服务器入口点
+│   ├── config.py          # 配置模型
+│   ├── yapi/
+│   │   ├── client.py      # YApi API 客户端
+│   │   ├── models.py      # Pydantic 数据模型
+│   │   └── errors.py      # 错误映射
+│   └── tools/             # MCP 工具(在 server.py 中注册)
+├── tests/                 # 测试套件
+├── specs/                 # 设计文档
+├── pyproject.toml         # 项目配置
+├── .env.example           # 环境变量模板
+└── README.md              # 本文件
+```
+
+## 故障排除
+
+### 服务器无法启动
+
+**问题**: `uvx: command not found`
+
+**解决方案**: 安装 uv: `pip install uv`
+
+---
+
+**问题**: 启动时出现 `ValidationError`
+
+**解决方案**: 验证所有必需的环境变量已设置:
+```bash
+# 检查必需的变量
+echo $YAPI_SERVER_URL
+echo $YAPI_TOKEN
+echo $YAPI_UID
+```
+
+### 认证错误
+
+**问题**: 所有请求返回 `-32001`(认证失败)
+
+**解决方案**:
+1. 验证 cookies 是否正确(无多余空格,完整值)
+2. 检查 cookies 是否过期(重新登录 YApi 并获取新 cookies)
+3. 确保 `YAPI_SERVER_URL` 正确(无尾部斜杠)
+
+### 搜索返回空结果
+
+**问题**: 搜索返回 `[]`,即使接口存在
+
+**解决方案**:
+1. 验证你有访问该项目的权限
+2. 检查 `project_id` 是否正确
+3. 尝试不同的关键词(某些 YApi 配置中匹配区分大小写)
+
+### 导入错误
+
+**问题**: `ModuleNotFoundError: No module named 'fastmcp'`
+
+**解决方案**:
+- 使用 uvx: 无需操作(自动管理依赖)
+- 使用 pip: 运行 `pip install -e .` 或 `pip install fastmcp httpx pydantic-settings`
+
+## 贡献
+
+欢迎贡献! 我们非常感谢各种形式的贡献,包括但不限于:
+
+- 🐛 报告 Bug
+- ✨ 建议新功能
+- 📝 改进文档
+- 💻 提交代码
+
+在开始贡献之前,请阅读我们的[贡献指南](CONTRIBUTING.md)。
+
+### 快速开始
+
+1. Fork 本仓库
+2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
+3. 提交更改 (`git commit -m 'feat: 添加惊人的功能'`)
+4. 推送到分支 (`git push origin feature/amazing-feature`)
+5. 创建 Pull Request
+
+### 代码质量要求
+
+- ✅ 所有测试通过: `pytest`
+- ✅ 代码已格式化: `ruff format`
+- ✅ 无检查错误: `ruff check`
+- ✅ 新功能包含测试
+
+详细信息请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## 许可证
+
+本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
+
+## 相关项目
+
+- [YApi](https://github.com/YMFE/yapi) - API 管理平台
+- [fastmcp](https://github.com/jlowin/fastmcp) - Python MCP 框架
+- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 规范

yapi_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+__init__.py,sha256=SBLYeM81kYugEWMJ4G5QBSqc4eSupENqh1tnw9Bl2uM,65
+config.py,sha256=ae9PiybfqSHxA7eoIYpMuEx6i8VD1oA2XvdesFoo0Uw,1325
+server.py,sha256=Vfyf7gidqthdxZaQB6vRqxzxFx5eXOirBhoHGVjknX0,5261
+tools/__init__.py,sha256=4pyNNYQTrZqzzxWqt32-TwlyoIvoYG33jYFPQWeybFY,32
+yapi/__init__.py,sha256=MKl1a1EGC2cQ0a6gtDcVcHgEQ3Xv1DKl9sF_5luwzYg,30
+yapi/client.py,sha256=l2_ADHY2_-YPrhIxhLlin4AFhLmDJ-nzPdC37teVpCM,6747
+yapi/errors.py,sha256=OyqxRn6AWKwwcheveP_pRnLDtebMsuepLDLeJrdJFGg,3126
+yapi/models.py,sha256=EQjJs9SRZildJ4AwYR1WUDGRehKXcj9aylLDeESYs7Q,2207
+yapi_mcp-0.1.0.dist-info/METADATA,sha256=X_KxnkT1oISHWAUFAJl_8hawhDwahWjGZqA4bl9QJO4,9756
+yapi_mcp-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+yapi_mcp-0.1.0.dist-info/entry_points.txt,sha256=OEEA4GoE6pBNK_fFob1IjcIGycITHjwivMFMuI9s_FY,41
+yapi_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=1KjcRj5gDUuy3iU-SpKUZVVwk4YPUIVVzCc9ktKGYpc,1085
+yapi_mcp-0.1.0.dist-info/RECORD,,

yapi_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

yapi_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+yapi-mcp = server:main

yapi_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 YApi MCP Server Contributors
+
+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.