Claude-Code-Workflow/ccw/MCP_SERVER.md

CCW MCP Server

The CCW MCP Server exposes CCW tools through the Model Context Protocol, allowing Claude Desktop and other MCP clients to access CCW functionality.

Installation

1. Install CCW globally or link it locally:

npm install -g ccw
# or
npm link

2. The MCP server executable is available as ccw-mcp.

Configuration

Claude Desktop Configuration

Add this to your Claude Desktop MCP settings file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ccw-tools": {
      "command": "ccw-mcp",
      "args": []
    }
  }
}

If CCW is not installed globally, use the full path:

{
  "mcpServers": {
    "ccw-tools": {
      "command": "node",
      "args": ["/full/path/to/ccw/bin/ccw-mcp.js"]
    }
  }
}

Restart Claude Desktop

After updating the configuration, restart Claude Desktop for the changes to take effect.

Available Tools

The MCP server exposes the following CCW tools:

File Operations

• edit_file - Edit files with update or line mode
• write_file - Create or overwrite files

Code Analysis

• smart_search - Intelligent code search with hybrid/exact/ripgrep modes
• get_modules_by_depth - Get module hierarchy by depth
• classify_folders - Classify project folders
• detect_changed_modules - Detect modules with git changes

Session Management

• session_manager - Manage workflow sessions

UI/Design Tools

• discover_design_files - Find design-related files
• ui_generate_preview - Generate UI previews
• ui_instantiate_prototypes - Create UI prototypes
• convert_tokens_to_css - Convert design tokens to CSS

Documentation

• generate_module_docs - Generate module documentation
• update_module_claude - Update CLAUDE.md files

CLI Execution

• cli_executor - Execute CLI commands through CCW

Usage in Claude Desktop

Once configured, you can use CCW tools directly in Claude Desktop conversations:

Can you use edit_file to update the header in README.md?

Use smart_search to find authentication logic: smart_search(query="authentication")

Get the module structure with get_modules_by_depth

Testing the Server

You can test the MCP server is working by checking the logs in Claude Desktop:

1. Open Claude Desktop
2. Check Developer Tools (Help → Developer Tools)
3. Look for ccw-tools v6.1.4 started message
4. Check Console for any errors

Troubleshooting

Server not starting

• Verify ccw-mcp is in your PATH or use full path in config
• Check Node.js version (requires >= 16.0.0)
• Look for errors in Claude Desktop Developer Tools

Tools not appearing

• Restart Claude Desktop after configuration changes
• Verify JSON syntax in configuration file
• Check server logs for initialization errors

Tool execution errors

• Ensure you have proper file permissions
• Check tool parameters match expected schema
• Review error messages in tool responses

Development

To modify or extend the MCP server:

1. Edit ccw/src/mcp-server/index.js for server logic
2. Add/modify tools in ccw/src/tools/
3. Register new tools in ccw/src/tools/index.js
4. Restart the server (restart Claude Desktop)

Architecture

The MCP server follows this structure:

ccw/
├── bin/
│   └── ccw-mcp.js          # Executable entry point
├── src/
│   ├── mcp-server/
│   │   └── index.js        # MCP server implementation
│   └── tools/
│       ├── index.js        # Tool registry
│       ├── edit-file.js    # Individual tool implementations
│       ├── write-file.js
│       └── ...

The server uses the @modelcontextprotocol/sdk to implement the MCP protocol over stdio transport.