search-agents
Search for specialized agents by keyword or name to find professional roles for project tasks and team compositions. Supports language preferences for efficient results.
Instructions
Search for agents by keyword or name
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | Language preference (en, ko) | en |
| query | Yes | Search query for agents |
Implementation Reference
- src/agentManager.ts:196-210 (handler)Core implementation of agent search functionality. Performs case-insensitive substring matching on agent names and descriptions from the cached agents.
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:1800-2022 (handler)MCP tool handler for the 'agents' tool with 'search' action. Invokes agentManager.searchAgents(query) and handles response formatting, language filtering, and GitHub issue creation if no results.
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), }, ], }; } case 'list': { let agents = agentManager.getAllAgents(language); - src/index.ts:1478-1520 (schema)Input schema for the MCP 'agents' tool, defining the 'search' action and required 'query' parameter 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:1386-1557 (registration)Registration of all MCP tools in ListToolsRequestSchema handler, including the 'agents' tool that provides search-agents functionality via action='search'.
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'], }, }, ], };