# yapi-mcp

> English | [中文](README.zh-CN.md)

> A zero-dependency [YApi](https://github.com/YMFE/yapi) [MCP](https://modelcontextprotocol.io) server that exposes YApi's API-management capabilities to Claude Code and any MCP client.

## Why this exists

The npm package `@yogeliu/yapi-mcp-server` has two defects that make it **completely unusable**:

1. **Broken `inputSchema` serialization** — it returns the Zod schema *object* itself as `inputSchema`. After `JSON.stringify` it becomes `{"_def":...}`, an invalid structure. MCP clients reject it with `tools fetch failed`, so none of the tools ever load.
2. **Wrong interface-list strategy** — YApi's `/api/interface/list` **ignores `catid`** on most versions and returns only the first page by default. The original package's "iterate categories" approach causes massive duplication and misses most interfaces; it also reads the wrong id field (`_id`).

This project is rewritten from scratch with **zero runtime dependencies** (only Node ≥18 built-in `fetch`), hand-written valid JSON Schemas, and project-level pagination with dedup — fixing all of the above.

## Tools

| Tool | Description |
|---|---|
| `yapi_list_projects` | List the configured project (id / name / desc) |
| `yapi_get_categories` | List project categories and the APIs under each |
| `yapi_search_apis` | Search APIs by keyword (title / path), optional method filter |
| `yapi_get_api_details` | Full detail of one API (params / headers / body / response) |
| `yapi_save_api` | Create or update an API (with `api_id` → update; without → create) |

## Install

### Option 1: npx (recommended)

No install needed — use it directly in your MCP config:
```json
{ "command": "npx", "args": ["-y", "@hizml/yapi-mcp"] }
```

### Option 2: clone
```bash
git clone https://github.com/hizml/yapi-mcp.git
```
Point the config at the local file:
```json
{ "command": "node", "args": ["/absolute/path/to/yapi-mcp/yapi-mcp.mjs"] }
```

## Configuration

Two environment variables:
- `YAPI_BASE_URL` — YApi host, e.g. `http://yapi.example.com`
- `YAPI_TOKEN` — format `projectId:tokenValue`, from the YApi project "Settings → token"

### Claude Code (`~/.claude.json`)
```json
{
  "mcpServers": {
    "yapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@hizml/yapi-mcp"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi-host",
        "YAPI_TOKEN": "227:your_token_here"
      }
    }
  }
}
```
Full example: [`examples/claude-code-config.json`](examples/claude-code-config.json).

## Features

- **Zero dependencies** — pure Node ESM, only Node ≥18 built-in `fetch`
- **Valid JSON Schema** — every `inputSchema` is hand-written standard JSON Schema, so clients validate it fine
- **Full pagination** — project-level pagination + dedup, no missing or duplicate APIs
- **Robust errors** — param errors, timeouts, and YApi `errcode` all become `isError` messages; the process never crashes
- **Debuggable** — set `DEBUG=1` to emit logs to stderr

## Known limitations

- Currently **single-token (single-project)**; for multiple projects, run multiple instances
- YApi's `/api/interface/list` `total` field is unreliable, so this tool stops paginating when a page returns fewer than the page size

## License

MIT