docs: fix installation guide and update MCP recommendations

- Fix installation method to use `ccw install` command - Update repository URL to correct GitHub location - Reduce MCP recommendations to 3 servers (ace-tool, chrome-devtools, exa) - Add ccwmcp documentation guide - Align documentation with actual CLI and frontend implementation
2026-03-01 15:03:57 +08:00 · 2026-02-28 23:40:45 +08:00
parent 29f0a6cdb8
commit 096fc1c380
4 changed files with 680 additions and 88 deletions
--- a/docs/guide/ccwmcp.md
+++ b/docs/guide/ccwmcp.md
@@ -0,0 +1,294 @@
+# CCWMCP Guide
+
+## What is CCWMCP?
+
+CCWMCP is CCW's custom MCP (Model Context Protocol) server that provides core tool integration for the CCW workflow system. It enables advanced features like team messaging, file operations, memory management, and user interaction within Claude Code.
+
+## Features
+
+CCWMCP provides the following capabilities:
+
+| Feature | Description |
+|---------|-------------|
+| **Enhanced Context** | ACE semantic search for codebase understanding |
+| **File Operations** | Advanced read, write, edit operations with validation |
+| **Team Operations** | Message bus for multi-agent team workflows |
+| **Memory Management** | Core memory system for cross-session persistence |
+| **User Interaction** | Interactive question/answer prompts |
+| **Code Diagnostics** | Real-time error detection and validation |
+
+## Available CCWMCP Tools
+
+### File Operations
+
+| Tool | Description |
+|------|-------------|
+| `mcp__ccw-tools__read_file` | Read single files with pagination support |
+| `mcp__ccw-tools__write_file` | Create or overwrite files with auto-directory creation |
+| `mcp__ccw-tools__edit_file` | Edit files with dry-run preview and line-based operations |
+
+**Usage in Skills**:
+```yaml
+allowed-tools: mcp__ccw-tools__read_file(*), mcp__ccw-tools__write_file(*), mcp__ccw-tools__edit_file(*)
+```
+
+### Search Operations
+
+| Tool | Description |
+|------|-------------|
+| `mcp__ace-tool__search_context` | Real-time semantic codebase search with context |
+| `mcp__ccw-tools__smart_search` | Structured search with regex and pattern matching |
+
+**Usage in Skills**:
+```yaml
+allowed-tools: mcp__ace-tool__search_context(*), mcp__ccw-tools__smart_search(*)
+```
+
+### Team Operations
+
+| Tool | Description |
+|------|-------------|
+| `mcp__ccw-tools__team_msg` | Team message bus for logging and communication |
+
+**Usage in Skills**:
+```yaml
+allowed-tools: mcp__ccw-tools__team_msg(*)
+```
+
+### Memory Operations
+
+| Tool | Description |
+|------|-------------|
+| `mcp__ccw-tools__core_memory` | Persistent memory management for cross-session context |
+
+**Usage in Skills**:
+```yaml
+allowed-tools: mcp__ccw-tools__core_memory(*)
+```
+
+### User Interaction
+
+| Tool | Description |
+|------|-------------|
+| `mcp__ccw-tools__ask_question` | Interactive question/answer prompts for user input |
+
+**Usage in Skills**:
+```yaml
+allowed-tools: mcp__ccw-tools__ask_question(*)
+```
+
+### Code Diagnostics
+
+| Tool | Description |
+|------|-------------|
+| `mcp__ide__getDiagnostics` | Real-time code error checking and validation |
+
+**Usage in Skills**:
+```yaml
+allowed-tools: mcp__ide__getDiagnostics(*)
+```
+
+## Installation
+
+CCWMCP is bundled with CCW installation. No separate installation is required.
+
+If you're installing CCW from source:
+
+```bash
+# 1. Clone the CCW repository
+git clone https://github.com/catlog22/Claude-Code-Workflow.git
+cd Claude-Code-Workflow
+
+# 2. Install dependencies
+npm install
+
+# 3. Install CCW (includes ccwmcp)
+ccw install
+```
+
+## Configuration
+
+CCWMCP tools are automatically available once CCW is installed. No additional configuration is required.
+
+### Verify CCWMCP is Working
+
+In Claude Code, test a CCWMCP tool:
+
+```
+# Test file read operation
+Bash: read_file("path/to/file.txt")
+
+# Test semantic search
+Bash: ace_tool__search_context("authentication logic")
+
+# Test memory operation
+Bash: core_memory("list")
+```
+
+## Usage Examples
+
+### Example 1: Reading a File
+
+```yaml
+---
+name: file-reader
+description: Read and display file contents
+allowed-tools: mcp__ccw-tools__read_file(*)
+---
+
+# Read file content
+read_file(path="/path/to/file.txt")
+```
+
+### Example 2: Editing a File
+
+```yaml
+---
+name: file-editor
+description: Edit files with validation
+allowed-tools: mcp__ccw-tools__edit_file(*)
+---
+
+# Edit file with dry-run preview
+edit_file(
+  path="/path/to/file.txt",
+  oldText="old content",
+  newText="new content",
+  dryRun=true  # Preview changes first
+)
+```
+
+### Example 3: Semantic Search
+
+```yaml
+---
+name: code-searcher
+description: Search codebase semantically
+allowed-tools: mcp__ace-tool__search_context(*)
+---
+
+# Search for authentication logic
+ace_tool__search_context(
+  project_root_path="/path/to/project",
+  query="user authentication login flow"
+)
+```
+
+### Example 4: Team Messaging
+
+```yaml
+---
+name: team-worker
+description: Multi-agent team worker
+allowed-tools: mcp__ccw-tools__team_msg(*)
+---
+
+# Log message to team bus
+team_msg(
+  operation="log",
+  team="session-id",
+  from="worker",
+  to="coordinator",
+  type="status",
+  summary="Task complete"
+)
+```
+
+## CCWMCP in Team Workflows
+
+CCWMCP is essential for CCW's team-lifecycle-v5 system:
+
+- **Team Messaging**: Enables communication between team members (analyst, writer, planner, executor, tester, reviewer)
+- **Fast-Advance**: Coordinates workflow progression through team pipeline
+- **Knowledge Transfer**: Shares context across team roles via shared-memory.json
+
+### Team Message Bus Protocol
+
+```javascript
+team_msg({
+  operation: "log",           // Operation: log, read, list, status
+  team: "session-id",         // Session ID (not team name)
+  from: "role",               // Sender role
+  to: "coordinator",          // Recipient (usually coordinator)
+  type: "draft_complete",     // Message type from role_spec
+  summary: "[role] task complete",
+  ref: "path/to/artifact"     // Optional artifact reference
+})
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| CCWMCP tools not available | Verify CCW files are in `~/.claude/` directory |
+| `mcp__ccw-tools__*` not found | Restart Claude Code after CCW installation |
+| Team messaging not working | Check session ID format (use folder name, not team name) |
+| File operations failing | Verify file paths are absolute, not relative |
+| Semantic search not working | Ensure ACE MCP server is installed and configured |
+
+## Integration with Other MCP Servers
+
+CCWMCP works alongside other MCP servers:
+
+| MCP Server | Purpose | Integration |
+|------------|---------|-------------|
+| **ACE Context Engine** | Semantic search | CCWMCP uses `mcp__ace-tool__search_context` |
+| **File System MCP** | File operations | CCWMCP provides `mcp__ccw-tools__*` file tools |
+| **Chrome DevTools MCP** | Browser automation | Used in UI design workflows |
+| **Web Reader MCP** | Web content | Used in research and documentation tasks |
+
+## Best Practices
+
+1. **Always use absolute paths** for file operations
+2. **Use dry-run mode** when editing files to preview changes
+3. **Verify session ID format** when using team messaging
+4. **Enable ACE MCP** for best semantic search experience
+5. **Check tool permissions** in skill frontmatter before use
+
+## Advanced Usage
+
+### Custom Tool Wrappers
+
+Create custom wrappers for CCWMCP tools:
+
+```yaml
+---
+name: custom-file-writer
+description: Custom file writer with validation
+allowed-tools: mcp__ccw-tools__write_file(*)
+---
+
+# Write file with backup
+write_file(
+  path="/path/to/file.txt",
+  content="file content",
+  backup=true  # Create backup before overwrite
+)
+```
+
+### Batch Operations
+
+Use CCWMCP for batch file operations:
+
+```yaml
+---
+name: batch-editor
+description: Edit multiple files at once
+allowed-tools: mcp__ccw-tools__edit_file(*)
+---
+
+# Batch edit with multiple replacements
+edit_file(
+  path="/path/to/file.txt",
+  edits=[
+    {oldText: "foo", newText: "bar"},
+    {oldText: "baz", newText: "qux"}
+  ]
+)
+```
+
+## Reference
+
+- [MCP Setup Guide](./mcp-setup.md) - Configure external MCP servers
+- [Installation](./installation.md) - CCW installation guide
+- [Team Workflows](../skills/team-workflows.md) - Team-lifecycle-v5 documentation
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -1,47 +1,59 @@
 # Getting Started with CCW

-Welcome to CCW (Claude Code Workspace) - an advanced AI-powered development environment that helps you write better code faster.
+Welcome to CCW (Claude Code Workflow) - an advanced workflow orchestration system for Claude Code that helps you build better software faster.

 ## What is CCW?

-CCW is a comprehensive development environment that combines:
+CCW is a Claude Code extension system that provides:

 - **Main Orchestrator (`/ccw`)**: Intent-aware workflow selection and automatic command routing
- **AI-Powered CLI Tools**: Analyze, review, and implement code with multiple AI backends
+- **AI-Powered CLI Tools**: Analyze, review, and implement code with multiple AI backends (Gemini, Codex, Qwen)
 - **Specialized Agents**: Code execution, TDD development, testing, debugging, and documentation
- **Workflow Orchestration**: 4-level workflow system from spec to implementation
- **Extensible Skills**: 50+ built-in skills with custom skill support
+- **Workflow Orchestration**: 5-phase workflow system from intent to execution
+- **Extensible Skills**: 100+ built-in skills with custom skill support
+- **Team Pipeline**: Multi-agent collaboration with role-based workflows (analyst, writer, planner, executor, tester, reviewer)
 - **MCP Integration**: Model Context Protocol for enhanced tool integration

 ## Quick Start

 ### Installation

-```bash
-# Install CCW globally
-npm install -g claude-code-workflow
+**Important**: CCW is NOT an npm package. It's a Claude Code extension system.

-# Or use with npx
-npx ccw --help
+```bash
+# 1. Clone the CCW repository
+git clone https://github.com/catlog22/Claude-Code-Workflow.git
+cd Claude-Code-Workflow
+
+# 2. Install dependencies
+npm install
+
+# 3. Install CCW (interactive - will prompt for Global/Path mode)
+ccw install
 ```

+See [Installation Guide](./installation.md) for detailed instructions.
+
 ### Your First Workflow

 Create a simple workflow in under 5 minutes:

-```bash
+```
 # Main orchestrator - automatically selects workflow based on intent
-/ccw "Create a new project"                    # Auto-selects appropriate workflow
-/ccw "Analyze the codebase structure"          # Auto-selects analysis workflow
-/ccw "Add user authentication"                 # Auto-selects implementation workflow
+/ccw
+# Prompt: "Create a new project"                    # Auto-selects appropriate workflow
+# Prompt: "Analyze the codebase structure"          # Auto-selects analysis workflow
+# Prompt: "Add user authentication"                 # Auto-selects implementation workflow

 # Auto-mode - skip confirmation
-/ccw -y "Fix the login timeout issue"          # Execute without confirmation prompts
+/ccw -y
+# Prompt: "Fix the login timeout issue"             # Execute without confirmation prompts

 # Or use specific workflow commands
 /workflow:init                                      # Initialize project state
-/workflow-plan "Add OAuth2 authentication"     # Create implementation plan
-/workflow-execute                               # Execute planned tasks
+/workflow:plan
+# Prompt: "Add OAuth2 authentication"               # Create implementation plan
+/workflow:execute                                   # Execute planned tasks
 ```

 ## Next Steps
@@ -51,5 +63,5 @@ Create a simple workflow in under 5 minutes:
 - [CLI Tools](./cli-tools.md) - Customize your CCW setup

 ::: tip Need Help?
-Check out our [GitHub Discussions](https://github.com/your-repo/ccw/discussions) or join our [Discord community](https://discord.gg/ccw).
+Check out our [GitHub Discussions](https://github.com/catlog22/Claude-Code-Workflow/discussions) or visit the [GitHub repository](https://github.com/catlog22/Claude-Code-Workflow).
 :::
--- a/docs/guide/installation.md
+++ b/docs/guide/installation.md
@@ -1,58 +1,91 @@
 # Installation

-Learn how to install and configure CCW on your system.
+Learn how to install and configure CCW (Claude Code Workflow) on your system.
+
+## What is CCW?
+
+CCW is a **Claude Code extension system** that provides advanced workflow orchestration, team collaboration, and MCP integration. It is **NOT** an npm package or standalone CLI tool.
+
+CCW is installed as a set of command definitions, skills, and agents in your `~/.claude/` directory, and is invoked directly within Claude Code using slash commands.

 ## Prerequisites

 Before installing CCW, make sure you have:

- **Node.js** >= 18.0.0
- **npm** >= 9.0.0 or **yarn** >= 1.22.0
- **Git** for version control features
+- **Claude Code** installed and configured
+- **Git** >= 2.30.0 (for version control features)
+- **Node.js** >= 20.0.0 (only required for MCP servers)
+- **npm** >= 10.0.0 or **bun** >= 1.0.0 (only for MCP server installation)
+
+> **Note**: CCW itself runs within Claude Code and doesn't require Node.js for its core functionality. Node.js is only needed if you want to use MCP servers.

 ## Install CCW

-### Global Installation (Recommended)
+### Method 1: Clone and Install (Recommended)

 ```bash
-npm install -g claude-code-workflow
+# 1. Clone the CCW repository
+git clone https://github.com/catlog22/Claude-Code-Workflow.git
+cd Claude-Code-Workflow
+
+# 2. Install dependencies
+npm install
+
+# 3. Install CCW to your system (interactive)
+ccw install
+
+# Or specify installation mode directly:
+# ccw install --mode Global    # Install to home directory (recommended)
+# ccw install --mode Path      # Install to specific project path
 ```

-### Project-Specific Installation
+The `ccw install` command will:
+- Copy `.claude/`, `.codex/`, `.gemini/`, `.qwen/`, `.ccw/` directories to the appropriate locations
+- Create installation manifest for tracking
+- Preserve user settings (`settings.json`, `settings.local.json`)
+- Optionally install Git Bash fix on Windows
+
+### Method 2: Manual Installation
+
+If you prefer manual installation, copy the directories:

 ```bash
-# In your project directory
-npm install --save-dev claude-code-workflow
-
-# Run with npx
-npx ccw [command]
+# Copy to your home directory
+cp -r .claude ~/.claude/
+cp -r .codex ~/.codex/
+cp -r .gemini ~/.gemini/
+cp -r .qwen ~/.qwen/
+cp -r .ccw ~/.ccw/
 ```

-### Using Yarn
+### Verify Installation

-```bash
-# Global
-yarn global add claude-code-workflow
+In Claude Code, invoke the CCW commands:

-# Project-specific
-yarn add -D claude-code-workflow
+```
+/ccw
 ```

-## Verify Installation
+You should see the CCW orchestrator prompt with workflow options.

-```bash
-ccw --version
-# Output: CCW v1.0.0
+To check available CCW commands, you can list them:

-ccw --help
-# Shows all available commands
+```
+Available CCW Commands:
+- /ccw - Main workflow orchestrator
+- /ccw-coordinator - External CLI orchestration
+- /workflow:init - Initialize project configuration
+- /workflow:status - Generate project views
+- /issue:discover - Discover and plan issues
+- /brainstorm - Multi-perspective brainstorming
+- /review-code - Multi-dimensional code review
 ```

 ## Configuration

 ### CLI Tools Configuration

-Create or edit `~/.claude/cli-tools.json`:
+Create or edit `~/.claude/cli-tools.json` to configure external AI tools:

 ```json
 {
@@ -71,14 +104,23 @@ Create or edit `~/.claude/cli-tools.json`:
      "secondaryModel": "gpt-5.2",
      "tags": [],
      "type": "builtin"
+    },
+    "qwen": {
+      "enabled": true,
+      "primaryModel": "coder-model",
+      "secondaryModel": "coder-model",
+      "tags": [],
+      "type": "builtin"
    }
  }
 }
 ```

+See [CLI Tools Guide](./cli-tools.md) for more configuration options.
+
 ### CLAUDE.md Instructions

-Create `CLAUDE.md` in your project root:
+Create `CLAUDE.md` in your project root to define project-specific instructions:

 ```markdown
 # Project Instructions
@@ -92,100 +134,178 @@ Create `CLAUDE.md` in your project root:
 - Frontend: Vue 3 + Vite
 - Backend: Node.js + Express
 - Database: PostgreSQL
+
+## CLI Endpoints
+- **CLI Tools Usage**: @~/.ccw/workflows/cli-tools-usage.md
+- **CLI Endpoints Config**: @~/.claude/cli-tools.json
 ```

+### Project Configuration
+
+Initialize CCW in your project:
+
+```
+/workflow:init
+```
+
+This creates `.workflow/project-tech.json` with your project's technology stack.
+
+## MCP Integration (Optional)
+
+CCW works best with MCP (Model Context Protocol) servers for enhanced capabilities:
+
+- **ACE Context Engine** - Real-time codebase semantic search
+- **Chrome DevTools MCP** - Browser automation and debugging
+- **Web Reader MCP** - Web content extraction
+- **File System MCP** - Enhanced file operations
+
+See [MCP Setup Guide](./mcp-setup.md) for detailed installation instructions.
+
 ## Updating CCW

 ```bash
-# Update to the latest version
-npm update -g claude-code-workflow
+# Navigate to your CCW clone location
+cd ~/.claude/ccw-source  # or wherever you cloned it

-# Or install a specific version
-npm install -g claude-code-workflow@latest
+# Pull latest changes
+git pull origin main
+
+# Copy updated files
+cp -r commands/* ~/.claude/commands/
+cp -r skills/* ~/.claude/skills/
+cp -r agents/* ~/.claude/agents/
 ```

 ## Uninstallation

 ```bash
-npm uninstall -g claude-code-workflow
+# Remove CCW commands
+rm ~/.claude/commands/ccw.md
+rm ~/.claude/commands/ccw-coordinator.md
+rm -rf ~/.claude/commands/workflow
+rm -rf ~/.claude/commands/issue
+rm -rf ~/.claude/commands/cli
+rm -rf ~/.claude/commands/memory
+
+# Remove CCW skills and agents
+rm -rf ~/.claude/skills/workflow-*
+rm -rf ~/.claude/skills/team-*
+rm -rf ~/.claude/agents/team-worker.md
+rm -rf ~/.claude/agents/cli-*-agent.md

 # Remove configuration (optional)
-rm -rf ~/.claude
+rm -rf ~/.claude/cli-tools.json
+rm -rf .workflow/
 ```

 ## Troubleshooting

+### Command Not Found
+
+If `/ccw` or other CCW commands don't work:
+
+1. **Verify files are in the correct location**:
+   ```bash
+   ls ~/.claude/commands/ccw.md
+   ls ~/.claude/commands/ccw-coordinator.md
+   ```
+
+2. **Restart Claude Code** - Commands may need a restart to be detected
+
+3. **Check file syntax** - Ensure `.md` files have valid frontmatter
+
+### MCP Tools Not Working
+
+If MCP tools (like `mcp__ace-tool__search_context`) don't work:
+
+1. **Verify MCP servers are running**:
+   - Check Claude Code Settings → MCP Servers
+   - Ensure required MCP servers are enabled
+
+2. **Install missing MCP servers**:
+   ```bash
+   # ACE Context Engine
+   npm install -g @anthropic/ace-mcp
+
+   # File System MCP
+   npm install -g @modelcontextprotocol/server-filesystem
+   ```
+
+3. **Check MCP configuration** - See [MCP Setup Guide](./mcp-setup.md)
+
 ### Permission Issues

-If you encounter permission errors:
+If you encounter permission errors when copying files:

 ```bash
-# Use sudo (not recommended)
-sudo npm install -g claude-code-workflow
+# Use appropriate permissions for your system
+# On Linux/macOS with sudo
+sudo cp -r commands/* ~/.claude/commands/

-# Or fix npm permissions (recommended)
-mkdir ~/.npm-global
-npm config set prefix '~/.npm-global'
-export PATH=~/.npm-global/bin:$PATH
+# Fix ownership
+sudo chown -R $USER:$USER ~/.claude/
 ```

-### PATH Issues
+### Configuration Errors

-Add npm global bin to your PATH:
+If `cli-tools.json` has syntax errors:

+1. **Validate JSON**:
   ```bash
-# For bash/zsh
-echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.bashrc
-
-# For fish
-echo 'set -gx PATH (npm config get prefix)/bin $PATH' >> ~/.config/fish/config.fish
+   cat ~/.claude/cli-tools.json | python -m json.tool
   ```

+2. **Check for trailing commas** - JSON doesn't allow them
+
+3. **Verify version field** - Should match expected format (e.g., "3.3.0")
+
 ::: info Next Steps
-After installation, check out the [First Workflow](./first-workflow.md) guide.
+After installation, check out the [Quick Start](./getting-started.md) guide.
 :::

 ## Quick Start Example

 After installation, try these commands to verify everything works:

-```bash
+```
 # 1. Initialize in your project
-cd your-project
-ccw init
+/workflow:init

-# 2. Try a simple analysis
-ccw cli -p "Analyze the project structure" --tool gemini --mode analysis
+# 2. Try a simple analysis using the CLI tool
+Bash: ccw cli -p "Analyze the project structure" --tool gemini --mode analysis

 # 3. Run the main orchestrator
-/ccw "Summarize the codebase architecture"
+/ccw
+# Prompt: "Summarize the codebase architecture"

-# 4. Check available commands
-ccw --help
+# 4. Try brainstorming
+/brainstorm "Improve the authentication flow"
 ```

 ### Expected Output

+**Using /ccw command:**
 ```
-$ ccw --version
-CCW v7.0.5
+You: /ccw
+Claude: CCW Orchestrator - 5-Phase Workflow Execution

-$ ccw init
-✔ Created .claude/CLAUDE.md
-✔ Created .ccw/workflows/
-✔ Configuration complete
+Phase 1: Intent Understanding
+What would you like to accomplish? Please describe your task.
+```

-$ ccw cli -p "Analyze project" --tool gemini --mode analysis
-Analyzing with Gemini...
-✔ Analysis complete
+**Using workflow init:**
+```
+You: /workflow:init
+✔ Created .workflow/project-tech.json
+✔ Project configuration complete
 ```

 ### Common First-Time Issues

 | Issue | Solution |
 |-------|----------|
-| `ccw: command not found` | Add npm global bin to PATH, or reinstall |
-| `Permission denied` | Use `sudo` or fix npm permissions |
-| `API key not found` | Configure API keys in `~/.claude/cli-tools.json` |
-| `Node version mismatch` | Update to Node.js >= 18.0.0 |
+| `/ccw` command not recognized | Verify commands copied to `~/.claude/commands/` and restart Claude Code |
+| `Permission denied` copying files | Use `sudo` or fix directory ownership with `chown` |
+| MCP tools not available | Install and configure MCP servers (see [MCP Setup](./mcp-setup.md)) |
+| CLI tools configuration error | Validate `~/.claude/cli-tools.json` has correct JSON syntax |

--- a/docs/guide/mcp-setup.md
+++ b/docs/guide/mcp-setup.md
@@ -0,0 +1,166 @@
+# MCP Setup Guide
+
+## What is MCP?
+
+Model Context Protocol (MCP) is a standardized way for AI assistants to interact with external tools and services. CCW integrates with MCP servers to provide enhanced capabilities like semantic code search, browser automation, and advanced file operations.
+
+## Recommended MCP Servers
+
+CCW Dashboard provides 3 recommended MCP servers with wizard-based installation:
+
+### 1. ACE Context Engine (Highly Recommended)
+
+- **Purpose**: Real-time codebase semantic search and context retrieval
+- **Installation**: `npx ace-tool --base-url <url> --token <token>`
+- **Used by**: CCW's `mcp__ace-tool__search_context` tool
+- **Why**: Provides semantic understanding of your codebase beyond simple text search
+
+**Configuration**:
+```json
+{
+  "mcpServers": {
+    "ace-tool": {
+      "command": "npx",
+      "args": ["ace-tool", "--base-url", "https://acemcp.heroman.wtf/relay/", "--token", "your-token"],
+      "env": {}
+    }
+  }
+}
+```
+
+**Required Fields**:
+- `baseUrl`: ACE MCP relay URL (default: `https://acemcp.heroman.wtf/relay/`)
+- `token`: Your ACE API token
+
+### 2. Chrome DevTools MCP
+
+- **Purpose**: Browser automation and debugging
+- **Installation**: `npx chrome-devtools-mcp@latest`
+- **Used by**: UI testing, web scraping, debugging
+- **Why**: Enables browser automation for web development tasks
+- **No configuration required**
+
+**Configuration**:
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["chrome-devtools-mcp@latest"],
+      "type": "stdio",
+      "env": {}
+    }
+  }
+}
+```
+
+### 3. Exa MCP (Web Search)
+
+- **Purpose**: Web search capabilities for documentation and research
+- **Installation**: `npx -y exa-mcp-server`
+- **Used by**: Research and documentation generation tasks
+- **Why**: Enables CCW to search the web for current information
+
+**Configuration**:
+```json
+{
+  "mcpServers": {
+    "exa": {
+      "command": "npx",
+      "args": ["-y", "exa-mcp-server"],
+      "env": {
+        "EXA_API_KEY": "your-exa-api-key"
+      }
+    }
+  }
+}
+```
+
+**Optional Fields**:
+- `apiKey`: Your Exa API key (optional but recommended for higher rate limits)
+
+## Complete MCP Configuration
+
+Combine all recommended MCP servers in your Claude Code settings:
+
+```json
+{
+  "mcpServers": {
+    "ace-tool": {
+      "command": "npx",
+      "args": ["ace-tool", "--base-url", "https://acemcp.heroman.wtf/relay/", "--token", "your-token"],
+      "env": {}
+    },
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["chrome-devtools-mcp@latest"],
+      "type": "stdio",
+      "env": {}
+    },
+    "exa": {
+      "command": "npx",
+      "args": ["-y", "exa-mcp-server"],
+      "env": {
+        "EXA_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## How to Configure MCP in Claude Code
+
+### Method 1: Using CCW Dashboard (Recommended)
+
+1. Run `ccw view` to open the CCW Dashboard
+2. Navigate to **MCP Manager** page
+3. Click on **Recommended** tab
+4. Click **Install** on any recommended MCP server
+5. Follow the wizard to configure
+
+### Method 2: Manual Configuration
+
+1. Open Claude Code
+2. Click on **Settings** (gear icon)
+3. Navigate to **MCP Servers** section
+4. Click **+ Add Server**
+5. Enter server name, command, and arguments
+6. Add environment variables if needed
+7. Click **Save**
+
+### Verify MCP Connection
+
+In Claude Code, invoke the MCP tools:
+
+```
+# Test ACE Context Engine
+Bash: ccw cli -p "Search for authentication logic" --tool gemini --mode analysis
+# This will use mcp__ace-tool__search_context if configured
+
+# List available MCP tools
+# Check Claude Code Settings → MCP Servers → Connection Status
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| MCP server not starting | Verify Node.js >= 18.0.0 is installed |
+| Connection refused | Check MCP server configuration in Claude Code settings |
+| ACE token invalid | Verify your ACE API token is correct |
+| `npx` command not found | Ensure Node.js and npm are in your PATH |
+| Windows path issues | CCW Dashboard auto-wraps commands with `cmd /c` on Windows |
+
+## Minimum MCP Setup for CCW
+
+For basic CCW functionality, the minimum recommended MCP servers are:
+
+1. **ACE Context Engine** - For semantic code search (required for best experience)
+
+All other MCP servers are optional and add specific capabilities.
+
+## Next Steps
+
+- [CCWMCP Guide](./ccwmcp.md) - Learn about CCW's custom MCP server
+- [Installation](./installation.md) - Complete CCW installation guide
+- [CLI Tools](./cli-tools.md) - Configure CLI tools for CCW