mcp-probe-kit 3.0.16 → 3.0.17

package/README.md

@@ -1,66 +1,68 @@
-<div align="center">
-  <img src="docs/assets/logo.png" alt="知时MCP Logo" width="160"/>
-  <h1>知时MCP | mcp-probe-kit</h1>
-  <p><strong>Know the Context, Feed the Moment.</strong></p>
-  <p>
-    <code>Introspection</code> · <code>Context Hydration</code> · <code>Delegated Orchestration</code>
-  </p>
-</div>
-
----
-
-<!-- mcp-name: io.github.mybolide/mcp-probe-kit -->
-
-> **Talk is cheap, show me the Context.**
-> 
-> mcp-probe-kit is a protocol-level toolkit designed for developers who want AI to truly understand their project's intent. It's not just a collection of 22 tools—it's a context-aware system that helps AI agents grasp what you're building.
-
-**Languages**: [English](README.md) | [简体中文](i18n/README.zh-CN.md) | [日本語](i18n/README.ja-JP.md) | [한국어](i18n/README.ko-KR.md) | [Español](i18n/README.es-ES.md) | [Français](i18n/README.fr-FR.md) | [Deutsch](i18n/README.de-DE.md) | [Português (BR)](i18n/README.pt-BR.md)
-
-[![npm version](https://img.shields.io/npm/v/mcp-probe-kit.svg)](https://www.npmjs.com/package/mcp-probe-kit)
-[![npm downloads](https://img.shields.io/npm/dm/mcp-probe-kit.svg)](https://www.npmjs.com/package/mcp-probe-kit)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![GitHub stars](https://img.shields.io/github/stars/mybolide/mcp-probe-kit.svg)](https://github.com/mybolide/mcp-probe-kit/stargazers)
-
-> 🚀 AI-Powered Complete Development Toolkit - Covering the Entire Development Lifecycle
-
-A powerful MCP (Model Context Protocol) server providing **22 tools** covering the complete workflow from product analysis to final release (Requirements → Design → Development → Quality → Release), all tools support **structured output**.
-
-**🎉 v3.0 Major Update**: Streamlined tool count, focus on core competencies, eliminate choice paralysis, let AI do more native work
-
-**Supports All MCP Clients**: Cursor, Claude Desktop, Cline, Continue, and more
-
-**Protocol Version**: MCP 2025-11-25 · **SDK**: @modelcontextprotocol/sdk 1.27.1
-
----
-
-## 📚 Complete Documentation
-
-**👉 [https://mcp-probe-kit.bytezonex.com](https://mcp-probe-kit.bytezonex.com/)**
-
-- [Quick Start](https://mcp-probe-kit.bytezonex.com/pages/getting-started.html) - Setup in 5 minutes
-- [All Tools](https://mcp-probe-kit.bytezonex.com/pages/all-tools.html) - Complete list of 22 tools
-- [Best Practices](https://mcp-probe-kit.bytezonex.com/pages/examples.html) - Full development workflow guide
-- [v3.0 Migration Guide](https://mcp-probe-kit.bytezonex.com/pages/migration.html) - Upgrade from v2.x to v3.0
-
----
-
-## ✨ Core Features
-
-### 📦 22 Tools
-
-- **🔄 Workflow Orchestration** (6 tools) - One-click complex development workflows
-  - `start_feature`, `start_bugfix`, `start_onboard`, `start_ui`, `start_product`, `start_ralph`
+<div align="center">
+  <img src="docs/assets/logo.png" alt="知时MCP Logo" width="160"/>
+  <h1>知时MCP | mcp-probe-kit</h1>
+  <p><strong>Know the Context, Feed the Moment.</strong></p>
+  <p>
+    <code>Introspection</code> · <code>Context Hydration</code> · <code>Delegated Orchestration</code>
+  </p>
+</div>
+
+---
+
+<!-- mcp-name: io.github.mybolide/mcp-probe-kit -->
+
+> **Talk is cheap, show me the Context.**
+> 
+> mcp-probe-kit is a protocol-level toolkit designed for developers who want AI to truly understand their project's intent. It's not just a collection of 28 tools—it's a context-aware system that helps AI agents grasp what you're building.
+
+**Languages**: [English](README.md) | [简体中文](i18n/README.zh-CN.md) | [日本語](i18n/README.ja-JP.md) | [한국어](i18n/README.ko-KR.md) | [Español](i18n/README.es-ES.md) | [Français](i18n/README.fr-FR.md) | [Deutsch](i18n/README.de-DE.md) | [Português (BR)](i18n/README.pt-BR.md)
+
+[![npm version](https://img.shields.io/npm/v/mcp-probe-kit.svg)](https://www.npmjs.com/package/mcp-probe-kit)
+[![npm downloads](https://img.shields.io/npm/dm/mcp-probe-kit.svg)](https://www.npmjs.com/package/mcp-probe-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub stars](https://img.shields.io/github/stars/mybolide/mcp-probe-kit.svg)](https://github.com/mybolide/mcp-probe-kit/stargazers)
+
+> 🚀 AI-Powered Complete Development Toolkit - Covering the Entire Development Lifecycle
+
+A powerful MCP (Model Context Protocol) server providing **28 tools** covering the complete workflow from product analysis to final release (Requirements → Design → Development → Quality → Release), all tools support **structured output**.
+
+**🎉 v3.0 Major Update**: Streamlined tool count, focus on core competencies, eliminate choice paralysis, let AI do more native work
+
+**Supports All MCP Clients**: Cursor, Claude Desktop, Cline, Continue, and more
+
+**Protocol Version**: MCP 2025-11-25 · **SDK**: @modelcontextprotocol/sdk 1.27.1
+
+---
+
+## 📚 Complete Documentation
+
+**👉 [https://mcp-probe-kit.bytezonex.com](https://mcp-probe-kit.bytezonex.com/)**
+
+- [Quick Start](https://mcp-probe-kit.bytezonex.com/pages/getting-started.html) - Setup in 5 minutes
+- [All Tools](https://mcp-probe-kit.bytezonex.com/pages/all-tools.html) - Complete list of 28 tools
+- [Best Practices](https://mcp-probe-kit.bytezonex.com/pages/examples.html) - Full development workflow guide
+- [v3.0 Migration Guide](https://mcp-probe-kit.bytezonex.com/pages/migration.html) - Upgrade from v2.x to v3.0
+
+---
+
+## ✨ Core Features
+
+### 📦 28 Tools
+
+- **🔄 Workflow Orchestration** (6 tools) - One-click complex development workflows
+  - `start_feature`, `start_bugfix`, `start_onboard`, `start_ui`, `start_product`, `start_ralph`
 - **🔍 Code Analysis** (4 tools) - Code quality, refactoring, and graph insight
   - `code_review`, `code_insight`, `fix_bug`, `refactor`
-- **📝 Git Tools** (2 tools) - Git commits and work reports
-  - `gencommit`, `git_work_report`
-- **⚡ Code Generation** (1 tool) - Test generation
-  - `gentest`
+- **📝 Git Tools** (2 tools) - Git commits and work reports
+  - `gencommit`, `git_work_report`
+- **⚡ Code Generation** (1 tool) - Test generation
+  - `gentest`
 - **📦 Project Management** (6 tools) - Project initialization and requirements management
   - `init_project`, `init_project_context`, `add_feature`, `estimate`, `interview`, `ask_user`
-- **🎨 UI/UX Tools** (3 tools) - Design systems and data synchronization
+- **🎨 UI/UX Utilities** (3 tools) - Design systems and UI data synchronization
   - `ui_design_system`, `ui_search`, `sync_ui_data`
+- **🧠 Memory & Cursor History** (6 tools) - Reusable asset memory and local Cursor conversation retrieval
+  - `read_memory_asset`, `memorize_asset`, `scan_and_extract_patterns`, `cursor_list_conversations`, `cursor_search_conversations`, `cursor_read_conversation`
 
 ### 🧠 Code Graph Bridge (GitNexus)
 
@@ -81,7 +83,97 @@ A powerful MCP (Model Context Protocol) server providing **22 tools** covering t
 - `start_bugfix` defaults to Toyota-style TBP 8-step root-cause analysis before repair
 - `fix_bug` returns a structured TBP skeleton covering phenomenon, timeline, ruled-out paths, boundary, root cause, evidence, and repair plan
 - This makes bug, regression, anomaly, and "why didn't it work" investigations follow analyze-first discipline instead of patching symptoms
-
+
+### 🧠 Memory Retrieval and Cursor History
+
+- Memory tools use **Qdrant** as the vector database backend
+- Embedding service supports two modes:
+  - `ollama`
+  - `openai-compatible`
+- Cursor history tools read the local Cursor database directly through Node.js, without Python bridge
+- Cursor history currently supports:
+  - Windows: `%APPDATA%\\Cursor\\User\\globalStorage\\state.vscdb`
+  - macOS: `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb`
+  - Linux: `~/.config/Cursor/User/globalStorage/state.vscdb`
+
+**Memory tools:**
+- `memorize_asset` - Persist reusable code/spec/pattern assets into vector memory
+- `read_memory_asset` - Read full asset content by `asset_id`
+- `scan_and_extract_patterns` - Extract reusable patterns from code/file/directory before deciding whether to persist
+
+**Memory backend and embedding configuration:**
+- Vector database: **Qdrant**
+- Recommended local setup: `Qdrant + Ollama`
+- Supported embedding providers:
+  - `ollama`
+  - `openai-compatible`
+- Required environment variables for memory write/search:
+  - `MEMORY_QDRANT_URL`
+  - `MEMORY_EMBEDDING_URL`
+  - `MEMORY_EMBEDDING_MODEL`
+- Optional environment variables:
+  - `MEMORY_QDRANT_API_KEY`
+  - `MEMORY_QDRANT_COLLECTION` (default: `mcp_probe_memory`)
+  - `MEMORY_EMBEDDING_API_KEY`
+  - `MEMORY_EMBEDDING_PROVIDER` (`ollama` by default)
+  - `MEMORY_SEARCH_LIMIT` (default: `3`)
+  - `MEMORY_SUMMARY_MAX_CHARS` (default: `280`)
+- Behavior notes:
+  - Read-only memory access only requires `MEMORY_QDRANT_URL`
+  - Memory write is enabled only when `MEMORY_QDRANT_URL`, `MEMORY_EMBEDDING_URL`, and `MEMORY_EMBEDDING_MODEL` are all configured
+  - The Qdrant collection is auto-created on first write, and vector dimension is inferred from the first embedding response
+
+**Recommended local memory setup (Qdrant + Ollama):**
+```bash
+docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant
+ollama pull nomic-embed-text
+```
+
+```json
+{
+  "mcpServers": {
+    "mcp-probe-kit": {
+      "command": "npx",
+      "args": ["-y", "mcp-probe-kit@latest"],
+      "env": {
+        "MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
+        "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
+        "MEMORY_EMBEDDING_PROVIDER": "ollama",
+        "MEMORY_EMBEDDING_URL": "http://127.0.0.1:11434/api/embeddings",
+        "MEMORY_EMBEDDING_MODEL": "nomic-embed-text",
+        "MEMORY_SEARCH_LIMIT": "3",
+        "MEMORY_SUMMARY_MAX_CHARS": "280"
+      }
+    }
+  }
+}
+```
+
+**OpenAI-compatible embedding setup:**
+```json
+{
+  "mcpServers": {
+    "mcp-probe-kit": {
+      "command": "npx",
+      "args": ["-y", "mcp-probe-kit@latest"],
+      "env": {
+        "MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
+        "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
+        "MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
+        "MEMORY_EMBEDDING_URL": "https://your-embedding-endpoint/v1/embeddings",
+        "MEMORY_EMBEDDING_API_KEY": "your-api-key",
+        "MEMORY_EMBEDDING_MODEL": "text-embedding-3-small"
+      }
+    }
+  }
+}
+```
+
+**Cursor history tools:**
+- `cursor_list_conversations` - List recent local Cursor conversations by title/workspace
+- `cursor_search_conversations` - Search local Cursor history by keyword or request id
+- `cursor_read_conversation` - Read a single local Cursor conversation timeline by `composer_id`
+
 ### 🎯 Structured Output
 
 Core and orchestration tools support **structured output**, returning machine-readable JSON data, improving AI parsing accuracy, supporting tool chaining and state tracking.
@@ -101,119 +193,119 @@ Core and orchestration tools support **structured output**, returning machine-re
 - Optional extensions capability switch: enable with `MCP_ENABLE_EXTENSIONS_CAPABILITY=1`
 - Optional MCP Apps resource output for UI tools: enable with `MCP_ENABLE_UI_APPS=1`
 - UI tools can expose preview resources via `ui://...` and response `_meta.ui.resourceUri`
-
-### 🧭 Delegated Orchestration Protocol
-
-All `start_*` orchestration tools return an **execution plan** in `structuredContent.metadata.plan`.  
-AI needs to **call tools step by step and persist files**, rather than the tool executing internally.
-
-**Plan Schema (Core Fields)**:
-```json
-{
-  "mode": "delegated",
-  "steps": [
-    {
-      "id": "spec",
-      "tool": "add_feature",
-      "args": { "feature_name": "user-auth", "description": "User authentication feature" },
-      "outputs": ["docs/specs/user-auth/requirements.md"]
-    }
-  ]
-}
-```
-
-**Field Description**:
-- `mode`: Fixed as `delegated`
-- `steps`: Array of execution steps
-- `tool`: Tool name (e.g. `add_feature`)
-- `action`: Manual action description when no tool (e.g. `update_project_context`)
-- `args`: Tool parameters
-- `outputs`: Expected artifacts
-- `when/dependsOn/note`: Optional conditions and notes
-
-### 🧩 Structured Output Field Specification (Key Fields)
-
-Both orchestration and atomic tools return `structuredContent`, common fields:
-- `summary`: One-line summary
-- `status`: Status (pending/success/failed/partial)
-- `steps`: Execution steps (orchestration tools)
-- `artifacts`: Artifact list (path + purpose)
-- `metadata.plan`: Delegated execution plan (only start_*)
-- `specArtifacts`: Specification artifacts (start_feature)
-- `estimate`: Estimation results (start_feature / estimate)
-
-### 🧠 Requirements Clarification Mode (Requirements Loop)
-
-When requirements are unclear, use `requirements_mode=loop` in `start_feature / start_bugfix / start_ui`.  
-This mode performs 1-2 rounds of structured clarification before entering spec/fix/UI execution.
-
-**Example:**
-```json
-{
-  "feature_name": "user-auth",
-  "description": "User authentication feature",
-  "requirements_mode": "loop",
-  "loop_max_rounds": 2,
-  "loop_question_budget": 5
-}
-```
-
-### 🧩 Template System (Regular Model Friendly)
-
-`add_feature` supports template profiles, default `auto` auto-selects: prefers `guided` when requirements are incomplete (includes detailed filling rules and checklists), selects `strict` when requirements are complete (more compact structure, suitable for high-capability models or archival scenarios).
-
-**Example:**
-```json
-{
-  "description": "Add user authentication feature",
-  "template_profile": "auto"
-}
-```
-
-**Applicable Tools**:
-- `start_feature` passes `template_profile` to `add_feature`
-- `start_bugfix` / `start_ui` also support `template_profile` for controlling guidance strength (auto/guided/strict)
-
-**Template Profile Strategy**:
-- `guided`: Less/incomplete requirements info, regular model priority
-- `strict`: Requirements structured, prefer more compact guidance
-- `auto`: Default recommendation, auto-selects guided/strict
-
-### 🔄 Workflow Orchestration
-
-6 intelligent orchestration tools that automatically combine multiple basic tools for one-click complex development workflows:
-- `start_feature` - New feature development (Requirements → Design → Estimation)
+
+### 🧭 Delegated Orchestration Protocol
+
+All `start_*` orchestration tools return an **execution plan** in `structuredContent.metadata.plan`.  
+AI needs to **call tools step by step and persist files**, rather than the tool executing internally.
+
+**Plan Schema (Core Fields)**:
+```json
+{
+  "mode": "delegated",
+  "steps": [
+    {
+      "id": "spec",
+      "tool": "add_feature",
+      "args": { "feature_name": "user-auth", "description": "User authentication feature" },
+      "outputs": ["docs/specs/user-auth/requirements.md"]
+    }
+  ]
+}
+```
+
+**Field Description**:
+- `mode`: Fixed as `delegated`
+- `steps`: Array of execution steps
+- `tool`: Tool name (e.g. `add_feature`)
+- `action`: Manual action description when no tool (e.g. `update_project_context`)
+- `args`: Tool parameters
+- `outputs`: Expected artifacts
+- `when/dependsOn/note`: Optional conditions and notes
+
+### 🧩 Structured Output Field Specification (Key Fields)
+
+Both orchestration and atomic tools return `structuredContent`, common fields:
+- `summary`: One-line summary
+- `status`: Status (pending/success/failed/partial)
+- `steps`: Execution steps (orchestration tools)
+- `artifacts`: Artifact list (path + purpose)
+- `metadata.plan`: Delegated execution plan (only start_*)
+- `specArtifacts`: Specification artifacts (start_feature)
+- `estimate`: Estimation results (start_feature / estimate)
+
+### 🧠 Requirements Clarification Mode (Requirements Loop)
+
+When requirements are unclear, use `requirements_mode=loop` in `start_feature / start_bugfix / start_ui`.  
+This mode performs 1-2 rounds of structured clarification before entering spec/fix/UI execution.
+
+**Example:**
+```json
+{
+  "feature_name": "user-auth",
+  "description": "User authentication feature",
+  "requirements_mode": "loop",
+  "loop_max_rounds": 2,
+  "loop_question_budget": 5
+}
+```
+
+### 🧩 Template System (Regular Model Friendly)
+
+`add_feature` supports template profiles, default `auto` auto-selects: prefers `guided` when requirements are incomplete (includes detailed filling rules and checklists), selects `strict` when requirements are complete (more compact structure, suitable for high-capability models or archival scenarios).
+
+**Example:**
+```json
+{
+  "description": "Add user authentication feature",
+  "template_profile": "auto"
+}
+```
+
+**Applicable Tools**:
+- `start_feature` passes `template_profile` to `add_feature`
+- `start_bugfix` / `start_ui` also support `template_profile` for controlling guidance strength (auto/guided/strict)
+
+**Template Profile Strategy**:
+- `guided`: Less/incomplete requirements info, regular model priority
+- `strict`: Requirements structured, prefer more compact guidance
+- `auto`: Default recommendation, auto-selects guided/strict
+
+### 🔄 Workflow Orchestration
+
+6 intelligent orchestration tools that automatically combine multiple basic tools for one-click complex development workflows:
+- `start_feature` - New feature development (Requirements → Design → Estimation)
 - `start_bugfix` - Bug fixing (TBP 8-step RCA → Fix → Testing)
-- `start_onboard` - Project onboarding (Generate project context docs)
-- `start_ui` - UI development (Design system → Components → Code)
-- `start_product` - Product design (PRD → Prototype → Design system → HTML)
-- `start_ralph` - Ralph Loop (Iterative development until goal completion)
-
-### 🚀 Product Design Workflow
-
-`start_product` is a complete product design orchestration tool, from requirements to interactive prototype:
-
-**Workflow:**
-1. **Requirements Analysis** - Generate standard PRD (product overview, feature requirements, page list)
-2. **Prototype Design** - Generate detailed prototype docs for each page
-3. **Design System** - Generate design specifications based on product type
-4. **HTML Prototype** - Generate interactive prototype viewable in browser
-5. **Project Context** - Auto-update project documentation
-
-**Structured Output Additions**:
-- `start_product.structuredContent.artifacts`: Artifact list (PRD, prototypes, design system, etc.)
-- `interview.structuredContent.mode`: `usage` / `questions` / `record`
-
-### 🎨 UI/UX Pro Max
-
-3 UI/UX tools with `start_ui` as the unified entry point:
-- `start_ui` - One-click UI development (supports intelligent mode) (orchestration tool)
-- `ui_design_system` - Intelligent design system generation
-- `ui_search` - UI/UX data search (BM25 algorithm)
-- `sync_ui_data` - Sync latest UI/UX data locally
-
-**Note**: `start_ui` automatically calls `ui_design_system` and `ui_search`, you don't need to call them separately.
-
+- `start_onboard` - Project onboarding (Generate project context docs)
+- `start_ui` - UI development (Design system → Components → Code)
+- `start_product` - Product design (PRD → Prototype → Design system → HTML)
+- `start_ralph` - Ralph Loop (Iterative development until goal completion)
+
+### 🚀 Product Design Workflow
+
+`start_product` is a complete product design orchestration tool, from requirements to interactive prototype:
+
+**Workflow:**
+1. **Requirements Analysis** - Generate standard PRD (product overview, feature requirements, page list)
+2. **Prototype Design** - Generate detailed prototype docs for each page
+3. **Design System** - Generate design specifications based on product type
+4. **HTML Prototype** - Generate interactive prototype viewable in browser
+5. **Project Context** - Auto-update project documentation
+
+**Structured Output Additions**:
+- `start_product.structuredContent.artifacts`: Artifact list (PRD, prototypes, design system, etc.)
+- `interview.structuredContent.mode`: `usage` / `questions` / `record`
+
+### 🎨 UI/UX Pro Max
+
+4 UI/UX tools with `start_ui` as the unified entry point:
+- `start_ui` - One-click UI development (supports intelligent mode) (orchestration tool)
+- `ui_design_system` - Intelligent design system generation
+- `ui_search` - UI/UX data search (BM25 algorithm)
+- `sync_ui_data` - Sync latest UI/UX data locally
+
+**Note**: `start_ui` automatically calls `ui_design_system` and `ui_search`, you don't need to call them separately.
+
 **Inspiration:**
 - [ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) - UI/UX design system philosophy
 - [json-render](https://github.com/vercel-labs/json-render) - JSON template rendering engine
@@ -224,14 +316,14 @@ This mode performs 1-2 rounds of structured clarification before entering spec/f
 - If some skills are missing, workflow continues with MCP main plan and marks unavailable skills in metadata.
 
 **Why use `sync_ui_data`?**
-
-Our `start_ui` tool relies on a rich UI/UX database (colors, icons, charts, components, design patterns, etc.) to generate high-quality design systems and code. This data comes from npm package [uipro-cli](https://www.npmjs.com/package/uipro-cli), including:
-- 🎨 Color schemes (mainstream brand colors, color palettes)
-- 🔣 Icon libraries (React Icons, Heroicons, etc.)
-- 📊 Chart components (Recharts, Chart.js, etc.)
-- 🎯 Landing page templates (SaaS, e-commerce, government, etc.)
-- 📐 Design specifications (spacing, fonts, shadows, etc.)
-
+
+Our `start_ui` tool relies on a rich UI/UX database (colors, icons, charts, components, design patterns, etc.) to generate high-quality design systems and code. This data comes from npm package [uipro-cli](https://www.npmjs.com/package/uipro-cli), including:
+- 🎨 Color schemes (mainstream brand colors, color palettes)
+- 🔣 Icon libraries (React Icons, Heroicons, etc.)
+- 📊 Chart components (Recharts, Chart.js, etc.)
+- 🎯 Landing page templates (SaaS, e-commerce, government, etc.)
+- 📐 Design specifications (spacing, fonts, shadows, etc.)
+
 **Data Sync Strategy:**
 1. **Embedded Data**: Synced at build time, works offline
 2. **Background Auto Sync**: Downloads latest data to `~/.mcp-probe-kit/ui-ux-data/` without changing current session output
@@ -239,106 +331,216 @@ Our `start_ui` tool relies on a rich UI/UX database (colors, icons, charts, comp
 4. **Manual Sync**: Use `sync_ui_data` to force refresh cache immediately (still applies next start by default)
 
 This ensures `start_ui` can generate professional-grade UI code even offline.
-
-### 🎤 Requirements Interview
-
-2 interview tools to clarify requirements before development:
-- `interview` - Structured requirements interview
-- `ask_user` - AI proactive questioning
-
----
-
-## 🧭 Tool Selection Guide
-
-### When to use orchestration tools vs individual tools?
-
-**Use orchestration tools (start_*) when:**
-- ✅ Need complete workflow (multiple steps)
-- ✅ Want to automate multiple tasks
-- ✅ Need to generate multiple artifacts (docs, code, tests, etc.)
-
-**Use individual tools when:**
-- ✅ Only need specific functionality
-- ✅ Already have project context docs
-- ✅ Need more fine-grained control
-
-### Common Scenario Selection
-
-| Scenario | Recommended Tool | Reason |
-|---------|-----------------|--------|
-| Develop new feature (complete flow) | `start_feature` | Auto-complete: spec→estimation |
-| Only need feature spec docs | `add_feature` | More lightweight, only generates docs |
+
+### 🎤 Requirements Interview
+
+2 interview tools to clarify requirements before development:
+- `interview` - Structured requirements interview
+- `ask_user` - AI proactive questioning
+
+---
+
+## 🧭 Tool Selection Guide
+
+### When to use orchestration tools vs individual tools?
+
+**Use orchestration tools (start_*) when:**
+- ✅ Need complete workflow (multiple steps)
+- ✅ Want to automate multiple tasks
+- ✅ Need to generate multiple artifacts (docs, code, tests, etc.)
+
+**Use individual tools when:**
+- ✅ Only need specific functionality
+- ✅ Already have project context docs
+- ✅ Need more fine-grained control
+
+### Common Scenario Selection
+
+| Scenario | Recommended Tool | Reason |
+|---------|-----------------|--------|
+| Develop new feature (complete flow) | `start_feature` | Auto-complete: spec→estimation |
+| Only need feature spec docs | `add_feature` | More lightweight, only generates docs |
 | Fix bug (complete flow) | `start_bugfix` | Root-cause-first flow: TBP RCA → fix → test |
 | Only need bug analysis | `fix_bug` | TBP 8-step RCA only, without full orchestration |
-| Generate design system | `ui_design_system` | Directly generate design specs |
-| Develop UI components | `start_ui` | Complete flow: design→components→code |
-| Product design (requirements to prototype) | `start_product` | One-click: PRD→prototype→HTML |
-| One-sentence requirement analysis | `init_project` | Generate complete project spec docs |
-| Project onboarding docs | `init_project_context` | Generate tech stack/architecture/conventions |
-
----
-
-## 🚀 Quick Start
-
-### Method 1: Use directly with npx (Recommended)
-
-No installation needed, use the latest version directly.
-
-#### Cursor / Cline Configuration
-
-**Config file location:**
-- Windows: `%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
-- macOS: `~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
-- Linux: `~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
-
-**Config content:**
-```json
-{
-  "mcpServers": {
-    "mcp-probe-kit": {
-      "command": "npx",
-      "args": ["mcp-probe-kit@latest"]
-    }
-  }
-}
-```
-
-#### Claude Desktop Configuration
-
-**Config file location:**
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Linux: `~/.config/Claude/claude_desktop_config.json`
-
-**Config content:**
-```json
-{
-  "mcpServers": {
-    "mcp-probe-kit": {
-      "command": "npx",
-      "args": ["-y", "mcp-probe-kit@latest"]
-    }
-  }
-}
-```
-
+| Generate design system | `ui_design_system` | Directly generate design specs |
+| Develop UI components | `start_ui` | Complete flow: design→components→code |
+| Product design (requirements to prototype) | `start_product` | One-click: PRD→prototype→HTML |
+| One-sentence requirement analysis | `init_project` | Generate complete project spec docs |
+| Project onboarding docs | `init_project_context` | Generate tech stack/architecture/conventions |
+
+---
+
+## 🚀 Quick Start
+
+### Method 1: Use directly with npx (Recommended)
+
+No installation needed, use the latest version directly.
+
+#### Cursor / Cline Configuration
+
+**Config file location:**
+- Windows: `%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
+- macOS: `~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
+- Linux: `~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
+
+**Config content:**
+```json
+{
+  "mcpServers": {
+    "mcp-probe-kit": {
+      "command": "npx",
+      "args": ["mcp-probe-kit@latest"]
+    }
+  }
+}
+```
+
+#### Claude Desktop Configuration
+
+**Config file location:**
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+**Config content:**
+```json
+{
+  "mcpServers": {
+    "mcp-probe-kit": {
+      "command": "npx",
+      "args": ["-y", "mcp-probe-kit@latest"]
+    }
+  }
+}
+```
+
 ### Method 2: Global Installation
 
 ```bash
 npm install -g mcp-probe-kit
-```
-
-Use in config file:
-```json
-{
-  "mcpServers": {
-    "mcp-probe-kit": {
-      "command": "mcp-probe-kit"
-    }
-  }
+```
+
+Use in config file:
+```json
+{
+  "mcpServers": {
+    "mcp-probe-kit": {
+      "command": "mcp-probe-kit"
+    }
+  }
 }
 ```
 
+### Optional Memory System Setup
+
+If you want to use `memorize_asset`, `read_memory_asset`, and `scan_and_extract_patterns`, you need both:
+
+1. A **Qdrant** vector database
+2. An **embedding service** in either `ollama` or `openai-compatible` mode
+
+#### Option A: Qdrant + Ollama
+
+Start Qdrant with Docker:
+
+```bash
+docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant
+```
+
+Start Ollama and pull the default embedding model:
+
+```bash
+ollama pull nomic-embed-text
+```
+
+Recommended MCP config env:
+
+```json
+{
+  "mcpServers": {
+    "mcp-probe-kit": {
+      "command": "npx",
+      "args": ["-y", "mcp-probe-kit@latest"],
+      "env": {
+        "MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
+        "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
+        "MEMORY_EMBEDDING_PROVIDER": "ollama",
+        "MEMORY_EMBEDDING_URL": "http://127.0.0.1:11434/api/embeddings",
+        "MEMORY_EMBEDDING_MODEL": "nomic-embed-text",
+        "MEMORY_SEARCH_LIMIT": "3",
+        "MEMORY_SUMMARY_MAX_CHARS": "280"
+      }
+    }
+  }
+}
+```
+
+#### Option B: Qdrant + OpenAI-Compatible Embedding API
+
+Start Qdrant with Docker:
+
+```bash
+docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant
+```
+
+Then point the embedding config to an OpenAI-compatible `/embeddings` endpoint:
+
+```json
+{
+  "mcpServers": {
+    "mcp-probe-kit": {
+      "command": "npx",
+      "args": ["-y", "mcp-probe-kit@latest"],
+      "env": {
+        "MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
+        "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
+        "MEMORY_QDRANT_API_KEY": "",
+        "MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
+        "MEMORY_EMBEDDING_URL": "https://your-embedding-endpoint/v1/embeddings",
+        "MEMORY_EMBEDDING_API_KEY": "your-api-key",
+        "MEMORY_EMBEDDING_MODEL": "text-embedding-3-small",
+        "MEMORY_SEARCH_LIMIT": "3",
+        "MEMORY_SUMMARY_MAX_CHARS": "280"
+      }
+    }
+  }
+}
+```
+
+#### Memory Environment Variables
+
+- `MEMORY_QDRANT_URL`: Qdrant base URL, required for all memory features
+- `MEMORY_QDRANT_API_KEY`: Optional Qdrant API key
+- `MEMORY_QDRANT_COLLECTION`: Collection name, default `mcp_probe_memory`
+- `MEMORY_EMBEDDING_PROVIDER`: `ollama` or `openai-compatible`
+- `MEMORY_EMBEDDING_URL`: Embedding endpoint URL
+- `MEMORY_EMBEDDING_API_KEY`: Optional for Ollama, usually required for hosted OpenAI-compatible providers
+- `MEMORY_EMBEDDING_MODEL`: Default is `nomic-embed-text`
+- `MEMORY_SEARCH_LIMIT`: Default search result count is `3`
+- `MEMORY_SUMMARY_MAX_CHARS`: Default summary truncation length is `280`
+
+#### Notes
+
+- Memory write capability is enabled only when `MEMORY_QDRANT_URL`, `MEMORY_EMBEDDING_URL`, and `MEMORY_EMBEDDING_MODEL` are configured
+- Memory read capability only requires `MEMORY_QDRANT_URL`
+- Qdrant collections are auto-created on first write with `Cosine` distance
+- Vector size is inferred from the first embedding response
+
+### Cursor History Support
+
+Cursor local history tools do not require Qdrant or embedding configuration.
+
+Supported platforms:
+
+- Windows
+- macOS
+- Linux
+
+Requirements:
+
+- Cursor must be installed locally
+- Cursor local database must exist under `User/globalStorage/state.vscdb`
+- Compatibility depends on Cursor's current local database schema
+
 ### Windows Notes for Graph Tools
 
 Applies to `code_insight`, `start_feature`, `start_bugfix`, and `init_project_context`.
@@ -380,101 +582,101 @@ Example config using a preinstalled `gitnexus` CLI:
 ### Restart Client
 
 After configuration, **completely quit and reopen** your MCP client.
-
-**👉 [Detailed Installation Guide](https://mcp-probe-kit.bytezonex.com/pages/getting-started.html)**
-
----
-
-## 💡 Usage Examples
-
-### Daily Development
-```bash
-code_review @feature.ts    # Code review
-gentest @feature.ts         # Generate tests
-gencommit                   # Generate commit message
-```
-
-### New Feature Development
-```bash
-start_feature user-auth "User authentication feature"
-# Auto-complete: Requirements analysis → Design → Effort estimation
-```
-
-### Bug Fixing
-```bash
-start_bugfix
-# Then paste error message
-# Auto-complete: Problem location → Fix solution → Test code
-```
-
-### Product Design
-```bash
-start_product "Online Education Platform" --product_type=SaaS
-# Auto-complete: PRD → Prototype → Design system → HTML prototype
-```
-
-### UI Development
-```bash
-start_ui "Login Page" --mode=auto
-# Auto-complete: Design system → Component generation → Code output
-```
-
-### Project Context Documentation
-```bash
-# Single file mode (default) - Generate a complete project-context.md
-init_project_context
-
-# Modular mode - Generate 6 category docs (suitable for large projects)
-init_project_context --mode=modular
-# Generates: project-context.md (index) + 5 category docs
-```
-
-### Git Work Report
-```bash
-# Generate daily report
-git_work_report --date 2026-02-03
-
-# Generate weekly report
-git_work_report --start_date 2026-02-01 --end_date 2026-02-07
-
-# Save to file
-git_work_report --date 2026-02-03 --output_file daily-report.md
-# Auto-analyze Git diff, generate concise professional report
-# If direct command fails, auto-provides temp script solution (auto-deletes after execution)
-```
-
-**👉 [More Usage Examples](https://mcp-probe-kit.bytezonex.com/pages/examples.html)**
-
----
-
-## ❓ FAQ
-
-### Q1: Tool not working or errors?
-
-Check detailed logs:
-
-**Windows (PowerShell):**
-```powershell
-npx -y mcp-probe-kit@latest 2>&1 | Tee-Object -FilePath .\mcp-probe-kit.log
-```
-
-**macOS/Linux:**
-```bash
-npx -y mcp-probe-kit@latest 2>&1 | tee ./mcp-probe-kit.log
-```
-
-### Q2: Client not recognizing tools after configuration?
-
-1. **Restart client** (completely quit then reopen)
-2. Check config file path is correct
-3. Confirm JSON format is correct, no syntax errors
-4. Check client developer tools or logs for error messages
-
+
+**👉 [Detailed Installation Guide](https://mcp-probe-kit.bytezonex.com/pages/getting-started.html)**
+
+---
+
+## 💡 Usage Examples
+
+### Daily Development
+```bash
+code_review @feature.ts    # Code review
+gentest @feature.ts         # Generate tests
+gencommit                   # Generate commit message
+```
+
+### New Feature Development
+```bash
+start_feature user-auth "User authentication feature"
+# Auto-complete: Requirements analysis → Design → Effort estimation
+```
+
+### Bug Fixing
+```bash
+start_bugfix
+# Then paste error message
+# Auto-complete: Problem location → Fix solution → Test code
+```
+
+### Product Design
+```bash
+start_product "Online Education Platform" --product_type=SaaS
+# Auto-complete: PRD → Prototype → Design system → HTML prototype
+```
+
+### UI Development
+```bash
+start_ui "Login Page" --mode=auto
+# Auto-complete: Design system → Component generation → Code output
+```
+
+### Project Context Documentation
+```bash
+# Single file mode (default) - Generate a complete project-context.md
+init_project_context
+
+# Modular mode - Generate 6 category docs (suitable for large projects)
+init_project_context --mode=modular
+# Generates: project-context.md (index) + 5 category docs
+```
+
+### Git Work Report
+```bash
+# Generate daily report
+git_work_report --date 2026-02-03
+
+# Generate weekly report
+git_work_report --start_date 2026-02-01 --end_date 2026-02-07
+
+# Save to file
+git_work_report --date 2026-02-03 --output_file daily-report.md
+# Auto-analyze Git diff, generate concise professional report
+# If direct command fails, auto-provides temp script solution (auto-deletes after execution)
+```
+
+**👉 [More Usage Examples](https://mcp-probe-kit.bytezonex.com/pages/examples.html)**
+
+---
+
+## ❓ FAQ
+
+### Q1: Tool not working or errors?
+
+Check detailed logs:
+
+**Windows (PowerShell):**
+```powershell
+npx -y mcp-probe-kit@latest 2>&1 | Tee-Object -FilePath .\mcp-probe-kit.log
+```
+
+**macOS/Linux:**
+```bash
+npx -y mcp-probe-kit@latest 2>&1 | tee ./mcp-probe-kit.log
+```
+
+### Q2: Client not recognizing tools after configuration?
+
+1. **Restart client** (completely quit then reopen)
+2. Check config file path is correct
+3. Confirm JSON format is correct, no syntax errors
+4. Check client developer tools or logs for error messages
+
 ### Q3: How to update to latest version?
 
 **npx method (Recommended):**
 Use `@latest` tag in config, automatically uses latest version.
-
+
 **Global installation method:**
 ```bash
 npm update -g mcp-probe-kit
@@ -505,41 +707,41 @@ Try this:
    `MCP_GITNEXUS_TIMEOUT_MS`
 
 **👉 [More FAQ](https://mcp-probe-kit.bytezonex.com/pages/getting-started.html)**
-
----
-
-## 🤝 Contributing
-
-Issues and Pull Requests welcome!
-
-**Improvement suggestions:**
-- Add useful tools
-- Optimize existing tool prompts
-- Improve documentation and examples
-- Fix bugs
-
----
-
-## 📄 License
-
-MIT License
-
----
-
-## 🔗 Related Links
-
-- **Author**: [Kyle (小墨)](https://www.bytezonex.com/)
-- **GitHub**: [mcp-probe-kit](https://github.com/mybolide/mcp-probe-kit)
-- **npm**: [mcp-probe-kit](https://www.npmjs.com/package/mcp-probe-kit)
-- **Documentation**: [https://mcp-probe-kit.bytezonex.com](https://mcp-probe-kit.bytezonex.com/)
-
-**Related Projects:**
-- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) - Official MCP protocol docs
-- [GitHub Spec-Kit](https://github.com/github/spec-kit) - GitHub spec-driven development toolkit
-- [ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) - UI/UX design system philosophy source
-- [json-render](https://github.com/vercel-labs/json-render) - JSON template rendering engine inspiration
-- [uipro-cli](https://www.npmjs.com/package/uipro-cli) - UI/UX data source
-
----
-
-**Made with ❤️ for AI-Powered Development**
+
+---
+
+## 🤝 Contributing
+
+Issues and Pull Requests welcome!
+
+**Improvement suggestions:**
+- Add useful tools
+- Optimize existing tool prompts
+- Improve documentation and examples
+- Fix bugs
+
+---
+
+## 📄 License
+
+MIT License
+
+---
+
+## 🔗 Related Links
+
+- **Author**: [Kyle (小墨)](https://www.bytezonex.com/)
+- **GitHub**: [mcp-probe-kit](https://github.com/mybolide/mcp-probe-kit)
+- **npm**: [mcp-probe-kit](https://www.npmjs.com/package/mcp-probe-kit)
+- **Documentation**: [https://mcp-probe-kit.bytezonex.com](https://mcp-probe-kit.bytezonex.com/)
+
+**Related Projects:**
+- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) - Official MCP protocol docs
+- [GitHub Spec-Kit](https://github.com/github/spec-kit) - GitHub spec-driven development toolkit
+- [ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) - UI/UX design system philosophy source
+- [json-render](https://github.com/vercel-labs/json-render) - JSON template rendering engine inspiration
+- [uipro-cli](https://www.npmjs.com/package/uipro-cli) - UI/UX data source
+
+---
+
+**Made with ❤️ for AI-Powered Development**