npm package: @funfe-dev/apipost-mcp
Description: ApiPost MCP - API文档管理工具，支持接口创建、修改、查看和批量操作
Author: funfe-dev
Latest version: 2.0.0

# ApiPost MCP

基于 MCP 协议和 [ApiPost 官方 OpenAPI](https://docs.apipost.net/docs/detail/2a37986cbc64000?target_id=23796913b176e1) 实现的 API 管理工具。

## 功能

- **连接测试** - 一键验证MCP服务器状态和配置
- **工作空间管理** - 查看、切换团队和项目工作空间
- **目录管理** - 创建API文档目录，支持层级结构
- **API接口管理** - 创建、查看、修改、删除接口文档
- **增量更新** - 支持字段级别的精确更新和删除
- **层级搜索** - 强化的目录层级搜索和父子关系定位
- **递归浏览** - 递归搜索子目录，支持深度限制
- **多维筛选** - 多维度搜索和批量操作
- **结构化显示** - 树形结构和分组显示
- **路径导航** - 完整路径显示，快速定位
- **权限管理** - 多种安全模式，灵活的操作权限控制

## 安装

### 方式一：通过 npx 使用（推荐）

```bash
# 直接运行（无需安装）
npx @funfe-dev/apipost-mcp

# 或者全局安装
npm install -g @funfe-dev/apipost-mcp
```

### 方式二：从源码安装

#### 环境要求

在开始安装之前，请确保您的系统已安装以下环境：

| 环境 | 版本要求 | 说明 |
|------|---------|------|
| **Node.js** | >= 18.0.0 | JavaScript 运行环境（MCP SDK 官方最低要求） |
| **npm** | >= 8.0.0 | Node.js 包管理器（通常随 Node.js 一起安装） |

#### 环境安装指南

**Node.js 安装：**
- 访问 [Node.js 官网](https://nodejs.org/) 下载 LTS 版本
- 或使用包管理器：
  ```bash
  # macOS (使用 Homebrew)
  sudo brew install node
  
  # Ubuntu/Debian
  sudo apt update && sudo apt install nodejs npm
  
  # CentOS/RHEL
  sudo yum install nodejs npm
  ```

**验证安装：**
```bash
node --version   # 应显示 v18.0.0 或更高版本
npm --version    # 应显示 8.0.0 或更高版本
```

#### 开始安装

```bash
git clone https://github.com/jlcodes99/apipost-mcp.git
cd apipost-mcp
npm install && npm run build
```

## 配置

### 方式一：使用 npx（推荐）

```json
{
  "mcpServers": {
    "apipost": {
      "command": "npx",
      "args": ["@funfe-dev/apipost-mcp"],
      "env": {
        "APIPOST_TOKEN": "your_access_token_here",
        "APIPOST_HOST": "https://open.apipost.net",
        "APIPOST_SECURITY_MODE": "limited",
        "APIPOST_DEFAULT_TEAM_NAME": "你的团队名称",
        "APIPOST_DEFAULT_PROJECT_NAME": "你的项目名称"
      }
    }
  }
}
```

### 方式二：使用本地安装

```json
{
  "mcpServers": {
    "apipost": {
      "command": "node",
      "args": ["/absolute/path/to/apipost-mcp/dist/index.js"],
      "env": {
        "APIPOST_TOKEN": "your_access_token_here",
        "APIPOST_HOST": "https://open.apipost.net",
        "APIPOST_SECURITY_MODE": "limited",
        "APIPOST_DEFAULT_TEAM_NAME": "你的团队名称",
        "APIPOST_DEFAULT_PROJECT_NAME": "你的项目名称"
      }
    }
  }
}
```


### 配置方式

#### 方式一：项目配置文件（推荐）

在项目根目录创建 `apipost.config.json` 文件：

```json
{
  "token": "your-apipost-token",
  "host": "https://open.apipost.net",
  "securityMode": "limited",
  "defaultTeamName": "我的团队",
  "defaultProjectName": "我的项目"
}
```

**特性：**
- 🤖 通过AI消息获取配置（向AI发送标准化请求）
- 📨 固定格式的提示词，便于AI识别和处理
- 📋 每次工具调用时自动刷新
- 🛡️ 敏感信息自动隐藏
- 📁 支持多种配置文件格式
- 🔄 智能后备机制（AI失败时使用直接shell命令）

#### 方式二：环境变量

| 变量名 | 是否必需 | 说明 |
|--------|------|------|
| `APIPOST_TOKEN` | 否* | API访问令牌 |
| `APIPOST_HOST` | 否 | API服务器地址，默认 `https://open.apipost.net` |
| `APIPOST_SECURITY_MODE` | 否 | 安全模式：`readonly`, `limited`, `full` |
| `APIPOST_DEFAULT_TEAM_NAME` | 否 | 默认团队名称 |
| `APIPOST_DEFAULT_PROJECT_NAME` | 否 | 默认项目名称 |

**配置优先级：** 项目配置文件 > 环境变量 > 默认值

**注意：** `*` Token不是强制必需的，但没有Token时只能使用配置查看工具。

### 安全模式说明

| 模式 | 权限 | 说明 |
|------|------|------|
| `readonly` | 只读 | 仅允许查看接口列表和详情，禁止创建、修改、删除 |
| `limited` | 读写 | 允许查看、创建、修改接口，禁止删除操作 |
| `full` | 完全访问 | 允许所有操作，包括查看、创建、修改、删除 |


## 可用工具

| 工具 | 功能 | 主要参数 |
|------|------|---------|
| `apipost_request_config_from_ai` | 向AI请求配置获取 | `request_type` |
| `apipost_process_ai_config` | 处理AI返回的配置 | `config_file_path`, `config_content`, `not_found` |
| `apipost_get_project_config` | 获取项目配置 | `show_content`, `refresh` |
| `apipost_test_connection` | 连接测试 | `random_string` |
| `apipost_workspace` | 工作空间管理 | `action` (必需) |
| `apipost_create_folder` | 创建目录 | `name`, `parent_id` |
| `apipost_smart_create` | 创建接口 | `method`, `url`, `name` |
| `apipost_list` | 强化列表搜索 | `search`, `parent_id`, `target_type`, `show_structure`, `recursive`, `group_by_folder` |
| `apipost_detail` | 查看详情 | `target_id` |
| `apipost_update` | 修改接口 | `target_id`, 其他可选 |
| `apipost_delete` | 删除接口 | `api_ids` |

### apipost_request_config_from_ai 说明

**AI配置请求工具**，向AI发送标准化的配置获取请求：
- 📨 生成固定格式的提示词，向AI发送配置获取请求
- 🤖 AI收到请求后会执行shell命令获取配置文件
- 📋 返回标准化的shell命令供AI执行
- 🔍 支持多种配置文件格式的自动搜索

**使用示例：**
```
apipost_request_config_from_ai request_type: "get_config"
```

**工作流程：**
1. MCP工具向AI发送标准化请求
2. AI收到请求并执行shell命令
3. AI返回配置文件路径和内容
4. 使用 `apipost_process_ai_config` 处理AI返回的信息

### apipost_process_ai_config 说明

**AI配置处理工具**，处理AI返回的配置信息并更新MCP配置：
- 🤖 解析AI返回的配置文件内容
- ⚙️ 自动更新全局配置变量
- 🔄 刷新API客户端配置
- ✅ 验证配置有效性

**使用示例：**
```
# 如果AI找到了配置文件
apipost_process_ai_config config_file_path: "apipost.config.json" config_content: "{\"token\":\"your-token\",...}"

# 如果AI未找到配置文件
apipost_process_ai_config not_found: true
```

### apipost_get_project_config 说明

**项目配置获取工具**，通过AI消息自动获取项目配置文件：
- 🤖 向AI发送标准化配置获取请求
- 📨 使用固定格式的提示词，便于AI识别处理
- 🔍 自动搜索多种配置文件（`apipost.config.json`, `.apipostrc.json` 等）
- 📋 显示配置文件路径和字段信息
- 🎯 展示当前使用的配置详情
- 🛡️ 自动隐藏敏感信息（如Token）
- 📝 提供配置文件模板和建议
- 🔄 智能后备机制（AI失败时使用直接方式）

**使用示例：**
```
apipost_get_project_config show_content: true
```

**配置文件搜索顺序：**
1. `apipost.config.json`
2. `.apipostrc.json`
3. `config/apipost.config.json`
4. `.apipostrc`

### apipost_test_connection 说明

**快速诊断工具**，适合首次使用或故障排查：
- ✅ 验证MCP服务器连接状态
- 🔧 检查环境变量配置
- 🏢 显示当前工作空间信息  
- 🛠️ 检查操作权限和安全模式
- 📊 提供系统环境详情
- 📋 显示配置来源信息

**使用示例：**
```
apipost_test_connection random_string: "test"
```

**AI配置获取机制：**
通过专门的工具与AI协作获取项目配置：

1. **请求配置**：
   ```
   apipost_request_config_from_ai request_type: "get_config"
   ```
   
   工具会向AI发送标准化请求：
   ```
   🔍 MCP配置获取请求
   
   我是ApiPost MCP工具，需要你帮助我获取项目中的配置文件。
   
   请执行以下shell命令来获取项目中的apipost配置文件：
   
   ```bash
   # 检查并读取配置文件（按优先级顺序）
   for file in "apipost.config.json" ".apipostrc.json" "config/apipost.config.json" ".apipostrc"; do
     if [ -f "$file" ]; then
       echo "CONFIG_FILE_FOUND: $file"
       echo "CONFIG_CONTENT_START"
       cat "$file"
       echo "CONFIG_CONTENT_END"
       break
     fi
   done
   ```
   ```

2. **处理AI响应**：
   AI执行命令后，使用以下工具处理结果：
   ```
   # 如果找到配置文件
   apipost_process_ai_config config_file_path: "apipost.config.json" config_content: "{配置内容}"
   
   # 如果未找到配置文件
   apipost_process_ai_config not_found: true
   ```

3. **自动配置提示**：
   - 🤖 其他工具调用时会自动检查配置状态
   - 📋 如果缺少配置会提示使用AI配置获取流程
   - ✅ 配置完成后可正常使用所有API工具

**零配置启动：**
- ✅ 无需强制配置即可启动MCP服务器
- 🔍 `apipost_get_project_config` 工具始终可用
- ⚠️ 其他API工具需要配置Token后才能使用
- 💡 提供清晰的配置指导和错误提示

### apipost_workspace 说明

**统一的工作空间管理工具**，支持以下操作：

| Action | 功能 | 主要参数 | 说明 |
|--------|------|---------|------|
| `current` | 查看当前工作空间 | `show_all` | 显示当前团队、项目信息，可选显示所有可用选项 |
| `list_teams` | 列出团队 | `show_details` | 显示所有可用团队，标识当前团队 |
| `list_projects` | 列出项目 | `team_id`, `show_details` | 显示指定团队的项目列表 |
| `switch` | 切换工作空间 | `team_id`, `project_id` 或 `team_name`, `project_name` | 切换到指定的团队和项目 |

**使用示例：**
```
# 查看当前工作空间
apipost_workspace action: "current"

# 列出所有团队
apipost_workspace action: "list_teams" show_details: true

# 列出项目
apipost_workspace action: "list_projects" team_id: "your_team_id"

# 切换工作空间（支持按名称或ID）
apipost_workspace action: "switch" team_name: "团队名" project_name: "项目名"
```

### apipost_create_folder 说明

**API文档目录创建工具**，支持在指定父目录下创建新的文件夹：

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `name` | string | 是 | 目录名称 |
| `parent_id` | string | 否 | 父目录ID，使用"0"表示根目录，默认为"0" |
| `description` | string | 否 | 目录描述（可选） |

**使用示例：**
```
# 在根目录创建目录
apipost_create_folder name: "用户管理" description: "用户相关接口"

# 在指定目录下创建子目录
apipost_create_folder name: "认证接口" parent_id: "folder_123" description: "用户认证相关接口"
```

### apipost_list 参数说明

| 参数 | 类型 | 说明 |
|------|------|------|
| `search` | string | 搜索关键词（接口名称、URL、方法、ID、描述） |
| `parent_id` | string | 父目录ID，精确查找子项目。"0"为根目录 |
| `target_type` | string | 类型筛选：`api`(仅接口)、`folder`(仅目录)、`all`(全部) |
| `show_structure` | boolean | 显示树形结构，默认false为列表模式 |
| `show_path` | boolean | 显示完整路径，默认false |
| `recursive` | boolean | 递归搜索子目录，默认false |
| `depth` | number | 深度限制（配合recursive），默认无限制 |
| `group_by_folder` | boolean | 按目录分组显示，默认false |
| `limit` | number | 显示数量限制（默认50，最大200） |
| `show_all` | boolean | 显示全部（忽略limit限制） |

### apipost_smart_create 说明

**API接口文档生成器**，支持通过分离参数创建完整的API文档，包括请求参数、响应格式、认证方式等：

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `method` | string | 是 | HTTP方法：GET, POST, PUT, DELETE |
| `url` | string | 是 | 接口URL路径 |
| `name` | string | 是 | 接口名称 |
| `parent_id` | string | 否 | 父目录ID，使用"0"表示根目录，默认为"0" |
| `description` | string | 否 | 接口详细描述 |
| `headers` | string | 否 | Headers参数JSON数组字符串 |
| `query` | string | 否 | Query参数JSON数组字符串 |
| `body` | string | 否 | Body参数JSON数组字符串 |
| `cookies` | string | 否 | Cookies参数JSON数组字符串 |
| `auth` | string | 否 | 认证配置JSON字符串 |
| `responses` | string | 否 | 响应示例JSON数组字符串 |

**使用示例：**
```
# 在根目录创建接口
apipost_smart_create method: "POST" url: "/api/users" name: "创建用户"

# 在指定目录下创建接口
apipost_smart_create method: "GET" url: "/api/users/{id}" name: "获取用户详情" parent_id: "folder_123"
```

## 获取 Token

1. [ApiPost OpenApi官方文档查看](https://docs.apipost.net/docs/detail/2a37986cbc64000?target_id=0)
2. 用户api_token。获取方式：Apipost客户端>工作台>项目设置>对外能力>open API

## 📝 更新日志

查看 [CHANGELOG.md](CHANGELOG.md) 了解版本更新信息。

---

💡 **提示**：这是一个专注于API接口管理的MCP工具，简化了接口创建和管理流程，提高团队协作效率。

## 版本特性

### v1.9.0 主要特性
- ✅ **完整的MCP工具集**：支持API文档的完整生命周期管理
- 🔧 **智能工作空间管理**：自动团队和项目切换
- 📋 **强化列表搜索**：支持递归搜索、分组显示、路径导航
- 🎯 **精确更新机制**：增量更新和字段级别控制
- 🛡️ **多级安全模式**：readonly/limited/full权限控制
- 🏗️ **智能API模板生成**：支持复杂参数和响应配置
- 🤖 **AI配置获取**：每次工具调用前自动向AI发送消息获取项目配置
- 🚀 **零配置启动**：无需强制配置即可启动，提供友好的配置指导
- 📱 **用户友好界面**：清晰的日志输出和错误提示

## 联系方式

- 📦 NPM包: [@funfe-dev/apipost-mcp](https://www.npmjs.com/package/@funfe-dev/apipost-mcp)
- 🐛 问题反馈: [GitHub Issues](https://github.com/jlcodes99/apipost-mcp/issues)
- 🌟 项目主页: [GitHub Repository](https://github.com/jlcodes99/apipost-mcp)

## 相关链接

- [ApiPost OpenAPI 文档](https://docs.apipost.net/docs/detail/2a37986cbc64000?target_id=23796913b176e1)
- [MCP 协议说明](https://github.com/modelcontextprotocol/specification)


⭐ 如果这个项目对你有帮助，请给我们一个星标！