feat: deploy skill
This commit is contained in:
6
docs/.dockerignore
Normal file
6
docs/.dockerignore
Normal file
@@ -0,0 +1,6 @@
|
||||
node_modules
|
||||
.worktrees
|
||||
.claude
|
||||
.git
|
||||
dist
|
||||
*.zip
|
||||
26
docs/Dockerfile
Normal file
26
docs/Dockerfile
Normal file
@@ -0,0 +1,26 @@
|
||||
# Stage 1: Build environment with HonKit
|
||||
FROM node:20-alpine AS build
|
||||
|
||||
WORKDIR /book
|
||||
|
||||
# Install HonKit globally
|
||||
RUN npm install -g honkit
|
||||
|
||||
# Copy GitBook source files
|
||||
COPY book.json SUMMARY.md README.md faq.md ./
|
||||
COPY introduction/ ./introduction/
|
||||
COPY getting-started/ ./getting-started/
|
||||
COPY mcp-tools/ ./mcp-tools/
|
||||
COPY clients/ ./clients/
|
||||
COPY project-management/ ./project-management/
|
||||
|
||||
# Build static HTML
|
||||
RUN honkit build . /output
|
||||
|
||||
# Stage 2: Serve with nginx
|
||||
FROM nginx:alpine
|
||||
|
||||
COPY --from=build /output /usr/share/nginx/html
|
||||
COPY nginx.conf /etc/nginx/conf.d/default.conf
|
||||
|
||||
EXPOSE 80
|
||||
39
docs/README.md
Normal file
39
docs/README.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# AgentFox 文档
|
||||
|
||||
> **AgentFox** — 为 LLM 而生的 API 文档服务
|
||||
|
||||
AgentFox 将你的 OpenAPI / Swagger 文档转换为 MCP（Model Context Protocol）服务，让 AI 编程助手能够按需查询 API 文档，而不是将整个规范塞进上下文窗口。
|
||||
|
||||
## 为什么选择 AgentFox？
|
||||
|
||||
| 传统方式 | AgentFox |
|
||||
|---------|----------|
|
||||
| 将完整 API 规范粘贴到对话中 | LLM 通过 MCP 按需查询 |
|
||||
| 每次消耗 10,000+ tokens | 每次调用仅 200-2,000 tokens |
|
||||
| 手动复制粘贴，容易遗漏 | 5 个工具自动渐进式下钻 |
|
||||
|
||||
## 快速导航
|
||||
|
||||
- **[什么是 AgentFox](introduction/what-is-agentfox.md)** — 了解产品核心概念
|
||||
- **[MCP 协议介绍](introduction/what-is-mcp.md)** — 了解底层协议
|
||||
- **[快速开始](getting-started/README.md)** — 5 分钟完成首次配置
|
||||
- **[客户端配置](clients/README.md)** — Claude Code、Cursor、Copilot 等配置指南
|
||||
- **[MCP 工具](mcp-tools/README.md)** — 5 个 MCP 工具详细文档
|
||||
- **[常见问题](faq.md)** — FAQ
|
||||
|
||||
## 支持的 AI 工具
|
||||
|
||||
AgentFox 兼容所有支持 MCP 协议的 AI 工具，包括：
|
||||
|
||||
- Claude Desktop / Claude Code
|
||||
- Cursor
|
||||
- GitHub Copilot
|
||||
- Windsurf
|
||||
- Cline
|
||||
- OpenAI Codex CLI
|
||||
- Gemini CLI
|
||||
- 以及更多...
|
||||
|
||||
---
|
||||
|
||||
访问 [www.agentfoxapp.com](https://www.agentfoxapp.com) 免费开始使用。
|
||||
47
docs/SUMMARY.md
Normal file
47
docs/SUMMARY.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# 目录
|
||||
|
||||
* [欢迎使用 AgentFox](README.md)
|
||||
|
||||
## 介绍 <a href="#introduction" id="introduction"></a>
|
||||
|
||||
* [什么是 AgentFox](introduction/what-is-agentfox.md)
|
||||
* [MCP 协议介绍](introduction/what-is-mcp.md)
|
||||
|
||||
## 快速开始 <a href="#getting-started" id="getting-started"></a>
|
||||
|
||||
* [概述](getting-started/README.md)
|
||||
* [注册与登录](getting-started/register-and-login.md)
|
||||
* [导入 API 文档](getting-started/import-api-docs.md)
|
||||
* [生成 API Key](getting-started/generate-api-key.md)
|
||||
* [连接第一个 LLM 客户端](getting-started/connect-first-client.md)
|
||||
|
||||
## MCP 工具 <a href="#mcp-tools" id="mcp-tools"></a>
|
||||
|
||||
* [工具概述](mcp-tools/README.md)
|
||||
* [get_project_overview](mcp-tools/get-project-overview.md)
|
||||
* [list_modules](mcp-tools/list-modules.md)
|
||||
* [list_endpoints](mcp-tools/list-endpoints.md)
|
||||
* [get_endpoint_detail](mcp-tools/get-endpoint-detail.md)
|
||||
* [search_endpoints](mcp-tools/search-endpoints.md)
|
||||
|
||||
## 客户端配置 <a href="#clients" id="clients"></a>
|
||||
|
||||
* [配置概述](clients/README.md)
|
||||
* [Claude Desktop](clients/claude-desktop.md)
|
||||
* [Claude Code](clients/claude-code.md)
|
||||
* [Cursor](clients/cursor.md)
|
||||
* [Windsurf](clients/windsurf.md)
|
||||
* [GitHub Copilot](clients/github-copilot.md)
|
||||
* [Cline](clients/cline.md)
|
||||
* [Codex](clients/codex.md)
|
||||
* [其他 MCP 客户端](clients/other-clients.md)
|
||||
|
||||
## 项目管理 <a href="#project-management" id="project-management"></a>
|
||||
|
||||
* [模块管理](project-management/module-management.md)
|
||||
* [重新导入文档](project-management/reimport-docs.md)
|
||||
* [API Key 管理](project-management/api-key-management.md)
|
||||
|
||||
## 其他 <a href="#other" id="other"></a>
|
||||
|
||||
* [常见问题](faq.md)
|
||||
11
docs/book.json
Normal file
11
docs/book.json
Normal file
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"title": "AgentFox 文档",
|
||||
"description": "AgentFox — 为 LLM 而生的 API 文档服务",
|
||||
"language": "zh-hans",
|
||||
"links": {
|
||||
"sidebar": {
|
||||
"AgentFox 官网": "https://www.agentfoxapp.com"
|
||||
}
|
||||
},
|
||||
"plugins": ["-sharing"]
|
||||
}
|
||||
87
docs/clients/README.md
Normal file
87
docs/clients/README.md
Normal file
@@ -0,0 +1,87 @@
|
||||
# 客户端配置概述
|
||||
|
||||
AgentFox 使用 MCP 协议的 Streamable HTTP 传输方式，兼容所有支持 MCP 的 AI 工具。
|
||||
|
||||
## 通用配置模板
|
||||
|
||||
所有 MCP 客户端都使用类似的 JSON 配置格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/{projectId}",
|
||||
"headers": {
|
||||
"Authorization": "Bearer {your-api-key}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 配置字段说明
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `mcpServers` | MCP 服务器配置的顶层对象 |
|
||||
| `my-api` | 服务器名称，可自定义（建议使用 API 名称，如 `stripe-api`） |
|
||||
| `type` | 传输类型，必须为 `http` |
|
||||
| `url` | MCP 服务 URL，从项目详情的 MCP 标签页复制 |
|
||||
| `headers.Authorization` | 认证头，格式为 `Bearer {你的API-Key}` |
|
||||
|
||||
### 获取配置信息
|
||||
|
||||
1. 登录 [AgentFox 控制台](https://www.agentfoxapp.com)
|
||||
2. 进入项目详情页 → 「MCP」标签
|
||||
3. 复制 MCP 服务 URL
|
||||
4. 从「设置」中获取 API Key
|
||||
|
||||
> **提示**：MCP 标签页中有预生成的配置代码片段，可一键复制。
|
||||
|
||||
## 多项目配置
|
||||
|
||||
如果你有多个项目，可以在 `mcpServers` 中添加多个服务器：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"stripe-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/project-id-1",
|
||||
"headers": {
|
||||
"Authorization": "Bearer afk_your-api-key"
|
||||
}
|
||||
},
|
||||
"github-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/project-id-2",
|
||||
"headers": {
|
||||
"Authorization": "Bearer afk_your-api-key"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 支持的客户端
|
||||
|
||||
| 客户端 | 类型 | 配置指南 |
|
||||
|--------|------|---------|
|
||||
| [Claude Desktop](claude-desktop.md) | 桌面应用 | JSON 配置文件 |
|
||||
| [Claude Code](claude-code.md) | CLI 工具 | 项目级或全局配置 |
|
||||
| [Cursor](cursor.md) | AI 编辑器 | 设置或配置文件 |
|
||||
| [Windsurf](windsurf.md) | AI 编辑器 | JSON 配置文件 |
|
||||
| [GitHub Copilot](github-copilot.md) | VS Code 扩展 | VS Code 配置 |
|
||||
| [Cline](cline.md) | VS Code 扩展 | 扩展设置 |
|
||||
| [Codex](codex.md) | CLI 工具 | CLI 参数或配置文件 |
|
||||
| [其他客户端](other-clients.md) | — | 通用配置 |
|
||||
|
||||
## 连接排障
|
||||
|
||||
如果连接失败，请检查：
|
||||
|
||||
1. **URL 是否正确**：确认 projectId 无误
|
||||
2. **API Key 是否有效**：确认 Key 未被轮换
|
||||
3. **网络是否通畅**：确认能访问 `www.agentfoxapp.com`
|
||||
4. **配置格式**：确认 `type` 为 `http`（不是 `sse` 或 `stdio`）
|
||||
70
docs/clients/claude-code.md
Normal file
70
docs/clients/claude-code.md
Normal file
@@ -0,0 +1,70 @@
|
||||
# Claude Code
|
||||
|
||||
Claude Code 是 Anthropic 的 CLI 编程助手，支持项目级和全局两种 MCP 配置方式。
|
||||
|
||||
## 方式一：项目级配置（推荐）
|
||||
|
||||
在项目根目录创建 `.mcp.json` 文件：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/{projectId}",
|
||||
"headers": {
|
||||
"Authorization": "Bearer {your-api-key}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
优点：配置跟随项目，团队成员可共享（注意不要将 API Key 提交到版本控制）。
|
||||
|
||||
## 方式二：全局配置
|
||||
|
||||
编辑 `~/.claude.json`，在顶层添加 `mcpServers`：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/{projectId}",
|
||||
"headers": {
|
||||
"Authorization": "Bearer {your-api-key}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
全局配置对所有项目生效。
|
||||
|
||||
## 验证连接
|
||||
|
||||
启动 Claude Code 后，可以通过以下方式验证：
|
||||
|
||||
```bash
|
||||
# 列出已配置的 MCP 服务器
|
||||
claude mcp list
|
||||
```
|
||||
|
||||
或在对话中直接使用：
|
||||
|
||||
```
|
||||
你：帮我看看这个 API 有哪些模块
|
||||
Claude：[调用 get_project_overview]
|
||||
这个 API 包含以下模块：...
|
||||
```
|
||||
|
||||
## 安全提示
|
||||
|
||||
如果使用项目级配置，建议将 `.mcp.json` 添加到 `.gitignore`，避免 API Key 泄露：
|
||||
|
||||
```bash
|
||||
echo ".mcp.json" >> .gitignore
|
||||
```
|
||||
|
||||
或者使用环境变量（如果客户端支持）来管理 API Key。
|
||||
77
docs/clients/claude-desktop.md
Normal file
77
docs/clients/claude-desktop.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# Claude Desktop
|
||||
|
||||
Claude Desktop 是 Anthropic 的桌面客户端，原生支持 MCP 协议。
|
||||
|
||||
## 配置步骤
|
||||
|
||||
### 1. 找到配置文件
|
||||
|
||||
| 系统 | 路径 |
|
||||
|------|------|
|
||||
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
|
||||
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
|
||||
|
||||
如果文件不存在，手动创建即可。
|
||||
|
||||
### 2. 编辑配置文件
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/{projectId}",
|
||||
"headers": {
|
||||
"Authorization": "Bearer {your-api-key}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
将 `{projectId}` 和 `{your-api-key}` 替换为实际值。
|
||||
|
||||
### 3. 重启 Claude Desktop
|
||||
|
||||
保存配置文件后，完全退出并重新打开 Claude Desktop。
|
||||
|
||||
### 4. 验证连接
|
||||
|
||||
在 Claude Desktop 中发送消息：
|
||||
|
||||
```
|
||||
请调用 get_project_overview 查看 API 概览
|
||||
```
|
||||
|
||||
如果看到项目信息，说明配置成功。
|
||||
|
||||
## 多项目配置
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"stripe-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/project-id-1",
|
||||
"headers": {
|
||||
"Authorization": "Bearer afk_your-key"
|
||||
}
|
||||
},
|
||||
"internal-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/project-id-2",
|
||||
"headers": {
|
||||
"Authorization": "Bearer afk_your-key"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
**Q: 修改配置后需要重启吗？**
|
||||
A: 是的，Claude Desktop 需要重启才能加载新的 MCP 配置。
|
||||
|
||||
**Q: 如何确认 MCP 服务已连接？**
|
||||
A: 在对话中，Claude 会自动识别可用的 MCP 工具。你可以直接要求它调用 AgentFox 的工具。
|
||||
51
docs/clients/cline.md
Normal file
51
docs/clients/cline.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# Cline
|
||||
|
||||
Cline 是一个 VS Code 扩展，提供 AI 编程助手功能，支持 MCP 协议。
|
||||
|
||||
## 配置步骤
|
||||
|
||||
### 1. 打开 MCP 设置
|
||||
|
||||
1. 打开 VS Code
|
||||
2. 点击侧栏的 Cline 图标
|
||||
3. 点击 MCP Servers 设置（齿轮图标）
|
||||
|
||||
### 2. 添加 AgentFox 服务器
|
||||
|
||||
在 MCP 配置中添加：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/{projectId}",
|
||||
"headers": {
|
||||
"Authorization": "Bearer {your-api-key}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 保存并验证
|
||||
|
||||
保存配置后，Cline 会自动连接 MCP 服务器。你可以在 MCP Servers 列表中看到连接状态。
|
||||
|
||||
## 使用方法
|
||||
|
||||
在 Cline 的对话中直接使用：
|
||||
|
||||
```
|
||||
你：根据 API 文档帮我实现用户登录功能
|
||||
Cline：让我先查看 API 文档...
|
||||
[调用 search_endpoints keyword="login"]
|
||||
[调用 get_endpoint_detail endpointId="..."]
|
||||
根据文档，登录接口是 POST /auth/login...
|
||||
```
|
||||
|
||||
## 验证连接
|
||||
|
||||
在 Cline 的 MCP Servers 面板中：
|
||||
- 绿色状态表示已连接
|
||||
- 可以查看已注册的 5 个 AgentFox 工具
|
||||
61
docs/clients/codex.md
Normal file
61
docs/clients/codex.md
Normal file
@@ -0,0 +1,61 @@
|
||||
# Codex (OpenAI)
|
||||
|
||||
Codex 是 OpenAI 推出的 CLI 编程助手，支持 MCP 协议。
|
||||
|
||||
## 配置步骤
|
||||
|
||||
### 方式一：通过 CLI 参数
|
||||
|
||||
```bash
|
||||
codex --mcp-config '{"my-api":{"type":"http","url":"https://www.agentfoxapp.com/mcp/{projectId}","headers":{"Authorization":"Bearer {your-api-key}"}}}'
|
||||
```
|
||||
|
||||
### 方式二：通过配置文件
|
||||
|
||||
编辑 `~/.codex/config.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/{projectId}",
|
||||
"headers": {
|
||||
"Authorization": "Bearer {your-api-key}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 方式三：项目级配置
|
||||
|
||||
在项目根目录创建 `.codex/mcp.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/{projectId}",
|
||||
"headers": {
|
||||
"Authorization": "Bearer {your-api-key}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 验证连接
|
||||
|
||||
启动 Codex 后，在对话中测试：
|
||||
|
||||
```
|
||||
你：调用 get_project_overview 查看 API 信息
|
||||
Codex：[调用 get_project_overview]
|
||||
项目信息如下：...
|
||||
```
|
||||
|
||||
## 安全提示
|
||||
|
||||
使用项目级配置时，建议将 `.codex/` 添加到 `.gitignore`。
|
||||
56
docs/clients/cursor.md
Normal file
56
docs/clients/cursor.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# Cursor
|
||||
|
||||
Cursor 是一款 AI 代码编辑器，支持通过 MCP 协议连接外部工具。
|
||||
|
||||
## 配置步骤
|
||||
|
||||
### 方式一：通过配置文件
|
||||
|
||||
在项目根目录创建 `.cursor/mcp.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/{projectId}",
|
||||
"headers": {
|
||||
"Authorization": "Bearer {your-api-key}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 方式二：通过设置界面
|
||||
|
||||
1. 打开 Cursor 设置（`Cmd/Ctrl + ,`）
|
||||
2. 搜索 "MCP"
|
||||
3. 在 MCP Servers 配置区域添加服务器信息
|
||||
|
||||
## 使用方法
|
||||
|
||||
配置完成后，在 Cursor 的 AI 对话中（Agent 模式）即可使用 AgentFox 的 MCP 工具：
|
||||
|
||||
```
|
||||
你：帮我调用用户注册接口，参考 API 文档
|
||||
Cursor：[调用 search_endpoints keyword="register"]
|
||||
[调用 get_endpoint_detail endpointId="..."]
|
||||
根据 API 文档，注册接口是 POST /api/users/register...
|
||||
```
|
||||
|
||||
> **提示**：确保使用 Cursor 的 Agent 模式（而非 Ask 模式），Agent 模式才能调用 MCP 工具。
|
||||
|
||||
## 验证连接
|
||||
|
||||
1. 打开 Cursor 设置 → MCP 区域
|
||||
2. 检查 AgentFox 服务器状态是否显示为已连接（绿色指示灯）
|
||||
3. 在对话中要求调用 `get_project_overview` 测试
|
||||
|
||||
## 安全提示
|
||||
|
||||
建议将 `.cursor/mcp.json` 添加到 `.gitignore`：
|
||||
|
||||
```bash
|
||||
echo ".cursor/mcp.json" >> .gitignore
|
||||
```
|
||||
71
docs/clients/github-copilot.md
Normal file
71
docs/clients/github-copilot.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# GitHub Copilot
|
||||
|
||||
GitHub Copilot 通过 VS Code 的 MCP 支持连接 AgentFox。
|
||||
|
||||
## 前提条件
|
||||
|
||||
- VS Code 版本 1.99 或更高
|
||||
- GitHub Copilot 扩展已安装并激活
|
||||
- GitHub Copilot Chat 扩展已安装
|
||||
|
||||
## 配置步骤
|
||||
|
||||
### 方式一：项目级配置（推荐）
|
||||
|
||||
在项目根目录创建 `.vscode/mcp.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"my-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/{projectId}",
|
||||
"headers": {
|
||||
"Authorization": "Bearer {your-api-key}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **注意**：VS Code MCP 配置的顶层键是 `servers`，不是 `mcpServers`。
|
||||
|
||||
### 方式二：用户级配置
|
||||
|
||||
在 VS Code 的 `settings.json` 中添加：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp": {
|
||||
"servers": {
|
||||
"my-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/{projectId}",
|
||||
"headers": {
|
||||
"Authorization": "Bearer {your-api-key}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 使用方法
|
||||
|
||||
在 Copilot Chat 中使用 Agent 模式（`@workspace` 或直接对话）：
|
||||
|
||||
```
|
||||
你：帮我查看支付相关的 API 端点
|
||||
Copilot：[调用 search_endpoints keyword="payment"]
|
||||
找到以下支付相关端点：...
|
||||
```
|
||||
|
||||
## 验证连接
|
||||
|
||||
1. 打开 VS Code 命令面板（`Cmd/Ctrl + Shift + P`）
|
||||
2. 搜索 "MCP: List Servers"
|
||||
3. 确认 AgentFox 服务器状态为已连接
|
||||
|
||||
## 安全提示
|
||||
|
||||
建议将 `.vscode/mcp.json` 添加到 `.gitignore`，或使用 VS Code 的用户级配置来避免 API Key 泄露。
|
||||
82
docs/clients/other-clients.md
Normal file
82
docs/clients/other-clients.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# 其他 MCP 客户端
|
||||
|
||||
任何支持 MCP 协议 Streamable HTTP 传输的 AI 工具都可以连接 AgentFox。
|
||||
|
||||
## 连接要素
|
||||
|
||||
连接 AgentFox 只需要三个信息：
|
||||
|
||||
| 要素 | 值 |
|
||||
|------|-----|
|
||||
| **传输类型** | HTTP（Streamable HTTP） |
|
||||
| **URL** | `https://www.agentfoxapp.com/mcp/{projectId}` |
|
||||
| **认证** | `Authorization: Bearer {your-api-key}` |
|
||||
|
||||
## 通用配置格式
|
||||
|
||||
大多数 MCP 客户端使用 JSON 配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/{projectId}",
|
||||
"headers": {
|
||||
"Authorization": "Bearer {your-api-key}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 其他已知兼容客户端
|
||||
|
||||
### Gemini CLI
|
||||
|
||||
Google 的 Gemini CLI 工具支持 MCP 协议。编辑 `~/.gemini/settings.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/{projectId}",
|
||||
"headers": {
|
||||
"Authorization": "Bearer {your-api-key}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Antigravity
|
||||
|
||||
Antigravity AI 开发平台支持 MCP。在平台的 MCP 配置中添加 AgentFox 服务器即可。
|
||||
|
||||
### OpenClaw
|
||||
|
||||
OpenClaw AI 开发平台同样支持 MCP 协议，配置方式类似。
|
||||
|
||||
## 技术细节
|
||||
|
||||
如果你的工具需要手动实现 MCP 客户端连接，以下是关键技术参数：
|
||||
|
||||
| 参数 | 值 |
|
||||
|------|-----|
|
||||
| 协议 | MCP (Model Context Protocol) |
|
||||
| 传输方式 | Streamable HTTP |
|
||||
| HTTP 方法 | POST（发送请求）、GET（SSE 会话恢复）、DELETE（终止会话） |
|
||||
| 会话管理 | 通过 `mcp-session-id` 响应头建立，后续请求携带 |
|
||||
| 认证方式 | HTTP Bearer Token |
|
||||
| Content-Type | `application/json` |
|
||||
|
||||
## 自检清单
|
||||
|
||||
如果连接不成功，请检查：
|
||||
|
||||
- [ ] 传输类型是 `http`（不是 `sse` 或 `stdio`）
|
||||
- [ ] URL 包含正确的 projectId
|
||||
- [ ] API Key 以 `afk_` 开头
|
||||
- [ ] Authorization 头格式为 `Bearer {key}`（注意 Bearer 后有空格）
|
||||
- [ ] 网络可以访问 `www.agentfoxapp.com`
|
||||
45
docs/clients/windsurf.md
Normal file
45
docs/clients/windsurf.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# Windsurf
|
||||
|
||||
Windsurf 是 Codeium 推出的 AI 代码编辑器，支持 MCP 协议。
|
||||
|
||||
## 配置步骤
|
||||
|
||||
### 1. 找到配置文件
|
||||
|
||||
| 系统 | 路径 |
|
||||
|------|------|
|
||||
| macOS | `~/.codeium/windsurf/mcp_config.json` |
|
||||
| Windows | `%USERPROFILE%\.codeium\windsurf\mcp_config.json` |
|
||||
| Linux | `~/.codeium/windsurf/mcp_config.json` |
|
||||
|
||||
如果文件不存在，手动创建即可。
|
||||
|
||||
### 2. 编辑配置文件
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/{projectId}",
|
||||
"headers": {
|
||||
"Authorization": "Bearer {your-api-key}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 重启 Windsurf
|
||||
|
||||
保存配置后，重启 Windsurf 使配置生效。
|
||||
|
||||
## 验证连接
|
||||
|
||||
在 Windsurf 的 Cascade 对话中：
|
||||
|
||||
```
|
||||
你：请调用 get_project_overview 查看我的 API 概览
|
||||
```
|
||||
|
||||
如果返回了项目信息，说明配置成功。
|
||||
47
docs/faq.md
Normal file
47
docs/faq.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# 常见问题
|
||||
|
||||
## 什么是 MCP？AgentFox 如何使用它？
|
||||
|
||||
MCP（Model Context Protocol）是一个开放标准，让 AI 助手能够连接外部工具和数据源。AgentFox 通过 MCP 工具暴露你的 API 文档，让 Claude Code、Cursor、Copilot 等 AI 编程助手可以按需查询端点详情，而无需将整个规范放入上下文窗口。
|
||||
|
||||
## 支持哪些 OpenAPI 格式？
|
||||
|
||||
AgentFox 支持 OpenAPI 3.x 和 Swagger 2.0 规范。你可以导入 JSON 或 YAML 格式的文档，也可以提供 URL 直接获取。导入时所有 `$ref` 引用会自动解引用。
|
||||
|
||||
## 能减少多少 Token 消耗？
|
||||
|
||||
每次 MCP 工具调用返回约 200-2,000 tokens 的精准信息，相比全量 API 规范的 10,000+ tokens。对于典型的集成任务，这意味着 **80-95%** 的 token 消耗降低。
|
||||
|
||||
## 我的 API 文档安全吗？
|
||||
|
||||
是的。每个账号拥有独立的 API Key（bcrypt 哈希加密，从不以明文存储）。MCP 端点每次请求都需要认证。用户控制台使用 JWT 并自动轮换 token。
|
||||
|
||||
## 兼容哪些 AI 工具？
|
||||
|
||||
任何支持 MCP 协议的工具都可以连接 AgentFox，包括 Claude Desktop、Claude Code、Cursor、Windsurf、GitHub Copilot、Cline、OpenAI Codex CLI、Gemini CLI 等。如果你的工具支持 MCP，就能与 AgentFox 配合使用。
|
||||
|
||||
## 可以私有化部署吗？
|
||||
|
||||
可以。AgentFox 支持云端和私有化部署。企业版包含完整的 Docker Compose 私有化部署支持，以及 SSO 集成和专属技术支持。
|
||||
|
||||
## 如何更新已导入的 API 文档？
|
||||
|
||||
在项目详情的「设置」标签中，点击「重新导入文档」。重新导入会替换所有模块和端点数据，但项目 ID 和 API Key 保持不变，LLM 客户端无需重新配置。详见 [重新导入文档](project-management/reimport-docs.md)。
|
||||
|
||||
## 丢失了 API Key 怎么办？
|
||||
|
||||
如果你是邮箱注册的用户，可以在「设置」中通过密码验证查看已有 Key。如果完全无法找回，可以轮换生成新的 Key（旧 Key 会立即失效）。详见 [API Key 管理](project-management/api-key-management.md)。
|
||||
|
||||
## MCP 连接失败怎么排查？
|
||||
|
||||
1. 确认 `type` 是 `http`（不是 `sse` 或 `stdio`）
|
||||
2. 确认 URL 中的 projectId 正确
|
||||
3. 确认 API Key 有效且格式为 `Bearer {key}`
|
||||
4. 确认网络可以访问 `www.agentfoxapp.com`
|
||||
5. 尝试重启 AI 工具
|
||||
|
||||
详见 [客户端配置概述](clients/README.md) 中的连接排障部分。
|
||||
|
||||
## 一个 API Key 可以用于多个项目吗？
|
||||
|
||||
是的。AgentFox 的 API Key 是账号级别的，一个 Key 对你账号下的所有项目生效。你只需要在 MCP 配置中使用不同的项目 URL 即可。
|
||||
39
docs/getting-started/README.md
Normal file
39
docs/getting-started/README.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# 快速开始
|
||||
|
||||
只需 4 步，即可让你的 AI 编程助手通过 MCP 查询 API 文档。
|
||||
|
||||
## 准备工作
|
||||
|
||||
- 一个浏览器（用于访问 AgentFox 控制台）
|
||||
- 一份 OpenAPI 3.x 或 Swagger 2.0 文档（JSON/YAML 文件或可访问的 URL）
|
||||
- 一个支持 MCP 的 AI 工具（Claude Code、Cursor、Copilot 等）
|
||||
|
||||
## 步骤
|
||||
|
||||
| 步骤 | 说明 | 耗时 |
|
||||
|------|------|------|
|
||||
| 1. [注册与登录](register-and-login.md) | 创建 AgentFox 账号 | 1 分钟 |
|
||||
| 2. [导入 API 文档](import-api-docs.md) | 上传 OpenAPI 文档 | 1 分钟 |
|
||||
| 3. [生成 API Key](generate-api-key.md) | 获取 MCP 认证密钥 | 30 秒 |
|
||||
| 4. [连接 LLM 客户端](connect-first-client.md) | 配置 AI 工具 | 2 分钟 |
|
||||
|
||||
完成后，你的 AI 助手就可以直接查询 API 文档了。
|
||||
|
||||
## 完成效果
|
||||
|
||||
配置完成后，你可以在 AI 工具中这样使用：
|
||||
|
||||
```
|
||||
你：帮我调用 Stripe 的创建支付接口
|
||||
|
||||
AI：让我先查看一下 API 文档...
|
||||
[调用 get_project_overview]
|
||||
[调用 list_endpoints moduleId="payments"]
|
||||
[调用 get_endpoint_detail endpointId="create-charge"]
|
||||
|
||||
根据 API 文档，创建支付的接口是：
|
||||
POST /v1/charges
|
||||
需要参数：amount, currency, source...
|
||||
```
|
||||
|
||||
AI 助手会自动通过 MCP 工具获取所需信息，无需你手动复制文档。
|
||||
75
docs/getting-started/connect-first-client.md
Normal file
75
docs/getting-started/connect-first-client.md
Normal file
@@ -0,0 +1,75 @@
|
||||
# 连接第一个 LLM 客户端
|
||||
|
||||
现在你已经有了项目和 API Key，可以将 AI 工具连接到 AgentFox 的 MCP 服务。
|
||||
|
||||
## 获取 MCP 配置信息
|
||||
|
||||
在项目详情页的「MCP」标签页中，你可以找到：
|
||||
|
||||
1. **MCP 服务 URL**：`https://www.agentfoxapp.com/mcp/{你的项目ID}`
|
||||
2. **配置代码片段**：可一键复制的 JSON 配置
|
||||
|
||||
## 通用配置模板
|
||||
|
||||
所有支持 MCP 的 AI 工具都使用类似的配置格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/{projectId}",
|
||||
"headers": {
|
||||
"Authorization": "Bearer {your-api-key}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
将 `{projectId}` 替换为你的项目 ID（从 MCP 标签页复制），将 `{your-api-key}` 替换为你的 API Key。
|
||||
|
||||
## 快速示例：Claude Code
|
||||
|
||||
以 Claude Code 为例，最快的连接方式：
|
||||
|
||||
1. 在项目根目录创建 `.mcp.json` 文件：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-api": {
|
||||
"type": "http",
|
||||
"url": "https://www.agentfoxapp.com/mcp/你的项目ID",
|
||||
"headers": {
|
||||
"Authorization": "Bearer 你的API-Key"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. 重启 Claude Code，即可使用
|
||||
|
||||
## 验证连接
|
||||
|
||||
连接成功后，你可以让 AI 助手执行一个简单的测试：
|
||||
|
||||
```
|
||||
你：调用 get_project_overview 查看 API 概览
|
||||
```
|
||||
|
||||
如果返回了项目名称、版本和模块列表，说明连接成功。
|
||||
|
||||
## 各客户端详细配置
|
||||
|
||||
不同 AI 工具的配置方式略有差异，请参考对应的详细指南：
|
||||
|
||||
- [Claude Desktop](../clients/claude-desktop.md)
|
||||
- [Claude Code](../clients/claude-code.md)
|
||||
- [Cursor](../clients/cursor.md)
|
||||
- [Windsurf](../clients/windsurf.md)
|
||||
- [GitHub Copilot](../clients/github-copilot.md)
|
||||
- [Cline](../clients/cline.md)
|
||||
- [Codex (OpenAI)](../clients/codex.md)
|
||||
- [其他客户端](../clients/other-clients.md)
|
||||
49
docs/getting-started/generate-api-key.md
Normal file
49
docs/getting-started/generate-api-key.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# 生成 API Key
|
||||
|
||||
API Key 是 LLM 客户端连接 AgentFox MCP 服务的认证凭证。你需要先生成一个 API Key 才能使用 MCP 服务。
|
||||
|
||||
## 生成步骤
|
||||
|
||||
1. 进入任意项目的详情页
|
||||
2. 点击页面顶部的「设置」（用户头像旁）
|
||||
3. 在「API Key」区域，点击「生成 API Key」
|
||||
4. 生成的密钥会立即显示
|
||||
|
||||
> **重要**：API Key 仅在生成时显示一次，之后无法再次查看完整密钥。请立即复制并安全保存。
|
||||
|
||||
## API Key 格式
|
||||
|
||||
API Key 以 `afk_` 为前缀，例如：
|
||||
|
||||
```
|
||||
afk_dGhpcyBpcyBhIHNhbXBsZQ
|
||||
```
|
||||
|
||||
## 安全说明
|
||||
|
||||
- API Key 使用 bcrypt 哈希加密存储，AgentFox 不保存明文密钥
|
||||
- 一个账号只有一个 API Key，对该账号下所有项目生效
|
||||
- 如果你通过第三方登录（Google/GitHub），需要先在「设置」中设置密码，才能查看或复制 API Key
|
||||
|
||||
## 查看和复制已有 Key
|
||||
|
||||
如果你之前已生成过 API Key：
|
||||
|
||||
1. 打开「设置」
|
||||
2. 在 API Key 区域，点击「查看」或「复制」
|
||||
3. 输入账号密码进行验证
|
||||
4. 验证通过后可查看或复制完整密钥
|
||||
|
||||
## 轮换 API Key
|
||||
|
||||
如果密钥泄露或需要更新：
|
||||
|
||||
1. 打开「设置」→ API Key 区域
|
||||
2. 点击「轮换 API Key」
|
||||
3. 确认操作
|
||||
|
||||
> **注意**：轮换后旧密钥立即失效，所有使用旧密钥的 MCP 客户端需要更新配置。
|
||||
|
||||
## 下一步
|
||||
|
||||
拿到 API Key 后，就可以 [连接你的第一个 LLM 客户端](connect-first-client.md) 了。
|
||||
59
docs/getting-started/import-api-docs.md
Normal file
59
docs/getting-started/import-api-docs.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# 导入 API 文档
|
||||
|
||||
AgentFox 支持导入 OpenAPI 3.x 和 Swagger 2.0 格式的 API 文档。
|
||||
|
||||
## 导入方式
|
||||
|
||||
### 方式一：从 URL 导入
|
||||
|
||||
1. 在控制台点击「导入 API 文档」按钮
|
||||
2. 选择「从 URL」标签
|
||||
3. 粘贴 OpenAPI 文档的 URL
|
||||
4. 点击「导入」
|
||||
|
||||
> **提示**：支持 localhost 和内网地址。AgentFox 会先尝试在浏览器端直接获取，如果遇到 CORS 限制，会自动通过服务端代理获取。
|
||||
|
||||
### 方式二：上传文件
|
||||
|
||||
1. 在控制台点击「导入 API 文档」按钮
|
||||
2. 选择「上传文件」标签
|
||||
3. 拖放文件到上传区域，或点击选择文件
|
||||
4. 支持 `.json`、`.yaml`、`.yml` 格式
|
||||
5. 点击「导入」
|
||||
|
||||
## 支持的格式
|
||||
|
||||
| 格式 | 版本 | 说明 |
|
||||
|------|------|------|
|
||||
| OpenAPI | 3.0 / 3.1 | 推荐，功能最完整 |
|
||||
| Swagger | 2.0 | 完整支持，自动转换 body 参数为 requestBody 格式 |
|
||||
|
||||
支持的文件类型：
|
||||
- JSON（`.json`）
|
||||
- YAML（`.yaml` / `.yml`）
|
||||
|
||||
## 导入后会发生什么？
|
||||
|
||||
1. **验证**：AgentFox 使用 `swagger-parser` 验证文档格式
|
||||
2. **解引用**：所有 `$ref` 引用被自动展开
|
||||
3. **分组**：端点按 OpenAPI tags 或 URL 路径前缀自动分组为模块
|
||||
4. **索引**：所有端点的参数、请求体、响应格式被索引存储
|
||||
|
||||
导入成功后，你将看到：
|
||||
- 项目名称（来自文档的 `info.title`）
|
||||
- 解析出的模块数量
|
||||
- 解析出的端点数量
|
||||
|
||||
## 示例：导入 Petstore API
|
||||
|
||||
你可以用以下公开的 OpenAPI 文档来测试：
|
||||
|
||||
```
|
||||
https://petstore3.swagger.io/api/v3/openapi.json
|
||||
```
|
||||
|
||||
导入后将创建包含多个模块（pet、store、user）和对应端点的项目。
|
||||
|
||||
## 下一步
|
||||
|
||||
文档导入成功后，接下来 [生成 API Key](generate-api-key.md) 以启用 MCP 服务。
|
||||
31
docs/getting-started/register-and-login.md
Normal file
31
docs/getting-started/register-and-login.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# 注册与登录
|
||||
|
||||
## 创建账号
|
||||
|
||||
访问 [www.agentfoxapp.com](https://www.agentfoxapp.com)，点击右上角的「免费开始」按钮。
|
||||
|
||||
### 方式一：邮箱注册
|
||||
|
||||
1. 点击「注册」
|
||||
2. 填写姓名、邮箱和密码（至少 8 个字符）
|
||||
3. 点击「创建账号」
|
||||
4. 自动跳转到控制台
|
||||
|
||||
### 方式二：第三方登录
|
||||
|
||||
AgentFox 支持以下第三方登录：
|
||||
|
||||
- **Google** — 使用 Google 账号快速登录
|
||||
- **GitHub** — 使用 GitHub 账号快速登录
|
||||
|
||||
点击对应的图标即可跳转到授权页面，授权后自动返回 AgentFox 控制台。
|
||||
|
||||
> **提示**：通过第三方登录的用户，如需查看或复制 API Key，需要先在「设置」中设置密码。
|
||||
|
||||
## 登录
|
||||
|
||||
已有账号的用户，直接在登录页输入邮箱和密码，或使用之前关联的第三方账号登录。
|
||||
|
||||
## 下一步
|
||||
|
||||
登录成功后，你将进入控制台。接下来 [导入你的第一份 API 文档](import-api-docs.md)。
|
||||
69
docs/introduction/what-is-agentfox.md
Normal file
69
docs/introduction/what-is-agentfox.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# 什么是 AgentFox
|
||||
|
||||
AgentFox 是一个 MCP 驱动的 API 文档服务，让 AI 编程助手（如 Claude Code、Cursor、GitHub Copilot）能够高效地查询你的 API 文档。
|
||||
|
||||
## 解决什么问题？
|
||||
|
||||
当你使用 AI 编程助手调用第三方 API 时，通常需要将 API 文档提供给 LLM。传统做法是将整个 OpenAPI 规范复制粘贴到对话中，这带来了几个问题：
|
||||
|
||||
- **Token 浪费**：一份完整的 OpenAPI 规范可能消耗 10,000-100,000+ tokens，而你可能只需要其中一个端点的信息
|
||||
- **上下文污染**：大量无关信息会降低 LLM 的理解准确度
|
||||
- **手动操作**：每次都需要手动查找、复制文档
|
||||
|
||||
## AgentFox 如何工作？
|
||||
|
||||
```
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ OpenAPI 文档 │───▶│ AgentFox │───▶│ MCP 端点 │
|
||||
│ (JSON/YAML) │ │ 解析 & 索引 │ │ /mcp/:id │
|
||||
└──────────────┘ └──────────────┘ └──────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ LLM 按需查询 │
|
||||
│ ~200-2K tokens │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
1. **导入**：上传 OpenAPI 3.x 或 Swagger 2.0 文档（JSON/YAML 文件或 URL）
|
||||
2. **解析**：AgentFox 自动解引用所有 `$ref`，将文档解析为模块和端点
|
||||
3. **生成 MCP 端点**：每个项目获得唯一的 MCP 服务 URL
|
||||
4. **LLM 按需查询**：AI 工具通过 5 个 MCP 工具渐进式获取所需信息
|
||||
|
||||
## 核心优势
|
||||
|
||||
### 渐进式下钻
|
||||
|
||||
LLM 不需要一次获取所有信息。它可以：
|
||||
- 先查看项目概览，了解有哪些模块
|
||||
- 再查看特定模块的端点列表
|
||||
- 最后获取具体端点的完整参数和响应格式
|
||||
|
||||
### Token 高效
|
||||
|
||||
| 操作 | Token 消耗 |
|
||||
|------|-----------|
|
||||
| `get_project_overview` | ~200 tokens |
|
||||
| `list_modules` | ~100-300 tokens |
|
||||
| `list_endpoints` | ~200-500 tokens |
|
||||
| `get_endpoint_detail` | ~500-2,000 tokens |
|
||||
| `search_endpoints` | ~200-500 tokens |
|
||||
| **全量 OpenAPI 规范** | **10,000-100,000+ tokens** |
|
||||
|
||||
典型的 API 集成任务只需 2-3 次工具调用（约 1,300 tokens），相比全量规范节省 **80-95%** 的 token 消耗。
|
||||
|
||||
### 全规范支持
|
||||
|
||||
- OpenAPI 3.0 / 3.1
|
||||
- Swagger 2.0
|
||||
- JSON 和 YAML 格式
|
||||
- 所有 `$ref` 引用自动解引用
|
||||
|
||||
### 一键导入
|
||||
|
||||
粘贴 URL 或上传文件，API 文档即时解析并索引。支持从 localhost 和内网地址获取文档。
|
||||
|
||||
## 下一步
|
||||
|
||||
- [了解 MCP 协议](what-is-mcp.md)
|
||||
- [快速开始](../getting-started/README.md)
|
||||
65
docs/introduction/what-is-mcp.md
Normal file
65
docs/introduction/what-is-mcp.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# MCP 协议介绍
|
||||
|
||||
MCP（Model Context Protocol）是由 Anthropic 推出的开放标准协议，用于连接 AI 助手与外部工具和数据源。
|
||||
|
||||
## 什么是 MCP？
|
||||
|
||||
你可以把 MCP 理解为 AI 世界的 "USB 接口"：
|
||||
|
||||
- **统一标准**：一个协议连接所有 AI 工具和数据源
|
||||
- **双向通信**：AI 助手可以调用工具，也可以接收数据
|
||||
- **安全可控**：每个连接都有明确的权限和认证机制
|
||||
|
||||
```
|
||||
┌────────────┐ MCP 协议 ┌────────────┐
|
||||
│ │◀────────────────────────▶│ │
|
||||
│ MCP 客户端 │ Streamable HTTP │ MCP 服务器 │
|
||||
│ (AI 工具) │ │ (数据源/工具) │
|
||||
│ │ Tools / Resources │ │
|
||||
└────────────┘ └────────────┘
|
||||
|
||||
Claude Code AgentFox
|
||||
Cursor 数据库
|
||||
Copilot 文件系统
|
||||
... ...
|
||||
```
|
||||
|
||||
## MCP 的核心概念
|
||||
|
||||
### Tools（工具）
|
||||
|
||||
MCP 服务器可以向客户端暴露一组工具（函数），AI 助手可以调用这些工具来获取信息或执行操作。
|
||||
|
||||
AgentFox 提供 5 个工具：
|
||||
- `get_project_overview` — 获取项目概览
|
||||
- `list_modules` — 列出所有模块
|
||||
- `list_endpoints` — 列出模块中的端点
|
||||
- `get_endpoint_detail` — 获取端点详情
|
||||
- `search_endpoints` — 搜索端点
|
||||
|
||||
### Transport（传输层）
|
||||
|
||||
MCP 支持多种传输方式。AgentFox 使用 **Streamable HTTP** 传输，这意味着：
|
||||
- 无需安装任何本地插件
|
||||
- 通过标准 HTTP 请求通信
|
||||
- 支持远程连接，适合云端部署
|
||||
|
||||
## AgentFox 如何使用 MCP？
|
||||
|
||||
AgentFox 是一个 **MCP 服务器**，它：
|
||||
|
||||
1. 接收你的 OpenAPI 文档并解析索引
|
||||
2. 为每个项目生成唯一的 MCP 端点 URL
|
||||
3. 通过 5 个 MCP 工具提供按需查询能力
|
||||
4. AI 工具（MCP 客户端）连接到这个端点，即可按需查询 API 文档
|
||||
|
||||
你的 AI 工具（如 Claude Code、Cursor）就是 **MCP 客户端**，它们通过 MCP 协议连接 AgentFox，获取所需的 API 信息。
|
||||
|
||||
## 了解更多
|
||||
|
||||
- [MCP 官方文档](https://modelcontextprotocol.io/)
|
||||
- [MCP 规范](https://spec.modelcontextprotocol.io/)
|
||||
|
||||
## 下一步
|
||||
|
||||
- [快速开始](../getting-started/README.md) — 5 分钟完成首次配置
|
||||
48
docs/mcp-tools/README.md
Normal file
48
docs/mcp-tools/README.md
Normal file
@@ -0,0 +1,48 @@
|
||||
# MCP 工具概述
|
||||
|
||||
AgentFox 提供 5 个 MCP 工具，采用渐进式下钻设计，让 LLM 按需获取精确信息。
|
||||
|
||||
## 设计理念
|
||||
|
||||
传统方式是将完整 API 规范一次性提供给 LLM（10,000+ tokens）。AgentFox 将信息分层，LLM 按需逐层获取：
|
||||
|
||||
```
|
||||
get_project_overview ← 项目级：名称、版本、模块摘要（~200 tokens）
|
||||
│
|
||||
├── list_modules ← 模块级：模块描述和端点数量（~100-300 tokens）
|
||||
│ │
|
||||
│ └── list_endpoints ← 端点列表：方法、路径、摘要（~200-500 tokens）
|
||||
│ │
|
||||
│ └── get_endpoint_detail ← 端点详情：参数、请求体、响应（~500-2000 tokens）
|
||||
│
|
||||
└── search_endpoints ← 关键词搜索：跨模块搜索端点（~200-500 tokens）
|
||||
```
|
||||
|
||||
## 推荐调用流程
|
||||
|
||||
对于典型的 API 集成任务，LLM 通常会按以下顺序调用：
|
||||
|
||||
1. **`get_project_overview`** — 了解项目结构和可用模块
|
||||
2. **`list_endpoints`** — 浏览目标模块的端点列表（或用 `search_endpoints` 搜索）
|
||||
3. **`get_endpoint_detail`** — 获取目标端点的完整信息
|
||||
|
||||
大多数任务只需要 2-3 次调用，总共约 1,000-1,500 tokens。
|
||||
|
||||
## Token 消耗对比
|
||||
|
||||
| 工具 | 平均 Token 消耗 | 说明 |
|
||||
|------|----------------|------|
|
||||
| `get_project_overview` | ~200 | 最轻量，建议首先调用 |
|
||||
| `list_modules` | ~100-300 | 按模块数量线性增长 |
|
||||
| `list_endpoints` | ~200-500 | 按端点数量线性增长 |
|
||||
| `get_endpoint_detail` | ~500-2,000 | 取决于参数和响应 schema 复杂度 |
|
||||
| `search_endpoints` | ~200-500 | 最多返回 20 条结果 |
|
||||
| **全量 OpenAPI 规范** | **10,000-100,000+** | 传统方式 |
|
||||
|
||||
## 工具列表
|
||||
|
||||
- [`get_project_overview`](get-project-overview.md) — 获取项目概览
|
||||
- [`list_modules`](list-modules.md) — 列出所有模块
|
||||
- [`list_endpoints`](list-endpoints.md) — 列出模块中的端点
|
||||
- [`get_endpoint_detail`](get-endpoint-detail.md) — 获取端点完整详情
|
||||
- [`search_endpoints`](search-endpoints.md) — 按关键词搜索端点
|
||||
92
docs/mcp-tools/get-endpoint-detail.md
Normal file
92
docs/mcp-tools/get-endpoint-detail.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# get_endpoint_detail
|
||||
|
||||
获取端点的完整详细信息，包括参数、请求体和响应格式。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `endpointId` | string | 是 | 端点 ID，可从 `list_endpoints` 或 `search_endpoints` 获取 |
|
||||
|
||||
## 返回结果
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "ep_001",
|
||||
"method": "POST",
|
||||
"path": "/v1/charges",
|
||||
"summary": "Create a charge",
|
||||
"description": "Creates a new charge object. If the charge fails, the API returns an error.",
|
||||
"operationId": "createCharge",
|
||||
"moduleName": "Payments",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "Idempotency-Key",
|
||||
"in": "header",
|
||||
"required": false,
|
||||
"schema": { "type": "string" },
|
||||
"description": "Unique key for idempotent requests"
|
||||
}
|
||||
],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"required": ["amount", "currency"],
|
||||
"properties": {
|
||||
"amount": { "type": "integer", "description": "Amount in cents" },
|
||||
"currency": { "type": "string", "description": "Three-letter ISO currency code" },
|
||||
"source": { "type": "string", "description": "Payment source token" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Charge created successfully",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": { "type": "string" },
|
||||
"amount": { "type": "integer" },
|
||||
"status": { "type": "string" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"deprecated": false
|
||||
}
|
||||
```
|
||||
|
||||
## 返回字段说明
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `id` | string | 端点 ID |
|
||||
| `method` | string | HTTP 方法 |
|
||||
| `path` | string | API 路径 |
|
||||
| `summary` | string | 端点摘要 |
|
||||
| `description` | string | 端点详细描述 |
|
||||
| `operationId` | string | 操作标识符 |
|
||||
| `moduleName` | string | 所属模块名称 |
|
||||
| `parameters` | array | URL/查询/头部/Cookie 参数列表（原始 OpenAPI schema） |
|
||||
| `requestBody` | object | 请求体规范 |
|
||||
| `responses` | object | HTTP 响应规范（按状态码分组） |
|
||||
| `deprecated` | boolean | 是否已弃用 |
|
||||
|
||||
## Token 消耗
|
||||
|
||||
约 **500-2,000 tokens**，取决于参数数量和响应 schema 的复杂程度。这是 token 消耗最多的工具，但也是信息最丰富的。
|
||||
|
||||
## 使用场景
|
||||
|
||||
- 需要了解如何调用某个具体端点
|
||||
- 查看请求参数的类型、是否必填、描述
|
||||
- 查看响应格式以便解析返回数据
|
||||
52
docs/mcp-tools/get-project-overview.md
Normal file
52
docs/mcp-tools/get-project-overview.md
Normal file
@@ -0,0 +1,52 @@
|
||||
# get_project_overview
|
||||
|
||||
获取项目的基本信息和模块摘要。这是推荐的第一个调用工具。
|
||||
|
||||
## 参数
|
||||
|
||||
无参数。
|
||||
|
||||
## 返回结果
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Stripe API",
|
||||
"description": "The Stripe REST API",
|
||||
"version": "3.0.0",
|
||||
"baseUrl": "https://api.stripe.com",
|
||||
"totalEndpoints": 247,
|
||||
"modules": [
|
||||
{
|
||||
"id": "mod_abc123",
|
||||
"name": "Payments",
|
||||
"endpointCount": 15
|
||||
},
|
||||
{
|
||||
"id": "mod_def456",
|
||||
"name": "Customers",
|
||||
"endpointCount": 8
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 返回字段说明
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `name` | string | 项目名称（来自 OpenAPI 的 `info.title`） |
|
||||
| `description` | string | 项目描述 |
|
||||
| `version` | string | OpenAPI 规范版本 |
|
||||
| `baseUrl` | string \| null | API 基础 URL |
|
||||
| `totalEndpoints` | number | 端点总数 |
|
||||
| `modules` | array | 模块列表（含 id、名称和端点数量） |
|
||||
|
||||
## Token 消耗
|
||||
|
||||
约 **200 tokens**，是最轻量的工具。
|
||||
|
||||
## 使用场景
|
||||
|
||||
- 初次连接时了解 API 的整体结构
|
||||
- 查看有哪些模块可供探索
|
||||
- 获取模块 ID 以供后续调用 `list_endpoints`
|
||||
59
docs/mcp-tools/list-endpoints.md
Normal file
59
docs/mcp-tools/list-endpoints.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# list_endpoints
|
||||
|
||||
列出指定模块中的所有端点摘要信息。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `moduleId` | string | 是 | 模块 ID，可从 `get_project_overview` 或 `list_modules` 获取 |
|
||||
|
||||
## 返回结果
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "ep_001",
|
||||
"method": "POST",
|
||||
"path": "/v1/charges",
|
||||
"summary": "Create a charge",
|
||||
"deprecated": false
|
||||
},
|
||||
{
|
||||
"id": "ep_002",
|
||||
"method": "GET",
|
||||
"path": "/v1/charges/{id}",
|
||||
"summary": "Retrieve a charge",
|
||||
"deprecated": false
|
||||
},
|
||||
{
|
||||
"id": "ep_003",
|
||||
"method": "POST",
|
||||
"path": "/v1/refunds",
|
||||
"summary": "Create a refund",
|
||||
"deprecated": false
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## 返回字段说明
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `id` | string | 端点 ID，用于 `get_endpoint_detail` |
|
||||
| `method` | string | HTTP 方法（GET、POST、PUT、DELETE 等） |
|
||||
| `path` | string | API 路径 |
|
||||
| `summary` | string | 端点简短描述 |
|
||||
| `deprecated` | boolean | 是否已弃用 |
|
||||
|
||||
结果按路径字母排序，然后按 HTTP 方法排序。
|
||||
|
||||
## Token 消耗
|
||||
|
||||
约 **200-500 tokens**，取决于模块中的端点数量。
|
||||
|
||||
## 使用场景
|
||||
|
||||
- 浏览特定模块中的所有端点
|
||||
- 找到目标端点的 ID，用于调用 `get_endpoint_detail`
|
||||
- 了解 API 提供了哪些操作
|
||||
49
docs/mcp-tools/list-modules.md
Normal file
49
docs/mcp-tools/list-modules.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# list_modules
|
||||
|
||||
列出项目中的所有模块及其描述信息。
|
||||
|
||||
## 参数
|
||||
|
||||
无参数。
|
||||
|
||||
## 返回结果
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "mod_abc123",
|
||||
"name": "Payments",
|
||||
"description": "Manage charges, refunds, and payment intents",
|
||||
"endpointCount": 15
|
||||
},
|
||||
{
|
||||
"id": "mod_def456",
|
||||
"name": "Customers",
|
||||
"description": "Create and manage customer records",
|
||||
"endpointCount": 8
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## 返回字段说明
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `id` | string | 模块 ID，用于 `list_endpoints` 和 `search_endpoints` |
|
||||
| `name` | string | 模块名称 |
|
||||
| `description` | string | 模块描述 |
|
||||
| `endpointCount` | number | 模块中的端点数量 |
|
||||
|
||||
## Token 消耗
|
||||
|
||||
约 **100-300 tokens**，取决于模块数量。
|
||||
|
||||
## 使用场景
|
||||
|
||||
- 需要查看模块的详细描述（`get_project_overview` 不包含描述）
|
||||
- 决定要探索哪个模块时
|
||||
- 需要获取模块 ID 用于后续调用
|
||||
|
||||
## 与 get_project_overview 的区别
|
||||
|
||||
`get_project_overview` 返回的模块列表只包含 id、名称和端点数量，不包含描述。如果需要模块描述来判断探索哪个模块，使用 `list_modules`。
|
||||
64
docs/mcp-tools/search-endpoints.md
Normal file
64
docs/mcp-tools/search-endpoints.md
Normal file
@@ -0,0 +1,64 @@
|
||||
# search_endpoints
|
||||
|
||||
按关键词搜索端点。支持跨模块搜索，也可以限定在特定模块内。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `keyword` | string | 是 | 搜索关键词 |
|
||||
| `moduleId` | string | 否 | 限定搜索范围的模块 ID，不填则搜索所有模块 |
|
||||
|
||||
## 搜索范围
|
||||
|
||||
关键词会匹配以下字段（不区分大小写）：
|
||||
- 端点路径（`path`）
|
||||
- 端点摘要（`summary`）
|
||||
- 端点描述（`description`）
|
||||
- 操作标识符（`operationId`）
|
||||
|
||||
## 返回结果
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "ep_001",
|
||||
"method": "POST",
|
||||
"path": "/v1/charges",
|
||||
"summary": "Create a charge",
|
||||
"moduleName": "Payments",
|
||||
"deprecated": false
|
||||
},
|
||||
{
|
||||
"id": "ep_005",
|
||||
"method": "POST",
|
||||
"path": "/v1/payment_intents",
|
||||
"summary": "Create a PaymentIntent",
|
||||
"moduleName": "Payments",
|
||||
"deprecated": false
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## 返回字段说明
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `id` | string | 端点 ID，可传给 `get_endpoint_detail` |
|
||||
| `method` | string | HTTP 方法 |
|
||||
| `path` | string | API 路径 |
|
||||
| `summary` | string | 端点摘要 |
|
||||
| `moduleName` | string | 所属模块名称 |
|
||||
| `deprecated` | boolean | 是否已弃用 |
|
||||
|
||||
最多返回 **20 条**结果，按路径和方法排序。
|
||||
|
||||
## Token 消耗
|
||||
|
||||
约 **200-500 tokens**。
|
||||
|
||||
## 使用场景
|
||||
|
||||
- 不知道端点在哪个模块，通过关键词搜索
|
||||
- 快速定位与某个功能相关的端点
|
||||
- 模糊搜索，如搜索 "user" 找到所有用户相关端点
|
||||
9
docs/nginx.conf
Normal file
9
docs/nginx.conf
Normal file
@@ -0,0 +1,9 @@
|
||||
server {
|
||||
listen 80;
|
||||
root /usr/share/nginx/html;
|
||||
index index.html;
|
||||
|
||||
location / {
|
||||
try_files $uri $uri/ /index.html;
|
||||
}
|
||||
}
|
||||
51
docs/project-management/api-key-management.md
Normal file
51
docs/project-management/api-key-management.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# API Key 管理
|
||||
|
||||
API Key 是 LLM 客户端连接 AgentFox MCP 服务的唯一认证凭证。
|
||||
|
||||
## 基本信息
|
||||
|
||||
- 每个账号只有一个 API Key
|
||||
- 该 Key 对账号下所有项目生效
|
||||
- Key 以 `afk_` 为前缀
|
||||
- 使用 bcrypt 哈希加密存储，不保存明文
|
||||
|
||||
## 生成 API Key
|
||||
|
||||
首次使用时需要生成：
|
||||
|
||||
1. 打开「设置」（点击右上角头像旁的齿轮图标）
|
||||
2. 在「API Key」区域，点击「生成 API Key」
|
||||
3. **立即复制并保存**生成的密钥
|
||||
|
||||
> **重要**：API Key 仅在生成时完整显示一次。
|
||||
|
||||
## 查看/复制已有 Key
|
||||
|
||||
如果之前已生成过 API Key：
|
||||
|
||||
1. 打开「设置」→ API Key 区域
|
||||
2. 点击「查看」或「复制」
|
||||
3. 输入账号密码进行身份验证
|
||||
4. 验证通过后可查看或复制
|
||||
|
||||
> **提示**：通过 Google/GitHub 登录的用户，需要先在「设置」中设置密码，才能执行此操作。
|
||||
|
||||
## 轮换 API Key
|
||||
|
||||
如果密钥泄露或出于安全考虑需要更换：
|
||||
|
||||
1. 打开「设置」→ API Key 区域
|
||||
2. 点击「轮换 API Key」
|
||||
3. 确认操作
|
||||
|
||||
轮换后的影响：
|
||||
- 旧密钥**立即失效**
|
||||
- 所有使用旧密钥的 MCP 客户端需要更新配置
|
||||
- 新密钥同样只显示一次，请立即保存
|
||||
|
||||
## 安全建议
|
||||
|
||||
- 不要将 API Key 提交到版本控制系统
|
||||
- 将包含 API Key 的 MCP 配置文件添加到 `.gitignore`
|
||||
- 定期轮换 API Key
|
||||
- 如果怀疑密钥泄露，立即轮换
|
||||
45
docs/project-management/module-management.md
Normal file
45
docs/project-management/module-management.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# 模块管理
|
||||
|
||||
模块是 AgentFox 中端点的分组方式。导入 API 文档时，端点会自动按规则分组到不同模块中。
|
||||
|
||||
## 自动分组规则
|
||||
|
||||
导入 API 文档时，AgentFox 按以下优先级自动创建模块：
|
||||
|
||||
1. **OpenAPI Tags**：如果端点定义了 `tags`，按 tag 名称分组
|
||||
2. **路径前缀**：如果没有 tags，按 URL 路径的第一段分组（如 `/users/...` → `users` 模块）
|
||||
|
||||
## 查看模块
|
||||
|
||||
在项目详情页的「模块」标签中，可以查看所有模块：
|
||||
|
||||
- 模块名称
|
||||
- 模块中的端点数量
|
||||
- 模块来源类型（tag / path_prefix / manual）
|
||||
|
||||
## 手动添加模块
|
||||
|
||||
1. 在「模块」标签页顶部，输入模块名称
|
||||
2. 点击「添加」按钮
|
||||
3. 新模块将显示在列表中（端点数量为 0）
|
||||
|
||||
手动添加的模块可用于重新组织端点。
|
||||
|
||||
## 删除模块
|
||||
|
||||
1. 在模块列表中，找到要删除的模块
|
||||
2. 点击删除按钮
|
||||
3. 确认删除
|
||||
|
||||
> **注意**：删除模块会同时删除模块中的所有端点。此操作不可撤销。
|
||||
|
||||
## 模块对 MCP 工具的影响
|
||||
|
||||
模块直接影响 LLM 的查询体验：
|
||||
|
||||
- `get_project_overview` 返回所有模块的 ID 和端点数量
|
||||
- `list_modules` 返回模块的详细描述
|
||||
- `list_endpoints` 需要传入 `moduleId` 来查看特定模块的端点
|
||||
- `search_endpoints` 可选传入 `moduleId` 来限定搜索范围
|
||||
|
||||
合理的模块划分有助于 LLM 更快定位到所需的端点。
|
||||
34
docs/project-management/reimport-docs.md
Normal file
34
docs/project-management/reimport-docs.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# 重新导入文档
|
||||
|
||||
当 API 文档更新后，你可以重新导入来更新 AgentFox 中的数据。
|
||||
|
||||
## 何时需要重新导入？
|
||||
|
||||
- API 新增了端点
|
||||
- 端点的参数或响应格式发生了变化
|
||||
- 模块结构需要重新组织
|
||||
|
||||
## 重新导入步骤
|
||||
|
||||
1. 进入项目详情页 → 「设置」标签
|
||||
2. 在「重新导入 API 文档」区域，点击「重新导入文档」
|
||||
3. 选择导入方式（URL 或上传文件）
|
||||
4. 确认导入
|
||||
|
||||
## 重要提醒
|
||||
|
||||
> **注意**：重新导入会删除当前项目中的所有模块和端点，然后根据新文档重新创建。
|
||||
|
||||
重新导入时：
|
||||
- 所有现有模块将被删除
|
||||
- 所有现有端点将被删除
|
||||
- **API Key 保持不变**（LLM 客户端无需更新配置）
|
||||
- **项目 ID 保持不变**（MCP URL 不变）
|
||||
|
||||
## 支持的格式
|
||||
|
||||
与首次导入相同：
|
||||
- OpenAPI 3.0 / 3.1
|
||||
- Swagger 2.0
|
||||
- JSON 和 YAML 格式
|
||||
- URL 或文件上传
|
||||
Reference in New Issue
Block a user