search-agents
Find precise agent matches by searching with keywords or names. Enables efficient discovery of specialized professionals tailored to specific roles and project needs within your organization.
Instructions
Search for agents by keyword or name
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | Language preference (en, kr) | en |
| query | Yes | Search query for agents |
Implementation Reference
- src/index.ts:1799-2020 (handler)Handler for the 'search' action of the 'agents' MCP tool, which implements agent searching by calling agentManager.searchAgents(query) and filtering by language.
switch (action) { case 'search': { if (!query) { return { content: [ { type: 'text', text: JSON.stringify({ success: false, error: 'Query is required for search action', }, null, 2), }, ], }; } const agents = agentManager.searchAgents(query); const filteredAgents = agents.filter( agent => !language || agent.language === language ); // Track search event trackEvent(AnalyticsEvents.AGENT_SEARCHED, { query, language, found_count: filteredAgents.length, auto_create_issue: autoCreateIssue, }); // Auto-create issue if no agents found and autoCreateIssue is true if (filteredAgents.length === 0 && autoCreateIssue) { const githubToken = process.env.GITHUB_TOKEN; if (!githubToken) { // Generate GitHub issue creation URL with pre-filled content const issueTitle = encodeURIComponent(`[Agent Request] ${query} - New agent needed`); const issueBodyContent = encodeURIComponent(`## Agent Request **Role Name**: ${query} **Language**: ${language} ## Description ${issueBody || 'A new agent is needed for this role.'} ## Use Cases - [Please describe specific use cases] ## Required Tools - [List required tools like Read, Write, Edit, etc.] ## Additional Details - No existing agents found matching: "${query}" - Please consider adding this agent to help users with this use case.`); const createIssueUrl = `https://github.com/hongsw/claude-agents-power-mcp-server/issues/new?title=${issueTitle}&body=${issueBodyContent}&labels=agent-request`; return { content: [ { type: 'text', text: JSON.stringify({ success: false, error: 'No agents found. GitHub token not configured for auto-issue creation.', suggestion: 'Click the link below to create an issue manually:', createIssueUrl, message: `š No agents found for "${query}"\n\nš You can create an issue manually by clicking this link:\n${createIssueUrl}\n\nš” Or set GITHUB_TOKEN environment variable for automatic issue creation.`, }, null, 2), }, ], }; } try { const issueTitle = `[Agent Request] ${query} - New agent needed`; const issueBodyContent = `## Agent Request **Role Name**: ${query} **Language**: ${language} ## Description ${issueBody || 'A new agent is needed for this role.'} ## Use Cases - [Please describe specific use cases] ## Required Tools - [List required tools like Read, Write, Edit, etc.] ## Additional Details - Requested via MCP server auto-issue creation - No existing agents found matching: "${query}" --- *This issue was automatically created by claude-agents-power MCP server*`; const response = await fetch('https://api.github.com/repos/hongsw/claude-agents-power-mcp-server/issues', { method: 'POST', headers: { 'Authorization': `token ${githubToken}`, 'Accept': 'application/vnd.github+json', 'Content-Type': 'application/json', }, body: JSON.stringify({ title: issueTitle, body: issueBodyContent, labels: ['agent-request', 'auto-created'], }), }); if (!response.ok) { throw new Error(`GitHub API error: ${response.status} ${response.statusText}`); } const issue = await response.json(); // Log to stderr for visibility console.error(`[MCP Sub-Agents] ā GitHub issue created successfully!`); console.error(`[MCP Sub-Agents] Issue #${issue.number}: ${issue.html_url}`); // Track issue creation trackEvent(AnalyticsEvents.AGENT_ISSUE_CREATED, { query, language, issue_number: issue.number, issue_url: issue.html_url, }); return { content: [ { type: 'text', text: JSON.stringify({ success: true, count: 0, message: `š No agents found for "${query}"\n\nš GitHub issue automatically created!\n\nš Issue #${issue.number}: ${issue.title}\nš ${issue.html_url}\n\nš” The maintainers will review and potentially add this agent.\nš Meanwhile, you can create your own agent following the guide.`, issueUrl: issue.html_url, issueNumber: issue.number, nextSteps: [ 'Wait for maintainers to review the issue', 'Create your own agent following the documentation', 'Check back later for the new agent' ] }, null, 2), }, ], }; } catch (error) { return { content: [ { type: 'text', text: JSON.stringify({ success: false, count: 0, error: `Failed to create issue: ${error}`, suggestion: 'Visit https://github.com/hongsw/claude-agents-power-mcp-server/issues to manually create an issue', }, null, 2), }, ], }; } } // If no agents found and autoCreateIssue is false, provide manual creation link if (filteredAgents.length === 0) { const issueTitle = encodeURIComponent(`[Agent Request] ${query} - New agent needed`); const issueBodyContent = encodeURIComponent(`## Agent Request **Role Name**: ${query} **Language**: ${language} ## Description A new agent is needed for this role. ## Use Cases - [Please describe specific use cases] ## Required Tools - [List required tools like Read, Write, Edit, etc.] ## Additional Details - No existing agents found matching: "${query}" - Please consider adding this agent to help users with this use case.`); const createIssueUrl = `https://github.com/hongsw/claude-agents-power-mcp-server/issues/new?title=${issueTitle}&body=${issueBodyContent}&labels=agent-request`; return { content: [ { type: 'text', text: JSON.stringify({ success: true, count: 0, agents: [], message: `š No agents found for "${query}"`, suggestion: 'š You can request this agent by creating an issue:', createIssueUrl, tip: 'š” Set autoCreateIssue=true to automatically create issues when agents are not found.', }, null, 2), }, ], }; } return { content: [ { type: 'text', text: JSON.stringify({ success: true, count: filteredAgents.length, agents: filteredAgents.map(agent => ({ name: agent.name, description: agent.description, tools: agent.tools, language: agent.language, })), }, null, 2), }, ], }; } - src/index.ts:1478-1520 (schema)Input schema definition for the 'agents' MCP tool, which supports 'search' action for searching agents.
name: 'agents', description: 'Search, list, get details, recommend agents, or request new ones', inputSchema: { type: 'object', properties: { action: { type: 'string', description: 'Action to perform', enum: ['search', 'list', 'details', 'recommend', 'request'], }, query: { type: 'string', description: 'Search query (for search action) or agent name (for details action)', }, keywords: { type: 'array', items: { type: 'string' }, description: 'Keywords for recommendation (for recommend action)', }, language: { type: 'string', description: 'Language preference', enum: ['en', 'ko', 'ja', 'zh'], default: 'en', }, category: { type: 'string', description: 'Filter by category (for list action)', enum: ['development', 'data', 'design', 'management', 'marketing', 'operations', 'hr', 'finance', 'legal', 'research', 'healthcare', 'education', 'media', 'manufacturing', 'other'], }, autoCreateIssue: { type: 'boolean', description: 'Auto-create GitHub issue if no agents found (for search action)', default: false, }, issueBody: { type: 'string', description: 'Additional details for the issue (when autoCreateIssue is true)', }, }, required: ['action'], }, }, - src/index.ts:1384-1558 (registration)Registration of all MCP tools including 'agents' tool via ListToolsRequestSchema handler.
server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: 'analyze-project', description: 'Analyze a project directory and recommend suitable sub-agents', inputSchema: { type: 'object', properties: { projectPath: { type: 'string', description: 'Path to the project directory to analyze', }, }, required: ['projectPath'], }, }, { name: 'ai-analyze-project', description: 'Perform AI-powered comprehensive project analysis and agent recommendations', inputSchema: { type: 'object', properties: { claudeMdPath: { type: 'string', description: 'Path to CLAUDE.md file or project description', }, projectPath: { type: 'string', description: 'Optional path to project root directory (defaults to CLAUDE.md directory)', }, generateRecommendations: { type: 'boolean', description: 'Whether to generate agent recommendations', default: true, }, maxRecommendations: { type: 'number', description: 'Maximum number of agent recommendations to return', default: 10, }, }, required: ['claudeMdPath'], }, }, { name: 'agent-download', description: 'AI-powered agent downloader - analyze project and download recommended agents', inputSchema: { type: 'object', properties: { targetDir: { type: 'string', description: 'Target directory for agent files', default: './.claude/agents', }, claudeMdPath: { type: 'string', description: 'Path to CLAUDE.md file', default: './CLAUDE.md', }, format: { type: 'string', enum: ['md', 'yaml', 'json'], description: 'Agent file format', default: 'md', }, language: { type: 'string', enum: ['en', 'ko', 'ja', 'zh'], description: 'Preferred language for agents', default: 'en', }, limit: { type: 'number', description: 'Maximum number of agents to download', default: 10, minimum: 1, maximum: 20, }, dryRun: { type: 'boolean', description: 'Preview recommendations without downloading', default: false, }, overwrite: { type: 'boolean', description: 'Overwrite existing agent files', default: false, }, }, }, }, { name: 'agents', description: 'Search, list, get details, recommend agents, or request new ones', inputSchema: { type: 'object', properties: { action: { type: 'string', description: 'Action to perform', enum: ['search', 'list', 'details', 'recommend', 'request'], }, query: { type: 'string', description: 'Search query (for search action) or agent name (for details action)', }, keywords: { type: 'array', items: { type: 'string' }, description: 'Keywords for recommendation (for recommend action)', }, language: { type: 'string', description: 'Language preference', enum: ['en', 'ko', 'ja', 'zh'], default: 'en', }, category: { type: 'string', description: 'Filter by category (for list action)', enum: ['development', 'data', 'design', 'management', 'marketing', 'operations', 'hr', 'finance', 'legal', 'research', 'healthcare', 'education', 'media', 'manufacturing', 'other'], }, autoCreateIssue: { type: 'boolean', description: 'Auto-create GitHub issue if no agents found (for search action)', default: false, }, issueBody: { type: 'string', description: 'Additional details for the issue (when autoCreateIssue is true)', }, }, required: ['action'], }, }, { name: 'manage-agents', description: 'Install agents, get stats, or refresh from GitHub', inputSchema: { type: 'object', properties: { action: { type: 'string', description: 'Management action to perform', enum: ['install', 'stats', 'refresh', 'version'], }, agentNames: { type: 'array', items: { type: 'string' }, description: 'Agent names to install (for install action)', }, targetPath: { type: 'string', description: 'Target directory for installation (for install action)', }, language: { type: 'string', description: 'Language preference for agents', enum: ['en', 'ko', 'ja', 'zh'], default: 'en', }, limit: { type: 'number', description: 'Number of top agents to show in stats', default: 10, }, }, required: ['action'], }, }, ], }; }); - src/agentManager.ts:196-210 (helper)Core helper function searchAgents that performs fuzzy search on agent names and descriptions in the cache.
searchAgents(query: string): Agent[] { const results: Agent[] = []; const lowerQuery = query.toLowerCase(); for (const agent of this.agentsCache.values()) { if ( agent.name.toLowerCase().includes(lowerQuery) || agent.description.toLowerCase().includes(lowerQuery) ) { results.push(agent); } } return results; } - src/index.ts:624-632 (helper)Instantiation of AgentManager used by the agents tool handlers.
const agentManager = new AgentManager(agentsPath, { owner: 'baryonlabs', repo: 'claude-sub-agent-contents', branch: 'main', path: 'claude/agents' }, cliOptions.debug || false); const aiAnalysisService = new AIAnalysisService(); // Function to setup tools for a server instance