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

{yapi → yapi_mcp/yapi}/models.py

@@ -1,60 +1,61 @@
-"""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")
+"""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")
+    catid: int = Field(..., description="Category ID this interface belongs to")
+    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.2.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: yapi-mcp
+Version: 0.1.2
+Summary: Model Context Protocol server for YApi 1.12.0 API management platform
+Project-URL: Homepage, https://github.com/geq1fan/yapi-mcp
+Project-URL: Repository, https://github.com/geq1fan/yapi-mcp
+Project-URL: Issues, https://github.com/geq1fan/yapi-mcp/issues
+Author: YApi MCP Team
+License: MIT
+License-File: LICENSE
+Keywords: api,fastmcp,mcp,model-context-protocol,yapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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-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
+
+[![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
+
+## 配置
+
+### 1. 获取 YApi Cookies
+
+1. 在浏览器中登录 YApi 实例
+2. 打开开发者工具(F12)
+3. 导航到 **Application** → **Cookies**(Chrome) 或 **Storage** → **Cookies**(Firefox)
+4. 复制以下 cookie 值:
+   - `_yapi_token` (必需)
+   - `_yapi_uid` (必需)
+   - `ZYBIPSCAS` (可选，仅某些自定义部署需要)
+
+### 2. 配置 MCP
+
+```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` 中。
+
+## 开发
+
+### 运行测试
+
+```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              # 本文件
+```
+
+## 贡献
+
+欢迎贡献! 我们非常感谢各种形式的贡献,包括但不限于:
+
+- 🐛 报告 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.2.dist-info/RECORD

@@ -0,0 +1,14 @@
+yapi_mcp/__init__.py,sha256=-B1Yt-BsgzhccXKx5Y6f3TWR1OQbb8I8cOvnSKYjcSU,136
+yapi_mcp/__main__.py,sha256=hOOyTtbTkoNugBbb_SofxEMRf8PuoOhWa8Z8-OyfWqw,151
+yapi_mcp/config.py,sha256=k19HWCCBfBJttlsWj4f2QdxvFoBvHSJ1AVvb08WT-tQ,1373
+yapi_mcp/server.py,sha256=NVkl_PKBzDjBbjyl2ynpxtf8cpKRtaWz9H0BZ6UDxpQ,6564
+yapi_mcp/tools/__init__.py,sha256=iCyxPtAUoQ7RU976LPMXgGghqm2l0bH-LYBCnEOLtew,33
+yapi_mcp/yapi/__init__.py,sha256=gK6ta7uNWkDqen5yWSDqqXYlCxz3uU-A2bKaqeO55Qk,31
+yapi_mcp/yapi/client.py,sha256=gcwYdeHT9Yjq-550HyDh61wJYS8TeeAgFMoXoeb-bIg,10058
+yapi_mcp/yapi/errors.py,sha256=RQvvdl1d-CBawZDTdgf3g_ThJUhGUvwRPCI-q2I6Mfc,3815
+yapi_mcp/yapi/models.py,sha256=MJZQx_esXPcQ7UTnhlo_QVU81NrIPF2pB36mxvcLJ5w,2349
+yapi_mcp-0.1.2.dist-info/METADATA,sha256=NpaST-JZA4syzU8qEK9A0LrcgVmmNogsuksUdYRr3Wo,5198
+yapi_mcp-0.1.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+yapi_mcp-0.1.2.dist-info/entry_points.txt,sha256=u1QWnfoawIuUR6RuyPmqi9TpySnasIRU1lvJZa315EU,43
+yapi_mcp-0.1.2.dist-info/licenses/LICENSE,sha256=b-a1jI555eCf0fkRmK3mrIGQe8hYqC5aXy0nGXiEasA,1106
+yapi_mcp-0.1.2.dist-info/RECORD,,

{yapi_mcp-0.1.0.dist-info → yapi_mcp-0.1.2.dist-info}/WHEEL

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

yapi_mcp-0.1.2.dist-info/entry_points.txt

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

{yapi_mcp-0.1.0.dist-info → yapi_mcp-0.1.2.dist-info}/licenses/LICENSE

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

__init__.py

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

server.py

@@ -1,148 +0,0 @@
-"""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()