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