Content
<div align="center">
# Auto Wiki
**Industrial-Grade Code Wiki Auto-Generation Engine · 工业级代码知识库自动生成引擎**
[](https://github.com/izhengnan/autowiki-mcp/actions/workflows/ci.yml)
[English](#overview) | [简体中文](#概述)
</div>
A reusable [MCP Server](https://modelcontextprotocol.io) + [Claude Code](https://claude.ai) Skill that automatically generates 50+ industrial-grade wiki pages from any codebase. Point it at your project, run `/autowiki`, and it produces deep documentation with Mermaid diagrams, line-level source code citations, and troubleshooting guides.
> **Recommended:** Claude Code with Opus 4.7 for best results — but works with any Claude Code setup.
---
## Overview
Auto Wiki scans your project, analyzes dependencies, and generates comprehensive documentation across **10 categories**. Each page follows an **11-section template** with **7 mandatory quality checks**.
### Documentation Categories
| Category | Coverage |
|----------|----------|
| Globals & Standards | Tech stack, directory structure, system overview, developer guide |
| Frontend Architecture | Routes, state management, component tree, API integration |
| Backend Architecture (MVC) | Controller, Service, Mapper layers with call chains |
| Backend Architecture (Design) | Entity models, DTOs, response formats, layered design |
| Backend Architecture (DI) | Dependency injection, component call chains, startup mechanism |
| Database Design | ER diagrams, table schemas, indexes, query patterns |
| Core Business Logic | Domain models, state machines, auction engine, scheduling |
| API Documentation | Endpoint reference with request/response schemas |
| Security Design | JWT authentication, RBAC, data protection |
| Deployment & Config | Environment config, database setup, topology |
---
## Quick Start
```bash
# 1. Install dependencies
npm install
# 2. Register as global MCP Server
claude mcp add autowiki -- node "$(pwd)/index.js"
# 3. Install the skill
mkdir -p ~/.claude/skills/autowiki
cp SKILL.md ~/.claude/skills/autowiki/SKILL.md
# 4. Restart Claude Code, then in any project terminal:
/autowiki
```
The system will scan your source tree, schedule 50+ documentation tasks in 5 batches, and write everything to `docs/wiki/`.
---
## How It Works
Auto Wiki runs a **multi-phase pipeline**:
### 1. Domain-Driven Planning
Scans the project tree and schedules 50+ tasks across 10 categories in 5 batches — globals, database, backend, frontend, core business + API, security + deployment.
### 2. Dependency Analysis
For each task, analyzes `import`/`require` statements to identify related source files, ensuring every document has comprehensive context (≥6 files per page).
### 3. Serial Writing Loop
One task at a time, the system:
- Reads all related source files with **real line numbers**
- Writes an **11-section markdown** with **4+ Mermaid diagrams** per page
- Includes `<cite>` blocks tracing every claim back to source code
### 4. Quality Validation
Every submission passes **7 automated checks** before saving — word count, section coverage, diagram count, citation count, appendix code examples, Mermaid syntax, and cite block presence.
### 5. Human Edit Protection
Manually edited blocks (marked with `<!-- human-edited -->`) are preserved across regenerations — never overwrite your customizations.
---
## Use Cases
| Scenario | Description |
|----------|-------------|
| **Onboarding** | New team members get complete codebase documentation in minutes, not weeks |
| **Legacy Revival** | Breathe life into undocumented or abandoned codebases |
| **API Docs** | Auto-generated endpoint references with curl examples |
| **Knowledge Preservation** | Prevent single-point-of-failure when key developers leave |
### Not Intended For
- Replacing hand-written design documents that require product-level decisions
- Public-facing developer portals (output is team-internal wiki quality)
- Live preview or real-time editing — it's a batch generation tool
---
## Prerequisites
- **Node.js** ≥ 18
- **Claude Code** CLI installed and authenticated
## Tech Stack
| Component | Technology |
|-----------|-----------|
| Runtime | Node.js 18+ |
| Protocol | [MCP SDK](https://github.com/modelcontextprotocol/sdk) |
| File Scanning | [fast-glob](https://github.com/mrmlnc/fast-glob) |
| Skill Definition | Claude Code SKILL.md |
---
## MCP Tools
| Tool | Function |
|------|----------|
| `autowiki_get_project_tree` | Scan project source structure |
| `autowiki_analyze_dependencies` | AST-based import/require inference |
| `autowiki_scan_files` | Glob-pattern file scanning |
| `autowiki_clear_task_queue` | Reset task queue |
| `autowiki_add_tasks_to_queue` | Batch-add documentation tasks |
| `autowiki_get_pending_task` | Fetch next task (injects 11-section template) |
| `autowiki_submit_task` | Submit with 7 quality checks |
| `autowiki_append_knowledge` | Append fragment knowledge to existing cards |
---
## Quality Gates
Every submitted document must pass these checks:
| Check | Threshold |
|-------|-----------|
| Word count | ≥ 2,000 characters |
| Citation block | `<cite>` tag must exist |
| Cited files | ≥ 4 unique source files |
| Mermaid diagrams | ≥ 4 per page (graph, sequence, flowchart, ER/class) |
| Section coverage | ≥ 8 of 11 required sections |
| Appendix | Runnable code examples (curl, JS, or Java) |
| Mermaid syntax | No unquoted `@` symbols, no `;` in ER diagram attributes |
On failure, the server returns a detailed list of what's missing — fix and resubmit.
---
## Project Structure
```
autowiki-mcp/
├── index.js # MCP Server (task queue + validation engine)
├── package.json # Dependencies
├── SKILL.md # Claude Code Skill definition (writing rules + pipeline)
├── README.md # This file
├── .gitignore
├── .github/workflows/
│ └── ci.yml # GitHub Actions CI
├── test/
│ └── human-edited.test.js
└── docs/wiki/ # Generated wiki output (created at runtime)
```
---
## Commands
```bash
npm install # Install dependencies
npm test # Run test suite (4 tests)
node index.js # Start MCP Server (for debugging/manual use)
```
---
## Design Principles
Pure LLM-driven documentation suffers from three defects: **output truncation**, **missing context**, and **inconsistent structure**. Auto Wiki addresses each with engineering:
| Defect | Solution |
|--------|----------|
| Long JSON output truncation | 5-batch scheduling, 8-15 tasks per batch |
| Missing related source files | `autowiki_analyze_dependencies` code-level inference |
| Omitted documentation sections | `requiredSections` template injection + server-side validation |
| Not enough diagrams | Enforced `minDiagrams: 4`, rejection if unmet |
| Hallucinated line numbers | Forces real line numbers from `Read` tool output |
---
## Customization
The `SKILL.md` file is the single source of truth for document structure, categories, and quality thresholds. Edit it to:
- Add or remove documentation categories
- Adjust quality check thresholds
- Change the 11-section writing template
- Add project-specific terminology rules
For project-specific rules, add a `CLAUDE.md` or append to your existing one.
---
## License
MIT
---
## 概述
Auto Wiki 是一个 MCP Server + Claude Code Skill，能够从任意代码库自动生成 **50+ 篇**工业级 Wiki 文档。在目标项目中运行 `/autowiki`，即可获得带 Mermaid 图表、行级代码溯源、故障排查指南的深度文档。
> **推荐搭配：** Claude Code + Opus 4.7 效果最佳，其他版本亦可使用。
### 文档分类
| 分类 | 覆盖范围 |
|------|---------|
| 全局与规范 | 技术栈、目录结构、系统概述、开发者指南 |
| 前端架构 | 路由、状态管理、组件树、API 集成 |
| 后端架构 (MVC) | Controller、Service、Mapper 层及调用链路 |
| 后端架构 (分层设计) | 实体模型、DTO、统一响应、分层规范 |
| 后端架构 (依赖管理) | DI 机制、组件调用链、启动流程 |
| 数据库设计 | ER 图、表结构、索引、典型查询 |
| 核心功能设计 | 领域模型、状态机、业务引擎、定时任务 |
| API 接口文档 | 端点参考、请求/响应结构 |
| 安全设计 | JWT 认证、RBAC 权限、数据保护 |
| 部署与配置 | 环境配置、数据库配置、部署拓扑 |
### 快速开始
```bash
# 1. 安装依赖
npm install
# 2. 注册为全局 MCP Server
claude mcp add autowiki -- node "$(pwd)/index.js"
# 3. 安装技能
mkdir -p ~/.claude/skills/autowiki
cp SKILL.md ~/.claude/skills/autowiki/SKILL.md
# 4. 重启 Claude Code，在任意项目中输入：
/autowiki
```
系统会自动扫描源码树、分 5 批排期 50+ 个文档任务，全部输出到 `docs/wiki/` 目录。
### 工作流程
1. **领域排期** — 按 10 大分类分 5 批追加任务
2. **依赖分析** — 通过 import/require 推导关联文件，确保每篇文档 ≥6 个引用文件
3. **串行撰写** — 逐个读取源文件 → 按 11 段模板撰写 → 嵌入 4+ 个 Mermaid 图表
4. **质量校验** — 7 项自动检查，不达标详细打回
5. **人工保护** — `<!-- human-edited -->` 区块在重新生成时自动保留
### 适用场景
| 场景 | 说明 |
|------|------|
| **团队 onboarding** | 新成员几分钟内获完整代码库文档 |
| **遗留系统重建** | 为无文档或废弃项目生成深度文档 |
| **API 文档** | 自动生成带 curl 示例的接口文档 |
| **知识留存** | 防止核心人员离开导致知识断层 |
### 质量校验
| 检查项 | 阈值 |
|--------|------|
| 字数 | ≥ 2000 字符 |
| 溯源区块 | 必须包含 `<cite>` 标签 |
| 引用文件 | ≥ 4 个唯一文件 |
| Mermaid 图表 | ≥ 4 个（graph/sequence/flowchart/ER-class） |
| 章节覆盖 | ≥ 8/11 段 |
| 附录代码 | 可运行的 curl、JS 或 Java 示例 |
| Mermaid 语法 | @ 符号必须加引号，ER 属性不能有分号 |
### 项目结构
```
autowiki-mcp/
├── index.js # MCP Server 主程序（任务队列 + 校验引擎）
├── package.json # 依赖声明
├── SKILL.md # Claude Code Skill 定义（写作规范 + 排期管线）
├── README.md # 本文件
├── .gitignore
├── .github/workflows/
│ └── ci.yml # GitHub Actions CI
├── test/
│ └── human-edited.test.js
└── docs/wiki/ # 生成的 Wiki 文档目录（运行时自动创建）
```
### 设计原理
纯 LLM 驱动的文档生成有三大缺陷：**输出截断**、**上下文遗漏**、**结构不一致**。本引擎通过以下手段逐一破解：
| 缺陷 | 对策 |
|------|------|
| 长 JSON 输出截断 | 分 5 批次排期，每次只追加 8-15 个任务 |
| 找不全关联文件 | `autowiki_analyze_dependencies` 代码级依赖推导 |
| 文档章节遗漏 | `requiredSections` 模板注入 + 服务端校验打回 |
| 图表数量不足 | 强制 `minDiagrams: 4`，不达标拒绝保存 |
| 行号幻觉 | 强制引用 `Read` 工具返回的真实行号 |
### 自定义扩展
编辑 `SKILL.md` 即可调整文档结构、分类树和质量阈值。项目级别的配置可在 `CLAUDE.md` 中添加。
### 命令
```bash
npm install # 安装依赖
npm test # 运行测试（4 个用例）
node index.js # 启动 MCP Server（调试用）
```
### License
MIT
