tarvacode-agent-selector 1.0.0

package/INSTRUCTIONS.md

@@ -0,0 +1,95 @@
+# MCP Server Instructions
+
+## Purpose
+
+This MCP server enables Claude Code to select the optimal specialized agent for any given task using semantic similarity matching against a database of agent and skill embeddings.
+
+## When to Use
+
+Use this server when:
+- Processing complex, multi-domain tasks that require specialist agents
+- The task description is ambiguous and you need to determine the best expert
+- Building automated workflows that route work to appropriate agents
+- The `find-best-agent` micro-agent needs to decompose and route PRD tasks
+
+## Tool Usage Guide
+
+### select_best_agent
+
+**Primary tool for agent selection.**
+
+Call this with a clear task description. The tool will:
+1. Generate a 1536-dimensional embedding using OpenAI
+2. Query Supabase for the best matching agent
+3. Return only the agent name
+
+**Best practices:**
+- Provide descriptive task text (50-500 characters works well)
+- Include domain-specific keywords for better matching
+- Use `match_threshold` of 0.5 (default) for balanced precision/recall
+- Lower threshold (0.3-0.4) for exploratory matching
+- Higher threshold (0.6-0.7) for high-confidence matching only
+
+**Example calls:**
+```
+// Database work
+select_best_agent({ task: "Design a normalized PostgreSQL schema for user authentication with OAuth2 support" })
+// → database-architect
+
+// Frontend work
+select_best_agent({ task: "Build a responsive React dashboard with data tables and charts" })
+// → react-developer
+
+// Architecture work
+select_best_agent({ task: "Plan the microservices architecture for a real-time collaboration platform" })
+// → chief-technology-architect
+
+// Patent work
+select_best_agent({ task: "Draft claims for a novel machine learning inference optimization method" })
+// → patent-attorney
+```
+
+### list_agents
+
+**Discovery tool for available agents.**
+
+Use when you need to:
+- See all available agents before making selection decisions
+- Validate that an agent exists before routing work
+- Present options to the user
+
+### get_agent_skills
+
+**Drill-down tool for agent capabilities.**
+
+Use when you need to:
+- Understand what specific skills an agent has
+- Validate that an agent can handle a specific deliverable type
+- Explore domain coverage for an agent
+
+## Integration with find-best-agent
+
+The `find-best-agent` micro-agent uses this server to:
+
+1. **Decompose** a complex PRD into logical tasks
+2. **Route** each task through `select_best_agent`
+3. **Map** tasks to their optimal agents
+4. **Execute** in parallel (independent tasks) or sequential (dependent tasks)
+
+## Caching
+
+The server implements a 15-minute embedding cache to reduce OpenAI API calls. Similar task descriptions will reuse cached embeddings.
+
+## Error Handling
+
+If no agent matches above the threshold, the server returns "chief-technology-architect" as a fallback. This ensures you always get a valid agent name to route work to.
+
+## Fallback Behavior
+
+| Scenario | Result |
+|----------|--------|
+| No agents match threshold | Returns "chief-technology-architect" |
+| Empty task description | Returns error |
+| Invalid agent name (get_skills) | Returns empty skills array |
+| OpenAI API error | Returns error with details |
+| Supabase connection error | Returns error with details |

package/README.md

@@ -0,0 +1,163 @@
+# 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
+
+```bash
+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`:
+
+```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:**
+```json
+{
+  "task": "Design a PostgreSQL schema for a multi-tenant SaaS application",
+  "match_threshold": 0.5
+}
+```
+
+**Output:**
+```json
+{
+  "agent_name": "database-architect"
+}
+```
+
+### list_agents
+
+Lists all available agents.
+
+**Output:**
+```json
+{
+  "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:**
+```json
+{
+  "agent_name": "database-architect"
+}
+```
+
+**Output:**
+```json
+{
+  "agent_name": "database-architect",
+  "skills": [
+    {
+      "skill_id": "A1",
+      "skill_name": "Workload Classification",
+      "domain": "A: Architecture strategy",
+      "deliverable": "classification_report"
+    }
+  ],
+  "count": 52
+}
+```
+
+## Development
+
+```bash
+# 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).

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { selectAgentTool } from "./tools/selectAgent.js";
+import { listAgentsTool } from "./tools/listAgents.js";
+import { getAgentSkillsTool } from "./tools/getAgentSkills.js";
+const SERVER_NAME = "tarvacode-agent-selector";
+const SERVER_VERSION = "1.0.0";
+// Define available tools
+const TOOLS = [
+    {
+        name: "select_best_agent",
+        description: "Finds the best specialized agent for a given task description using semantic similarity matching. Returns ONLY the agent name.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                task: {
+                    type: "string",
+                    description: "The task description to find the best agent for",
+                },
+                match_threshold: {
+                    type: "number",
+                    description: "Minimum similarity score (0-1) to consider a match. Default: 0.5",
+                    default: 0.5,
+                },
+            },
+            required: ["task"],
+        },
+    },
+    {
+        name: "list_agents",
+        description: "Lists all available specialized agents with their descriptions and available tools.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: "get_agent_skills",
+        description: "Gets the skills available for a specific agent, organized by domain.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_name: {
+                    type: "string",
+                    description: "The name of the agent to get skills for",
+                },
+            },
+            required: ["agent_name"],
+        },
+    },
+];
+async function main() {
+    const server = new Server({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // Handle list tools request
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return { tools: TOOLS };
+    });
+    // Handle tool calls
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            let result;
+            switch (name) {
+                case "select_best_agent":
+                    result = await selectAgentTool({
+                        task: args?.task,
+                        match_threshold: args?.match_threshold,
+                    });
+                    break;
+                case "list_agents":
+                    result = await listAgentsTool();
+                    break;
+                case "get_agent_skills":
+                    result = await getAgentSkillsTool({
+                        agent_name: args?.agent_name,
+                    });
+                    break;
+                default:
+                    throw new Error(`Unknown tool: ${name}`);
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: errorMessage }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Start the server
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`${SERVER_NAME} v${SERVER_VERSION} started`);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GAEvB,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,MAAM,WAAW,GAAG,0BAA0B,CAAC;AAC/C,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B,yBAAyB;AACzB,MAAM,KAAK,GAAW;IACpB;QACE,IAAI,EAAE,mBAAmB;QACzB,WAAW,EACT,gIAAgI;QAClI,WAAW,EAAE;YACX,IAAI,EAAE,QAAiB;YACvB,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,iDAAiD;iBAC/D;gBACD,eAAe,EAAE;oBACf,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,kEAAkE;oBACpE,OAAO,EAAE,GAAG;iBACb;aACF;YACD,QAAQ,EAAE,CAAC,MAAM,CAAC;SACnB;KACF;IACD;QACE,IAAI,EAAE,aAAa;QACnB,WAAW,EACT,qFAAqF;QACvF,WAAW,EAAE;YACX,IAAI,EAAE,QAAiB;YACvB,UAAU,EAAE,EAAE;YACd,QAAQ,EAAE,EAAE;SACb;KACF;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,WAAW,EACT,sEAAsE;QACxE,WAAW,EAAE;YACX,IAAI,EAAE,QAAiB;YACvB,UAAU,EAAE;gBACV,UAAU,EAAE;oBACV,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,yCAAyC;iBACvD;aACF;YACD,QAAQ,EAAE,CAAC,YAAY,CAAC;SACzB;KACF;CACF,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB;QACE,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KACxB,EACD;QACE,YAAY,EAAE;YACZ,KAAK,EAAE,EAAE;SACV;KACF,CACF,CAAC;IAEF,4BAA4B;IAC5B,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE;QAC1D,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,oBAAoB;IACpB,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAChE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;QAEjD,IAAI,CAAC;YACH,IAAI,MAAe,CAAC;YAEpB,QAAQ,IAAI,EAAE,CAAC;gBACb,KAAK,mBAAmB;oBACtB,MAAM,GAAG,MAAM,eAAe,CAAC;wBAC7B,IAAI,EAAE,IAAI,EAAE,IAAc;wBAC1B,eAAe,EAAE,IAAI,EAAE,eAAqC;qBAC7D,CAAC,CAAC;oBACH,MAAM;gBAER,KAAK,aAAa;oBAChB,MAAM,GAAG,MAAM,cAAc,EAAE,CAAC;oBAChC,MAAM;gBAER,KAAK,kBAAkB;oBACrB,MAAM,GAAG,MAAM,kBAAkB,CAAC;wBAChC,UAAU,EAAE,IAAI,EAAE,UAAoB;qBACvC,CAAC,CAAC;oBACH,MAAM;gBAER;oBACE,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC;YAC7C,CAAC;YAED,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;qBACtC;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,YAAY,GAChB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,wBAAwB,CAAC;YAEpE,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;qBAC9C;iBACF;gBACD,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,mBAAmB;IACnB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,OAAO,CAAC,KAAK,CAAC,GAAG,WAAW,KAAK,cAAc,UAAU,CAAC,CAAC;AAC7D,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/lib/embeddings.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Generate embedding for a single text with caching.
+ */
+export declare function generateEmbedding(text: string): Promise<number[]>;
+/**
+ * Generate embeddings for multiple texts with batching.
+ */
+export declare function generateEmbeddings(texts: string[]): Promise<number[][]>;
+//# sourceMappingURL=embeddings.d.ts.map

package/dist/lib/embeddings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings.d.ts","sourceRoot":"","sources":["../../src/lib/embeddings.ts"],"names":[],"mappings":"AAmDA;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA8BvE;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAS7E"}

package/dist/lib/embeddings.js

@@ -0,0 +1,72 @@
+import OpenAI from "openai";
+const EMBEDDING_MODEL = "text-embedding-3-small";
+let openaiClient = null;
+const embeddingCache = new Map();
+const CACHE_TTL_MS = 15 * 60 * 1000; // 15 minutes
+function getOpenAIClient() {
+    if (openaiClient) {
+        return openaiClient;
+    }
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+        throw new Error("Missing OpenAI configuration. Set OPENAI_API_KEY environment variable.");
+    }
+    openaiClient = new OpenAI({ apiKey });
+    return openaiClient;
+}
+/**
+ * Normalize text for cache key.
+ */
+function normalizeText(text) {
+    return text.trim().toLowerCase();
+}
+/**
+ * Clean expired cache entries.
+ */
+function cleanCache() {
+    const now = Date.now();
+    for (const [key, entry] of embeddingCache.entries()) {
+        if (now - entry.timestamp > CACHE_TTL_MS) {
+            embeddingCache.delete(key);
+        }
+    }
+}
+/**
+ * Generate embedding for a single text with caching.
+ */
+export async function generateEmbedding(text) {
+    const cacheKey = normalizeText(text);
+    // Check cache
+    const cached = embeddingCache.get(cacheKey);
+    if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS) {
+        return cached.embedding;
+    }
+    // Clean old entries periodically
+    if (embeddingCache.size > 100) {
+        cleanCache();
+    }
+    const client = getOpenAIClient();
+    const response = await client.embeddings.create({
+        model: EMBEDDING_MODEL,
+        input: text,
+    });
+    const embedding = response.data[0].embedding;
+    // Cache the result
+    embeddingCache.set(cacheKey, {
+        embedding,
+        timestamp: Date.now(),
+    });
+    return embedding;
+}
+/**
+ * Generate embeddings for multiple texts with batching.
+ */
+export async function generateEmbeddings(texts) {
+    const client = getOpenAIClient();
+    const response = await client.embeddings.create({
+        model: EMBEDDING_MODEL,
+        input: texts,
+    });
+    return response.data.map((item) => item.embedding);
+}
+//# sourceMappingURL=embeddings.js.map

package/dist/lib/embeddings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings.js","sourceRoot":"","sources":["../../src/lib/embeddings.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,MAAM,eAAe,GAAG,wBAAwB,CAAC;AAEjD,IAAI,YAAY,GAAkB,IAAI,CAAC;AAQvC,MAAM,cAAc,GAAG,IAAI,GAAG,EAAsB,CAAC;AACrD,MAAM,YAAY,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,aAAa;AAElD,SAAS,eAAe;IACtB,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAE1C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,wEAAwE,CACzE,CAAC;IACJ,CAAC;IAED,YAAY,GAAG,IAAI,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IACtC,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;GAEG;AACH,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,SAAS,UAAU;IACjB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,cAAc,CAAC,OAAO,EAAE,EAAE,CAAC;QACpD,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,GAAG,YAAY,EAAE,CAAC;YACzC,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAY;IAClD,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAErC,cAAc;IACd,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC5C,IAAI,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,SAAS,GAAG,YAAY,EAAE,CAAC;QAC3D,OAAO,MAAM,CAAC,SAAS,CAAC;IAC1B,CAAC;IAED,iCAAiC;IACjC,IAAI,cAAc,CAAC,IAAI,GAAG,GAAG,EAAE,CAAC;QAC9B,UAAU,EAAE,CAAC;IACf,CAAC;IAED,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;IAEjC,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;QAC9C,KAAK,EAAE,eAAe;QACtB,KAAK,EAAE,IAAI;KACZ,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAE7C,mBAAmB;IACnB,cAAc,CAAC,GAAG,CAAC,QAAQ,EAAE;QAC3B,SAAS;QACT,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;KACtB,CAAC,CAAC;IAEH,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,KAAe;IACtD,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;IAEjC,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;QAC9C,KAAK,EAAE,eAAe;QACtB,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;IAEH,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AACrD,CAAC"}

package/dist/lib/supabase.d.ts

@@ -0,0 +1,26 @@
+import { SupabaseClient } from "@supabase/supabase-js";
+export declare function getSupabaseClient(): SupabaseClient;
+export interface Agent {
+    name: string;
+    description: string;
+    tools: string[];
+}
+export interface Skill {
+    skill_id: string;
+    skill_name: string;
+    domain: string;
+    deliverable: string | null;
+}
+/**
+ * Select the best agent for a task using the two-tier stored procedure.
+ */
+export declare function selectBestAgent(taskEmbedding: number[], matchThreshold?: number, topK?: number): Promise<string>;
+/**
+ * List all available agents.
+ */
+export declare function listAgents(): Promise<Agent[]>;
+/**
+ * Get skills for a specific agent.
+ */
+export declare function getAgentSkills(agentName: string): Promise<Skill[]>;
+//# sourceMappingURL=supabase.d.ts.map

package/dist/lib/supabase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supabase.d.ts","sourceRoot":"","sources":["../../src/lib/supabase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAIrE,wBAAgB,iBAAiB,IAAI,cAAc,CAgBlD;AAED,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,KAAK;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,aAAa,EAAE,MAAM,EAAE,EACvB,cAAc,GAAE,MAAY,EAC5B,IAAI,GAAE,MAAU,GACf,OAAO,CAAC,MAAM,CAAC,CAcjB;AAED;;GAEG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CAUnD;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAYxE"}

package/dist/lib/supabase.js

@@ -0,0 +1,54 @@
+import { createClient } from "@supabase/supabase-js";
+let supabaseClient = null;
+export function getSupabaseClient() {
+    if (supabaseClient) {
+        return supabaseClient;
+    }
+    const supabaseUrl = process.env.SUPABASE_URL;
+    const supabaseKey = process.env.SUPABASE_ANON_KEY || process.env.SUPABASE_SERVICE_ROLE_KEY;
+    if (!supabaseUrl || !supabaseKey) {
+        throw new Error("Missing Supabase configuration. Set SUPABASE_URL and SUPABASE_ANON_KEY environment variables.");
+    }
+    supabaseClient = createClient(supabaseUrl, supabaseKey);
+    return supabaseClient;
+}
+/**
+ * Select the best agent for a task using the two-tier stored procedure.
+ */
+export async function selectBestAgent(taskEmbedding, matchThreshold = 0.5, topK = 5) {
+    const supabase = getSupabaseClient();
+    const { data, error } = await supabase.rpc("select_best_agent", {
+        task_embedding: taskEmbedding,
+        match_threshold: matchThreshold,
+        top_k: topK,
+    });
+    if (error) {
+        throw new Error(`Failed to select agent: ${error.message}`);
+    }
+    return data;
+}
+/**
+ * List all available agents.
+ */
+export async function listAgents() {
+    const supabase = getSupabaseClient();
+    const { data, error } = await supabase.rpc("list_agents");
+    if (error) {
+        throw new Error(`Failed to list agents: ${error.message}`);
+    }
+    return data;
+}
+/**
+ * Get skills for a specific agent.
+ */
+export async function getAgentSkills(agentName) {
+    const supabase = getSupabaseClient();
+    const { data, error } = await supabase.rpc("get_agent_skills", {
+        agent_name: agentName,
+    });
+    if (error) {
+        throw new Error(`Failed to get agent skills: ${error.message}`);
+    }
+    return data;
+}
+//# sourceMappingURL=supabase.js.map

package/dist/lib/supabase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supabase.js","sourceRoot":"","sources":["../../src/lib/supabase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAkB,MAAM,uBAAuB,CAAC;AAErE,IAAI,cAAc,GAA0B,IAAI,CAAC;AAEjD,MAAM,UAAU,iBAAiB;IAC/B,IAAI,cAAc,EAAE,CAAC;QACnB,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IAC7C,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;IAE3F,IAAI,CAAC,WAAW,IAAI,CAAC,WAAW,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,+FAA+F,CAChG,CAAC;IACJ,CAAC;IAED,cAAc,GAAG,YAAY,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACxD,OAAO,cAAc,CAAC;AACxB,CAAC;AAeD;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,aAAuB,EACvB,iBAAyB,GAAG,EAC5B,OAAe,CAAC;IAEhB,MAAM,QAAQ,GAAG,iBAAiB,EAAE,CAAC;IAErC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,mBAAmB,EAAE;QAC9D,cAAc,EAAE,aAAa;QAC7B,eAAe,EAAE,cAAc;QAC/B,KAAK,EAAE,IAAI;KACZ,CAAC,CAAC;IAEH,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,2BAA2B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,IAAc,CAAC;AACxB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,MAAM,QAAQ,GAAG,iBAAiB,EAAE,CAAC;IAErC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAE1D,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,0BAA0B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,OAAO,IAAe,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,SAAiB;IACpD,MAAM,QAAQ,GAAG,iBAAiB,EAAE,CAAC;IAErC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,kBAAkB,EAAE;QAC7D,UAAU,EAAE,SAAS;KACtB,CAAC,CAAC;IAEH,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,+BAA+B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAClE,CAAC;IAED,OAAO,IAAe,CAAC;AACzB,CAAC"}

package/dist/tools/getAgentSkills.d.ts

@@ -0,0 +1,14 @@
+import { Skill } from "../lib/supabase.js";
+export interface GetAgentSkillsInput {
+    agent_name: string;
+}
+export interface GetAgentSkillsOutput {
+    agent_name: string;
+    skills: Skill[];
+    count: number;
+}
+/**
+ * Get the skills available for a specific agent.
+ */
+export declare function getAgentSkillsTool(input: GetAgentSkillsInput): Promise<GetAgentSkillsOutput>;
+//# sourceMappingURL=getAgentSkills.d.ts.map

package/dist/tools/getAgentSkills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getAgentSkills.d.ts","sourceRoot":"","sources":["../../src/tools/getAgentSkills.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAc/B"}

package/dist/tools/getAgentSkills.js

@@ -0,0 +1,17 @@
+import { getAgentSkills } from "../lib/supabase.js";
+/**
+ * Get the skills available for a specific agent.
+ */
+export async function getAgentSkillsTool(input) {
+    const { agent_name } = input;
+    if (!agent_name || agent_name.trim().length === 0) {
+        throw new Error("Agent name is required");
+    }
+    const skills = await getAgentSkills(agent_name);
+    return {
+        agent_name,
+        skills,
+        count: skills.length,
+    };
+}
+//# sourceMappingURL=getAgentSkills.js.map

package/dist/tools/getAgentSkills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getAgentSkills.js","sourceRoot":"","sources":["../../src/tools/getAgentSkills.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAS,MAAM,oBAAoB,CAAC;AAY3D;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAA0B;IAE1B,MAAM,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC;IAE7B,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC5C,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,UAAU,CAAC,CAAC;IAEhD,OAAO;QACL,UAAU;QACV,MAAM;QACN,KAAK,EAAE,MAAM,CAAC,MAAM;KACrB,CAAC;AACJ,CAAC"}

package/dist/tools/listAgents.d.ts

@@ -0,0 +1,10 @@
+import { Agent } from "../lib/supabase.js";
+export interface ListAgentsOutput {
+    agents: Agent[];
+    count: number;
+}
+/**
+ * List all available agents with their descriptions and tools.
+ */
+export declare function listAgentsTool(): Promise<ListAgentsOutput>;
+//# sourceMappingURL=listAgents.d.ts.map

package/dist/tools/listAgents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listAgents.d.ts","sourceRoot":"","sources":["../../src/tools/listAgents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAOhE"}

package/dist/tools/listAgents.js

@@ -0,0 +1,12 @@
+import { listAgents } from "../lib/supabase.js";
+/**
+ * List all available agents with their descriptions and tools.
+ */
+export async function listAgentsTool() {
+    const agents = await listAgents();
+    return {
+        agents,
+        count: agents.length,
+    };
+}
+//# sourceMappingURL=listAgents.js.map

package/dist/tools/listAgents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listAgents.js","sourceRoot":"","sources":["../../src/tools/listAgents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAS,MAAM,oBAAoB,CAAC;AAOvD;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAElC,OAAO;QACL,MAAM;QACN,KAAK,EAAE,MAAM,CAAC,MAAM;KACrB,CAAC;AACJ,CAAC"}

package/dist/tools/selectAgent.d.ts

@@ -0,0 +1,17 @@
+export interface SelectAgentInput {
+    task: string;
+    match_threshold?: number;
+}
+export interface SelectAgentOutput {
+    agent_name: string;
+}
+/**
+ * Select the best agent for a given task description.
+ *
+ * This tool:
+ * 1. Generates an embedding for the task description
+ * 2. Calls the Supabase stored procedure to find the best matching agent
+ * 3. Returns ONLY the agent name
+ */
+export declare function selectAgentTool(input: SelectAgentInput): Promise<SelectAgentOutput>;
+//# sourceMappingURL=selectAgent.d.ts.map

package/dist/tools/selectAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectAgent.d.ts","sourceRoot":"","sources":["../../src/tools/selectAgent.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,iBAAiB,CAAC,CAgB5B"}

package/dist/tools/selectAgent.js

@@ -0,0 +1,24 @@
+import { generateEmbedding } from "../lib/embeddings.js";
+import { selectBestAgent } from "../lib/supabase.js";
+/**
+ * Select the best agent for a given task description.
+ *
+ * This tool:
+ * 1. Generates an embedding for the task description
+ * 2. Calls the Supabase stored procedure to find the best matching agent
+ * 3. Returns ONLY the agent name
+ */
+export async function selectAgentTool(input) {
+    const { task, match_threshold = 0.5 } = input;
+    if (!task || task.trim().length === 0) {
+        throw new Error("Task description is required");
+    }
+    // Generate embedding for the task
+    const taskEmbedding = await generateEmbedding(task);
+    // Call stored procedure to find best agent
+    const agentName = await selectBestAgent(taskEmbedding, match_threshold);
+    return {
+        agent_name: agentName,
+    };
+}
+//# sourceMappingURL=selectAgent.js.map

package/dist/tools/selectAgent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectAgent.js","sourceRoot":"","sources":["../../src/tools/selectAgent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAWrD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAuB;IAEvB,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,GAAG,EAAE,GAAG,KAAK,CAAC;IAE9C,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAClD,CAAC;IAED,kCAAkC;IAClC,MAAM,aAAa,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAEpD,2CAA2C;IAC3C,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;IAExE,OAAO;QACL,UAAU,EAAE,SAAS;KACtB,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "tarvacode-agent-selector",
+  "version": "1.0.0",
+  "description": "MCP server for semantic agent selection using pgvector embeddings",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "agent-selection",
+    "embeddings",
+    "pgvector"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@supabase/supabase-js": "^2.39.0",
+    "openai": "^4.28.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  Tool,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { selectAgentTool } from "./tools/selectAgent.js";
+import { listAgentsTool } from "./tools/listAgents.js";
+import { getAgentSkillsTool } from "./tools/getAgentSkills.js";
+
+const SERVER_NAME = "tarvacode-agent-selector";
+const SERVER_VERSION = "1.0.0";
+
+// Define available tools
+const TOOLS: Tool[] = [
+  {
+    name: "select_best_agent",
+    description:
+      "Finds the best specialized agent for a given task description using semantic similarity matching. Returns ONLY the agent name.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        task: {
+          type: "string",
+          description: "The task description to find the best agent for",
+        },
+        match_threshold: {
+          type: "number",
+          description:
+            "Minimum similarity score (0-1) to consider a match. Default: 0.5",
+          default: 0.5,
+        },
+      },
+      required: ["task"],
+    },
+  },
+  {
+    name: "list_agents",
+    description:
+      "Lists all available specialized agents with their descriptions and available tools.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {},
+      required: [],
+    },
+  },
+  {
+    name: "get_agent_skills",
+    description:
+      "Gets the skills available for a specific agent, organized by domain.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        agent_name: {
+          type: "string",
+          description: "The name of the agent to get skills for",
+        },
+      },
+      required: ["agent_name"],
+    },
+  },
+];
+
+async function main() {
+  const server = new Server(
+    {
+      name: SERVER_NAME,
+      version: SERVER_VERSION,
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  // Handle list tools request
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
+  });
+
+  // Handle tool calls
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    try {
+      let result: unknown;
+
+      switch (name) {
+        case "select_best_agent":
+          result = await selectAgentTool({
+            task: args?.task as string,
+            match_threshold: args?.match_threshold as number | undefined,
+          });
+          break;
+
+        case "list_agents":
+          result = await listAgentsTool();
+          break;
+
+        case "get_agent_skills":
+          result = await getAgentSkillsTool({
+            agent_name: args?.agent_name as string,
+          });
+          break;
+
+        default:
+          throw new Error(`Unknown tool: ${name}`);
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : "Unknown error occurred";
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ error: errorMessage }),
+          },
+        ],
+        isError: true,
+      };
+    }
+  });
+
+  // Start the server
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  console.error(`${SERVER_NAME} v${SERVER_VERSION} started`);
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/src/lib/embeddings.ts

@@ -0,0 +1,99 @@
+import OpenAI from "openai";
+
+const EMBEDDING_MODEL = "text-embedding-3-small";
+
+let openaiClient: OpenAI | null = null;
+
+// Simple in-memory cache with 15-minute TTL
+interface CacheEntry {
+  embedding: number[];
+  timestamp: number;
+}
+
+const embeddingCache = new Map<string, CacheEntry>();
+const CACHE_TTL_MS = 15 * 60 * 1000; // 15 minutes
+
+function getOpenAIClient(): OpenAI {
+  if (openaiClient) {
+    return openaiClient;
+  }
+
+  const apiKey = process.env.OPENAI_API_KEY;
+
+  if (!apiKey) {
+    throw new Error(
+      "Missing OpenAI configuration. Set OPENAI_API_KEY environment variable."
+    );
+  }
+
+  openaiClient = new OpenAI({ apiKey });
+  return openaiClient;
+}
+
+/**
+ * Normalize text for cache key.
+ */
+function normalizeText(text: string): string {
+  return text.trim().toLowerCase();
+}
+
+/**
+ * Clean expired cache entries.
+ */
+function cleanCache(): void {
+  const now = Date.now();
+  for (const [key, entry] of embeddingCache.entries()) {
+    if (now - entry.timestamp > CACHE_TTL_MS) {
+      embeddingCache.delete(key);
+    }
+  }
+}
+
+/**
+ * Generate embedding for a single text with caching.
+ */
+export async function generateEmbedding(text: string): Promise<number[]> {
+  const cacheKey = normalizeText(text);
+
+  // Check cache
+  const cached = embeddingCache.get(cacheKey);
+  if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS) {
+    return cached.embedding;
+  }
+
+  // Clean old entries periodically
+  if (embeddingCache.size > 100) {
+    cleanCache();
+  }
+
+  const client = getOpenAIClient();
+
+  const response = await client.embeddings.create({
+    model: EMBEDDING_MODEL,
+    input: text,
+  });
+
+  const embedding = response.data[0].embedding;
+
+  // Cache the result
+  embeddingCache.set(cacheKey, {
+    embedding,
+    timestamp: Date.now(),
+  });
+
+  return embedding;
+}
+
+/**
+ * Generate embeddings for multiple texts with batching.
+ */
+export async function generateEmbeddings(texts: string[]): Promise<number[][]> {
+  const client = getOpenAIClient();
+
+  const response = await client.embeddings.create({
+    model: EMBEDDING_MODEL,
+    input: texts,
+  });
+
+  return response.data.map((item) => item.embedding);
+}

package/src/lib/supabase.ts

@@ -0,0 +1,89 @@
+import { createClient, SupabaseClient } from "@supabase/supabase-js";
+
+let supabaseClient: SupabaseClient | null = null;
+
+export function getSupabaseClient(): SupabaseClient {
+  if (supabaseClient) {
+    return supabaseClient;
+  }
+
+  const supabaseUrl = process.env.SUPABASE_URL;
+  const supabaseKey = process.env.SUPABASE_ANON_KEY || process.env.SUPABASE_SERVICE_ROLE_KEY;
+
+  if (!supabaseUrl || !supabaseKey) {
+    throw new Error(
+      "Missing Supabase configuration. Set SUPABASE_URL and SUPABASE_ANON_KEY environment variables."
+    );
+  }
+
+  supabaseClient = createClient(supabaseUrl, supabaseKey);
+  return supabaseClient;
+}
+
+export interface Agent {
+  name: string;
+  description: string;
+  tools: string[];
+}
+
+export interface Skill {
+  skill_id: string;
+  skill_name: string;
+  domain: string;
+  deliverable: string | null;
+}
+
+/**
+ * Select the best agent for a task using the two-tier stored procedure.
+ */
+export async function selectBestAgent(
+  taskEmbedding: number[],
+  matchThreshold: number = 0.5,
+  topK: number = 5
+): Promise<string> {
+  const supabase = getSupabaseClient();
+
+  const { data, error } = await supabase.rpc("select_best_agent", {
+    task_embedding: taskEmbedding,
+    match_threshold: matchThreshold,
+    top_k: topK,
+  });
+
+  if (error) {
+    throw new Error(`Failed to select agent: ${error.message}`);
+  }
+
+  return data as string;
+}
+
+/**
+ * List all available agents.
+ */
+export async function listAgents(): Promise<Agent[]> {
+  const supabase = getSupabaseClient();
+
+  const { data, error } = await supabase.rpc("list_agents");
+
+  if (error) {
+    throw new Error(`Failed to list agents: ${error.message}`);
+  }
+
+  return data as Agent[];
+}
+
+/**
+ * Get skills for a specific agent.
+ */
+export async function getAgentSkills(agentName: string): Promise<Skill[]> {
+  const supabase = getSupabaseClient();
+
+  const { data, error } = await supabase.rpc("get_agent_skills", {
+    agent_name: agentName,
+  });
+
+  if (error) {
+    throw new Error(`Failed to get agent skills: ${error.message}`);
+  }
+
+  return data as Skill[];
+}

package/src/tools/getAgentSkills.ts

@@ -0,0 +1,32 @@
+import { getAgentSkills, Skill } from "../lib/supabase.js";
+
+export interface GetAgentSkillsInput {
+  agent_name: string;
+}
+
+export interface GetAgentSkillsOutput {
+  agent_name: string;
+  skills: Skill[];
+  count: number;
+}
+
+/**
+ * Get the skills available for a specific agent.
+ */
+export async function getAgentSkillsTool(
+  input: GetAgentSkillsInput
+): Promise<GetAgentSkillsOutput> {
+  const { agent_name } = input;
+
+  if (!agent_name || agent_name.trim().length === 0) {
+    throw new Error("Agent name is required");
+  }
+
+  const skills = await getAgentSkills(agent_name);
+
+  return {
+    agent_name,
+    skills,
+    count: skills.length,
+  };
+}

package/src/tools/listAgents.ts

@@ -0,0 +1,18 @@
+import { listAgents, Agent } from "../lib/supabase.js";
+
+export interface ListAgentsOutput {
+  agents: Agent[];
+  count: number;
+}
+
+/**
+ * List all available agents with their descriptions and tools.
+ */
+export async function listAgentsTool(): Promise<ListAgentsOutput> {
+  const agents = await listAgents();
+
+  return {
+    agents,
+    count: agents.length,
+  };
+}

package/src/tools/selectAgent.ts

@@ -0,0 +1,39 @@
+import { generateEmbedding } from "../lib/embeddings.js";
+import { selectBestAgent } from "../lib/supabase.js";
+
+export interface SelectAgentInput {
+  task: string;
+  match_threshold?: number;
+}
+
+export interface SelectAgentOutput {
+  agent_name: string;
+}
+
+/**
+ * Select the best agent for a given task description.
+ *
+ * This tool:
+ * 1. Generates an embedding for the task description
+ * 2. Calls the Supabase stored procedure to find the best matching agent
+ * 3. Returns ONLY the agent name
+ */
+export async function selectAgentTool(
+  input: SelectAgentInput
+): Promise<SelectAgentOutput> {
+  const { task, match_threshold = 0.5 } = input;
+
+  if (!task || task.trim().length === 0) {
+    throw new Error("Task description is required");
+  }
+
+  // Generate embedding for the task
+  const taskEmbedding = await generateEmbedding(task);
+
+  // Call stored procedure to find best agent
+  const agentName = await selectBestAgent(taskEmbedding, match_threshold);
+
+  return {
+    agent_name: agentName,
+  };
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}