# @aegis-ai/mcp-toolselect

An MCP server that recommends which tools to use for a given task. It learns from usage patterns and adapts recommendations over time based on success rates.

## Install

```bash
bun install @aegis-ai/mcp-toolselect
```

Or clone and run directly:

```bash
git clone https://github.com/aegis-ai/mcp-toolselect.git
cd mcp-toolselect
bun install
bun src/index.ts
```

## Configuration

Add to your MCP client config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "toolselect": {
      "command": "bunx",
      "args": ["@aegis-ai/mcp-toolselect"]
    }
  }
}
```

Or if running from source:

```json
{
  "mcpServers": {
    "toolselect": {
      "command": "bun",
      "args": ["/path/to/mcp-toolselect/src/index.ts"]
    }
  }
}
```

## Tools

### recommend_tools

Get ranked tool recommendations for a task description. Returns confidence scores, priority levels, and historical success rates.

**Parameters:**
- `task` (string, required) - Description of the task
- `max_results` (number, optional) - Max recommendations to return (default: 5)

**Example:**
```json
{
  "task": "Write integration tests for the payment API",
  "max_results": 3
}
```

**Response:**
```json
{
  "task": "Write integration tests for the payment API",
  "analysis": {
    "keywords": ["testing", "coding", "api"],
    "complexity": "medium",
    "estimatedDuration": "medium"
  },
  "recommendations": [
    {
      "tool": "jest",
      "confidence": 0.85,
      "reason": "matches keyword \"testing\"; strength \"integration tests\" found in task",
      "priority": "required",
      "successRate": 0.92,
      "timesUsed": 47
    }
  ]
}
```

### register_tool

Register a tool with its capabilities so it can be recommended for future tasks.

**Parameters:**
- `name` (string, required) - Unique tool name
- `description` (string, required) - What the tool does
- `category` (string, required) - Category (e.g. coding, testing, deployment, research, analysis)
- `strengths` (string[], required) - What the tool is good at
- `use_cases` (string[], required) - Typical scenarios where the tool shines

**Example:**
```json
{
  "name": "playwright",
  "description": "Browser automation and end-to-end testing framework",
  "category": "testing",
  "strengths": ["browser automation", "e2e testing", "cross-browser", "screenshot comparison"],
  "use_cases": ["end-to-end tests", "visual regression testing", "web scraping", "form automation"]
}
```

### record_usage

Record that a tool was used for a task and whether it succeeded. This feedback drives future recommendation quality.

**Parameters:**
- `tool` (string, required) - Tool name
- `task` (string, required) - Task description
- `success` (boolean, required) - Whether the tool completed the task successfully
- `duration_ms` (number, optional) - Execution time in milliseconds
- `notes` (string, optional) - Additional context

**Example:**
```json
{
  "tool": "playwright",
  "task": "Run e2e tests for checkout flow",
  "success": true,
  "duration_ms": 12500,
  "notes": "All 15 tests passed"
}
```

### get_tool_stats

Get usage statistics and success rates for registered tools.

**Parameters:**
- `tool` (string, optional) - Specific tool name. Omit to get all stats.

**Example response:**
```json
{
  "totalTools": 8,
  "totalUsages": 142,
  "tools": [
    {
      "name": "playwright",
      "timesUsed": 47,
      "successCount": 43,
      "failCount": 4,
      "avgDurationMs": 11200,
      "overallSuccessRate": 0.91,
      "contextSuccessRates": {
        "testing": 0.94,
        "debugging": 0.78
      }
    }
  ]
}
```

### list_tools

List all registered tools grouped by category.

**Parameters:**
- `category` (string, optional) - Filter by category

## How It Works

1. **Register tools** with their capabilities and use cases
2. **Ask for recommendations** by describing your task
3. **Record outcomes** after using a tool (success/failure)
4. The system learns which tools work best for which types of tasks and adjusts future confidence scores accordingly

The recommendation engine:
- Analyzes task descriptions to extract keywords and estimate complexity
- Matches keywords against registered tool strengths and use cases
- Adjusts confidence using historical success rates (exponential moving average)
- Returns prioritized recommendations sorted by relevance

## Data Storage

All data is stored locally in `~/.mcp-toolselect/`:
- `tool-registry.json` - Registered tools and their metadata
- `tool-stats.json` - Aggregated usage statistics
- `usage-log.jsonl` - Append-only usage log for auditing

## License

MIT - Copyright 2026 AEGIS AI Cooperative