Metadata-Version: 2.4
Name: api-doc-mcp-server
Version: 1.0.5
Summary: An MCP tool for automatically generating API documentation that can be integrated with Cursor
Home-page: https://github.com/your-username/api-doc-mcp-server
Author: Your Name
Author-email: your.email@example.com
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: mcp-server==0.1.4
Requires-Dist: fastapi>=0.68.0
Requires-Dist: uvicorn>=0.15.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# API文档生成MCP工具

这是一个用于自动化生成API文档的MCP工具，可集成到Cursor中使用。该工具能够编排整个API文档生成工作流，从分析项目结构到最终生成完整的API文档。

## 功能特点

- 自动编排API文档生成工作流
- 分析项目结构，识别API路由及相关代码文件
- 提取API信息（路由、参数、响应结构等）
- 生成Markdown格式的API文档
- 检查文档完整性并自动补充遗漏内容

## 工作流说明

1. **开始工作流** - 启动API文档生成流程
2. **分析项目结构** - 识别项目中的API路由、控制器、认证拦截器和过滤器
3. **检索API路由** - 定位所有相关的代码文件
4. **阅读代码文件** - 提取API路由、参数和响应信息
5. **编写API文档** - 根据提取的信息生成Markdown格式文档
6. **检查文档完整性** - 确保所有API都已包含在文档中
7. **补充遗漏内容** - 如有遗漏，继续编写直到完成
8. **工作流结束** - 完成整个文档生成过程

## API文档内容要求

生成的API文档包含以下信息：

- API地址
- API所属类路径
- API功能描述
- API是否需要鉴权
- 参数字段说明
- 响应数据结构和字段说明
- 请求响应示例

## 安装和运行

### 环境要求

- Python 3.8 或更高版本
- pip 包管理器

### 安装步骤

可以通过多种方式安装和使用本工具：

#### 方式一：通过pip安装

```bash
pip install api-doc-mcp-server
```

#### 方式二：使用uvx直接运行（推荐）

```bash
uvx --from api-doc-mcp-server api_doc_mcp_server
```

#### 方式三：从源码运行

1. 克隆或下载项目代码：
   ```bash
   git clone <项目地址>
   cd api-doc-mcp-server
   ```

2. 安装依赖：
   ```bash
   pip install -r requirements.txt
   ```

## 在Cursor中使用

### 简单配置方式

在Cursor项目根目录下添加 [mcp.json](file:///D:/codes/pycharm_worksapce/api-doc-mcp-server/mcp.json) 配置文件，内容如下：

```json
{
  "mcpServers": {
    "api-doc-mcp-server": {
      "command": "uvx",
      "args": [
        "--from", "api-doc-mcp-server", "api_doc_mcp_server"
      ]
    }
  }
}
```

这种方式利用 `uvx` 工具直接运行包而无需预先安装，是最便捷的使用方式。

### 传统配置方式

如果你已经通过pip安装了工具，可以使用以下配置：

```json
{
  "mcpServers": {
    "api-doc-mcp-server": {
      "command": "api-doc-mcp-server"
    }
  }
}
```

### 服务模式运行（可选）

如果你希望以服务模式运行工具（适用于需要同时在多个项目中使用的情况），可以按以下步骤操作：

1. 从源码运行服务：
   ```bash
   uvx --from api-doc-mcp-server api_doc_mcp_server serve
   ```

2. 在Cursor项目根目录下添加 [mcp.json](file:///D:/codes/pycharm_worksapce/api-doc-mcp-server/mcp.json) 配置文件，内容如下：
   ```json
   {
     "mcpServers": {
       "api-doc-mcp-server": {
         "url": "http://127.0.0.1:8000/sse"
       }
     }
   }
   ```

### 详细使用步骤

1. 在Cursor中打开需要生成API文档的项目
2. 重启Cursor以加载配置
3. 启动"API文档生成工具"工作流
4. 工具将自动分析项目结构并指导Cursor完成文档生成

## 发布信息

- 当前版本：v1.0.2
- 发布日期：2025-08-09
- 详细发布说明请查看 [RELEASE.md](file:///D:/codes/pycharm_worksapce/api-doc-mcp-server/RELEASE.md)

## 注意事项

- 该工具作为指挥和监督角色，代码检索和解析工作由Cursor AI完成
- 过程尽量减少人工参与，实现自动化生成
- 生成的文档格式为Markdown，便于查看和维护
- stdio模式下无需单独启动服务，工具会按需启动
- 服务模式下需要保持终端窗口运行以确保服务正常
- 使用uvx方式需要系统已安装uv工具

## 故障排除

如果遇到问题，请尝试以下解决方案：

1. 确保所有依赖已正确安装
2. 检查端口8000是否被其他程序占用（仅服务模式）
3. 确认Cursor中的MCP工具配置正确
4. 查看终端输出的日志信息以定位问题
5. 如果使用uvx方式，确保已安装uv工具：`pip install uv`
