From 71c604411d486210594aec0b19b5acfd57eaaba6 Mon Sep 17 00:00:00 2001 From: YANG JIANKUAN Date: Sun, 12 Apr 2026 20:15:41 +0800 Subject: [PATCH] feat: deploy skill --- docker-compose.dev.yml | 20 ++++ docker-compose.yml | 6 ++ docs/.dockerignore | 6 ++ docs/Dockerfile | 26 ++++++ docs/README.md | 39 ++++++++ docs/SUMMARY.md | 47 ++++++++++ docs/book.json | 11 +++ docs/clients/README.md | 87 ++++++++++++++++++ docs/clients/claude-code.md | 70 ++++++++++++++ docs/clients/claude-desktop.md | 77 ++++++++++++++++ docs/clients/cline.md | 51 ++++++++++ docs/clients/codex.md | 61 ++++++++++++ docs/clients/cursor.md | 56 +++++++++++ docs/clients/github-copilot.md | 71 ++++++++++++++ docs/clients/other-clients.md | 82 +++++++++++++++++ docs/clients/windsurf.md | 45 +++++++++ docs/faq.md | 47 ++++++++++ docs/getting-started/README.md | 39 ++++++++ docs/getting-started/connect-first-client.md | 75 +++++++++++++++ docs/getting-started/generate-api-key.md | 49 ++++++++++ docs/getting-started/import-api-docs.md | 59 ++++++++++++ docs/getting-started/register-and-login.md | 31 +++++++ docs/introduction/what-is-agentfox.md | 69 ++++++++++++++ docs/introduction/what-is-mcp.md | 65 +++++++++++++ docs/mcp-tools/README.md | 48 ++++++++++ docs/mcp-tools/get-endpoint-detail.md | 92 +++++++++++++++++++ docs/mcp-tools/get-project-overview.md | 52 +++++++++++ docs/mcp-tools/list-endpoints.md | 59 ++++++++++++ docs/mcp-tools/list-modules.md | 49 ++++++++++ docs/mcp-tools/search-endpoints.md | 64 +++++++++++++ docs/nginx.conf | 9 ++ docs/project-management/api-key-management.md | 51 ++++++++++ docs/project-management/module-management.md | 45 +++++++++ docs/project-management/reimport-docs.md | 34 +++++++ packages/web/nginx.conf | 7 ++ .../web/src/pages/landing/FooterSection.tsx | 2 +- .../web/src/pages/landing/HeroSection.tsx | 2 +- 37 files changed, 1701 insertions(+), 2 deletions(-) create mode 100644 docs/.dockerignore create mode 100644 docs/Dockerfile create mode 100644 docs/README.md create mode 100644 docs/SUMMARY.md create mode 100644 docs/book.json create mode 100644 docs/clients/README.md create mode 100644 docs/clients/claude-code.md create mode 100644 docs/clients/claude-desktop.md create mode 100644 docs/clients/cline.md create mode 100644 docs/clients/codex.md create mode 100644 docs/clients/cursor.md create mode 100644 docs/clients/github-copilot.md create mode 100644 docs/clients/other-clients.md create mode 100644 docs/clients/windsurf.md create mode 100644 docs/faq.md create mode 100644 docs/getting-started/README.md create mode 100644 docs/getting-started/connect-first-client.md create mode 100644 docs/getting-started/generate-api-key.md create mode 100644 docs/getting-started/import-api-docs.md create mode 100644 docs/getting-started/register-and-login.md create mode 100644 docs/introduction/what-is-agentfox.md create mode 100644 docs/introduction/what-is-mcp.md create mode 100644 docs/mcp-tools/README.md create mode 100644 docs/mcp-tools/get-endpoint-detail.md create mode 100644 docs/mcp-tools/get-project-overview.md create mode 100644 docs/mcp-tools/list-endpoints.md create mode 100644 docs/mcp-tools/list-modules.md create mode 100644 docs/mcp-tools/search-endpoints.md create mode 100644 docs/nginx.conf create mode 100644 docs/project-management/api-key-management.md create mode 100644 docs/project-management/module-management.md create mode 100644 docs/project-management/reimport-docs.md diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml index 281552a..6e9d8f6 100644 --- a/docker-compose.dev.yml +++ b/docker-compose.dev.yml @@ -51,6 +51,26 @@ services: MCP_PORT: "3001" NODE_ENV: development + docs: + build: + context: ./docs + dockerfile: Dockerfile + target: build + command: > + sh -c "honkit serve --port 4000" + volumes: + - ./docs/book.json:/book/book.json + - ./docs/SUMMARY.md:/book/SUMMARY.md + - ./docs/README.md:/book/README.md + - ./docs/faq.md:/book/faq.md + - ./docs/introduction:/book/introduction + - ./docs/getting-started:/book/getting-started + - ./docs/mcp-tools:/book/mcp-tools + - ./docs/clients:/book/clients + - ./docs/project-management:/book/project-management + ports: + - "4000:4000" + web: build: context: . diff --git a/docker-compose.yml b/docker-compose.yml index e26646d..f231049 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -54,6 +54,11 @@ services: server: condition: service_healthy + docs: + build: + context: ./docs + dockerfile: Dockerfile + web: build: context: . @@ -63,6 +68,7 @@ services: depends_on: - server - mcp + - docs volumes: pgdata: diff --git a/docs/.dockerignore b/docs/.dockerignore new file mode 100644 index 0000000..52c951c --- /dev/null +++ b/docs/.dockerignore @@ -0,0 +1,6 @@ +node_modules +.worktrees +.claude +.git +dist +*.zip diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 0000000..a7c4774 --- /dev/null +++ b/docs/Dockerfile @@ -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 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..da0a910 --- /dev/null +++ b/docs/README.md @@ -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) 免费开始使用。 diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000..563eb8d --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,47 @@ +# 目录 + +* [欢迎使用 AgentFox](README.md) + +## 介绍 + +* [什么是 AgentFox](introduction/what-is-agentfox.md) +* [MCP 协议介绍](introduction/what-is-mcp.md) + +## 快速开始 + +* [概述](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 工具 + +* [工具概述](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) + +## 客户端配置 + +* [配置概述](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) + +## 项目管理 + +* [模块管理](project-management/module-management.md) +* [重新导入文档](project-management/reimport-docs.md) +* [API Key 管理](project-management/api-key-management.md) + +## 其他 + +* [常见问题](faq.md) diff --git a/docs/book.json b/docs/book.json new file mode 100644 index 0000000..83bb4fb --- /dev/null +++ b/docs/book.json @@ -0,0 +1,11 @@ +{ + "title": "AgentFox 文档", + "description": "AgentFox — 为 LLM 而生的 API 文档服务", + "language": "zh-hans", + "links": { + "sidebar": { + "AgentFox 官网": "https://www.agentfoxapp.com" + } + }, + "plugins": ["-sharing"] +} diff --git a/docs/clients/README.md b/docs/clients/README.md new file mode 100644 index 0000000..e9102f1 --- /dev/null +++ b/docs/clients/README.md @@ -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`） diff --git a/docs/clients/claude-code.md b/docs/clients/claude-code.md new file mode 100644 index 0000000..9e3bcd5 --- /dev/null +++ b/docs/clients/claude-code.md @@ -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。 diff --git a/docs/clients/claude-desktop.md b/docs/clients/claude-desktop.md new file mode 100644 index 0000000..7d0d376 --- /dev/null +++ b/docs/clients/claude-desktop.md @@ -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 的工具。 diff --git a/docs/clients/cline.md b/docs/clients/cline.md new file mode 100644 index 0000000..b7fffc9 --- /dev/null +++ b/docs/clients/cline.md @@ -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 工具 diff --git a/docs/clients/codex.md b/docs/clients/codex.md new file mode 100644 index 0000000..17f1ef7 --- /dev/null +++ b/docs/clients/codex.md @@ -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`。 diff --git a/docs/clients/cursor.md b/docs/clients/cursor.md new file mode 100644 index 0000000..94e949e --- /dev/null +++ b/docs/clients/cursor.md @@ -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 +``` diff --git a/docs/clients/github-copilot.md b/docs/clients/github-copilot.md new file mode 100644 index 0000000..59c0e33 --- /dev/null +++ b/docs/clients/github-copilot.md @@ -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 泄露。 diff --git a/docs/clients/other-clients.md b/docs/clients/other-clients.md new file mode 100644 index 0000000..372209d --- /dev/null +++ b/docs/clients/other-clients.md @@ -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` diff --git a/docs/clients/windsurf.md b/docs/clients/windsurf.md new file mode 100644 index 0000000..20f58a9 --- /dev/null +++ b/docs/clients/windsurf.md @@ -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 概览 +``` + +如果返回了项目信息，说明配置成功。 diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..c7e37cd --- /dev/null +++ b/docs/faq.md @@ -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 即可。 diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md new file mode 100644 index 0000000..e801fa3 --- /dev/null +++ b/docs/getting-started/README.md @@ -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 工具获取所需信息，无需你手动复制文档。 diff --git a/docs/getting-started/connect-first-client.md b/docs/getting-started/connect-first-client.md new file mode 100644 index 0000000..6e466b5 --- /dev/null +++ b/docs/getting-started/connect-first-client.md @@ -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) diff --git a/docs/getting-started/generate-api-key.md b/docs/getting-started/generate-api-key.md new file mode 100644 index 0000000..1e2b713 --- /dev/null +++ b/docs/getting-started/generate-api-key.md @@ -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) 了。 diff --git a/docs/getting-started/import-api-docs.md b/docs/getting-started/import-api-docs.md new file mode 100644 index 0000000..97312ee --- /dev/null +++ b/docs/getting-started/import-api-docs.md @@ -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 服务。 diff --git a/docs/getting-started/register-and-login.md b/docs/getting-started/register-and-login.md new file mode 100644 index 0000000..4192099 --- /dev/null +++ b/docs/getting-started/register-and-login.md @@ -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)。 diff --git a/docs/introduction/what-is-agentfox.md b/docs/introduction/what-is-agentfox.md new file mode 100644 index 0000000..3a1f5eb --- /dev/null +++ b/docs/introduction/what-is-agentfox.md @@ -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) diff --git a/docs/introduction/what-is-mcp.md b/docs/introduction/what-is-mcp.md new file mode 100644 index 0000000..1db4d93 --- /dev/null +++ b/docs/introduction/what-is-mcp.md @@ -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 分钟完成首次配置 diff --git a/docs/mcp-tools/README.md b/docs/mcp-tools/README.md new file mode 100644 index 0000000..0007ef9 --- /dev/null +++ b/docs/mcp-tools/README.md @@ -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) — 按关键词搜索端点 diff --git a/docs/mcp-tools/get-endpoint-detail.md b/docs/mcp-tools/get-endpoint-detail.md new file mode 100644 index 0000000..6b25b29 --- /dev/null +++ b/docs/mcp-tools/get-endpoint-detail.md @@ -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 消耗最多的工具，但也是信息最丰富的。 + +## 使用场景 + +- 需要了解如何调用某个具体端点 +- 查看请求参数的类型、是否必填、描述 +- 查看响应格式以便解析返回数据 diff --git a/docs/mcp-tools/get-project-overview.md b/docs/mcp-tools/get-project-overview.md new file mode 100644 index 0000000..96631df --- /dev/null +++ b/docs/mcp-tools/get-project-overview.md @@ -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` diff --git a/docs/mcp-tools/list-endpoints.md b/docs/mcp-tools/list-endpoints.md new file mode 100644 index 0000000..73fdc3c --- /dev/null +++ b/docs/mcp-tools/list-endpoints.md @@ -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 提供了哪些操作 diff --git a/docs/mcp-tools/list-modules.md b/docs/mcp-tools/list-modules.md new file mode 100644 index 0000000..43f1e66 --- /dev/null +++ b/docs/mcp-tools/list-modules.md @@ -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`。 diff --git a/docs/mcp-tools/search-endpoints.md b/docs/mcp-tools/search-endpoints.md new file mode 100644 index 0000000..1387142 --- /dev/null +++ b/docs/mcp-tools/search-endpoints.md @@ -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" 找到所有用户相关端点 diff --git a/docs/nginx.conf b/docs/nginx.conf new file mode 100644 index 0000000..f749e02 --- /dev/null +++ b/docs/nginx.conf @@ -0,0 +1,9 @@ +server { + listen 80; + root /usr/share/nginx/html; + index index.html; + + location / { + try_files $uri $uri/ /index.html; + } +} diff --git a/docs/project-management/api-key-management.md b/docs/project-management/api-key-management.md new file mode 100644 index 0000000..d3d5801 --- /dev/null +++ b/docs/project-management/api-key-management.md @@ -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 +- 如果怀疑密钥泄露，立即轮换 diff --git a/docs/project-management/module-management.md b/docs/project-management/module-management.md new file mode 100644 index 0000000..4f21fea --- /dev/null +++ b/docs/project-management/module-management.md @@ -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 更快定位到所需的端点。 diff --git a/docs/project-management/reimport-docs.md b/docs/project-management/reimport-docs.md new file mode 100644 index 0000000..d27d275 --- /dev/null +++ b/docs/project-management/reimport-docs.md @@ -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 或文件上传 diff --git a/packages/web/nginx.conf b/packages/web/nginx.conf index 5763509..53f5f28 100644 --- a/packages/web/nginx.conf +++ b/packages/web/nginx.conf @@ -21,6 +21,13 @@ server { proxy_cache off; } + location /docs/ { + proxy_pass http://docs:80/; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + } + location / { try_files $uri $uri/ /index.html; } diff --git a/packages/web/src/pages/landing/FooterSection.tsx b/packages/web/src/pages/landing/FooterSection.tsx index 26ad883..865d571 100644 --- a/packages/web/src/pages/landing/FooterSection.tsx +++ b/packages/web/src/pages/landing/FooterSection.tsx @@ -10,7 +10,7 @@ export default function FooterSection() { links: [ { label: t('footer.features'), href: '#features' }, { label: t('footer.pricing'), href: '#pricing' }, - { label: t('footer.docs'), href: '#' }, + { label: t('footer.docs'), href: '/docs/' }, { label: t('footer.changelog'), href: '#' }, ], }, diff --git a/packages/web/src/pages/landing/HeroSection.tsx b/packages/web/src/pages/landing/HeroSection.tsx index 1491618..c88f411 100644 --- a/packages/web/src/pages/landing/HeroSection.tsx +++ b/packages/web/src/pages/landing/HeroSection.tsx @@ -131,7 +131,7 @@ export default function HeroSection() { {t('hero.cta')}