# MCP-SERVER

**Repository Path**: sushiguchangge/mcp-server

## Basic Information

- **Project Name**: MCP-SERVER
- **Description**: 获取你的apifox接口，每个项目都需要进行配置才能获取到，运行：pnpm api:sync
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-17
- **Last Updated**: 2026-08-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Apifox Cursor 同步工具

## 项目简介

这个工具可以自动将 Apifox 中的接口定义同步到本地，让 Cursor 能够直接读取接口信息，无需手动复制粘贴。

## 功能特性

- **自动同步**：从 Apifox 拉取最新的 OpenAPI 接口定义
- **智能压缩**：自动移除冗余字段，节省 Cursor 的 token 消耗
- **无缝集成**：通过 @ 符号直接引用接口定义
- **类型安全**：生成的代码严格遵循接口定义

## 快速开始

### 1. 安装依赖

```bash
npm install
```

或者使用 pnpm：

```bash
pnpm install
```

### 2. 配置环境变量

复制 `.env.example` 为 `.env`，填入您的 Apifox 凭证：

```bash
cp .env.example .env
```

然后编辑 `.env` 文件：

```env
# Apifox 访问令牌
# 获取方式：Apifox -> 设置 -> 账户 -> API 访问 Token
APIFOX_ACCESS_TOKEN=your_api_token_here

# Apifox 项目 ID
# 获取方式：项目设置 -> 基本信息 -> 项目 ID
APIFOX_PROJECT_ID=your_project_id_here
```

### 3. 同步接口

运行同步命令：

```bash
npm run api:sync
```

或者使用 pnpm：

```bash
pnpm api:sync
```

同步成功后，会在 `.cursor/context/apifox.json` 生成接口定义文件。

## 在 Cursor 中使用

### 方式一：使用 @ 引用

在 Cursor 中输入以下提示词：

```
根据 @apifox.json 编写调用用户登录接口的 TypeScript 函数
```

Cursor 会自动读取接口定义，生成正确的代码。

### 方式二：查看接口文档

直接在 Cursor 中输入：

```
查看 @apifox.json 中获取商品列表的接口定义
```

Cursor 会展示该接口的详细信息，包括请求参数和响应格式。

### 方式三：自动补全

在编写 API 调用代码时，Cursor 会自动根据 apifox.json 中的定义提供类型建议和参数提示。

## 项目结构

```
project-root/
├── .cursor/
│   ├── context/
│   │   └── apifox.json    # 同步生成的接口定义
│   └── rules/
│       └── .cursorrules   # Cursor 规则配置
├── scripts/
│   └── sync-apifox.js    # 同步脚本
├── .env                  # 环境变量（包含敏感信息）
├── .env.example          # 环境变量模板
├── package.json          # 项目配置
└── README.md             # 项目文档
```

## 进阶配置

### 自动同步（定时任务）

如果您希望定期自动同步接口，可以使用操作系统的定时任务：

**Windows 任务计划程序**：

```powershell
# 每天上午 9 点执行同步
schtasks /create /tn "Apifox Sync" /tr "npm run api:sync" /sc daily /st 09:00
```

**macOS / Linux crontab**：

```bash
# 每天上午 9 点执行同步
0 9 * * * cd /path/to/project && npm run api:sync
```

### 提交前自动同步

您可以在 Git 提交前自动同步接口定义。编辑 `package.json`：

```json
{
  "scripts": {
    "precommit": "npm run api:sync",
    "api:sync": "node scripts/sync-apifox.js"
  }
}
```

然后在提交时运行：

```bash
npm run precommit && git add .cursor/context/apifox.json && git commit -m "sync: 更新接口定义"
```

### 生成 TypeScript 类型

如果您使用 TypeScript，可以结合 `openapi-typescript` 自动生成类型定义：

```bash
# 安装 openapi-typescript
npm install openapi-typescript --save-dev

# 生成类型定义
npx openapi-typescript .cursor/context/apifox.json -o src/types/api.d.ts
```

## 常见问题

### Q1：同步失败，提示 Token 无效

请检查 `.env` 文件中的 `APIFOX_ACCESS_TOKEN` 是否正确。确保您复制的是完整的 Token，包含 `sk-` 前缀。

### Q2：提示没有权限访问项目

请检查 `APIFOX_PROJECT_ID` 是否正确。确保该项目确实是您的账户下的项目，或者您有该项目的访问权限。

### Q3：Cursor 读取不到接口定义

请确保：

1. 已成功运行 `npm run api:sync`
2. `.cursor/context/apifox.json` 文件存在且内容正确
3. 在 Cursor 中使用 `@apifox.json` 引用（不是 `@apifox`）

### Q4：接口更新后同步没有变化

Apifox 可能有缓存，请尝试在 Apifox 刷新页面后重新同步。或者检查 apifox.json 文件是否已更新。

## 注意事项

1. **敏感信息**：`APIFOX_ACCESS_TOKEN` 是敏感信息，请勿提交到代码仓库。`.env` 文件已添加到 `.gitignore`。

2. **Token 安全**：如果 Token 泄露，请及时在 Apifox 设置中重置。

3. **网络要求**：同步脚本需要能够访问 `api.apifox.com`。如果您的网络无法访问该域名，请配置代理。

4. **文件大小**：接口定义文件可能会比较大。如果接口非常多，可以考虑在 `.cursorrules` 中配置只引用特定模块的接口。

## 技术支持

如果遇到问题，请检查：

1. Node.js 版本是否 >= 14.0.0
2. 网络是否可以访问 Apifox API
3. Token 和 Project ID 是否正确

## 许可证

MIT License