Segment MCP tools into workflow-based groups with selective enablement

## Summary

Add the ability to enable/disable MCP tool groups based on workflow arguments. This will reduce cognitive load, improve performance, and provide a cleaner tool surface for specific tasks.

## Motivation

Currently, all MCP tools are loaded regardless of the task at hand. When a user is only creating issues, they don't need access to performance benchmarking tools. Segmenting tools into logical groups allows:

- **Reduced latency**: Fewer tools = faster tool resolution
- **Lower token usage**: Smaller tool descriptions in context
- **Clearer focus**: Only relevant tools visible for the task
- **Better UX**: Less overwhelming for users

## Configuration Precedence

**CLI args override environment variables. Env vars are defaults when no args given.**

```
CLI args (--tools=X) → takes priority if specified
↓
ENV vars (CLAUDE_FLOW_TOOL_GROUPS) → used if no CLI args
↓
Config file (.claude-flow.json) → project defaults
↓
Default (all tools enabled)
```

## Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `CLAUDE_FLOW_TOOL_GROUPS` | Comma-separated tool groups | `implement,test,fix` |
| `CLAUDE_FLOW_TOOL_MODE` | Preset mode | `develop` |

```bash
# .env file
CLAUDE_FLOW_TOOL_GROUPS=implement,test,fix,memory
CLAUDE_FLOW_TOOL_MODE=develop

# Or export in shell
export CLAUDE_FLOW_TOOL_GROUPS=issue,branch
```

**CLI always wins:**
```bash
# Env has: CLAUDE_FLOW_TOOL_GROUPS=implement,test
# CLI overrides completely:
npx claude-flow mcp start --tools=security,monitor
# Result: Only security and monitor tools loaded
```

## Proposed Tool Groups (10 Groups)

| # | Group | Arg | Description | Example Tools |
|---|-------|-----|-------------|---------------|
| 1 | **create** | `--tools=create` | Project/resource creation | `agent_spawn`, `task_create`, `workflow_create`, `swarm_init`, `daa_agent_create` |
| 2 | **issue** | `--tools=issue` | Issue management | `github_issue_track`, `claims_*`, `task_*` |
| 3 | **branch** | `--tools=branch` | Branch/PR management | `github_pr_manage`, `analyze_diff*`, `github_workflow` |
| 4 | **implement** | `--tools=implement` | Code implementation | `hooks_pre-edit`, `hooks_post-edit`, `hooks_route`, `hooks_explain` |
| 5 | **test** | `--tools=test` | Testing workflows | `performance_benchmark`, `hooks_worker-dispatch` (testgaps), `system_health` |
| 6 | **fix** | `--tools=fix` | Bug fixing & debugging | `hooks_route`, `performance_bottleneck`, `system_status`, `hooks_explain` |
| 7 | **optimize** | `--tools=optimize` | Performance optimization | `performance_*`, `neural_optimize`, `coordination_load_balance` |
| 8 | **monitor** | `--tools=monitor` | System monitoring & status | `system_status`, `system_metrics`, `agent_health`, `swarm_status`, `task_status` |
| 9 | **security** | `--tools=security` | Security & threat detection | `aidefence_*`, `transfer_detect-pii`, `hooks_pre-command` |
| 10 | **memory** | `--tools=memory` | Memory & knowledge management | `memory_*`, `embeddings_*`, `neural_patterns`, `hive-mind_memory` |

### Special Groups

| Group | Arg | Description |
|-------|-----|-------------|
| **all** | `--tools=all` | All tools (default) |
| **minimal** | `--tools=minimal` | Core essentials only (status, memory_store/retrieve) |

## Implementation

### 1. Tool Group Configuration

```typescript
// src/mcp/tool-groups.ts
export const TOOL_GROUPS = {
create: [
'agent_spawn', 'agent_pool', 'task_create',
'workflow_create', 'swarm_init', 'hive-mind_init',
'hive-mind_spawn', 'daa_agent_create', 'daa_workflow_create',
'terminal_create', 'session_save'
],
issue: [
'github_issue_track', 'claims_claim', 'claims_release',
'claims_status', 'claims_list', 'claims_handoff',
'claims_board', 'task_create', 'task_update', 'task_list'
],
branch: [
'github_pr_manage', 'github_repo_analyze', 'github_workflow',
'github_metrics', 'analyze_diff', 'analyze_diff-risk',
'analyze_diff-classify', 'analyze_diff-reviewers',
'analyze_file-risk', 'analyze_diff-stats'
],
implement: [
'hooks_pre-edit', 'hooks_post-edit', 'hooks_pre-task',
'hooks_post-task', 'hooks_route', 'hooks_explain',
'hooks_model-route', 'hooks_model-outcome',
'memory_store', 'memory_retrieve', 'memory_search'
],
test: [
'performance_benchmark', 'performance_profile',
'hooks_worker-dispatch', 'system_health', 'agent_health',
'swarm_health', 'hooks_worker-status'
],
fix: [
'hooks_route', 'hooks_explain', 'hooks_intelligence*',
'performance_bottleneck', 'system_status', 'system_health',
'agent_status', 'task_status', 'hooks_metrics'
],
optimize: [
'performance_optimize', 'performance_metrics', 'performance_report',
'performance_bottleneck', 'neural_optimize', 'neural_compress',
'coordination_load_balance', 'coordination_topology',
'hooks_worker-dispatch', 'claims_rebalance'
],
monitor: [
'system_status', 'system_metrics', 'system_health', 'system_info',
'agent_status', 'agent_list', 'agent_health', 'agent_metrics',
'swarm_status', 'swarm_health', 'task_status', 'task_list',
'workflow_status', 'hive-mind_status', 'hooks_metrics',
'hooks_worker-status', 'hooks_intelligence_stats'
],
security: [
'aidefence_scan', 'aidefence_analyze', 'aidefence_stats',
'aidefence_learn', 'aidefence_is_safe', 'aidefence_has_pii',
'transfer_detect-pii', 'hooks_pre-command', 'hooks_post-command'
],
memory: [
'memory_store', 'memory_retrieve', 'memory_search',
'memory_delete', 'memory_list', 'memory_stats',
'embeddings_init', 'embeddings_generate', 'embeddings_compare',
'embeddings_search', 'embeddings_status', 'embeddings_neural',
'embeddings_hyperbolic', 'neural_patterns', 'neural_predict',
'hive-mind_memory', 'hooks_intelligence_pattern-store',
'hooks_intelligence_pattern-search'
],
// Special groups
all: ['*'],
minimal: [
'system_status', 'memory_store', 'memory_retrieve',
'agent_list', 'task_list'
]
} as const;
```

### 2. Configuration Resolution

```typescript
// src/mcp/tool-config.ts
export function resolveToolGroups(cliArgs?: string, cliMode?: string): string[] {
// 1. CLI args take priority
if (cliArgs) {
return cliArgs.split(',').map(g => g.trim());
}

if (cliMode) {
return PRESET_MODES[cliMode] || ['all'];
}

// 2. Check environment variables
const envGroups = process.env.CLAUDE_FLOW_TOOL_GROUPS;
if (envGroups) {
return envGroups.split(',').map(g => g.trim());
}

const envMode = process.env.CLAUDE_FLOW_TOOL_MODE;
if (envMode) {
return PRESET_MODES[envMode] || ['all'];
}

// 3. Check config file
const config = loadProjectConfig();
if (config?.mcp?.toolGroups) {
return config.mcp.toolGroups;
}

// 4. Default: all tools
return ['all'];
}
```

### 3. CLI Integration

```bash
# Enable single group (overrides env)
npx claude-flow mcp start --tools=issue

# Enable multiple groups (overrides env)
npx claude-flow mcp start --tools=issue,branch,fix

# Preset modes (overrides env)
npx claude-flow mcp start --mode=pr-review # branch + fix + monitor
npx claude-flow mcp start --mode=develop # implement + test + fix + memory
npx claude-flow mcp start --mode=devops # create + monitor + optimize + security
npx claude-flow mcp start --mode=research # memory + monitor + implement

# No args = use env vars or defaults
npx claude-flow mcp start
# Uses CLAUDE_FLOW_TOOL_GROUPS or CLAUDE_FLOW_TOOL_MODE if set
```

### 4. Preset Modes

| Mode | Groups Included | Use Case |
|------|-----------------|----------|
| `pr-review` | branch, fix, monitor, security | Code review workflows |
| `develop` | create, implement, test, fix, memory | Active development |
| `devops` | create, monitor, optimize, security | Infrastructure/ops work |
| `research` | memory, monitor, implement | Research & exploration |
| `triage` | issue, monitor, fix | Issue triage & debugging |

### 5. MCP Server Changes

Modify tool registration to filter based on enabled groups:

```typescript
// src/mcp/server.ts
export function registerTools(server: McpServer, cliTools?: string, cliMode?: string) {
const enabledGroups = resolveToolGroups(cliTools, cliMode);
const enabledTools = expandToolGroups(enabledGroups);

for (const [name, handler] of ALL_TOOLS) {
if (isToolEnabled(name, enabledTools)) {
server.tool(name, handler.schema, handler.execute);
}
}

// Log which groups are active
console.log(`[MCP] Tool groups enabled: ${enabledGroups.join(', ')}`);
console.log(`[MCP] Tools registered: ${countEnabledTools(enabledTools)}`);
}

function isToolEnabled(toolName: string, enabledTools: Set): boolean {
if (enabledTools.has('*')) return true;
if (enabledTools.has(toolName)) return true;

// Check wildcard patterns (e.g., 'claims_*')
for (const pattern of enabledTools) {
if (pattern.endsWith('*')) {
const prefix = pattern.slice(0, -1);
if (toolName.startsWith(prefix)) return true;
}
}

return false;
}
```

## Acceptance Criteria

- [ ] Define 10 tool groups in configuration file
- [ ] Add `--tools` CLI argument to `mcp start` command
- [ ] Add `--mode` CLI argument for preset modes
- [ ] Support comma-separated multiple groups
- [ ] **Implement env var support: `CLAUDE_FLOW_TOOL_GROUPS`, `CLAUDE_FLOW_TOOL_MODE`**
- [ ] **CLI args override env vars (precedence: CLI > ENV > Config > Default)**
- [ ] Filter tool registration based on enabled groups
- [ ] Support wildcard patterns in group definitions (e.g., `claims_*`)
- [ ] Add `mcp tools list --group=` to show tools in a group
- [ ] Add `mcp tools groups` to list all available groups
- [ ] Log active groups and tool count on MCP server start
- [ ] Update documentation with tool group reference
- [ ] Add tests for tool filtering logic and precedence
- [ ] Support config file `.claude-flow.json` for project defaults

## Tool Count Estimates

| Group | Approx. Tools |
|-------|---------------|
| create | 12 |
| issue | 10 |
| branch | 10 |
| implement | 12 |
| test | 7 |
| fix | 10 |
| optimize | 10 |
| monitor | 17 |
| security | 9 |
| memory | 18 |
| **Total unique** | ~80 |
| **all** | 200+ |

## Related

- ADR-026: Intelligent Model Routing (similar filtering concept)
- V3 CLI modernization efforts

/cc @ruvnet

Start with the proposed src/mcp/tool-groups.ts, src/mcp/tool-config.ts, and src/mcp/server.ts entry points, then trace how the mcp start command currently registers tools. Review the acceptance criteria for CLI, environment, config precedence, filtering, group-listing commands, logging, documentation, and tests; the work is done when these behaviors are covered and validated.

Written by the indexing model from the issue text.