# mcp-server-apidebug

[English](#english) | [中文](#中文)

---

## English

### MCP Server for API Debugging

A standalone MCP (Model Context Protocol) server for API debugging, login authentication, API configuration management, and indexed API execution.

### Features

- **api_config**: Manage API debugging configuration, Base URL, common Headers, and API list
- **api_debug**: Execute API requests directly, supports GET/POST/PUT/DELETE/PATCH methods, query parameters, headers, body, automatic Content-Type detection
- **api_execute**: Execute requests by index saved in api_config
- **api_login**: Execute login requests based on environment variables
- **api_help**: View API debugging tool documentation and examples

### Installation

Global installation (Recommended):

```bash
npm install -g @liangshanli/mcp-server-apidebug
```

Local installation:

```bash
npm install @liangshanli/mcp-server-apidebug
```

### Local Development

```bash
npm start
```

Or start the server directly:

```bash
node src/server.js
```

### Quick Self-Test

```bash
npm test
```

This will output the MCP `tools/list` result.

### Environment Variables

| Variable | Default | Description |
| --- | --- | --- |
| `PROJECT_PATH` | `.` | Project directory; uses current directory when not set |
| `TOOL_PREFIX` | `default` | Tool name prefix; default tools are `default_api_debug`, `default_api_config`, etc. |
| `CONFIG_DIR` | empty | Optional config directory override; generally not needed. When not set, uses `PROJECT_PATH/.setting/{TOOL_PREFIX}` |
| `API_DEBUG_BASE_URL` | empty | API base URL; when configured, no need to set `baseUrl` via `api_config` |
| `API_DEBUG_ALLOWED_METHODS` | `GET,POST,PUT,DELETE,PATCH` | Allowed HTTP methods, comma-separated |
| `API_DEBUG_LOGIN_URL` | `/api/login` | Login API URL |
| `API_DEBUG_LOGIN_METHOD` | `POST` | Login API method |
| `API_DEBUG_LOGIN_BODY` | `{"username":"","password":""}` | Login request body, supports JSON string or plain string |
| `API_DEBUG_LOGIN_DESCRIPTION` | empty | Login tool description |
| `API_DEBUG_LOGIN_USER_HEADER` | `new-api-user` | Header name for user ID (extracted from login response) |

### MCP Configuration Example

```json
{
  "servers": {
    "apidebug": {
      "command": "npx",
      "args": [
        "@liangshanli/mcp-server-apidebug"
      ],
      "env": {
        "API_DEBUG_BASE_URL": "https://api.example.com",
        "API_DEBUG_ALLOWED_METHODS": "GET,POST,PUT,DELETE,PATCH",
        "API_DEBUG_LOGIN_URL": "/api/user/login",
        "API_DEBUG_LOGIN_METHOD": "POST",
        "API_DEBUG_LOGIN_BODY": "{\"username\":\"your_username\",\"password\":\"your_password\"}",
        "API_DEBUG_LOGIN_USER_HEADER": "new-api-user",
        "API_DEBUG_LOGIN_DESCRIPTION": "Execute login requests based on environment variables. Use api_config interface to handle login configuration after successful login."
      }
    }
  }
}
```

### Configuration Storage

Default storage path:

```
{PROJECT_PATH}/.setting/{TOOL_PREFIX}/api.json
```

If `PROJECT_PATH` is not set, defaults to `.`; if `TOOL_PREFIX` is not set, defaults to `default`.

### Usage Examples

1. Set Base URL:

```json
{
  "action": "updateBaseUrl",
  "baseUrl": "https://api.example.com"
}
```

2. Debug an API:

```json
{
  "url": "/api/users",
  "method": "GET",
  "query": {
    "page": 1,
    "limit": 10
  }
}
```

3. Add an API and execute by index:

```json
{
  "action": "addApi",
  "api": {
    "url": "/api/login",
    "method": "POST",
    "body": {
      "username": "admin",
      "password": "123456"
    }
  }
}
```

```json
{
  "index": 0
}
```

---

## 中文

### API 调试 MCP 服务器

独立运行的 MCP (Model Context Protocol) 服务器，用于 API 调试、登录认证、API 配置管理和按索引执行 API 请求。

### 工具列表

- **api_config**：管理 API 调试配置、Base URL、公共 Headers 和接口列表
- **api_debug**：直接执行 API 请求，支持 GET/POST/PUT/DELETE/PATCH 方法、query 参数、headers、body，自动检测 Content-Type
- **api_execute**：按 `api_config` 中保存的接口索引执行请求
- **api_login**：根据环境变量执行登录请求
- **api_help**：查看 API 调试工具说明和示例

### 安装依赖

全局安装（推荐）：

```bash
npm install -g @liangshanli/mcp-server-apidebug
```

本地安装：

```bash
npm install @liangshanli/mcp-server-apidebug
```

### 本地运行

```bash
npm start
```

或直接启动 server：

```bash
node src/server.js
```

### 快速自检

```bash
npm test
```

会输出 MCP `tools/list` 结果。

### 环境变量

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `PROJECT_PATH` | `.` | 项目目录；不设置时使用当前目录 |
| `TOOL_PREFIX` | `default` | 工具名前缀；默认工具名为 `default_api_debug`、`default_api_config` 等 |
| `CONFIG_DIR` | 空 | 可选覆盖配置目录；一般不需要设置。未设置时使用 `PROJECT_PATH/.setting/{TOOL_PREFIX}` |
| `API_DEBUG_BASE_URL` | 空 | API 基础 URL；配置后无需再通过 `api_config` 设置 `baseUrl` |
| `API_DEBUG_ALLOWED_METHODS` | `GET,POST,PUT,DELETE,PATCH` | 允许执行的 HTTP 方法，逗号分隔 |
| `API_DEBUG_LOGIN_URL` | `/api/login` | 登录接口 URL |
| `API_DEBUG_LOGIN_METHOD` | `POST` | 登录接口方法 |
| `API_DEBUG_LOGIN_BODY` | `{"username":"","password":""}` | 登录请求体，支持 JSON 字符串或普通字符串 |
| `API_DEBUG_LOGIN_DESCRIPTION` | 空 | 登录工具说明 |
| `API_DEBUG_LOGIN_USER_HEADER` | `new-api-user` | 用户 ID 的 Header 名称（从登录响应中提取） |

### MCP 配置示例

```json
{
  "servers": {
    "apidebug": {
      "command": "npx",
      "args": [
        "@liangshanli/mcp-server-apidebug"
      ],
      "env": {
        "API_DEBUG_BASE_URL": "https://api.example.com",
        "API_DEBUG_ALLOWED_METHODS": "GET,POST,PUT,DELETE,PATCH",
        "API_DEBUG_LOGIN_URL": "/api/user/login",
        "API_DEBUG_LOGIN_METHOD": "POST",
        "API_DEBUG_LOGIN_BODY": "{\"username\":\"your_username\",\"password\":\"your_password\"}",
        "API_DEBUG_LOGIN_USER_HEADER": "new-api-user",
        "API_DEBUG_LOGIN_DESCRIPTION": "根据环境变量执行登录请求。使用 api_config 接口处理登录成功后的配置。"
      }
    }
  }
}
```

### 配置保存路径

默认保存目录规则：

```
{PROJECT_PATH}/.setting/{TOOL_PREFIX}/api.json
```

如果 `PROJECT_PATH` 不设置，则默认 `.`；如果 `TOOL_PREFIX` 不设置，则默认 `default`。

### 使用示例

1. 设置 Base URL：

```json
{
  "action": "updateBaseUrl",
  "baseUrl": "https://api.example.com"
}
```

2. 调试接口：

```json
{
  "url": "/api/users",
  "method": "GET",
  "query": {
    "page": 1,
    "limit": 10
  }
}
```

3. 添加接口后按索引执行：

```json
{
  "action": "addApi",
  "api": {
    "url": "/api/login",
    "method": "POST",
    "body": {
      "username": "admin",
      "password": "123456"
    }
  }
}
```

```json
{
  "index": 0
}
```