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')}