tarvacode-agent-selector MCP Server

An MCP (Model Context Protocol) server for semantic agent selection using pgvector embeddings in Supabase.

Overview

This server provides tools to find the best specialized Claude Code agent for a given task using semantic similarity matching:

1. select_best_agent - Find the optimal agent for a task description
2. list_agents - List all available agents
3. get_agent_skills - Get skills for a specific agent

Architecture

Task Description
      ↓
OpenAI Embedding (text-embedding-3-small)
      ↓
Supabase Stored Procedure (two-tier selection)
  - Top-K agent shortlist by embedding similarity
  - Rerank by max skill similarity
  - Fallback to chief-technology-architect
      ↓
Agent Name

Setup

Prerequisites

• Node.js >= 18.0.0
• npm or yarn
• Access to:
  • Supabase project with pgvector extension
  • OpenAI API key

Installation

cd find-best-agent/mcp-server
npm install
npm run build

Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | OPENAI_API_KEY | OpenAI API key for embeddings | Yes | | SUPABASE_URL | Supabase project URL | Yes | | SUPABASE_ANON_KEY | Supabase anon/public key | Yes |

Claude Code Configuration

Add to your project's .claude/mcp.json:

{
  "mcpServers": {
    "tarvacode-agent-selector": {
      "command": "node",
      "args": ["./find-best-agent/mcp-server/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
        "SUPABASE_URL": "${SUPABASE_URL}",
        "SUPABASE_ANON_KEY": "${SUPABASE_ANON_KEY}"
      }
    }
  }
}

Tools

select_best_agent

Finds the best agent for a task using two-tier semantic matching.

Input:

{
  "task": "Design a PostgreSQL schema for a multi-tenant SaaS application",
  "match_threshold": 0.5
}

Output:

{
  "agent_name": "database-architect"
}

list_agents

Lists all available agents.

Output:

{
  "agents": [
    {
      "name": "database-architect",
      "description": "World-class Database Architect...",
      "tools": ["Read", "Write", "Edit", "Grep", "Glob", "Bash", "Task"]
    }
  ],
  "count": 20
}

get_agent_skills

Gets skills for a specific agent.

Input:

{
  "agent_name": "database-architect"
}

Output:

{
  "agent_name": "database-architect",
  "skills": [
    {
      "skill_id": "A1",
      "skill_name": "Workload Classification",
      "domain": "A: Architecture strategy",
      "deliverable": "classification_report"
    }
  ],
  "count": 52
}

Development

# Run in development mode
npm run dev

# Type check
npm run typecheck

# Build
npm run build

Selection Algorithm

The stored procedure implements a two-tier selection:

1. Agent-Level Shortlist: Find top-K agents by cosine similarity between task embedding and agent embeddings
2. Skill-Level Rerank: For each candidate, compute max similarity against skill embeddings
3. Final Score: Use the higher of agent similarity or max skill similarity
4. Threshold: Only return agents above the match threshold
5. Fallback: Return "chief-technology-architect" if no match above threshold

This approach balances speed (coarse agent matching) with accuracy (granular skill validation).