@gulibs/safe-coder 0.0.26 → 0.0.28

package/README.md

@@ -1,1237 +1,921 @@
-# Safe Coder MCP 服务
-
-一个基于 Model Context Protocol (MCP) 的服务器，提供以下功能：
-- **最新库文档** - 从 npm、GitHub 和 HTTP 源获取文档
-- **文档爬取和技能生成** - 递归爬取文档网站并生成 Agent Skill
-- **网页文档浏览** - 浏览和搜索网页文档内容
-- **全面错误检测** - 使用 ESLint、TypeScript、模式匹配和上下文分析
-- **代码验证** - 带自动修复功能
-- **错误解决方案建议** - 针对常见编码问题
-
-## 功能特性
-
-### 文档获取
-
-- 从 npm 注册表获取
-- 从 GitHub 仓库获取
-- 从直接 HTTP 文档站点获取
-- 智能缓存，基于版本键和 TTL
-- 热门包的背景刷新
-
-### 文档爬取和技能生成 🚀
-
-#### 核心功能
-- 递归爬取文档网站，自动跟踪文档链接
-- 智能边界检测，只在文档路径内爬取
-- 生成结构化的 Agent Skill 输出（Markdown 格式）
-- 支持深度限制、页面限制和速率控制
-- 自动组织内容，生成目录和章节
-
-#### 基础特性
-- **SPA 检测**：自动检测单页应用并提供建议
-- **智能重试**：对临时错误自动重试，提高成功率
-- **错误分类**：详细的错误类型统计和分析
-- **进度监控**：实时显示爬取进度和性能指标
-
-#### 🌟 增强特性（新增）
-- **双重爬取策略**：支持 BFS（广度优先）和 DFS（深度优先）两种策略
-- **并行爬取**：1-10个worker并发，速度提升 **4-6倍** ⚡
-- **断点续传**：中断后可恢复，支持大规模文档爬取
-- **llms.txt支持**：自动检测和使用llms.txt文件，效率提升 **2-3倍** ⚡
-- **Markdown支持**：完整支持.md文件爬取和结构化提取
-- **智能质量检测**：6项指标多维度评估内容质量
-
-### 网页文档浏览
-
-- 浏览和搜索网页文档内容
-- 自动检测文档页面（节省 token）
-- 支持查询过滤和导航链接提取
-- 智能内容提取和组织
-
-### 错误检测
-
-- 多层检测：
-  1. ESLint - 代码质量检查
-  2. TypeScript 编译器 - 类型检查
-  3. 模式匹配 - 常见错误模式
-  4. 上下文分析 - 未定义变量和 API 使用错误
-- 优先级错误报告（语法 → 类型 → 运行时 → 逻辑 → 警告）
-
-### 代码验证
-
-- 完整的验证管道
-- 自动修复常见错误（语法、缺失导入）
-- 错误解决方案数据库
-- 在代码展示前进行验证
-
-## 安装方式
-
-### 方式一：通过 npm 安装（推荐）
-
-如果已发布到 npm：
-
+# Safe Coder MCP Server
+
+> **Version:** 0.0.27  
+> **Status:** Development Preview  
+> **Architecture:** MCP Server (orchestration layer)
+
+MCP Server for documentation crawling orchestration. Coordinates with `@gulibs/safe-coder-cli` to crawl documentation websites, process content, and provide structured guidance for creating Cursor AI SKILL files.
+
+## ⚠️ Current Version Status
+
+**Version 0.0.27 - Development Preview:**
+- ✅ Architecture refactored: Clean separation between MCP Server and CLI
+- ✅ Core functionality: Crawling orchestration, content processing, SKILL guidance
+- ✅ **NEW: `save_skill` tool** - Automatic SKILL file creation with complete directory structure
+- ⚠️ **Not published to npm** - requires manual installation from source
+
+## What This Package Does
+
+**Safe Coder MCP Server is an orchestration layer** that:
+
+1. ✅ **Checks dependencies** - Verifies `safe-coder-cli` is installed
+2. ✅ **Spawns CLI process** - Executes crawling via child process
+3. ✅ **Parses CLI output** - Reads JSON from stdout, progress from stderr
+4. ✅ **Processes content** - Extracts key points, code patterns, topics
+5. ✅ **Generates guidance** - Creates structured SKILL generation recommendations
+6. ✅ **Manages cache** - Stores results for 7 days in `~/.safe-coder/cache/`
+7. ✅ **Saves SKILL files** - Creates complete directory structure (SKILL.md + references/)
+8. ✅ **Exposes MCP tools** - Provides 4 tools to Cursor AI
+
+**This package does NOT:**
+- ❌ Perform web crawling (delegated to CLI)
+- ❌ Run browser automation (CLI responsibility)
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Cursor / Claude Desktop (MCP Client)                      │
+│  • Calls MCP tools                                         │
+│  • Receives data + guidance                                │
+│  • Creates SKILL.md based on guidance                      │
+└────────────────┬────────────────────────────────────────────┘
+                 │ MCP Protocol (JSON-RPC over stdio)
+┌────────────────▼────────────────────────────────────────────┐
+│  @gulibs/safe-coder (MCP Server) - THIS PACKAGE            │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │ 1. Dependency Check (which safe-coder-cli)           │  │
+│  │ 2. CLI Executor (spawn child process)                │  │
+│  │ 3. Parse JSON Output (stdout → data)                 │  │
+│  │ 4. Content Processor (extract key info)              │  │
+│  │ 5. Guide Generator (create SKILL guidance)           │  │
+│  │ 6. Cache Manager (store/retrieve results)            │  │
+│  └──────────────────────────────────────────────────────┘  │
+│                                                             │
+│  Tools: crawl_documentation, save_skill,                   │
+│         list_cached_documentation, clear_cache            │
+└────────────────┬────────────────────────────────────────────┘
+                 │ spawn('safe-coder-cli', ['crawl', url, ...])
+                 │ stdin: commands, stdout: JSON, stderr: progress
+┌────────────────▼────────────────────────────────────────────┐
+│  @gulibs/safe-coder-cli (Standalone CLI Tool)              │
+│  • HTTP + Browser-based web crawling                       │
+│  • Content extraction and markup conversion                │
+│  • JSON output to stdout (results)                         │
+│  • JSON output to stderr (progress messages)               │
+└────────────────┬────────────────────────────────────────────┘
+                 │ HTTP requests / Puppeteer / Playwright
+┌────────────────▼────────────────────────────────────────────┐
+│  Documentation Website (e.g., react.dev, vuejs.org)        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Installation
+
+### Step 1: Prerequisites
+
+**Node.js 18+**
 ```bash
-# 全局安装
-npm install -g @gulibs/safe-coder
-
-# 或者本地安装到项目
-npm install @gulibs/safe-coder
+node --version  # Must be v18.0.0 or higher
 ```
 
-### 方式二：从源码安装
+### Step 2: Install CLI Tool (Required)
 
-```bash
-# 克隆或下载项目
-git clone <repository-url>
-cd safe-coder
-
-# 安装依赖
-npm install
-
-# 构建项目
-npm run build
-```
-
-## 配置
-
-设置环境变量（可选）：
-
-- `CACHE_TTL_MINUTES` - 文档缓存 TTL（分钟），默认：60
-- `GITHUB_TOKEN` - GitHub API token（用于访问私有仓库，可选）
-- `ENABLE_AUTO_FIX` - 启用自动修复，默认：true
-- `RATE_LIMIT_REQUESTS` - 每个窗口的最大请求数，默认：100
-- `RATE_LIMIT_WINDOW_MS` - 速率限制窗口（毫秒），默认：60000
-- `LOG_LEVEL` - 日志级别：`DEBUG`、`INFO`、`WARN`、`ERROR`，默认：`INFO`
-- `LOG_COLORS` - 启用彩色日志输出，默认：`true`（设置为 `false` 禁用）
-
-### 代理配置（适用于国内网络环境）
-
-如果无法直接访问 npm registry 或 GitHub API，可以配置代理：
-
-- `HTTP_PROXY` 或 `http_proxy` - HTTP 代理地址，例如：`http://127.0.0.1:7890`
-- `HTTPS_PROXY` 或 `https_proxy` - HTTPS 代理地址，例如：`http://127.0.0.1:7890`
-- `NO_PROXY` 或 `no_proxy` - 不使用代理的地址列表（逗号分隔），例如：`localhost,127.0.0.1`
-
-**示例配置：**
+⚠️ **The MCP server requires `@gulibs/safe-coder-cli` to be globally installed.**
 
+**Option A: From npm (after publication)**
 ```bash
-# 使用 HTTP/HTTPS 代理
-export HTTP_PROXY=http://127.0.0.1:7890
-export HTTPS_PROXY=http://127.0.0.1:7890
-
-# 或者使用 SOCKS5 代理（如果代理支持）
-export HTTP_PROXY=socks5://127.0.0.1:1080
-export HTTPS_PROXY=socks5://127.0.0.1:1080
-
-# 排除本地地址
-export NO_PROXY=localhost,127.0.0.1,*.local
-```
-
-**在 Cursor 配置文件中设置：**
-
-```json
-{
-  "mcpServers": {
-    "safe-coder": {
-      "command": "npx",
-      "args": ["-y", "@gulibs/safe-coder"],
-      "env": {
-        "HTTP_PROXY": "http://127.0.0.1:7890",
-        "HTTPS_PROXY": "http://127.0.0.1:7890",
-        "NO_PROXY": "localhost,127.0.0.1"
-      }
-    }
-  }
-}
+npm install -g @gulibs/safe-coder-cli
 ```
 
-## 使用方法
-
-### 1. 运行服务器
-
+**Option B: From source (current development setup)**
 ```bash
-# 开发模式（使用 tsx）
-npm run dev
-
-# 生产模式（需要先构建）
+# Clone and build CLI
+cd /path/to/safe-coder-cli
+npm install
 npm run build
-npm start
-```
-
-服务器通过 stdio 运行，使用 MCP 协议进行通信。
-
-### 2. 监控服务状态
-
-#### 查看日志
+npm link  # Makes 'safe-coder-cli' available globally
 
-所有日志输出到 `stderr`（标准错误输出），包括：
-- 服务器启动信息
-- 工具调用记录（请求 ID、参数、执行时间）
-- 错误和警告信息
-
-**日志格式示例：**
-
-```
-[2024-01-01T12:00:00.000Z] [INFO] Safe Coder MCP server started {"version":"1.0.0","pid":12345}
-[2024-01-01T12:00:00.100Z] [INFO] MCP server connected to transport
-[2024-01-01T12:00:00.200Z] [INFO] Tool invoked: get_documentation {"requestId":"req-1234567890-1","tool":"get_documentation","params":{"packageName":"react"}}
-[2024-01-01T12:00:00.500Z] [INFO] Tool completed: get_documentation {"requestId":"req-1234567890-1","tool":"get_documentation","duration":"500ms","success":true}
-```
-
-**日志级别（通过 `LOG_LEVEL` 环境变量设置）：**
-- `DEBUG` - 详细调试信息
-- `INFO` - 一般信息（工具调用、完成）默认
-- `WARN` - 警告信息
-- `ERROR` - 错误信息
-
-#### 使用 get_status 工具
-
-在 Cursor 中，你可以调用 `get_status` 工具来查看服务器状态：
-
-```json
-{
-  "status": "running",
-  "uptime": 3600,
-  "version": "1.0.0",
-  "tools": ["get_documentation", "detect_errors", "validate_code", "resolve_error", "get_status"],
-  "cacheSize": 10,
-  "pid": 12345
-}
+# Verify
+safe-coder-cli --version
+# Output: 0.0.1
 ```
 
-#### 在 Cursor 中查看日志
-
-1. **打开 Cursor 的开发者工具**：
-   - macOS: `Cmd + Shift + P` → "Developer: Toggle Developer Tools"
-   - Windows/Linux: `Ctrl + Shift + P` → "Developer: Toggle Developer Tools"
-
-2. **查看控制台**：
-   - 在开发者工具中切换到 "Console" 标签
-   - MCP 服务器的日志会显示在这里
-
-3. **启用调试模式**：
-
-在 Cursor 配置中添加：
-
-```json
-{
-  "mcpServers": {
-    "safe-coder": {
-      "command": "npx",
-      "args": ["-y", "@gulibs/safe-coder"],
-      "env": {
-        "LOG_LEVEL": "DEBUG",
-        "LOG_COLORS": "true"
-      }
-    }
-  }
-}
-```
-
-### 3. 在 Cursor 中配置
-
-> **⚠️ 重要提示**：如果包还没有发布到 npm，请使用"本地开发配置"方式。
-
-#### 步骤 1：找到 Cursor 配置文件
-
-Cursor 的 MCP 配置文件位置：
-- **macOS**: `~/Library/Application Support/Cursor/User/globalStorage/mcp.json`
-- **Windows**: `%APPDATA%\Cursor\User\globalStorage\mcp.json`
-- **Linux**: `~/.config/Cursor/User/globalStorage/mcp.json`
-
-或者通过 Cursor 设置界面：
-1. 打开 Cursor 设置（`Cmd/Ctrl + ,`）
-2. 搜索 "MCP" 或 "Model Context Protocol"
-3. 找到 MCP 服务器配置
-
-#### 步骤 2：添加配置
+### Step 3: Install MCP Server
 
-根据你的安装方式选择对应的配置：
-
-##### 方式 A：本地开发配置（推荐，如果包未发布）
-
-使用项目的绝对路径：
-
-```json
-{
-  "mcpServers": {
-    "safe-coder": {
-      "command": "node",
-      "args": ["/Users/wormhole/Documents/Developments/Our/mcp/safe-coder/dist/index.js"],
-      "env": {
-        "CACHE_TTL_MINUTES": "60",
-        "GITHUB_TOKEN": "your_token_here"
-      }
-    }
-  }
-}
-```
-
-**获取你的项目路径：**
+⚠️ **Not yet published to npm - use local installation:**
 
+**Development Installation:**
 ```bash
-# 在项目目录下运行
-pwd
-```
-
-##### 方式 B：通过 npm 安装（需要先发布到 npm）
-
-如果包已发布到 npm，可以使用 npx：
+cd /path/to/safe-coder
+npm install
+npm run build
 
-```json
-{
-  "mcpServers": {
-    "safe-coder": {
-      "command": "npx",
-      "args": ["-y", "@gulibs/safe-coder"],
-      "env": {
-        "CACHE_TTL_MINUTES": "60",
-        "GITHUB_TOKEN": "your_token_here"
-      }
-    }
-  }
-}
+# Optional: Link for global access
+npm link
 ```
 
-或者全局安装后使用：
+### Step 4: Configure Cursor
 
-```bash
-# 全局安装
-npm install -g @gulibs/safe-coder
-
-# 查看全局安装路径
-npm root -g
-```
+**Edit Cursor MCP configuration:**
 
-然后配置（替换 `<global-node-modules-path>` 为实际路径）：
+File location: `~/Library/Application Support/Cursor/User/globalStorage/mcp.json`
 
 ```json
 {
   "mcpServers": {
     "safe-coder": {
       "command": "node",
-      "args": ["<global-node-modules-path>/@gulibs/safe-coder/dist/index.js"],
-      "env": {
-        "CACHE_TTL_MINUTES": "60",
-        "GITHUB_TOKEN": "your_token_here"
-      }
+      "args": ["/absolute/path/to/safe-coder/dist/index.js"]
     }
   }
 }
 ```
 
-##### 如果从源码安装：
-
-找到你安装的路径，然后配置：
-
+**Replace `/absolute/path/to/safe-coder`** with actual path, e.g.:
 ```json
 {
   "mcpServers": {
     "safe-coder": {
       "command": "node",
-      "args": ["/绝对路径/to/safe-coder/dist/index.js"],
-      "env": {
-        "CACHE_TTL_MINUTES": "60",
-        "GITHUB_TOKEN": "your_token_here"
-      }
+      "args": ["/Users/yourname/projects/mcp/safe-coder/dist/index.js"]
     }
   }
 }
 ```
 
-**获取绝对路径的方法：**
-
-在项目目录下运行：
-
-```bash
-# macOS/Linux
-pwd
-
-# Windows PowerShell
-(Get-Location).Path
-```
-
-##### 如果使用本地项目安装（node_modules）：
-
+**Future (after npm publication):**
 ```json
 {
   "mcpServers": {
     "safe-coder": {
-      "command": "node",
-      "args": ["./node_modules/@gulibs/safe-coder/dist/index.js"],
-      "env": {
-        "CACHE_TTL_MINUTES": "60",
-        "GITHUB_TOKEN": "your_token_here"
-      }
+      "command": "npx",
+      "args": ["-y", "@gulibs/safe-coder@latest"]
     }
   }
 }
 ```
 
-#### 步骤 3：验证配置
-
-1. **检查配置文件格式**：确保 JSON 格式正确，可以使用在线 JSON 验证器
-2. **重启 Cursor**：保存配置后，完全重启 Cursor
-3. **检查连接状态**：
-   - 在 Cursor 设置中查看 MCP 服务器列表
-   - 应该能看到 "safe-coder" 服务器
-   - 状态应该显示为已连接（绿色）
+### Step 5: Restart Cursor
 
-#### 步骤 4：测试工具
+Restart Cursor to load the MCP server.
 
-在 Cursor 的 AI 对话中测试：
-
-```
-请使用 get_documentation 工具获取 axios 库的文档
-```
+## Usage: SKILL File Generation Workflow
 
-如果工具正常工作，说明配置成功！
+### ⚠️ Important: How SKILL Files Are Created
 
-### 3. 使用 MCP 工具
+**The MCP server does NOT create `SKILL.md` files directly.** Here's the actual workflow:
 
-配置完成后，你可以在 Cursor 的 AI 对话中使用以下工具：
+#### What the MCP Server Returns
 
-**可用工具列表：**
-1. `get_documentation` - 获取文档
-2. `browse_documentation` - 浏览网页文档
-3. `crawl_documentation` - 爬取文档并生成技能
-4. `detect_spa` - 检测单页应用
-5. `detect_errors` - 检测代码错误
-6. `validate_code` - 验证代码
-7. `resolve_error` - 解决错误
-8. `get_status` - 获取服务器状态
-9. `get_version` - 获取版本号
+1. **Crawled content** - Full text from all pages
+2. **Processed data** - Key points, code patterns, categories, topics
+3. **SKILL generation guide** - Structured recommendations for SKILL.md
+4. **Quality assessment** - Scores for content quality, completeness
 
-#### `get_documentation` - 获取文档
+#### Where SKILL Files Are Saved
 
-获取库或包的文档。
+**You must explicitly tell Cursor AI where to save the file:**
 
-**参数：**
-- `packageName`（必需）：包名（npm）、仓库（owner/repo）或 URL
-- `version`（可选）：版本或分支 / 标签
-- `source`（可选）：源类型（'npm'、'github'、'http'）- 如果不指定会自动检测
-
-**使用示例：**
-
-```
-请帮我获取 axios 库的文档
 ```
-
-或者直接调用：
-
-```json
-{
-  "packageName": "axios",
-  "version": "latest",
-  "source": "npm"
-}
+User: "Crawl React docs and create a SKILL file"
+      ↓
+Cursor AI: [Calls crawl_documentation, receives data + guidance]
+      ↓
+User: "Save it to ~/.claude/skills/react-docs/SKILL.md"
+      ↓
+Cursor AI: [Creates file at specified location]
 ```
 
-#### `browse_documentation` - 浏览网页文档
-
-浏览和搜索网页文档页面。
-
-**参数：**
-- `url`（必需）：文档 URL
-- `query`（可选）：搜索查询词，用于过滤内容
-- `navigateTo`（可选）：导航到文档内的其他页面
-
-**使用示例：**
-
+**Recommended location pattern:**
 ```
-浏览 https://react.dev/docs/getting-started 的文档
+~/.claude/skills/
+├── react-docs/SKILL.md          # React documentation
+├── vue-guide/SKILL.md           # Vue.js guide
+├── typescript-handbook/SKILL.md # TypeScript handbook
+└── [tech-name]/SKILL.md         # Generic pattern
 ```
 
-```
-在 https://expressjs.com/en/guide 中查找关于路由的内容
-```
+**Naming conventions:**
+- Directory: `[technology-name]` (lowercase, hyphens)
+- File: Always `SKILL.md` (Cursor convention)
+- Examples: `react-docs`, `vue-guide`, `next-js-docs`
 
-#### `crawl_documentation` - 爬取文档并生成Agent Skill 🚀
-
-递归爬取文档网站，提取内容并生成结构化的 Agent Skill。
-
-**基础参数：**
-- `url`（必需）：文档根 URL
-- `maxDepth`（可选）：最大爬取深度（默认：3）
-- `maxPages`（可选）：最大页面数（默认：50）
-- `includePaths`（可选）：额外包含的路径模式
-- `excludePaths`（可选）：排除的路径模式
-- `rateLimit`（可选）：请求间隔（毫秒，默认：500）
-- `maxRetries`（可选）：失败请求的最大重试次数（默认：2）
-- `retryDelay`（可选）：重试前的延迟（毫秒，默认：1000）
-- `outputDir`（可选）：保存技能文件的目录（如果不提供，只返回内容）
-- `filename`（可选）：自定义文件名（不含扩展名）
-
-**🌟 增强参数（新增）：**
-- `crawlStrategy`（可选）：爬取策略 `'bfs'` | `'dfs'`（默认：bfs）
-  - **BFS**（广度优先）：逐层爬取，适合全面覆盖
-  - **DFS**（深度优先）：深入一条路径，适合深度理解
-- `workers`（可选）：并发worker数量 1-10（默认：1）
-  - 建议：小型站点2-3个，大型站点5-8个
-  - 性能提升：3 workers ≈ 3倍，5 workers ≈ 4-5倍
-- `skipLlmsTxt`（可选）：是否跳过llms.txt检测（默认：false）
-  - 启用时自动检测和使用llms.txt，效率提升2-3倍
-- `checkpoint`（可选）：断点续传配置
-  - `enabled`：是否启用断点功能
-  - `interval`：每N页保存一次（默认：10）
-  - `file`：checkpoint文件路径（可选）
-- `resume`（可选）：是否从上次断点恢复（默认：false）
-
-**基础功能：**
-- ✅ **SPA 检测**：自动检测单页应用（SPA）并提供建议
-- ✅ **智能重试**：对临时错误（超时、网络错误等）自动重试
-- ✅ **错误分类**：详细的错误类型分类和统计
-- ✅ **进度日志**：实时显示爬取进度和统计信息
-
-**🎯 使用示例：**
-
-##### 1. 快速基础爬取
-```
-爬取 https://react.dev/docs 的文档并生成技能
-```
+### Complete Example Workflow
 
-##### 2. 并行加速爬取（推荐）
+**1. Request crawl:**
 ```
-从 https://react.dev 生成 agent skill，使用 5 个并发worker，最多爬取 200 页
+User: "Crawl the React documentation at https://react.dev and create a SKILL file"
 ```
 
-对应参数：
-```json
-{
-  "url": "https://react.dev",
-  "workers": 5,
-  "maxPages": 200,
-  "rateLimit": 200
-}
-```
-
-##### 3. 深度优先策略
-```
-使用 DFS 策略爬取 https://docs.example.com，深度限制为 6
-```
-
-对应参数：
-```json
-{
-  "url": "https://docs.example.com",
-  "crawlStrategy": "dfs",
-  "maxDepth": 6,
-  "workers": 3
-}
+**2. Cursor AI calls MCP tool:**
+```typescript
+crawl_documentation({
+  url: "https://react.dev",
+  maxPages: 200,  // Default
+  depth: 3        // Default
+})
 ```
 
-##### 4. 大规模爬取（带断点）
+**3. MCP Server process:**
 ```
-爬取 https://large-docs.com，最多 1000 页，启用断点每 50 页保存一次
+[Dependency Check] ✓ safe-coder-cli found at /usr/local/bin/safe-coder-cli
+[Spawning CLI] safe-coder-cli crawl https://react.dev --output-format json ...
+[Progress] Crawling... 10/50 pages
+[Progress] Crawling... 25/50 pages
+[Progress] Crawling... 50/50 pages complete
+[Processing] Analyzing content...
+[Processing] Generating SKILL guidance...
+[Cache] Saving to ~/.safe-coder/cache/aHR0cHM6Ly9yZWFjdC5kZXY=.json
+[Complete] Ready to return
 ```
 
-对应参数：
+**4. MCP returns to Cursor:**
 ```json
 {
-  "url": "https://large-docs.com",
-  "maxPages": 1000,
-  "workers": 8,
-  "checkpoint": {
-    "enabled": true,
-    "interval": 50
-  }
+  "success": true,
+  "data": {
+    "source": {
+      "url": "https://react.dev",
+      "crawledAt": "2026-01-15T14:30:00Z",
+      "pageCount": 50,
+      "depth": 3
+    },
+    "pages": [
+      {
+        "url": "https://react.dev/learn",
+        "title": "Quick Start",
+        "content": "Welcome to React...",
+        "keyPoints": [
+          "React is a JavaScript library",
+          "Components are building blocks",
+          "...more..."
+        ],
+        "codePatterns": [
+          {
+            "language": "jsx",
+            "pattern": "function Component() { return <div>...</div> }",
+            "description": "Functional component syntax"
+          }
+        ],
+        "wordCount": 1500,
+        "codeBlocks": 12
+      }
+      // ... 49 more pages
+    ],
+    "analysis": {
+      "mainTopics": ["Components", "Hooks", "State", "Props", "Effects"],
+      "difficulty": "intermediate",
+      "technicalDensity": 0.65
+    }
+  },
+  "skillGenerationGuide": {
+    "suggestedStructure": [
+      "Overview",
+      "Quick Start", 
+      "Core Concepts",
+      "Hooks Reference",
+      "Best Practices",
+      "Common Patterns",
+      "Troubleshooting"
+    ],
+    "keyTopics": [
+      "JSX Syntax",
+      "Components (Functional & Class)",
+      "Props and State",
+      "Hooks (useState, useEffect, useContext, etc.)",
+      "Event Handling",
+      "Conditional Rendering",
+      "Lists and Keys"
+    ],
+    "recommendedSections": {
+      "overview": "React is a JavaScript library for building user interfaces...",
+      "quickStart": [
+        "Install: npx create-react-app my-app",
+        "Create first component",
+        "Understand JSX"
+      ],
+      "coreFeatures": [
+        "Component-based architecture",
+        "Virtual DOM",
+        "One-way data flow",
+        "Declarative UI"
+      ],
+      "bestPractices": [
+        "Use functional components with Hooks",
+        "Keep components small and focused",
+        "Lift state up when needed"
+      ]
+    },
+    "tips": [
+      "Focus on the Hooks API (modern approach)",
+      "Include examples for common Hooks",
+      "Explain component lifecycle clearly",
+      "Cover both client and server rendering"
+    ],
+    "quality": {
+      "contentQuality": 90,
+      "codeExamples": 85,
+      "completeness": 88,
+      "overall": 87
+    }
+  },
+  "fromCache": false,
+  "message": "Successfully crawled 50 pages. Quality score: 87/100"
 }
 ```
 
-##### 5. 恢复中断的爬取
+**5. Tell Cursor where to save:**
 ```
-从断点恢复 https://large-docs.com 的爬取
+User: "Save this as a SKILL file at ~/.claude/skills/react-docs/SKILL.md"
 ```
 
-对应参数：
-```json
-{
-  "url": "https://large-docs.com",
-  "resume": true,
-  "checkpoint": { "enabled": true }
-}
-```
+**6. Cursor AI generates and saves:**
+- Uses `data.pages` for content
+- Uses `skillGenerationGuide` for structure
+- Creates formatted `SKILL.md`
+- Saves to specified location
 
-**📊 性能对比：**
+## MCP Tools Reference
 
-| 爬取规模 | 串行模式 | 并行模式(workers=5) | 提升 |
-|---------|---------|-------------------|------|
-| 50页 | ~90秒 | ~22秒 | **4倍** ⚡ |
-| 100页 | ~180秒 | ~45秒 | **4倍** ⚡ |
-| 200页 | ~360秒 | ~80秒 | **4.5倍** ⚡ |
+### Tool 1: `crawl_documentation` 
 
-**输出内容：**
-- `skillContent`: Markdown 格式的技能内容
-- `metadata`: 技能元数据（标题、描述、源 URL 等）
-- `crawlStats`: 爬取统计（总页数、最大深度、错误列表、质量指标）
-- `files`（可选）：保存的文件路径
-  - `skillFile`: SKILL.md 文件路径
-  - `manifestFile`: metadata.json 文件路径
+(**Recommended Workflow**: Use with `save_skill` for complete automation)
 
-**💡 最佳实践：**
-1. **先小规模测试**：maxPages设为10-20验证效果
-2. **逐步增加并发**：从workers=2开始，观察效果
-3. **大规模使用断点**：超过200页建议启用checkpoint
-4. **关注质量指标**：diversity和coverage应 > 0.5
+Crawl documentation website and return processed data with SKILL generation guidance.
 
-**🌐 SPA网站支持（新增）：**
+**Parameters:**
 
-系统智能检测并处理单页应用（React、Vue、Angular等），自动切换HTTP和浏览器渲染模式。
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `url` | `string` | ✅ Yes | - | Documentation URL to crawl |
+| `maxPages` | `number` | No | `200` | Maximum pages to crawl |
+| `depth` | `number` | No | `3` | Maximum crawl depth |
+| `workers` | `number` | No | `1` | Number of parallel workers |
+| `useBrowser` | `boolean` | No | `false` | Force browser automation |
+| `browser` | `'puppeteer'` \| `'playwright'` | No | `'puppeteer'` | Browser type |
+| `spaStrategy` | `'smart'` \| `'auto'` \| `'manual'` | No | `'smart'` | SPA detection |
+| `useCache` | `boolean` | No | `true` | Use cached results |
+| `forceRefresh` | `boolean` | No | `false` | Bypass cache |
 
-##### 自动处理SPA（推荐）
-```
-爬取 https://react.dev 的文档  # 自动检测并处理SPA
-```
+**⚠️ Parameters NOT Currently Exposed (CLI supports, MCP doesn't):**
+- `strategy` (bfs/dfs) - Crawl strategy
+- `checkpoint`, `resume` - Checkpoint/resume functionality
+- `rateLimit`, `maxRetries`, `retryDelay` - Rate limiting and retry control
+- `includePaths`, `excludePaths` - URL path filtering
+- `skipLlmsTxt` - llms.txt detection control
 
-##### SPA策略配置
+**Returns:**
 ```typescript
 {
-  "spaStrategy": "smart",  // smart（智能）| auto（自动）| manual（手动）
-  "spaFallback": "warn",   // warn（警告）| skip（跳过）| error（错误）
-  "browserPath": "/path/to/chrome",  // 可选：自定义浏览器路径
-  "waitForTimeout": 3000,            // 可选：等待内容加载时间
-  "networkIdleTimeout": 500          // 可选：网络空闲等待时间
+  success: boolean;
+  data: {
+    source: { url, crawledAt, pageCount, depth };
+    pages: Array<{
+      url, title, content, keyPoints, codePatterns,
+      category, wordCount, codeBlocks, headings
+    }>;
+    metadata: { technology, version, documentType, categories };
+    statistics: { totalPages, maxDepthReached, errors, linkDiscovery };
+    analysis: {
+      totalWords, totalCodeBlocks, categories,
+      mainTopics, technicalDensity, difficulty
+    };
+  };
+  skillGenerationGuide: {
+    suggestedStructure: string[];
+    keyTopics: string[];
+    recommendedSections: {
+      overview, quickStart, coreFeatures, bestPractices, troubleshooting
+    };
+    tips: string[];
+    quality: { contentQuality, codeExamples, completeness, overall };
+  };
+  fromCache: boolean;
+  cacheAge?: string;  // If from cache
+  message: string;
 }
 ```
 
-**三种SPA策略**：
-- **smart（默认）**: HTTP优先，内容不足时自动切换浏览器（推荐）
-- **auto**: 检测到SPA立即使用浏览器
-- **manual**: 仅在useBrowserAutomation=true时使用浏览器
+**Example Cursor prompts:**
 
-**浏览器要求**：
-- ✅ 系统已安装Chrome/Chromium/Edge（推荐，自动检测）
-- ✅ 或安装完整版puppeteer（自动下载Chromium）
-- ✅ 或设置CHROME_PATH环境变量
-- 📖 详见：[SPA浏览器设置指南](docs/SPA_BROWSER_SETUP.md)
+```bash
+# Basic usage
+"Crawl https://react.dev and create a SKILL"
 
-**性能对比**：
-- HTTP模式：0.5-1秒/页
-- 浏览器模式：2-3秒/页
-- smart策略：平均<1.5秒/页（自动优化）
+# Limit pages
+"Crawl Vue.js docs but only 50 pages"
 
-**使用示例**：
+# Force refresh
+"Re-crawl React docs, ignore cache"
 
-快速SPA爬取：
-```
-爬取 https://vuejs.org，自动处理SPA，最多100页
+# Use browser for SPA
+"Crawl https://app.example.com with Playwright"
 ```
 
-已知SPA站点：
-```
-从 https://angular.io 生成技能，使用浏览器渲染，5个并发worker
-```
+### Tool 2: `list_cached_documentation`
 
-对应参数：
-```json
+List all cached documentation crawl results with metadata.
+
+**Parameters:** None
+
+**Returns:**
+```typescript
 {
-  "url": "https://angular.io",
-  "spaStrategy": "auto",
-  "workers": 5,
-  "maxPages": 200
+  success: boolean;
+  entries: Array<{
+    url: string;
+    technology?: string;
+    pageCount: number;
+    cachedAt: string;  // ISO timestamp
+    age: string;       // Human-readable, e.g., "2 hours ago"
+    size: string;      // Human-readable, e.g., "2.5 MB"
+  }>;
+  statistics: {
+    totalEntries: number;
+    totalSize: number;  // Bytes
+    oldestEntry?: Date;
+    newestEntry?: Date;
+  };
+  message: string;
 }
 ```
 
-**📚 详细文档：**
-- SPA浏览器设置：`docs/SPA_BROWSER_SETUP.md`
-- 完整使用指南：`docs/ENHANCED_CRAWLING.md`
-- 快速上手：查看项目中的 `QUICKSTART_*.md` 文档
-- 实施细节：`IMPLEMENTATION_SUMMARY.md`
-
-#### `detect_errors` - 检测错误
-
-检测代码中的错误和警告。
-
-**参数：**
-- `code`（必需）：要分析的代码
-- `filename`（可选）：用于上下文的文件名（默认：'code.ts'）
-
-**使用示例：**
-
-```
-请检测这段代码的错误：
-const x = y;
-console.log(z);
+**Example Cursor prompts:**
+```bash
+"Show me all cached documentation"
+"List cached docs"
+"What's in the cache?"
 ```
 
-#### `validate_code` - 验证代码
+### Tool 3: `save_skill` ⭐ NEW
 
-验证代码并可选择自动修复常见错误。
+**Save complete SKILL directory structure to filesystem.**
 
-**参数：**
-- `code`（必需）：要验证的代码
-- `filename`（可选）：用于上下文的文件名
-- `autoFix`（可选）：启用自动修复（默认：true）
+Creates a properly formatted Cursor Agent Skill with:
+- `SKILL.md` - Main skill file with metadata
+- `references/` - Reference documentation organized by category
+- Standard directory structure compatible with Cursor
 
-**使用示例：**
+**Parameters:**
 
-```
-请验证并修复这段代码：
-function test() {
-  return x
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `skillName` | `string` | ✅ Yes | - | Name for skill directory (e.g., "react-docs") |
+| `skillContent` | `string` | ✅ Yes | - | Content for SKILL.md file |
+| `referenceFiles` | `Record<string, string>` | No | `{}` | Map of category → markdown content |
+| `baseDirectory` | `string` | No | `~/.claude/skills` | Base directory for skills |
+| `overwrite` | `boolean` | No | `false` | Overwrite existing skill |
+
+**Returns:**
+```typescript
+{
+  success: boolean;
+  skillDirectory: string;            // Absolute path to skill directory
+  filesCreated: {
+    skillMd: string;                 // Path to SKILL.md
+    references: string[];            // Paths to reference files
+  };
+  message: string;
 }
 ```
 
-#### `resolve_error` - 解决错误
-
-获取特定错误的解决方案建议。
-
-**参数：**
-- `errorType`（必需）：错误类型
-- `message`（必需）：错误消息
-- `line`（可选）：错误发生的行号
-
-**使用示例：**
-
+**Directory Structure Created:**
 ```
-我遇到了一个 undefined-variable 错误，消息是 "Variable 'x' is used but not defined"，在第 5 行
+~/.claude/skills/
+└── [skillName]/
+    ├── SKILL.md                     # Main skill file
+    └── references/                  # Reference documentation
+        ├── api.md                   # API category
+        ├── guides.md                # Guides category
+        ├── getting_started.md       # Getting started
+        └── ...                      # Other categories
 ```
 
-#### `detect_spa` - 检测单页应用
-
-检测网站是否为需要 JavaScript 渲染的单页应用（SPA）。
+**Example Cursor Prompts:**
 
-**参数：**
-- `url`（必需）：要检测的 URL
+```bash
+# After crawling, extract and save skill data
+"Use the crawled React data to create a complete SKILL:
+ - skillName: 'react-docs'
+ - skillContent: [generated from guidance]
+ - referenceFiles: [organized by category]"
 
-**使用示例：**
+# Save with custom location
+"Save the Vue skill to ~/my-skills/"
 
-```
-检测 https://react-dnd.github.io/react-dnd/docs 是否是 SPA
+# Overwrite existing
+"Update the react-docs skill with new content"
 ```
 
-**返回：**
-- `isSPA`：是否为 SPA
-- `confidence`：检测置信度（high/medium/low）
-- `indicators`：检测到的 SPA 指标
-- `suggestion`：建议（如果检测到 SPA）
+**Automated Workflow Example:**
 
-### 4. 使用 MCP 资源
+```
+User: "Crawl React docs and save as a complete SKILL"
 
-#### `safe-coder://documentation` - 缓存的文档
+Step 1: Cursor calls crawl_documentation
+Step 2: Receives data with pages organized by category
+Step 3: Cursor calls save_skill with:
+  {
+    skillName: "react-docs",
+    skillContent: "[Generated SKILL.md from guidance]",
+    referenceFiles: {
+      "api": "[API pages content]",
+      "guides": "[Guide pages content]",
+      "getting_started": "[Getting started content]"
+    }
+  }
+Step 4: Tool creates complete directory structure
+Step 5: Returns paths to all created files
+```
 
-访问缓存的文档条目，查看缓存状态。
+### Tool 4: `clear_cache`
 
-#### `safe-coder://error-patterns` - 错误模式数据库
+Clear cached documentation results by pattern, all entries, or expired only.
 
-访问错误模式数据库，查看已知的错误模式和解决方案。
+**Parameters:**
 
-## 开发
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `urlPattern` | `string` | No | - | URL pattern to match (substring) |
+| `clearAll` | `boolean` | No | `false` | Clear all cached entries |
 
-### 项目结构
+**Behavior:**
+- If `clearAll: true` → Delete all cached entries
+- If `urlPattern` provided → Delete entries matching pattern
+- If neither → Delete only expired entries (>7 days old)
 
+**Returns:**
+```typescript
+{
+  success: boolean;
+  deletedCount: number;
+  message: string;
+}
 ```
-safe-coder/
-├── src/
-│   ├── documentation/  # 文档获取、缓存、爬取和技能生成
-│   │   ├── index.ts           # 文档服务
-│   │   ├── web-doc-browser.ts # 网页文档浏览
-│   │   ├── doc-crawler.ts     # 文档爬取
-│   │   └── skill-generator.ts # 技能生成
-│   ├── errors/         # 错误检测（ESLint、TypeScript、模式、上下文）
-│   ├── validation/     # 代码验证和自动修复
-│   ├── server/         # MCP 服务器实现
-│   ├── types/          # TypeScript 类型定义
-│   ├── utils/          # 配置和工具函数
-│   └── index.ts        # 入口文件
-├── tests/              # 测试文件
-├── dist/               # 编译输出
-└── package.json
-```
-
-### 开发命令
 
+**Example Cursor prompts:**
 ```bash
-# 安装依赖
-npm install
-
-# 构建项目
-npm run build
-
-# 开发模式运行（自动重新编译）
-npm run dev
-
-# 运行测试
-npm test
-
-# 监听模式运行测试
-npm run test:watch
+# Clear all
+"Clear all cached documentation"
 
-# 类型检查
-npm run type-check
+# Clear by pattern
+"Clear cache for react.dev"
+"Delete cached Vue docs"
 
-# 代码检查
-npm run lint
+# Clear expired only
+"Clear old cached docs"
 ```
 
-### 调试
-
-如果遇到问题，可以：
-
-1. **检查服务器是否正常运行**：
-
-   ```bash
-   npm run dev
-   ```
-
-   应该看到：`Safe Coder MCP server running on stdio`
-
-2. **查看 Cursor 的 MCP 日志**：
-   - 在 Cursor 中打开开发者工具
-   - 查看控制台中的 MCP 相关错误
-
-3. **测试工具调用**：
-   可以在 Cursor 的 AI 对话中直接请求使用工具，例如：
-
-   ```
-   请使用 get_documentation 工具获取 react 的文档
-   ```
-
-## 常见问题
+## Internal Workflow
 
-### Q: 服务器无法启动？
+### 1. Dependency Check
 
-**A:** 检查以下几点：
-- 确保已运行 `npm install` 和 `npm run build`
-- 检查 Node.js 版本（建议 18+）
-- 查看错误日志
-
-### Q: 无法获取 GitHub 文档？
-
-**A:**
-- 如果访问私有仓库，需要设置 `GITHUB_TOKEN` 环境变量
-- 公开仓库通常不需要 token，但设置 token 可以提高速率限制
+```typescript
+const checker = new DependencyChecker();
+const check = await checker.checkCLIInstalled();
 
-### Q: 错误检测不准确？
+if (!check.installed) {
+  throw new Error(`
+⚠️  safe-coder-cli is not installed.
 
-**A:**
-- 确保代码文件扩展名正确（`.ts` 用于 TypeScript，`.js` 用于 JavaScript）
-- 某些复杂的错误可能需要更多上下文
-- 可以尝试使用 `validate_code` 工具获得更全面的分析
+Please install globally:
+  npm install -g @gulibs/safe-coder-cli
 
-### Q: 如何更新错误模式数据库？
+Or from source:
+  cd /path/to/safe-coder-cli
+  npm install && npm run build && npm link
 
-**A:**
-- 编辑 `src/errors/patterns.json` 文件
-- 添加新的错误模式
-- 重新构建项目
+Then verify:
+  safe-coder-cli --version
+  `);
+}
+```
 
-### Q: 文档爬取工具如何使用？
+### 2. CLI Execution
 
-**A:**
-- 使用 `crawl_documentation` 工具，提供文档根 URL
-- 工具会自动检测文档页面，跟踪链接，生成技能
-- 支持配置深度和页面限制
-- 详见 `DOC_CRAWLER_USAGE.md`
+```typescript
+const executor = new CLIExecutor(checker);
+const result = await executor.executeCrawl({
+  url: 'https://react.dev',
+  maxPages: 200,
+  maxDepth: 3,
+  // ... other params
+}, (progress) => {
+  console.error(`[Progress] ${progress.message}`);
+});
+```
+
+**Under the hood:**
+```bash
+spawn('safe-coder-cli', [
+  'crawl', 
+  'https://react.dev',
+  '--output-format', 'json',
+  '--max-pages', '200',
+  '--depth', '3'
+])
 
-**示例：**
-```
-爬取 https://react.dev/docs 的文档并生成技能
+# stdout → JSON result
+# stderr → Progress messages
 ```
 
-### Q: 爬取大型文档站点时需要注意什么？
+### 3. Content Processing
 
-**A:**
-- 使用 `maxPages` 参数限制页面数量（默认 50）
-- 使用 `maxDepth` 参数限制爬取深度（默认 3）
-- 调整 `rateLimit` 避免对服务器造成压力（默认 500ms）
-- 使用 `workers` 参数启用并行爬取（推荐5-8个）
-- 启用 `checkpoint` 断点续传（超过200页建议启用）
-- 大型站点建议分多次爬取不同部分
-
-### Q: 如何爬取SPA网站（React、Vue等）？
-
-**A:**
-- 系统自动检测SPA并智能切换到浏览器渲染
-- 确保系统已安装Chrome/Chromium/Edge浏览器
-- 使用 `spaStrategy: "smart"` 获得最佳性能（默认）
-- 或使用 `spaStrategy: "auto"` 强制使用浏览器
-- 详见：`docs/SPA_BROWSER_SETUP.md`
+```typescript
+const processor = new ContentProcessor();
+const processed = await processor.process(rawResult);
 
-**示例**：
+// Extracts:
+// - Key points from each page
+// - Code patterns and examples
+// - Content categories
+// - Technical density
+// - Difficulty level
 ```
-爬取 https://react.dev，自动处理SPA
-```
-
-### Q: 系统没有Chrome怎么办？
 
-**A:**
-有三种解决方案：
-1. **安装Chrome**（推荐）：
-   - macOS: `brew install --cask google-chrome`
-   - Windows: `winget install Google.Chrome`
-   - Linux: `sudo apt install google-chrome-stable`
+### 4. SKILL Guidance Generation
 
-2. **安装完整版puppeteer**（自动下载Chromium）：
-   ```bash
-   npm install puppeteer
-   ```
-
-3. **设置浏览器路径**：
-   ```bash
-   export CHROME_PATH=/path/to/chrome
-   ```
+```typescript
+const guideGenerator = new GuideGenerator();
+const guide = guideGenerator.generate(processed);
 
-详细指南：`docs/SPA_BROWSER_SETUP.md`
+// Creates:
+// - Suggested SKILL structure
+// - Key topics to cover
+// - Recommended sections
+// - Writing tips
+// - Quality assessment
+```
 
-### Q: 网页文档浏览和文档爬取有什么区别？
+### 5. Caching
 
-**A:**
-- **`browse_documentation`**: 浏览单个文档页面，支持查询和导航
-- **`crawl_documentation`**: 递归爬取多个页面，生成完整的技能文件
-- 浏览适合查看特定内容，爬取适合生成完整文档技能
+```typescript
+const cache = new CacheManager();
 
-## 发布到 npm（开发者）
+// Save (7-day TTL)
+await cache.set(url, processed, guide);
 
-如果你想将这个包发布到 npm：
+// Retrieve
+const cached = await cache.get(url);
+if (cached && !forceRefresh) {
+  return cached;
+}
+```
 
-### 1. 准备发布
+**Cache location:** `~/.safe-coder/cache/`  
+**Cache format:** JSON files with base64-encoded URL as filename  
+**TTL:** 7 days (default)
 
-```bash
-# 确保已登录 npm
-npm login
+## Error Handling
 
-# 检查包名是否可用（如果已发布，需要更新版本号）
-npm view @gulibs/safe-coder
+### CLI Not Installed
 
-# 更新版本号
-npm version patch  # 或 minor, major
 ```
+Error: safe-coder-cli is not installed
 
-### 2. 发布
+Please install:
+  npm install -g @gulibs/safe-coder-cli
 
-```bash
-# 发布到 npm
-npm publish
-
-# 如果使用作用域包且是首次发布，需要添加访问权限
-npm publish --access public
+Current PATH checked:
+  /usr/local/bin
+  /usr/bin
+  /bin
+  ...
 ```
 
-### 3. 验证发布
+### CLI Execution Failed
 
-```bash
-# 检查包是否已发布
-npm view @gulibs/safe-coder
-
-# 测试安装
-npm install -g @gulibs/safe-coder
 ```
+Error: CLI process exited with code 1
 
-## 本地开发配置示例
-
-如果你在本地开发，可以创建一个测试配置：
+stderr output:
+  [Error] Failed to crawl: Network timeout
+  [Error] URL: https://example.com
 
-### 创建测试配置文件
+Possible solutions:
+  - Check network connectivity
+  - Try with --use-browser flag
+  - Increase timeout with --rate-limit
+```
 
-在项目根目录创建 `cursor-mcp-config.json`：
+### Cache Errors
 
-```json
-{
-  "mcpServers": {
-    "safe-coder": {
-      "command": "node",
-      "args": ["./dist/index.js"],
-      "env": {
-        "CACHE_TTL_MINUTES": "60",
-        "GITHUB_TOKEN": ""
-      }
-    }
-  }
-}
 ```
+Warning: Failed to cache results
+Error: EACCES: permission denied, mkdir '~/.safe-coder/cache'
 
-然后将此配置复制到 Cursor 的配置目录。
+Continuing without cache...
+```
 
-### 快速测试脚本
+Cache errors are non-fatal - the operation continues without caching.
 
-创建 `test-mcp.sh`（macOS/Linux）或 `test-mcp.bat`（Windows）：
+## Configuration
 
-```bash
-#!/bin/bash
-# test-mcp.sh
+### Cache Settings
 
-echo "构建项目..."
-npm run build
+Modify cache behavior by editing `src/cache/cache-manager.ts`:
 
-echo "测试 MCP 服务器..."
-node dist/index.js
+```typescript
+const cache = new CacheManager(
+  '/custom/cache/path',  // Default: ~/.safe-coder/cache
+  14                      // TTL in days (default: 7)
+);
 ```
 
-## 故障排除
+### CLI Arguments Mapping
 
-### 问题：Cursor 无法找到服务器
+| MCP Parameter | CLI Argument |
+|---------------|--------------|
+| `url` | `<url>` (positional) |
+| `maxPages` | `--max-pages <number>` |
+| `depth` | `--max-depth <number>` |
+| `workers` | `--workers <number>` |
+| `useBrowser` | (implicitly sets `--spa-strategy auto`) |
+| `browser` | `--browser <type>` |
+| `spaStrategy` | `--spa-strategy <type>` |
+| - | `--output-format json` (forced) |
 
-**解决方案：**
-1. 检查路径是否正确（使用绝对路径）
-2. 确保 `dist/index.js` 文件存在
-3. 检查 Node.js 是否在 PATH 中：`which node` 或 `where node`
+## Troubleshooting
 
-### 问题：服务器启动失败
+### MCP Server Not Appearing in Cursor
 
-**解决方案：**
-1. 检查依赖是否安装：`npm install`
-2. 检查构建是否成功：`npm run build`
-3. 查看错误日志
+1. **Check configuration file exists:**
+   ```bash
+   cat ~/Library/Application\ Support/Cursor/User/globalStorage/mcp.json
+   ```
 
-### 问题：工具无法使用
+2. **Verify JSON syntax is valid**
 
-**解决方案：**
-1. 确认服务器在 Cursor 中显示为已连接
-2. 检查 Cursor 版本是否支持 MCP
-3. 查看 Cursor 开发者工具中的错误信息
+3. **Check absolute path is correct:**
+   ```bash
+   node /absolute/path/to/safe-coder/dist/index.js
+   # Should not error
+   ```
 
-### 问题：权限错误
+4. **Restart Cursor completely**
 
-**解决方案：**
+### "CLI Not Found" Error
 
 ```bash
-# 确保 dist/index.js 有执行权限
-chmod +x dist/index.js
-```
+# Check if CLI is in PATH
+which safe-coder-cli
 
-## 许可证
-
-MIT
+# If not found, reinstall
+cd /path/to/safe-coder-cli
+npm link
 
-## 🎓 在大模型中使用MCP Server生成Agent Skill
-
-### 快速上手
-
-#### 步骤1：在Claude/Cursor中触发爬取
-
-**中文触发词：**
-```
-帮我爬取 https://react.dev 的文档并生成Agent Skill
+# Verify
+safe-coder-cli --version
 ```
 
-```
-使用并行爬取从 https://docs.example.com 生成技能，要快一点
-```
+### Slow Crawling
 
-```
-递归抓取 https://nextjs.org/docs 的文档，深度优先策略
-```
+- Reduce `maxPages` (e.g., 50 instead of 200)
+- Decrease `depth` (e.g., 2 instead of 3)
+- Increase `workers` (e.g., 3 for parallel crawling) - *requires CLI support*
 
-**英文触发词：**
-```
-Crawl https://react.dev and generate an agent skill
-```
+### Cache Not Working
 
-```
-Use parallel crawling to create a skill from https://docs.example.com
-```
-
-```
-Recursive crawl https://nextjs.org/docs with DFS strategy
-```
-
-#### 步骤2：配置爬取参数
-
-Claude/Cursor会自动调用`crawl_documentation`工具，你可以在对话中指定参数：
-
-**基础爬取：**
-```
-爬取 https://react.dev/docs，最多50页
-```
+```bash
+# Check cache directory
+ls -la ~/.safe-coder/cache/
 
-**快速爬取（推荐）：**
-```
-爬取 https://react.dev，使用5个并发worker，最多200页
-```
+# Permissions issue?
+chmod 755 ~/.safe-coder/cache/
 
-**深度研究：**
-```
-使用DFS策略深入爬取 https://docs.example.com，深度限制为6层
+# Clear and rebuild
+rm -rf ~/.safe-coder/cache/
+# Cache will recreate on next crawl
 ```
 
-**大规模爬取：**
-```
-爬取 https://large-docs.com，最多1000页，启用断点续传每50页保存
-```
+## Development
 
-### 使用场景
+### Project Structure
 
-#### 场景1：快速探索新技术栈
-```
-帮我爬取 Svelte 的官方文档，快速生成一个技能
 ```
+safe-coder/
+├── src/
+│   ├── index.ts                     # Entry point
+│   ├── server/
+│   │   └── safe-coder-mcp.ts        # MCP server class
+│   ├── executor/
+│   │   ├── dependency-checker.ts    # Check CLI installation
+│   │   └── cli-executor.ts          # Spawn CLI process
+│   ├── processor/
+│   │   ├── content-processor.ts     # Analyze content
+│   │   └── guide-generator.ts       # Generate SKILL guidance
+│   ├── cache/
+│   │   └── cache-manager.ts         # Cache management
+│   └── tools/
+│       ├── crawl-documentation.ts   # Main MCP tool
+│       ├── cache-tools.ts           # Cache MCP tools
+│       └── index.ts                 # Tool exports
+├── dist/                            # Compiled output
+├── tsconfig.json
+├── package.json
+└── README.md
+```
+
+### Build and Test
 
-**自动参数：**
-- workers: 3（快速）
-- maxPages: 50（快速探索）
-- crawlStrategy: bfs（全面覆盖）
-
-#### 场景2：深入学习框架
-```
-深入爬取 Vue 3 的文档，我要完整理解它的 API
-```
+```bash
+# Install dependencies
+npm install
 
-**自动参数：**
-- crawlStrategy: dfs（深入学习）
-- maxDepth: 5（深入层级）
-- workers: 5（加速）
-- maxPages: 200（完整覆盖）
+# Build
+npm run build
 
-#### 场景3：大型文档站点
-```
-爬取 MDN Web Docs 的 JavaScript 部分，分多次进行，支持断点恢复
-```
+# Watch mode
+npm run build -- --watch
 
-**自动参数：**
-- workers: 8（大规模）
-- maxPages: 1000
-- checkpoint: { enabled: true, interval: 50 }
+# Test locally
+node dist/index.js
 
-#### 场景4：恢复中断的爬取
+# Test with MCP Inspector (if available)
+npx @modelcontextprotocol/inspector node dist/index.js
 ```
-上次爬取中断了，从断点继续爬取 https://large-docs.com
-```
-
-**自动参数：**
-- resume: true
-- checkpoint: { enabled: true }
-
-### 生成的Agent Skill格式
 
-爬取完成后，会生成标准的Claude Agent Skill格式：
+### Running with Debug Output
 
-```
-SKILL.md                    # 主技能文件
-├── 技能元数据（YAML frontmatter）
-├── When to Use This Skill  # 使用场景
-├── Core Concepts          # 核心概念
-├── API Reference         # API参考
-├── Examples              # 示例代码
-└── Reference Files       # 引用文件列表
-
-references/               # 引用文件目录
-├── page-1.md
-├── page-2.md
-└── ...
+```typescript
+// In src/index.ts
+console.error('[Debug] MCP Server starting...');
+console.error('[Debug] Available tools:', server.listTools());
 ```
 
-### 技能质量指标
+MCP uses stdio, so:
+- `stdout` → MCP protocol messages (JSON-RPC)
+- `stderr` → Debug/log output (visible in Cursor logs)
 
-系统会自动评估生成的Skill质量：
+## Roadmap / Future Enhancements
 
-| 指标 | 说明 | 优秀标准 |
-|-----|-----|---------|
-| **内容充足性** | 每页内容长度 | > 100字符/页 |
-| **结构完整性** | 标题、章节组织 | 至少1个标题/页 |
-| **内容多样性** | URL路径和主题分布 | diversity > 0.7 |
-| **API覆盖度** | 代码示例比例 | coverage > 0.5 |
+### Planned Features
 
-### 使用生成的Skill
+1. **Expose More CLI Parameters**
+   - [ ] `strategy` (bfs/dfs)
+   - [ ] `checkpoint`, `resume`
+   - [ ] `rateLimit`, `maxRetries`
+   - [ ] `includePaths`, `excludePaths`
 
-#### 方法1：直接在对话中使用
+2. **Direct File Creation Tool**
+   - [ ] `save_skill` tool to create SKILL.md directly
+   - [ ] Automatic filename generation
+   - [ ] Default location management
 
-生成的Skill会自动出现在Claude的技能列表中，你可以直接引用：
+3. **Enhanced Processing**
+   - [ ] Semantic analysis of content
+   - [ ] Automatic category detection
+   - [ ] Code example quality scoring
+   - [ ] Cross-reference detection
 
-```
-根据我刚生成的React技能，帮我写一个自定义Hook
-```
-
-#### 方法2：保存为文件
+4. **Better Caching**
+   - [ ] Configurable TTL per URL
+   - [ ] Cache compression
+   - [ ] Partial cache updates
+   - [ ] Cache analytics
 
-如果指定了`outputDir`，Skill会保存为文件：
+## Contributing
 
-```
-爬取并保存到 ./skills 目录，文件名为 react-docs
-```
+This package is part of the Safe Coder project. Contributions welcome!
 
-生成文件：
-- `./skills/react-docs.md` - Skill内容
-- `./skills/react-docs.metadata.json` - 元数据
+### Development Workflow
 
-#### 方法3：分享给团队
+1. Fork and clone both `safe-coder` and `safe-coder-cli`
+2. Make changes
+3. Build and test locally
+4. Submit pull request
 
-将生成的SKILL.md文件放入项目的`.claude/skills/`目录，团队成员都可使用：
+### Testing
 
 ```bash
-# 复制到项目技能目录
-cp output/react-docs.md .claude/skills/
+# Unit tests (when implemented)
+npm test
 
-# 提交到版本控制
-git add .claude/skills/react-docs.md
-git commit -m "Add React documentation skill"
-```
+# Integration test
+# 1. Build both packages
+cd safe-coder-cli && npm run build && npm link
+cd ../safe-coder && npm run build && npm link
 
-### 常见问题
-
-#### Q: 如何选择爬取策略？
-**A:**
-- **BFS（广度优先）**：适合扁平结构、需要全面覆盖的文档
-- **DFS（深度优先）**：适合层级结构、需要深入理解的文档
-
-#### Q: workers设置多少合适？
-**A:**
-- 小型站点（<50页）：workers: 2-3
-- 中型站点（50-200页）：workers: 3-5
-- 大型站点（>200页）：workers: 5-8
-
-#### Q: 什么时候需要启用断点？
-**A:**
-- 爬取页面超过200页
-- 网络不稳定
-- 需要分批次爬取
-
-#### Q: 如何提高爬取速度？
-**A:**
-1. 增加workers数量（推荐5-8个）
-2. 降低rateLimit（200-300ms）
-3. 确保站点有llms.txt（自动检测）
-
-#### Q: 生成的Skill质量不够怎么办？
-**A:**
-1. 增加maxPages（建议200+）
-2. 调整maxDepth（建议3-5）
-3. 使用includePaths精确指定路径
-4. 查看日志中的质量指标建议
-
-### 性能提示
-
-**🚀 极速模式（适合快速探索）：**
-```json
-{
-  "workers": 5,
-  "maxPages": 50,
-  "rateLimit": 200,
-  "crawlStrategy": "bfs"
-}
+# 2. Configure in Cursor
+# 3. Test end-to-end
 ```
 
-**🎯 深度模式（适合完整学习）：**
-```json
-{
-  "workers": 5,
-  "maxPages": 300,
-  "maxDepth": 5,
-  "crawlStrategy": "dfs",
-  "checkpoint": { "enabled": true }
-}
-```
+## License
 
-**⚡ 超快模式（适合有llms.txt的站点）：**
-```json
-{
-  "workers": 8,
-  "skipLlmsTxt": false,
-  "rateLimit": 200
-}
-```
+MIT
 
-### 完整文档
+## Related Projects
 
-- **快速上手指南**：项目中的快速开始文档
-- **详细使用说明**：`docs/ENHANCED_CRAWLING.md`
-- **实施技术细节**：`IMPLEMENTATION_SUMMARY.md`
-- **原始文档爬取指南**：`docs/DOC_CRAWLER_USAGE.md`
+- **@gulibs/safe-coder-cli** - Standalone documentation crawler
+- **Cursor** - AI-powered code editor
+- **Model Context Protocol (MCP)** - Protocol for AI tool integration
 
----
+## Support
 
-## 贡献
+Issues: https://github.com/gulibs/safe-coder/issues  
+Discord: [Link TBD]
 
-欢迎提交 Issue 和 Pull Request！
+---
 
-基于 [Skill_Seekers](examples/Skill_Seekers/) 项目的优秀实践，我们实现了完整对标并超越的TypeScript版本。
+**Safe Coder** - Bringing documentation intelligence to your AI coding assistant.