catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-03-01 15:03:57 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: fix installation guide and update MCP recommendations

Browse Source 
- 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
This commit is contained in:
catlog22
2026-02-28 23:40:45 +08:00
parent 29f0a6cdb8
commit 096fc1c380
4 changed files with 680 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

294
docs/guide/ccwmcp.md Normal file
View File

@@ -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

48
docs/guide/getting-started.md
View File

@@ -1,47 +1,59 @@
# Getting Started with CCW # 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? ## 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 - **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 - **Specialized Agents**: Code execution, TDD development, testing, debugging, and documentation
- **Workflow Orchestration**: 4-level workflow system from spec to implementation - **Workflow Orchestration**: 5-phase workflow system from intent to execution
- **Extensible Skills**: 50+ built-in skills with custom skill support - **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 - **MCP Integration**: Model Context Protocol for enhanced tool integration
## Quick Start ## Quick Start
### Installation ### Installation
```bash **Important**: CCW is NOT an npm package. It's a Claude Code extension system.
# Install CCW globally
npm install -g claude-code-workflow
# Or use with npx ```bash
npx ccw --help # 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 ### Your First Workflow
Create a simple workflow in under 5 minutes: Create a simple workflow in under 5 minutes:
```bash ```
# Main orchestrator - automatically selects workflow based on intent # Main orchestrator - automatically selects workflow based on intent
/ccw "Create a new project" # Auto-selects appropriate workflow /ccw
/ccw "Analyze the codebase structure" # Auto-selects analysis workflow # Prompt: "Create a new project" # Auto-selects appropriate workflow
/ccw "Add user authentication" # Auto-selects implementation workflow # Prompt: "Analyze the codebase structure" # Auto-selects analysis workflow
# Prompt: "Add user authentication" # Auto-selects implementation workflow
# Auto-mode - skip confirmation # 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 # Or use specific workflow commands
/workflow:init # Initialize project state /workflow:init # Initialize project state
/workflow-plan "Add OAuth2 authentication" # Create implementation plan /workflow:plan
/workflow-execute # Execute planned tasks # Prompt: "Add OAuth2 authentication" # Create implementation plan
/workflow:execute # Execute planned tasks
``` ```
## Next Steps ## Next Steps
@@ -51,5 +63,5 @@ Create a simple workflow in under 5 minutes:
- [CLI Tools](./cli-tools.md) - Customize your CCW setup - [CLI Tools](./cli-tools.md) - Customize your CCW setup
::: tip Need Help? ::: 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).
::: :::

258
docs/guide/installation.md
View File

@@ -1,58 +1,91 @@
# Installation # 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 ## Prerequisites
Before installing CCW, make sure you have: Before installing CCW, make sure you have:
- **Node.js** >= 18.0.0 - **Claude Code** installed and configured
- **npm** >= 9.0.0 or **yarn** >= 1.22.0 - **Git** >= 2.30.0 (for version control features)
- **Git** 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 ## Install CCW
### Global Installation (Recommended) ### Method 1: Clone and Install (Recommended)
```bash ```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 ```bash
# In your project directory # Copy to your home directory
npm install --save-dev claude-code-workflow cp -r .claude ~/.claude/
cp -r .codex ~/.codex/
# Run with npx cp -r .gemini ~/.gemini/
npx ccw [command] cp -r .qwen ~/.qwen/
cp -r .ccw ~/.ccw/
``` ```
### Using Yarn ### Verify Installation
```bash In Claude Code, invoke the CCW commands:
# Global
yarn global add claude-code-workflow
# Project-specific ```
yarn add -D claude-code-workflow /ccw
``` ```
## Verify Installation You should see the CCW orchestrator prompt with workflow options.
```bash To check available CCW commands, you can list them:
ccw --version
# Output: CCW v1.0.0
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 ## Configuration
### CLI Tools Configuration ### CLI Tools Configuration
Create or edit `~/.claude/cli-tools.json`: Create or edit `~/.claude/cli-tools.json` to configure external AI tools:
```json ```json
{ {
@@ -71,14 +104,23 @@ Create or edit `~/.claude/cli-tools.json`:
"secondaryModel": "gpt-5.2", "secondaryModel": "gpt-5.2",
"tags": [], "tags": [],
"type": "builtin" "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 ### CLAUDE.md Instructions
Create `CLAUDE.md` in your project root: Create `CLAUDE.md` in your project root to define project-specific instructions:
```markdown ```markdown
# Project Instructions # Project Instructions
@@ -92,100 +134,178 @@ Create `CLAUDE.md` in your project root:
- Frontend: Vue 3 + Vite - Frontend: Vue 3 + Vite
- Backend: Node.js + Express - Backend: Node.js + Express
- Database: PostgreSQL - 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 ## Updating CCW
```bash ```bash
# Update to the latest version # Navigate to your CCW clone location
npm update -g claude-code-workflow cd ~/.claude/ccw-source # or wherever you cloned it
# Or install a specific version # Pull latest changes
npm install -g claude-code-workflow@latest git pull origin main
# Copy updated files
cp -r commands/* ~/.claude/commands/
cp -r skills/* ~/.claude/skills/
cp -r agents/* ~/.claude/agents/
``` ```
## Uninstallation ## Uninstallation
```bash ```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) # Remove configuration (optional)
rm -rf ~/.claude rm -rf ~/.claude/cli-tools.json
rm -rf .workflow/
``` ```
## Troubleshooting ## 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 ### Permission Issues
If you encounter permission errors: If you encounter permission errors when copying files:
```bash ```bash
# Use sudo (not recommended) # Use appropriate permissions for your system
sudo npm install -g claude-code-workflow # On Linux/macOS with sudo
sudo cp -r commands/* ~/.claude/commands/
# Or fix npm permissions (recommended) # Fix ownership
mkdir ~/.npm-global sudo chown -R $USER:$USER ~/.claude/
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
``` ```
### PATH Issues ### Configuration Errors
Add npm global bin to your PATH: If `cli-tools.json` has syntax errors:
```bash 1. **Validate JSON**:
# For bash/zsh ```bash
echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.bashrc cat ~/.claude/cli-tools.json | python -m json.tool
```
# For fish 2. **Check for trailing commas** - JSON doesn't allow them
echo 'set -gx PATH (npm config get prefix)/bin $PATH' >> ~/.config/fish/config.fish
``` 3. **Verify version field** - Should match expected format (e.g., "3.3.0")
::: info Next Steps ::: 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 ## Quick Start Example
After installation, try these commands to verify everything works: After installation, try these commands to verify everything works:
```bash ```
# 1. Initialize in your project # 1. Initialize in your project
cd your-project /workflow:init
ccw init
# 2. Try a simple analysis # 2. Try a simple analysis using the CLI tool
ccw cli -p "Analyze the project structure" --tool gemini --mode analysis Bash: ccw cli -p "Analyze the project structure" --tool gemini --mode analysis
# 3. Run the main orchestrator # 3. Run the main orchestrator
/ccw "Summarize the codebase architecture" /ccw
# Prompt: "Summarize the codebase architecture"
# 4. Check available commands # 4. Try brainstorming
ccw --help /brainstorm "Improve the authentication flow"
``` ```
### Expected Output ### Expected Output
**Using /ccw command:**
``` ```
$ ccw --version You: /ccw
CCW v7.0.5 Claude: CCW Orchestrator - 5-Phase Workflow Execution
$ ccw init Phase 1: Intent Understanding
✔ Created .claude/CLAUDE.md What would you like to accomplish? Please describe your task.
✔ Created .ccw/workflows/ ```
✔ Configuration complete
$ ccw cli -p "Analyze project" --tool gemini --mode analysis **Using workflow init:**
Analyzing with Gemini... ```
✔ Analysis complete You: /workflow:init
✔ Created .workflow/project-tech.json
✔ Project configuration complete
``` ```
### Common First-Time Issues ### Common First-Time Issues
| Issue | Solution | | Issue | Solution |
|-------|----------| |-------|----------|
| `ccw: command not found` | Add npm global bin to PATH, or reinstall | | `/ccw` command not recognized | Verify commands copied to `~/.claude/commands/` and restart Claude Code |
| `Permission denied` | Use `sudo` or fix npm permissions | | `Permission denied` copying files | Use `sudo` or fix directory ownership with `chown` |
| `API key not found` | Configure API keys in `~/.claude/cli-tools.json` | | MCP tools not available | Install and configure MCP servers (see [MCP Setup](./mcp-setup.md)) |
| `Node version mismatch` | Update to Node.js >= 18.0.0 | | CLI tools configuration error | Validate `~/.claude/cli-tools.json` has correct JSON syntax |

166
docs/guide/mcp-setup.md Normal file
View File

@@ -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