# 1. 全局安装
npm i -g @easy-base/docs-mcp

# 2. 拉取所有预制文档 + 构建索引（首次 10-30 分钟；redis hybrid 较慢）
docs-mcp install --build

# 3. 交互式勾选服务，生成 .mcp.json（默认 docs-mcp serve 可移植块）
docs-mcp config
#    或：docs-mcp config --all -o .mcp.json

# 4. 在 Claude Code 中启用
#    把生成的 .mcp.json 放到需要 AI 辅助的项目根目录（或 .claude/ 下），重启会话

git clone https://github.com/base-kit/docs-mcp.git docs-mcp-local
cd docs-mcp-local
npm install
npm link              # 让 docs-mcp 命令指向本地（config 默认 docs-mcp serve 块需要它在 PATH）
docs-mcp install --build
docs-mcp config      # 或用 npm run dev ... 直接 tsx 跑源码开发

docs-mcp-local/                                ← 本仓库（单 npm 工程）
├── package.json                              ← CLI + 内核 deps 合一
├── bin/docs-mcp.mjs                          ← CLI 入口（tsx / node strip-types）
├── tsconfig.json                             ← 一个 tsconfig，编译 src/ → dist/
├── src/
│   ├── cli/                                  ← CLI 层（commander）
│   │   ├── index.ts                          ← 命令路由
│   │   ├── commands/                         ← 9 个子命令
│   │   ├── log.ts / git.ts / mcp-config.ts
│   ├── core/                                 ← 共享内核
│   │   ├── indexer.ts                        ← 文件收集 + Markdown 切块 + 清理
│   │   ├── embed.ts                          ← all-MiniLM-L6-v2（hf-mirror 镜像）
│   │   ├── server.ts                         ← MCP stdio server
│   │   ├── tools.ts                          ← 4 工具实现
│   │   ├── manifest.ts / config.ts / types.ts / build-index.ts
│   └── preset/                               ← preset 类型
│       ├── schema.ts                         ← Preset 类型 + zod 校验
│       └── loader.ts                         ← 读 presets/*.json
├── presets/                                  ← 预制清单（每服务一文件，提交进 git）
├── services/                                 ← service config（install/add 自动生成）
├── templates/consumer/                       ← 消费方规范模板（CLAUDE.md + mcp-refs/，config --with-claude-md 输出）
├── data/                                     ← 索引产物（git ignored，可重建）
├── packages/                                 ← 拉取的源码（git ignored）
├── .mcp.json.template                        ← .mcp.json 模板（${DOCS_MCP_ROOT} 占位符）
├── .mcp.json                                 ← 用户本地（git ignored，docs-mcp config 生成）
└── README.md / CLAUDE.md / CONTRIBUTING.md

presets/<svc>.json（用户编辑 / add 命令生成）
  → install: git clone → packages/<pkg>/
  → install: 写 services/<svc>.json（自动推导 sources[].root）
  → build:   node dist/core/build-index.js <svc>
  → Orama.index() → data/<svc>/index.json + pages.json + manifest.json

Claude Code 读 .mcp.json → spawn `docs-mcp serve <svc>`（或 `node <root>/dist/core/server.js`）
  → loadIndex() 探测索引是否含 embedding 字段 → 选 hybrid / fulltext schema
  → 注册 4 工具（search_/get_/list_/grep_）
  → stdio JSON-RPC 接收 tool call → Orama.search() → 返回结果

# 全部预制 + 立即构建索引（首次推荐）
docs-mcp install --build

# 只安装指定服务
docs-mcp install vue vite pinia --build

# 强制重新克隆（packages/ 内已存在也覆盖）
docs-mcp install --force --build

# 调整 git clone 深度（默认 --depth 1 浅克隆，省磁盘）
docs-mcp install redis --depth 5 --build

# 跳过内核依赖检查（已确认环境完备时加速）
docs-mcp install --no-deps --build

# 已安装的服务，想升级文档？
docs-mcp update vue          # git pull + 重建索引（默认）
docs-mcp update --all        # 全部已安装服务
docs-mcp update vue --verify # 更新后顺带验证
docs-mcp update vue --force  # 浅克隆 pull 失败时，强制重新克隆

# 全交互模式（推荐新手，逐项填写元数据）
docs-mcp add https://github.com/withastro/docs --interactive

# 命令行模式（适合 CI/脚本）
docs-mcp add https://github.com/foo/bar.git \
  --name astro \
  --docs-root src/content/docs \
  --exclude "blog/**,i18n/**" \
  --mode hybrid \
  --docs-name "Astro Docs" \
  --server-name astro-docs      # .mcp.json 注册名（默认 <name>-docs）

# 添加后构建索引 + 生成 .mcp.json
docs-mcp build astro
docs-mcp config --services astro,vite

# 移除服务（默认删 packages/ + services/ + data/ + preset 四件套）
docs-mcp remove foo

# 移除但保留部分（调试 / 节省重下时间）
docs-mcp remove foo --keep-data     # 保留索引（下次 build 跳过）
docs-mcp remove foo --keep-source   # 保留 packages/ 源码

# 交互模式（推荐，空格勾选、回车确认）
docs-mcp config

# 指定服务 + 输出路径
docs-mcp config --services vue,vite,pinia -o .mcp.json

# 全选已构建服务
docs-mcp config --all

# 输出到目标项目（不在本仓库执行）
docs-mcp config --all -o /path/to/your-project/.mcp.json

# 生成绝对路径块（clone 源码且未 npm link 时用；否则默认 docs-mcp serve 可移植块）
docs-mcp config --all --absolute -o .mcp.json

# 一并输出消费方规范（CLAUDE.md + 选中服务 mcp-refs 速查）到目标项目
docs-mcp config --all --with-claude-md -o /path/to/your-project/.mcp.json

# 组合：指定服务 + 消费方规范 + 绝对路径
docs-mcp config --services vue,vite --with-claude-md --absolute -o .mcp.json

{
  "mcpServers": {
    "vite-docs": {
      "command": "docs-mcp",
      "args": ["serve", "vite"]
    },
    "vue-docs": { "...": "..." }
  }
}

your-project/
├── .mcp.json                  ← docs-mcp config 生成
├── CLAUDE.md                  ← 消费方规范（已有则输出为 CLAUDE.docs-mcp.md）
└── .claude/mcp-refs/
    ├── vue.md                 ← 各服务文档路径速查
    └── vite.md

# 列出服务（默认全部预制 + 安装/构建状态）
docs-mcp list
docs-mcp list --installed      # 仅已安装到 packages/ 的
docs-mcp list --built          # 仅已构建索引的
docs-mcp list --available      # 仅预制但未安装的
docs-mcp list --json           # JSON 输出（便于脚本解析）

# 浏览预制元数据
docs-mcp preset list           # 所有预制
docs-mcp preset show vue       # 某预制的完整配置

# 构建 / 重建索引
docs-mcp build vue              # 单服务
docs-mcp build --all           # 全部已安装服务
docs-mcp build --core-only     # 仅重新编译 src/ → dist/（源码开发用）

# 验证（端到端 MCP 协议测试 + HTML 报告）
docs-mcp verify                # 全部已构建服务
docs-mcp verify vite vue pinia # 指定服务
docs-mcp verify -o /tmp/reports

# 手动运行某服务（调试用，通常由 .mcp.json 自动 spawn）
docs-mcp serve vue