<div align="center">

# Auto Wiki

**Industrial-Grade Code Wiki Auto-Generation Engine · 工业级代码知识库自动生成引擎**

[![CI](https://github.com/izhengnan/autowiki-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/izhengnan/autowiki-mcp/actions/workflows/ci.yml)
![License](https://img.shields.io/badge/license-MIT-green)
![Node](https://img.shields.io/badge/node-%3E%3D18-blue)

[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