# apiForge-mcp

**Repository Path**: feng-kailong/api-forge-mcp

## Basic Information

- **Project Name**: apiForge-mcp
- **Description**: 一个基于 Model Context Protocol (MCP) 的 Java 服务，主要用于：通过查询项目数据库自动生成 Apifox 测试接口。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-11
- **Last Updated**: 2026-06-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# apiForge-mcp

**简体中文** | [English](README_EN.md)

一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的 Java 服务，主要用于：

> **通过查询项目数据库自动生成 Apifox 测试接口。**

AI 客户端可通过 MCP 协议调用本服务，先用 SQL 查询业务库结构 / 字段 / 样例数据，再把整理出的接口信息以 OpenAPI 3.0 格式提交给 Apifox，从而快速产出可用于联调和测试的接口定义。

---

## 功能特性

- 支持 **STDIO** 与 **HTTP** 两种 MCP 传输模式，默认推荐 STDIO（与 Claude Desktop / Qoder / Cursor 等客户端零网络对接）。
- 内置 3 个 MCP 工具：
    - `createApi`：将一段 OpenAPI 3.0 文档导入到指定 Apifox 项目；
    - `dataSourceSelect`：执行只读 SQL（仅 `SELECT` / `WITH`）查询业务数据库，返回 JSON 结果；
    - `getSwaggerContentExample`：返回一份最小可用的 OpenAPI 3.0 示例，供 AI 在不熟悉格式时参考。
- 通过策略枚举内聚多数据库方言，开箱支持 **MySQL / PostgreSQL / Oracle / SQL Server / MariaDB / SQLite** 6 种数据库。
- 启动时自动建表 `api_forge_record`，对每次 `createApi` 调用做审计记录（可通过 `ENABLE_RECORD=0` 关闭）。
- HikariCP 懒加载共享连接池，业务侧调用 `dataSourceSelect` 与审计写入复用同一个池子。

---

## 技术栈

| 组件 | 版本 |
| --- | --- |
| Java | 17 |
| Spring Boot | 3.2.x |
| MCP Java SDK | 1.1.1（mcp-core + mcp-json-jackson2） |
| 连接池 | HikariCP |
| JSON | fastjson2、Jackson |
| 日志 | logback（STDIO 模式下重定向到 stderr，避免污染 JSON-RPC） |
| 构建 | Maven，`spring-boot-maven-plugin` + `<layout>ZIP</layout>`（启用 PropertiesLauncher） |

---

## 快速开始

### 1. 构建可执行 jar

```bash
mvn -DskipTests clean package
```

产物：`target/apiForge-mcp-1.0.0.jar`

### 2. 在 MCP 客户端注册（STDIO 模式，推荐）

在客户端的 MCP 配置文件（如 `mcp-server-config.json`）的 `mcpServers` 段添加：

```json
{
  "apiForge": {
    "command": "java",
    "args": [
      "-Dloader.main=io.github.nbutfkl.apiforge.mcp.stdio.StdioMcpServerLauncher",
      "-jar",
      "D:/application/my/apiForge-mcp/apiForge/target/apiForge-mcp-1.0.0.jar"
    ],
    "env": {
      "APIFOX_ACCESS_TOKEN": "access_token",
      "APIFOX_PROJECT_ID": "project_id",
      "ENABLE_RECORD": "1",
      "DATASOURCE_TYPE": "mysql",
      "DATASOURCE_HOST": "localhost",
      "DATASOURCE_PORT": "3306",
      "DATASOURCE_USER": "username",
      "DATASOURCE_PASSWORD": "password",
      "DATASOURCE_DATABASE": "database"
    }
  }
}
```

> ⚠️ `args` 顺序很重要：`-Dloader.main=...` 必须在 `-jar` **之前**。否则会被 JVM 当作程序参数透传，导致默认走 HTTP 启动入口，客户端表现为 “Loading tools” 卡死。

### 3. 在客户端中使用

注册成功后，AI 即可调用以下工具：

```
getSwaggerContentExample → 拿到 openapi 3.0 模板
dataSourceSelect         → 查表结构 / 字段说明 / 样例数据
createApi                → 拼成 openapi 3.0 文档导入到 Apifox
```

---

## 环境变量

| 变量 | 必填 | 说明 |
| --- | :---: | --- |
| `APIFOX_ACCESS_TOKEN` | ✅ | Apifox 个人访问令牌，用作 `Authorization: Bearer <token>` |
| `APIFOX_PROJECT_ID`   | ✅ | 目标 Apifox 项目 ID，导入接口时使用 |
| `DATASOURCE_TYPE`     | ✅ | 数据库类型，可选：`mysql` / `postgresql` / `oracle` / `sqlserver` / `mariadb` / `sqlite` |
| `DATASOURCE_HOST`     | ✅ | 数据库主机；SQLite 此项随意（不会用） |
| `DATASOURCE_PORT`     | ⭕ | 数据库端口；SQLite 不需要 |
| `DATASOURCE_USER`     | ✅ | 数据库账号 |
| `DATASOURCE_PASSWORD` | ⭕ | 数据库密码 |
| `DATASOURCE_DATABASE` | ✅ | 数据库名；**SQLite 此处填 `.db` 文件路径** |
| `ENABLE_RECORD`       | ⭕ | 是否记录每次 `createApi` 调用，`0` 关闭，默认开启 |

---

## MCP 工具说明

### `createApi`
- **作用**：把 OpenAPI 3.0 格式的 JSON 文档导入到 `APIFOX_PROJECT_ID` 对应的项目。
- **参数**：
    - `swaggerContent` *(string, 必填)*：OpenAPI 3.0 文档内容。
- **典型调用流程**：
  1. AI 先调 `dataSourceSelect` 查表结构；
  2. 不熟悉格式时调 `getSwaggerContentExample` 拿模板；
  3. 拼装好后调 `createApi` 导入。

### `dataSourceSelect`
- **作用**：在配置的业务库上执行**只读** SQL，返回 JSON 数组结果（最多 100 行，超出截断）。
- **参数**：
    - `sql` *(string, 必填)*：以 `SELECT` 或 `WITH` 开头的查询语句。其它语句会被拒绝。
- **安全说明**：服务侧用关键字前缀做硬校验，避免 AI 误发 DML/DDL。

### `getSwaggerContentExample`
- **作用**：返回一份最小可用的 OpenAPI 3.0 JSON 示例。
- **参数**：无。

---

## 操作记录表 `api_forge_record`

启动时按 `DATASOURCE_TYPE` 自动建表（若不存在），结构如下：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | bigint / bigserial / NUMBER 等 | 自增主键 |
| `content` | text / CLOB / NVARCHAR(MAX) | 调用 `createApi` 时提交的请求体（JSON） |
| `result` | text / CLOB / NVARCHAR(MAX) | Apifox 返回的响应或异常信息 |
| `status` | int | `1` 成功 / `0` 失败 |
| `create_time` | datetime / timestamp | 调用时间 |

如不需要审计写入，把 `ENABLE_RECORD` 置为 `0` 即可。

---

## 启动模式

### STDIO 模式（默认推荐）

入口类：`io.github.nbutfkl.apiforge.mcp.stdio.StdioMcpServerLauncher`

通过 `-Dloader.main` 指定，PropertiesLauncher 会在 fat-jar 内查找该类并加载。

### HTTP 模式

直接 `java -jar apiForge-mcp-1.0.0.jar` 即可，默认监听 `http://localhost:7999/mcp`。
客户端配置改为：

```json
{
  "apiForge": {
    "url": "http://localhost:7999/mcp"
  }
}
```

可在 [`application.yml`](src/main/resources/application.yml) 中调整端口与 endpoint。

---

## 多数据库适配

所有方言相关信息（驱动类、URL 模板、建表 DDL、INSERT SQL）集中在
[`DataSourceTypeEnums`](src/main/java/io/github/nbutfkl/apiforge/mcp/service/enums/DataSourceTypeEnums.java)。
新增数据库只需要：

1. 在该枚举中加一个值；
2. 在 [`pom.xml`](pom.xml) 引入对应 JDBC 驱动；
3. 业务代码无需任何 if-else。

---

## 常见问题

**Q1：客户端一直显示 “Loading tools”？**
A：99% 是 `args` 没加 `-Dloader.main=...` 或顺序错了。STDIO 入口必须显式指定，详见上面 [快速开始 §2](#2-在-mcp-客户端注册stdio-模式推荐)。

**Q2：`MCP error -32603: Failed to obtain JDBC Connection`？**
A：方言策略要求 `DATASOURCE_TYPE` 必填；同时检查白名单 / 网络 / 账号密码。日志在 stderr，可在客户端面板查看或本地用 `2> mcp.err.log` 重定向。

**Q3：`api_forge_record` 表没有写入？**
A：先确认 `ENABLE_RECORD != 0`，再去 stderr 看 `写入 api_forge_record 失败` 的完整堆栈（已经带 `Caused by`），通常是表结构不一致或权限不足。

**Q4：能否禁用日志写到 stderr？**
A：STDIO 协议要求 stdout 严格只走 JSON-RPC，所以日志只能走 stderr，不可改。如需关闭日志，调低 `logging.level` 即可。

---

## 许可证

本项目尚未指定开源协议，使用前请与作者确认。