Content
# Yapi Auto MCP Server
A Model Context Protocol (MCP) server for YApi, allowing you to directly manipulate YApi interface documents in AI programming tools like Cursor.
## Project Introduction
Yapi Auto MCP Server is a server based on [Model Context Protocol](https://modelcontextprotocol.io/), designed specifically for the YApi interface management platform. It allows you to directly:
- 🔍 **Search and view** interface documents in YApi projects
- ✏️ **Create and update** interface definitions
- 📋 **Manage project and category** structures
- 🔗 **Seamlessly integrate** with AI programming workflows
- 🛠 **Support multiple YApi Project configurations**
Through the MCP protocol, AI assistants can understand your YApi interface structure, providing more accurate suggestions and code generation during the programming process.
## Main Features
### 🔍 Interface Query and Search
- **yapi_search_apis**: Search for interfaces by name, path, tags, etc.
- **yapi_get_api_desc**: Get detailed information about a specific interface (request/response structure, parameters, etc.)
- **yapi_list_projects**: List all accessible projects
- **yapi_get_categories**: Get interface categories and interface lists under a project
### ✏️ Interface Management
- **yapi_save_api**: Create a new interface or update an existing one
- Supports complete interface definitions (path, method, parameters, request body, response, etc.)
- Supports JSON Schema and form data formats
- Automatically handles interface status and category management
### 🎯 Intelligent Features
- **Multi-project support**: Manage multiple YApi projects simultaneously
- **Caching mechanism**: Improve query response speed
- **Detailed logs**: Facilitate debugging and monitoring
- **Flexible configuration**: Supports environment variables and command-line arguments
## Quick Start
### Recommended Method: Using npx (No Installation Required)
1. **Get YApi Token**: Log in to your YApi platform and get the Token in the project settings.
2. **Configure Cursor**: Add an MCP server in Cursor settings:
```json
{
"mcpServers": {
"yapi-auto-mcp": {
"command": "npx",
"args": [
"-y",
"yapi-auto-mcp",
"--stdio",
"--yapi-base-url=https://your-yapi-domain.com",
"--yapi-token=projectId:your_token_here"
]
}
}
}
```
3. **Start Using**: Restart Cursor, and you can directly operate YApi in the conversation!
## Installation and Configuration
### Method 1: Directly Use npx (Recommended)
No local installation is required, run directly through npx:
```json
{
"mcpServers": {
"yapi-auto-mcp": {
"command": "npx",
"args": [
"-y",
"yapi-auto-mcp",
"--stdio",
"--yapi-base-url=https://yapi.example.com",
"--yapi-token=projectId:token1,projectId2:token2",
"--yapi-cache-ttl=10",
"--yapi-log-level=info"
]
}
}
}
```
### Method 2: Using Environment Variables
Define environment variables in the MCP configuration:
```json
{
"mcpServers": {
"yapi-auto-mcp": {
"command": "npx",
"args": [
"-y",
"yapi-auto-mcp",
"--stdio"
],
"env": {
"YAPI_BASE_URL": "https://yapi.example.com",
"YAPI_TOKEN": "projectId:token1,projectId2:token2",
"YAPI_CACHE_TTL": "10",
"YAPI_LOG_LEVEL": "info"
}
}
}
}
```
### Method 3: Local Development Mode
Suitable for scenarios where you need to modify code or debug:
1. **Clone and Install**:
```bash
git clone <repository-url>
cd yapi-mcp
pnpm install
```
2. **Configure Environment Variables** (create a `.env` file in the project root directory):
```env
# YApi Basic Configuration
YAPI_BASE_URL=https://your-yapi-domain.com
YAPI_TOKEN=projectId:your_token_here,projectId2:your_token2_here
# Server Configuration
PORT=3388
# Optional Configuration
YAPI_CACHE_TTL=10
YAPI_LOG_LEVEL=info
```
3. **Start the Service**:
**SSE Mode** (HTTP Service):
```bash
pnpm run dev
```
Then configure in Cursor:
```json
{
"mcpServers": {
"yapi-mcp": {
"url": "http://localhost:3388/sse"
}
}
}
```
**Stdio Mode**:
```bash
pnpm run build
node dist/cli.js --stdio
```
## Usage Guide
### Get YApi Token
1. Log in to your YApi platform
2. Go to the project settings page
3. Generate or view the Token in the Token configuration
<img src="./images/token.png" alt="Token Example">
Token format description:
- Single project: `projectId:token`
- Multiple projects: `projectId1:token1,projectId2:token2`
### Usage Example
After configuration, you can use it like this in Cursor:
<img src="./images/demo1.png" alt="Usage Example">
**Common Operation Examples**:
1. **Search for Interfaces**:
> "Help me find interfaces related to user login"
2. **View Interface Details**:
> "Show detailed information about the user registration interface"
3. **Create a New Interface**:
> "Help me create an interface to get a list of users, the path is /api/users, using the GET method"
4. **Update Interface**:
> "Update the user login interface, add a verification code parameter"
## Advanced Configuration
### Command-Line Argument Details
| Argument | Description | Example | Default |
| -------------------- | ------------------------------- | -------------------------------------------- | ------- |
| `--yapi-base-url` | YApi server base URL | `--yapi-base-url=https://yapi.example.com` | - |
| `--yapi-token` | YApi project Token (supports multiple projects) | `--yapi-token=1026:token1,1027:token2` | - |
| `--yapi-cache-ttl` | Cache validity (minutes) | `--yapi-cache-ttl=10` | 10 |
| `--yapi-log-level` | Log level | `--yapi-log-level=info` | info |
| `--port` | HTTP service port (SSE mode) | `--port=3388` | 3388 |
| `--stdio` | Enable stdio mode (MCP required) | `--stdio` | - |
### Environment Variable Description
Create a `.env` file for configuration:
```env
# Required Configuration
YAPI_BASE_URL=https://your-yapi-domain.com
YAPI_TOKEN=projectId:your_token_here
# Optional Configuration
PORT=3388 # HTTP Service Port
YAPI_CACHE_TTL=10 # Cache Validity (minutes)
YAPI_LOG_LEVEL=info # Log Level: debug, info, warn, error, none
```
### Log Level Description
- **debug**: Output all logs, including detailed debugging information
- **info**: Output information, warnings, and error logs (default)
- **warn**: Output only warnings and error logs
- **error**: Output only error logs
- **none**: Do not output any logs
### Configuration Method Selection Suggestions
| Use Case | Recommended Method | Advantages |
| -------- | ------------------ | ---------- |
| Daily Use | npx + Command-Line Arguments | No installation required, simple configuration |
| Team Sharing | npx + Environment Variables | Unified configuration, easy to manage |
| Development Debugging | Local Installation + SSE Mode | Easy to debug and modify code |
| Enterprise Deployment | Local Installation + stdio Mode | Better performance, more stable |
