# YAPI MCP Server

English | [中文](./README_zh.md)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [YAPI](https://github.com/YMFE/yapi) - enabling AI assistants to manage API documentation.

## Features

| Tool | Description | YAPI API |
|------|-------------|----------|
| `yapi_list_projects` | List all configured projects | - |
| `yapi_run_auto_test` | Run automated tests | `/api/open/run_auto_test` |
| `yapi_import_data` | Import API data | `/api/open/import_data` |
| `yapi_interface_add` | Add new interface | `/api/interface/add` |
| `yapi_interface_save` | Save interface | `/api/interface/save` |
| `yapi_interface_up` | Update interface | `/api/interface/up` |
| `yapi_interface_get` | Get interface details | `/api/interface/get` |
| `yapi_interface_list` | List interfaces | `/api/interface/list` |
| `yapi_interface_list_menu` | Get interface menu | `/api/interface/list_menu` |
| `yapi_interface_add_cat` | Add interface category | `/api/interface/add_cat` |
| `yapi_interface_get_cat_menu` | Get all categories | `/api/interface/getCatMenu` |

## Installation

Clone the repository, then install dependencies and build in the project directory:

```bash
git clone <repo-url>
cd yapi-mcp
npm install
npm run build
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `YAPI_BASE_URL` | Yes | YAPI server URL, e.g., `https://yapi.example.com` |
| `YAPI_PROJECTS` | Yes | Project configuration in format: `projectId1:token1,projectId2:token2` |

### YAPI_PROJECTS Format

```
projectId1:token1,projectId2:token2
```

Example:

```
123:abc123token,456:def456token
```

You can get the project token from YAPI project settings page.

## Usage with Cursor

Add to your Cursor MCP configuration file:

### macOS/Linux

Edit `~/.cursor/mcp.json` and replace `/path/to/yapi-mcp` with your actual project path:

```json
{
  "mcpServers": {
    "yapi": {
      "command": "node",
      "args": ["/path/to/yapi-mcp/dist/index.js"],
      "env": {
        "YAPI_BASE_URL": "https://your-yapi-server.com",
        "YAPI_PROJECTS": "123:your-token-here,456:another-token"
      }
    }
  }
}
```

### Windows

Edit `%APPDATA%\Cursor\mcp.json` and use your actual project path (e.g. `C:\\Users\\YourName\\yapi-mcp\\dist\\index.js`):

```json
{
  "mcpServers": {
    "yapi": {
      "command": "node",
      "args": ["C:\\path\\to\\yapi-mcp\\dist\\index.js"],
      "env": {
        "YAPI_BASE_URL": "https://your-yapi-server.com",
        "YAPI_PROJECTS": "123:your-token-here"
      }
    }
  }
}
```

## Usage with Claude Desktop

Add to your Claude Desktop configuration:

### macOS

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` and replace `/path/to/yapi-mcp` with your actual project path:

```json
{
  "mcpServers": {
    "yapi": {
      "command": "node",
      "args": ["/path/to/yapi-mcp/dist/index.js"],
      "env": {
        "YAPI_BASE_URL": "https://your-yapi-server.com",
        "YAPI_PROJECTS": "123:your-token-here"
      }
    }
  }
}
```

### Windows

Edit `%APPDATA%\Claude\claude_desktop_config.json` with the same configuration, using your actual project path.

## Tool Examples

### List All Projects

```json
{
  "name": "yapi_list_projects",
  "arguments": {}
}
```

### Get Interface List (Default Project)

```json
{
  "name": "yapi_interface_list",
  "arguments": {
    "page": 1,
    "limit": 20
  }
}
```

### Get Interface List (Specific Project)

```json
{
  "name": "yapi_interface_list",
  "arguments": {
    "project": 456,
    "page": 1,
    "limit": 20
  }
}
```

### Add New Interface

```json
{
  "name": "yapi_interface_add",
  "arguments": {
    "catid": 456,
    "title": "Get User Info",
    "path": "/api/user/info",
    "method": "GET",
    "desc": "Get user details by ID"
  }
}
```

### Get Interface Details

```json
{
  "name": "yapi_interface_get",
  "arguments": {
    "id": 789
  }
}
```

### Run Automated Tests

```json
{
  "name": "yapi_run_auto_test",
  "arguments": {
    "project": 456,
    "env_name": "dev"
  }
}
```

## Development

```bash
# Clone the repository
cd yapi-mcp

# Install dependencies
npm install

# Development mode
npm run dev

# Build
npm run build

# Run
npm start
```

## Security

- Never commit your YAPI tokens to version control
- Use environment variables to store sensitive configuration
- Consider using a secrets manager for production deployments

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.