octocode-mcp 1.0.0

package/build/index.js

@@ -0,0 +1,2371 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import z from 'zod';
+import { exec, execSync } from 'child_process';
+import { promisify } from 'util';
+import NodeCache from 'node-cache';
+import crypto from 'crypto';
+
+const TOOL_NAMES = {
+    SEARCH_GITHUB_CODE: 'search_github_code',
+    FETCH_GITHUB_FILE_CONTENT: 'fetch_github_file_content',
+    VIEW_REPOSITORY: 'view_repository',
+    NPM_VIEW: 'npm_view',
+    SEARCH_GITHUB_REPOS: 'search_github_repos',
+    SEARCH_GITHUB_COMMITS: 'search_github_commits',
+    SEARCH_GITHUB_PULL_REQUESTS: 'search_github_pull_requests',
+    GET_USER_ORGANIZATIONS: 'get_user_organizations',
+    NPM_SEARCH: 'npm_search',
+    VIEW_REPOSITORY_STRUCTURE: 'view_repository_structure',
+    SEARCH_GITHUB_ISSUES: 'search_github_issues',
+    SEARCH_GITHUB_DISCUSSIONS: 'search_github_discussions',
+    SEARCH_GITHUB_TOPICS: 'search_github_topics',
+    SEARCH_GITHUB_USERS: 'search_github_users',
+};
+const INDEX_MAP = {
+    CRITICAL: '#CRITICAL#',
+    WARNING: '#WARNING#',
+    CODE: '#CODE#',
+    VALIDATION: '#VALIDATION#',
+    USER: '#USER#',
+    EFFICIENCY: '#EFFICIENCY#',
+};
+
+const PROMPT_SYSTEM_PROMPT = `Expert code discovery assistant with advanced reasoning capabilities. Find production-ready code examples from GitHub/npm using sophisticated research workflows.
+
+## ${INDEX_MAP.CRITICAL} CORE REQUIREMENTS
+- ${INDEX_MAP.CODE} **3+ COMPLETE CODE EXAMPLES** (20+ lines) with syntax highlighting
+- ${INDEX_MAP.CODE} **REPOSITORY CITATIONS**: \`\`\`language:owner/repo/filepath
+- ${INDEX_MAP.CODE} **WORKING IMPLEMENTATIONS** with imports/exports/context
+- ${INDEX_MAP.CODE} **REPOSITORY LINKS** for each example
+
+## ${INDEX_MAP.EFFICIENCY} ADVANCED RESEARCH METHODOLOGY
+
+**🧠 CHAIN-OF-THOUGHT REASONING:**
+1. **UNDERSTAND INTENT**: Analyze user query complexity and extract core requirements
+2. **DECOMPOSE PROBLEM**: Break complex queries into searchable components
+3. **HYPOTHESIS FORMATION**: Predict likely implementation patterns and technologies
+4. **EVIDENCE GATHERING**: Execute targeted searches to validate/refute hypotheses
+5. **SYNTHESIS**: Combine findings into coherent, actionable insights
+6. **VALIDATION**: Cross-reference multiple sources for accuracy
+
+**🔍 MULTI-STEP RESEARCH FLOWS:**
+
+**EXPLORATORY DISCOVERY:**
+1. ${TOOL_NAMES.SEARCH_GITHUB_TOPICS} → Semantic landscape mapping
+2. ${TOOL_NAMES.SEARCH_GITHUB_REPOS} → Repository ecosystem analysis
+3. ${TOOL_NAMES.SEARCH_GITHUB_CODE} → Implementation pattern discovery
+4. Cross-validation via ${TOOL_NAMES.SEARCH_GITHUB_ISSUES} + ${TOOL_NAMES.SEARCH_GITHUB_PULL_REQUESTS}
+
+**DEEP IMPLEMENTATION ANALYSIS:**
+1. ${TOOL_NAMES.VIEW_REPOSITORY} → Context establishment
+2. ${TOOL_NAMES.VIEW_REPOSITORY_STRUCTURE} → Architecture understanding
+3. ${TOOL_NAMES.FETCH_GITHUB_FILE_CONTENT} → Core implementation extraction
+4. ${TOOL_NAMES.SEARCH_GITHUB_COMMITS} → Evolution tracking
+
+**COMPARATIVE RESEARCH:**
+1. Parallel repository analysis across multiple solutions
+2. Cross-reference implementation approaches
+3. Analyze trade-offs via issue/PR discussions
+4. Synthesize best practices from multiple sources
+
+**ORGANIZATIONAL INTELLIGENCE:**
+- **Auto-trigger ${TOOL_NAMES.GET_USER_ORGANIZATIONS}** when company context detected
+- **Prioritize internal repositories** for relevant findings
+- **Cross-organizational pattern analysis** for knowledge transfer
+
+## ${INDEX_MAP.VALIDATION} ADAPTIVE SEARCH STRATEGIES
+
+**PROGRESSIVE COMPLEXITY:**
+- **Simple Query**: Single tool → immediate results
+- **Medium Query**: 2-3 tools → comparative analysis  
+- **Complex Query**: Full research flow → comprehensive investigation
+
+**DYNAMIC STOPPING CRITERIA:**
+- **High Confidence**: 3+ quality examples with validation
+- **Medium Confidence**: Continue with related searches
+- **Low Confidence**: Expand search scope or acknowledge limitations
+
+**QUALITY VALIDATION PIPELINE:**
+1. **Repository Quality**: >1K stars OR recent activity OR enterprise usage
+2. **Code Quality**: Production patterns, error handling, documentation
+3. **Cross-Validation**: Multiple sources confirm patterns
+4. **Recency**: Prefer modern implementations and active maintenance
+
+## ${INDEX_MAP.USER} SOPHISTICATED RESPONSE STRATEGIES
+
+**REASONING TRANSPARENCY:**
+- Show hypothesis formation and validation process
+- Explain search strategy decisions and pivots
+- Highlight confidence levels and evidence strength
+
+**CONTEXTUAL ADAPTATION:**
+- **Beginner-friendly**: Include learning context and explanations
+- **Expert-level**: Focus on nuanced implementation details
+- **Organizational**: Emphasize internal patterns and knowledge transfer
+
+**MULTI-PERSPECTIVE ANALYSIS:**
+- **Technical**: Implementation details and architecture
+- **Strategic**: Adoption patterns and ecosystem trends  
+- **Practical**: Real-world usage and gotchas
+
+**WORKING CODE EXAMPLES:**
+\`\`\`language:owner/repo/filepath
+// Complete implementation with reasoning context
+// Why this approach? What alternatives exist?
+// Production considerations and trade-offs
+\`\`\`
+
+**CONSTRAINTS & QUALITY GATES:**
+- Extract code from results with implementation context
+- Provide reasoning for tool selection and search strategies
+- Acknowledge uncertainty and suggest follow-up investigations
+- Prioritize user organization repos when relevant
+
+**DO NOT PROVIDE:**
+- ${INDEX_MAP.WARNING} Repository lists without extracted implementations
+- ${INDEX_MAP.WARNING} Descriptions without working examples
+- ${INDEX_MAP.WARNING} Single-source conclusions without validation
+- ${INDEX_MAP.WARNING} Recommendations without evidence-based reasoning`;
+
+const execAsync = promisify(exec);
+const cache = new NodeCache({
+    stdTTL: 3600, // 1 hour cache
+    checkperiod: 600, // Check for expired keys every 10 minutes
+});
+function generateCacheKey(prefix, params) {
+    const paramString = JSON.stringify(params, Object.keys(params).sort());
+    const hash = crypto.createHash('md5').update(paramString).digest('hex');
+    return `${prefix}:${hash}`;
+}
+async function withCache(cacheKey, operation) {
+    // Check if result exists in cache
+    const cachedResult = cache.get(cacheKey);
+    if (cachedResult) {
+        return cachedResult;
+    }
+    // Execute operation
+    const result = await operation();
+    // Only cache successful responses
+    if (!result.isError) {
+        cache.set(cacheKey, result);
+    }
+    return result;
+}
+async function searchGitHubCode(params) {
+    const cacheKey = generateCacheKey('gh-code', params);
+    return withCache(cacheKey, async () => {
+        try {
+            const command = buildGitHubCodeSearchCommand(params);
+            const content = execSync(command, { encoding: 'utf-8' });
+            const result = {
+                searchType: 'code',
+                query: params.query || '',
+                results: content,
+                rawOutput: content,
+            };
+            return createSuccessResult(result);
+        }
+        catch (error) {
+            return createErrorResult('Failed to search GitHub code', error);
+        }
+    });
+}
+async function searchGitHubCommits(params) {
+    const cacheKey = generateCacheKey('gh-commits', params);
+    return withCache(cacheKey, async () => {
+        try {
+            const command = buildGitHubCommitsSearchCommand(params);
+            const content = execSync(command, { encoding: 'utf-8' });
+            const result = {
+                searchType: 'commits',
+                query: params.query || '',
+                results: content,
+                rawOutput: content,
+            };
+            return createSuccessResult(result);
+        }
+        catch (error) {
+            return createErrorResult('Failed to search GitHub commits', error);
+        }
+    });
+}
+async function searchGitHubPullRequests(params) {
+    const cacheKey = generateCacheKey('gh-prs', params);
+    return withCache(cacheKey, async () => {
+        try {
+            const command = buildGitHubPullRequestsSearchCommand(params);
+            const content = execSync(command, { encoding: 'utf-8' });
+            const result = {
+                searchType: 'prs',
+                query: params.query || '',
+                results: content,
+                rawOutput: content,
+            };
+            return createSuccessResult(result);
+        }
+        catch (error) {
+            return createErrorResult('Failed to search GitHub pull requests', error);
+        }
+    });
+}
+async function searchGitHubRepos(params) {
+    const cacheKey = generateCacheKey('gh-repos', params);
+    return withCache(cacheKey, async () => {
+        try {
+            const command = buildGitHubReposSearchCommand(params);
+            const content = execSync(command, { encoding: 'utf-8' });
+            const result = {
+                searchType: 'repos',
+                query: params.query || '',
+                results: content,
+                rawOutput: content,
+            };
+            return createSuccessResult(result);
+        }
+        catch (error) {
+            return createErrorResult('Failed to search GitHub repositories', error);
+        }
+    });
+}
+async function viewGitHubRepositoryInfo(params) {
+    const cacheKey = generateCacheKey('gh-repo-view', params);
+    return withCache(cacheKey, async () => {
+        try {
+            const owner = params.owner || '';
+            const command = `gh repo view ${owner}/${params.repo}`;
+            const content = execSync(command, { encoding: 'utf-8' });
+            const result = {
+                owner,
+                repo: params.repo,
+                repositoryInfo: content,
+                rawOutput: content,
+            };
+            return createSuccessResult(result);
+        }
+        catch (error) {
+            return createErrorResult('Failed to view GitHub repository', error);
+        }
+    });
+}
+async function getUserOrganizations(params) {
+    const cacheKey = generateCacheKey('gh-orgs', params);
+    return withCache(cacheKey, async () => {
+        try {
+            const limit = params.limit || 30;
+            const command = `gh org list --limit ${limit}`;
+            const output = execSync(command, {
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `GitHub Organizations for authenticated user:
+
+${output}
+
+ IMPORTANT: Use any of these organization names as the 'owner' parameter in other search tools:
+- search_github_code
+- search_github_repos  
+- search_github_commits
+- search_github_pull_requests
+- fetch_github_file_content
+- view_repository
+
+Example: If you see a private repository in the list above, use the organization name as the 'owner' to filter results to that organization.
+If the search for code or repositories by owner fails, try searching without an owner filter`,
+                    },
+                ],
+                isError: false,
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get user organizations: ${error.message}
+
+Make sure you are authenticated with GitHub CLI (gh auth login) and have access to organizations.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+async function fetchGitHubFileContent(params) {
+    const cacheKey = generateCacheKey('gh-file-content', params);
+    return withCache(cacheKey, async () => {
+        try {
+            const command = `gh api /repos/${params.owner}/${params.repo}/contents/${params.filePath}?ref=${params.branch} --jq .content | base64 -d`;
+            const content = execSync(command, { encoding: 'utf-8' });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: content,
+                    },
+                ],
+                isError: false,
+            };
+        }
+        catch (error) {
+            return createErrorResult('Failed to retrieve file content', error);
+        }
+    });
+}
+async function npmView(packageName) {
+    const cacheKey = generateCacheKey('npm-view', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const { stdout } = await execAsync(`npm view ${packageName} repository.url repository.directory dependencies devdependencies peerDependencies version --json`);
+            const result = JSON.parse(stdout);
+            return createSuccessResult(result);
+        }
+        catch (error) {
+            return createErrorResult('Failed to get npm repository information', error);
+        }
+    });
+}
+async function npmSearch(args) {
+    const { query, json = true, searchlimit = 20 } = args;
+    let command = `npm search "${query}" --searchlimit=${searchlimit}`;
+    if (json) {
+        command += ' --json';
+    }
+    try {
+        const { stdout, stderr } = await execAsync(command);
+        if (stderr) {
+            return {
+                content: [{ type: 'text', text: `Error searching NPM: ${stderr}` }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: 'text', text: stdout }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to execute npm search: ${error.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+async function viewRepositoryStructure(params) {
+    const cacheKey = generateCacheKey('gh-repo-structure', params);
+    return withCache(cacheKey, async () => {
+        const { owner, repo, branch, path: requestedPath = '' } = params;
+        const directoryListing = [];
+        let apiResponse = null;
+        let actualBranch = branch;
+        // Define branch fallback order
+        const branchFallbacks = [branch, 'main', 'master', 'develop', 'trunk'];
+        try {
+            // Construct the path segment
+            const pathSegment = requestedPath.startsWith('/')
+                ? requestedPath.substring(1)
+                : requestedPath;
+            // Try each branch in the fallback order
+            let lastError = null;
+            let success = false;
+            for (const tryBranch of branchFallbacks) {
+                try {
+                    const command = `gh api repos/${owner}/${repo}/contents/${pathSegment}?ref=${tryBranch}`;
+                    const stdout = execSync(command, { encoding: 'utf-8' });
+                    const items = JSON.parse(stdout);
+                    // If we get here, the request succeeded
+                    apiResponse = items;
+                    actualBranch = tryBranch;
+                    success = true;
+                    // Populate directoryListing with names of items at the current path
+                    if (Array.isArray(items)) {
+                        for (const item of items) {
+                            let itemName = item.name;
+                            if (item.type === 'dir') {
+                                itemName += '/';
+                            }
+                            directoryListing.push(itemName);
+                        }
+                    }
+                    else if (items) {
+                        // Handle single file case (though unusual for structure view)
+                        if (items.name) {
+                            directoryListing.push(items.type === 'dir' ? `${items.name}/` : items.name);
+                        }
+                    }
+                    break; // Success, exit the loop
+                }
+                catch (error) {
+                    lastError = error instanceof Error ? error : new Error(String(error));
+                    // If this is not a 404 error (branch not found), or if it's the last attempt, break
+                    const errorMessage = lastError.message.toLowerCase();
+                    if (!errorMessage.includes('no commit found') &&
+                        !errorMessage.includes('404') &&
+                        !errorMessage.includes('not found')) {
+                        // This is a different kind of error (permissions, network, etc.), don't continue fallback
+                        break;
+                    }
+                    // Continue to next branch fallback
+                    continue;
+                }
+            }
+            if (!success) {
+                // All branch attempts failed
+                const attemptedBranches = branchFallbacks.join(', ');
+                throw new Error(`Failed to access repository structure. Tried branches: ${attemptedBranches}. ` +
+                    `Last error: ${lastError?.message || 'Unknown error'}`);
+            }
+            directoryListing.sort(); // Sort for consistent output
+            const result = {
+                owner,
+                repo,
+                branch: actualBranch, // Include the branch that actually worked
+                structure: directoryListing,
+                rawOutput: apiResponse,
+                // Add metadata about branch fallback if different from requested
+                ...(actualBranch !== branch && {
+                    branchFallback: {
+                        requested: branch,
+                        used: actualBranch,
+                        message: `Branch '${branch}' not found, used '${actualBranch}' instead`,
+                    },
+                }),
+            };
+            return createSuccessResult(result);
+        }
+        catch (error) {
+            // Final error handling with comprehensive error message
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return createErrorResult(`Failed to view GitHub repository structure for ${owner}/${repo} at path '${requestedPath}': ${errorMessage}`, error);
+        }
+    });
+}
+async function searchGitHubIssues(params) {
+    const cacheKey = generateCacheKey('gh-issues', params);
+    return withCache(cacheKey, async () => {
+        try {
+            const command = buildGitHubIssuesSearchCommand(params);
+            const content = execSync(command, { encoding: 'utf-8' });
+            const result = {
+                searchType: 'issues',
+                query: params.query || '',
+                results: content,
+                rawOutput: content,
+            };
+            return createSuccessResult(result);
+        }
+        catch (error) {
+            return createErrorResult('Failed to search GitHub issues', error);
+        }
+    });
+}
+async function searchGitHubTopics(params) {
+    const cacheKey = generateCacheKey('gh-topics', params);
+    return withCache(cacheKey, async () => {
+        try {
+            // Use GitHub API for topics search since gh search topics doesn't exist
+            const command = buildGitHubTopicsAPICommand(params);
+            const content = execSync(command, { encoding: 'utf-8' });
+            const result = {
+                searchType: 'topics',
+                query: params.query || '',
+                results: content,
+                rawOutput: content,
+            };
+            return createSuccessResult(result);
+        }
+        catch (error) {
+            return createErrorResult('Failed to search GitHub topics', error);
+        }
+    });
+}
+async function searchGitHubUsers(params) {
+    const cacheKey = generateCacheKey('gh-users', params);
+    return withCache(cacheKey, async () => {
+        try {
+            // Use GitHub API for users search since gh search users doesn't exist
+            const command = buildGitHubUsersAPICommand(params);
+            const content = execSync(command, { encoding: 'utf-8' });
+            const result = {
+                searchType: 'users',
+                query: params.query || '',
+                results: content,
+                rawOutput: content,
+            };
+            return createSuccessResult(result);
+        }
+        catch (error) {
+            return createErrorResult('Failed to search GitHub users', error);
+        }
+    });
+}
+async function searchGitHubDiscussions(params) {
+    const cacheKey = generateCacheKey('gh-discussions', params);
+    return withCache(cacheKey, async () => {
+        try {
+            // Use GitHub API for discussions search since gh search discussions doesn't exist
+            const command = buildGitHubDiscussionsAPICommand(params);
+            const content = execSync(command, { encoding: 'utf-8' });
+            const result = {
+                searchType: 'discussions',
+                query: params.query || '',
+                results: content,
+                rawOutput: content,
+            };
+            // Parse the response to check if we have any discussions
+            try {
+                const parsedContent = JSON.parse(content);
+                const discussionCount = parsedContent?.data?.search?.discussionCount || 0;
+                // If no discussions found and we have a specific owner, provide helpful context
+                if (discussionCount === 0 && params.owner) {
+                    const scopeInfo = params.repo
+                        ? `repository "${params.owner}/${params.repo}"`
+                        : `organization "${params.owner}"`;
+                    result.results = JSON.stringify({
+                        ...parsedContent,
+                        searchInfo: {
+                            message: `No discussions found in ${scopeInfo}. This search was scoped to ${params.owner} only and did not search other organizations. The repository may not have discussions enabled.`,
+                            searchScope: params.repo
+                                ? `repo:${params.owner}/${params.repo}`
+                                : `org:${params.owner}`,
+                            query: params.query,
+                            discussionCount: 0,
+                        },
+                    }, null, 2);
+                }
+            }
+            catch (parseError) {
+                // If we can't parse the JSON, just return the original result
+            }
+            return createSuccessResult(result);
+        }
+        catch (error) {
+            return createErrorResult('Failed to search GitHub discussions', error);
+        }
+    });
+}
+function buildGitHubCodeSearchCommand(params) {
+    // Apply progressive single-word search strategy for optimal discovery
+    const processedQuery = processSearchQuery(params.query || '');
+    let command = `gh search code ${processedQuery}`;
+    if (params.owner)
+        command += ` --owner ${params.owner}`;
+    if (params.repo)
+        command += ` --repo ${params.repo}`;
+    if (params.language)
+        command += ` --language ${params.language}`;
+    if (params.filename)
+        command += ` --filename ${params.filename}`;
+    if (params.extension)
+        command += ` --extension ${params.extension}`;
+    if (params.match)
+        command += ` --match ${params.match}`;
+    if (params.limit)
+        command += ` --limit ${params.limit}`;
+    return command;
+}
+/**
+ * Process search query to implement progressive single-word search strategy:
+ * - Prioritize single terms over combined searches
+ * - "RAG" stays as "RAG" (single word search)
+ * - "RAG Ranking" becomes "RAG" (use first term only for initial search)
+ * - Only combine terms when explicitly needed after initial searches
+ * - Preserve quoted phrases as-is for exact matches
+ */
+function processSearchQuery(query) {
+    if (!query)
+        return '""';
+    // Check if query is already properly quoted single term
+    const singleQuotedPattern = /^"[^"]*"$/;
+    if (singleQuotedPattern.test(query.trim())) {
+        return query.trim();
+    }
+    // Check if query is multiple quoted terms (advanced search)
+    const multipleQuotedPattern = /^(\s*"[^"]+"\s*)+$/;
+    if (multipleQuotedPattern.test(query.trim())) {
+        return query.trim();
+    }
+    // Plain text query - PRIORITIZE SINGLE WORDS for progressive search
+    const terms = query
+        .trim()
+        .split(/\s+/)
+        .filter(term => term.length > 0);
+    if (terms.length === 0)
+        return '""';
+    // FOR PROGRESSIVE SEARCH: Use only the first term initially
+    // This implements the "RAG" then "Ranking" strategy instead of "RAG Ranking"
+    if (terms.length === 1) {
+        return `"${terms[0]}"`;
+    }
+    // For multiple terms, prioritize the first term (most important)
+    // This encourages users to do separate searches: "RAG" first, then "Ranking"
+    return `"${terms[0]}"`;
+}
+function buildGitHubCommitsSearchCommand(params) {
+    let command = `gh search commits "${params.query}"`;
+    if (params.owner)
+        command += ` --owner ${params.owner}`;
+    if (params.repo)
+        command += ` --repo ${params.repo}`;
+    if (params.author)
+        command += ` --author ${params.author}`;
+    if (params.committer)
+        command += ` --committer ${params.committer}`;
+    if (params.authorDate)
+        command += ` --author-date ${params.authorDate}`;
+    if (params.committerDate)
+        command += ` --committer-date ${params.committerDate}`;
+    if (params.authorEmail)
+        command += ` --author-email ${params.authorEmail}`;
+    if (params.authorName)
+        command += ` --author-name "${params.authorName}"`;
+    if (params.committerEmail)
+        command += ` --committer-email ${params.committerEmail}`;
+    if (params.committerName)
+        command += ` --committer-name "${params.committerName}"`;
+    if (params.merge !== undefined)
+        command += ` --merge`;
+    if (params.hash)
+        command += ` --hash ${params.hash}`;
+    if (params.parent)
+        command += ` --parent ${params.parent}`;
+    if (params.tree)
+        command += ` --tree ${params.tree}`;
+    if (params.visibility)
+        command += ` --visibility ${params.visibility}`;
+    if (params.limit)
+        command += ` --limit ${params.limit}`;
+    if (params.sort && params.sort !== 'best-match')
+        command += ` --sort ${params.sort}`;
+    if (params.order)
+        command += ` --order ${params.order}`;
+    return command;
+}
+function buildGitHubPullRequestsSearchCommand(params) {
+    let command = `gh search prs "${params.query}"`;
+    if (params.owner)
+        command += ` --owner ${params.owner}`;
+    if (params.repo)
+        command += ` --repo ${params.repo}`;
+    if (params.author)
+        command += ` --author ${params.author}`;
+    if (params.assignee)
+        command += ` --assignee ${params.assignee}`;
+    if (params.mentions)
+        command += ` --mentions ${params.mentions}`;
+    if (params.commenter)
+        command += ` --commenter ${params.commenter}`;
+    if (params.involves)
+        command += ` --involves ${params.involves}`;
+    if (params.reviewedBy)
+        command += ` --reviewed-by ${params.reviewedBy}`;
+    if (params.reviewRequested)
+        command += ` --review-requested ${params.reviewRequested}`;
+    if (params.state)
+        command += ` --state ${params.state}`;
+    if (params.head)
+        command += ` --head ${params.head}`;
+    if (params.base)
+        command += ` --base ${params.base}`;
+    if (params.language)
+        command += ` --language ${params.language}`;
+    if (params.created)
+        command += ` --created ${params.created}`;
+    if (params.updated)
+        command += ` --updated ${params.updated}`;
+    if (params.merged)
+        command += ` --merged ${params.merged}`;
+    if (params.closed)
+        command += ` --closed ${params.closed}`;
+    if (params.draft !== undefined)
+        command += ` --draft ${params.draft}`;
+    if (params.limit)
+        command += ` --limit ${params.limit}`;
+    if (params.sort)
+        command += ` --sort ${params.sort}`;
+    if (params.order)
+        command += ` --order ${params.order}`;
+    return command;
+}
+function buildGitHubReposSearchCommand(params) {
+    // Process query to use single-word strategy
+    const processedQuery = processSearchQuery(params.query || '');
+    let command = `gh search repos ${processedQuery}`;
+    if (params.owner)
+        command += ` --owner ${params.owner}`;
+    if (params.archived !== undefined)
+        command += ` --archived ${params.archived}`;
+    if (params.created)
+        command += ` --created "${params.created}"`;
+    if (params.followers !== undefined)
+        command += ` --followers ${params.followers}`;
+    if (params.forks !== undefined)
+        command += ` --forks ${params.forks}`;
+    if (params.goodFirstIssues !== undefined)
+        command += ` --good-first-issues ${params.goodFirstIssues}`;
+    if (params.helpWantedIssues !== undefined)
+        command += ` --help-wanted-issues ${params.helpWantedIssues}`;
+    if (params.includeForks)
+        command += ` --include-forks ${params.includeForks}`;
+    if (params.language)
+        command += ` --language ${params.language}`;
+    if (params.license)
+        command += ` --license ${params.license}`;
+    if (params.limit)
+        command += ` --limit ${params.limit}`;
+    if (params.match)
+        command += ` --match ${params.match}`;
+    if (params.numberTopics !== undefined)
+        command += ` --number-topics ${params.numberTopics}`;
+    if (params.order)
+        command += ` --order ${params.order}`;
+    if (params.size)
+        command += ` --size "${params.size}"`;
+    // DEFAULT TO UPDATED SORTING for recency prioritization
+    const sortBy = params.sort || 'updated';
+    if (sortBy !== 'best-match') {
+        command += ` --sort ${sortBy}`;
+    }
+    if (params.stars !== undefined)
+        command += ` --stars ${params.stars}`;
+    if (params.topic)
+        command += ` --topic ${params.topic}`;
+    if (params.updated)
+        command += ` --updated "${params.updated}"`;
+    if (params.visibility)
+        command += ` --visibility ${params.visibility}`;
+    return command;
+}
+function buildGitHubIssuesSearchCommand(params) {
+    let command = `gh search issues "${params.query}"`;
+    if (params.owner)
+        command += ` --owner ${params.owner}`;
+    if (params.repo)
+        command += ` --repo ${params.repo}`;
+    if (params.app)
+        command += ` --app ${params.app}`;
+    if (params.archived !== undefined)
+        command += ` --archived ${params.archived}`;
+    if (params.author)
+        command += ` --author ${params.author}`;
+    if (params.assignee)
+        command += ` --assignee ${params.assignee}`;
+    if (params.closed)
+        command += ` --closed ${params.closed}`;
+    if (params.commenter)
+        command += ` --commenter ${params.commenter}`;
+    if (params.comments !== undefined)
+        command += ` --comments ${params.comments}`;
+    if (params.created)
+        command += ` --created ${params.created}`;
+    if (params.includePrs !== undefined)
+        command += ` --include-prs`;
+    if (params.interactions !== undefined)
+        command += ` --interactions ${params.interactions}`;
+    if (params.involves)
+        command += ` --involves ${params.involves}`;
+    if (params.label)
+        command += ` --label ${params.label}`;
+    if (params.language)
+        command += ` --language ${params.language}`;
+    if (params.locked !== undefined)
+        command += ` --locked ${params.locked}`;
+    if (params.match)
+        command += ` --match ${params.match}`;
+    if (params.mentions)
+        command += ` --mentions ${params.mentions}`;
+    if (params.milestone)
+        command += ` --milestone ${params.milestone}`;
+    if (params.noAssignee !== undefined)
+        command += ` --no-assignee`;
+    if (params.noLabel !== undefined)
+        command += ` --no-label`;
+    if (params.noMilestone !== undefined)
+        command += ` --no-milestone`;
+    if (params.noProject !== undefined)
+        command += ` --no-project`;
+    if (params.project)
+        command += ` --project ${params.project}`;
+    if (params.reactions !== undefined)
+        command += ` --reactions ${params.reactions}`;
+    if (params.state)
+        command += ` --state ${params.state}`;
+    if (params.teamMentions)
+        command += ` --team-mentions ${params.teamMentions}`;
+    if (params.updated)
+        command += ` --updated ${params.updated}`;
+    if (params.visibility)
+        command += ` --visibility ${params.visibility}`;
+    if (params.limit)
+        command += ` --limit ${params.limit}`;
+    if (params.sort)
+        command += ` --sort ${params.sort}`;
+    if (params.order)
+        command += ` --order ${params.order}`;
+    return command;
+}
+function buildGitHubTopicsAPICommand(params) {
+    // Build GitHub API search query for topics
+    const searchQuery = params.query || '';
+    // Add filters to the search query
+    const queryParts = [searchQuery];
+    if (params.featured)
+        queryParts.push('is:featured');
+    if (params.curated)
+        queryParts.push('is:curated');
+    if (params.repositories)
+        queryParts.push(`repositories:${params.repositories}`);
+    if (params.created)
+        queryParts.push(`created:${params.created}`);
+    const finalQuery = queryParts.join(' ').trim();
+    // Use GitHub API to search topics
+    let command = `gh api search/topics -q '.items'`;
+    if (finalQuery) {
+        command = `gh api 'search/topics?q=${encodeURIComponent(finalQuery)}'`;
+    }
+    // Add pagination parameters
+    const limit = params.limit || 30;
+    command += `${finalQuery ? '&' : '?'}per_page=${limit}`;
+    if (params.sort)
+        command += `&sort=${params.sort}`;
+    if (params.order)
+        command += `&order=${params.order}`;
+    return command;
+}
+function buildGitHubUsersAPICommand(params) {
+    // Build GitHub API search query for users
+    const searchQuery = params.query || '';
+    // Add filters to the search query
+    const queryParts = [searchQuery];
+    if (params.type)
+        queryParts.push(`type:${params.type}`);
+    if (params.location)
+        queryParts.push(`location:"${params.location}"`);
+    if (params.language)
+        queryParts.push(`language:${params.language}`);
+    if (params.followers)
+        queryParts.push(`followers:${params.followers}`);
+    if (params.repos)
+        queryParts.push(`repos:${params.repos}`);
+    if (params.created)
+        queryParts.push(`created:${params.created}`);
+    const finalQuery = queryParts.join(' ').trim();
+    // Use GitHub API to search users
+    let command = `gh api search/users -q '.items'`;
+    if (finalQuery) {
+        command = `gh api 'search/users?q=${encodeURIComponent(finalQuery)}'`;
+    }
+    // Add pagination parameters
+    const limit = params.limit || 30;
+    command += `${finalQuery ? '&' : '?'}per_page=${limit}`;
+    if (params.sort)
+        command += `&sort=${params.sort}`;
+    if (params.order)
+        command += `&order=${params.order}`;
+    return command;
+}
+function buildGitHubDiscussionsAPICommand(params) {
+    // GitHub Discussions search is not available via REST API
+    // We'll use GraphQL API through gh api graphql
+    const query = `
+    query($searchQuery: String!, $first: Int!) {
+      search(query: $searchQuery, type: DISCUSSION, first: $first) {
+        discussionCount
+        edges {
+          node {
+            ... on Discussion {
+              title
+              body
+              url
+              createdAt
+              updatedAt
+              author {
+                login
+              }
+              repository {
+                nameWithOwner
+              }
+              category {
+                name
+              }
+              answerChosenAt
+            }
+          }
+        }
+      }
+    }
+  `;
+    // Build search query
+    const searchQuery = params.query || '';
+    const queryParts = [searchQuery];
+    // Always scope to specific repo if both owner and repo are provided
+    if (params.repo && params.owner) {
+        queryParts.push(`repo:${params.owner}/${params.repo}`);
+    }
+    else if (params.owner) {
+        // If only owner is specified, search within that owner's organization
+        // This prevents fallback to user's organizations when searching for specific packages
+        queryParts.push(`org:${params.owner}`);
+    }
+    // If no owner is specified, search globally (current behavior)
+    if (params.author)
+        queryParts.push(`author:${params.author}`);
+    if (params.category)
+        queryParts.push(`category:"${params.category}"`);
+    if (params.answered !== undefined) {
+        queryParts.push(params.answered ? 'is:answered' : 'is:unanswered');
+    }
+    if (params.created)
+        queryParts.push(`created:${params.created}`);
+    if (params.updated)
+        queryParts.push(`updated:${params.updated}`);
+    const finalQuery = queryParts.join(' ').trim();
+    const limit = params.limit || 30;
+    return `gh api graphql -f query='${query}' -f searchQuery='${finalQuery}' -F first=${limit}`;
+}
+function createSuccessResult(data) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+        isError: false,
+    };
+}
+function createErrorResult(message, error) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${message}: ${error.message}`,
+            },
+        ],
+        isError: true,
+    };
+}
+
+const SEARCH_GITHUB_CODE_DESCRIPTION = `Advanced code discovery engine for finding battle-tested implementations with intelligent pattern recognition.
+
+**🧠 INTELLIGENT SEARCH STRATEGIES:**
+
+**1. SEMANTIC CODE PATTERNS** (highest precision):
+   - **Function Signatures**: \`function handleAuth(\`, \`async function process\`
+   - **Class Definitions**: \`class AuthProvider\`, \`class DataManager\`
+   - **Import Patterns**: \`import { useAuth }\`, \`from '@/utils/auth'\`
+   - **Type Definitions**: \`interface UserType\`, \`type ApiResponse\`
+
+**2. CONTEXTUAL IMPLEMENTATION SEARCH**:
+   - **Error Handling**: \`try { await\`, \`catch (error)\`, \`.catch(\`
+   - **State Management**: \`useState(\`, \`useEffect(\`, \`const [state\`
+   - **API Patterns**: \`fetch(\`, \`axios.post\`, \`api.get\`
+   - **Testing Patterns**: \`describe(\`, \`it('should\`, \`expect(\`
+
+**3. ARCHITECTURAL DISCOVERY**:
+   - **Middleware**: \`app.use(\`, \`middleware(\`, \`next(\`
+   - **Routing**: \`router.get\`, \`Route path\`, \`useRouter\`
+   - **Database**: \`SELECT\`, \`INSERT INTO\`, \`mongoose.Schema\`
+   - **Configuration**: \`config.\`, \`process.env.\`, \`dotenv\`
+
+**🎯 PROGRESSIVE SEARCH REFINEMENT:**
+
+**Phase 1 - Broad Discovery**:
+- Start with high-level concepts: "authentication", "validation", "caching"
+- Use language filters for technology focus
+- Target active repositories (>100 stars or recent commits)
+
+**Phase 2 - Pattern Refinement**:
+- Add implementation specifics: "JWT authentication", "form validation"
+- Include framework context: "React authentication", "Express middleware"
+- Filter by file extensions: .ts, .js, .py, .go
+
+**Phase 3 - Precise Implementation**:
+- Exact code constructs: "function validateJWT", "useAuth hook"
+- Specific libraries: "passport.js", "next-auth", "auth0"
+- Edge cases: "error handling", "refresh tokens"
+
+**🔍 CONTEXT-AWARE SEARCH OPTIMIZATION:**
+
+**Query Classification**:
+- **Library Research**: Focus on popular implementations and examples
+- **Problem Solving**: Include error handling and edge cases  
+- **Learning**: Prioritize well-documented, educational examples
+- **Architecture**: Emphasize complete systems and integrations
+
+**Quality Indicators**:
+- **Production Signals**: Error handling, logging, monitoring
+- **Modern Patterns**: TypeScript usage, async/await, hooks
+- **Documentation**: Inline comments, JSDoc, README examples
+- **Testing**: Co-located test files and comprehensive coverage
+
+**ADAPTIVE RESULT PROCESSING:**
+- **1-15 results**: Extract all via ${TOOL_NAMES.FETCH_GITHUB_FILE_CONTENT}
+- **16-50 results**: Quality filter by stars/activity → extract top 10
+- **51-200 results**: Add language/framework filters → re-search
+- **200+ results**: Use specific code constructs → targeted extraction
+
+**🚀 ADVANCED SEARCH TECHNIQUES:**
+
+**Multi-dimensional Search**:
+- **Horizontal**: Same pattern across languages/frameworks
+- **Vertical**: Deep dive into specific implementation approaches
+- **Temporal**: Track pattern evolution through commit history
+- **Organizational**: Compare approaches across teams/companies
+
+**Cross-Reference Validation**:
+- **Issue Correlation**: Link implementations to solved problems
+- **PR Analysis**: Understand implementation decisions and trade-offs
+- **Discussion Context**: Community consensus and best practices
+- **Commit History**: Evolution and stability of patterns
+
+**FAILURE RECOVERY STRATEGIES:**
+- **Semantic Expansion**: "auth" → "authentication", "authorization"
+- **Technology Translation**: "React auth" → "Vue authentication" 
+- **Abstraction Levels**: "JWT implementation" → "token-based auth"
+- **Alternative Ecosystems**: Explore related technologies and patterns
+
+**REQUIREMENTS:**
+- **MANDATORY**: Always use ${TOOL_NAMES.VIEW_REPOSITORY} first for branch discovery - **NEVER** search code without this step
+- Target repositories: >1K stars OR recent activity OR enterprise usage
+- Cross-validate findings with ${TOOL_NAMES.SEARCH_GITHUB_ISSUES} when needed
+- Extract complete context including imports, types, and documentation
+
+**DO NOT:**
+- Search code without first calling ${TOOL_NAMES.VIEW_REPOSITORY} for branch discovery
+- Start with overly specific phrases before broad exploration
+- Skip cross-validation for critical implementation decisions  
+- Extract code without understanding its architectural context
+- Ignore error handling and edge case implementations`;
+
+function registerSearchGitHubCodeTool(server) {
+    server.tool(TOOL_NAMES.SEARCH_GITHUB_CODE, SEARCH_GITHUB_CODE_DESCRIPTION, {
+        query: z.string().describe('Search query for code'),
+        owner: z.string().describe('Repository owner/organization'),
+        repo: z
+            .string()
+            .optional()
+            .describe('Repository name (often too restrictive)'),
+        branch: z
+            .string()
+            .describe('Branch for workflow documentation (required but not used by CLI)'),
+        language: z.string().optional().describe('Programming language filter'),
+        filename: z.string().optional().describe('Filename filter'),
+        extension: z.string().optional().describe('File extension filter'),
+        match: z.enum(['file', 'path']).optional().describe('Search scope'),
+        limit: z
+            .number()
+            .optional()
+            .default(50)
+            .describe('Maximum results (default: 50)'),
+    }, async (args) => {
+        try {
+            return await searchGitHubCode(args);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to search GitHub code: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+const FETCH_GITHUB_FILE_CONTENT_DESCRIPTION = `Extract complete working code with full context - the core of code analysis.
+
+**PURPOSE:**
+Extract complete, working code implementations rather than code snippets.
+
+**CRITICAL FOR SEARCH EXPANSION:**
+Transform search results into actionable implementations. Search tools find files - this tool extracts the complete, working code with full context needed for implementation.
+
+**MANDATORY WORKFLOW:**
+1. **ALWAYS** Use ${TOOL_NAMES.VIEW_REPOSITORY} first to discover the correct default branch
+2. Find files with ${TOOL_NAMES.SEARCH_GITHUB_CODE}  
+3. Extract complete implementations with this tool
+4. Follow dependency chains to related files
+
+**CRITICAL REQUIREMENT:**
+**NEVER** use this tool without first calling ${TOOL_NAMES.VIEW_REPOSITORY} to get the correct branch information. Wrong branch names cause complete tool failure.
+
+**WHAT TO FETCH:**
+- **Core implementations**: Main functions/classes with complete logic
+- **Dependencies**: Files referenced in imports/exports paths
+- **Configuration**: package.json, tsconfig.json, webpack.config.js, etc.
+- **Documentation**: README.md, API docs, usage examples
+- **Tests**: For usage patterns and validation
+- **Related utilities**: Helper functions and shared modules
+
+**ENHANCED AUTO-RECOVERY:**
+Tries multiple fallback strategies:
+1. Specified branch → main → master → develop → trunk (with ref parameter)
+2. If all fail: Try without ref parameter (uses repository default branch)
+Handles incorrect branch info from ${TOOL_NAMES.VIEW_REPOSITORY} and GitHub API limitations.
+
+**SUCCESS CRITERIA:**
+Production-ready code with all necessary context for immediate implementation.
+
+**DO NOT:**
+- Extract incomplete snippets without context
+- Skip dependency files or configuration
+- Use this tool without first calling ${TOOL_NAMES.VIEW_REPOSITORY}
+- Assume branch names without verification`;
+
+function registerFetchGitHubFileContentTool(server) {
+    server.tool(TOOL_NAMES.FETCH_GITHUB_FILE_CONTENT, FETCH_GITHUB_FILE_CONTENT_DESCRIPTION, {
+        owner: z
+            .string()
+            .describe(`Filter by repository owner/organization (e.g., 'example-org') get from ${TOOL_NAMES.GET_USER_ORGANIZATIONS} tool`),
+        repo: z.string().describe('The name of the GitHub repository'),
+        branch: z
+            .string()
+            .describe(`RECOMMENDED: The branch of the repository (e.g., "main", "master", "dev"). If branch doesn't exist, automatically tries common alternatives (main/master/develop/trunk) and finally default branch. Get from ${TOOL_NAMES.VIEW_REPOSITORY} for best results.`),
+        filePath: z
+            .string()
+            .describe('The path to the file within the repository'),
+    }, async (args) => {
+        try {
+            return await fetchGitHubFileContent(args);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to fetch GitHub file content: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+const VIEW_REPOSITORY_DESCRIPTION = `**CRITICAL: MANDATORY first step for all file operations** - discovers default branch information.
+
+**PURPOSE:**
+Extract default branch from repository metadata and README to prevent tool failures. This tool provides the foundation for all subsequent GitHub operations.
+
+**WHY ABSOLUTELY CRITICAL:**
+- Wrong branch names cause **COMPLETE TOOL FAILURE** in all file operations
+- Only correct branches contain current repository state
+- **ALL** subsequent GitHub operations depend on correct branch discovery
+- Prevents expensive retry cycles and API rate limiting
+
+**BRANCH DISCOVERY METHODS:**
+- License badge URLs: github.com/OWNER/REPO/blob/BRANCH/LICENSE
+- CI/CD badge URLs: Check for ?branch=BRANCH parameters  
+- Repository metadata: Default branch in CLI output
+- README badges and links analysis
+
+**ABSOLUTELY REQUIRED BEFORE:**
+- ${TOOL_NAMES.SEARCH_GITHUB_CODE} (needs branch for workflow)
+- ${TOOL_NAMES.VIEW_REPOSITORY_STRUCTURE} (needs branch for directory exploration)
+- ${TOOL_NAMES.FETCH_GITHUB_FILE_CONTENT} (needs branch for file fetching)
+
+**ENHANCED INTEGRATION:**
+Tools now include intelligent fallback mechanisms that complement this tool's branch discovery:
+- Multiple branch attempts with common alternatives
+- Graceful degradation when specific branches fail
+- Comprehensive error reporting for troubleshooting
+
+**SUCCESS INDICATORS:**
+- Repository info retrieved successfully
+- Branch identifiable in badges/metadata
+- Repository appears active with recent commits
+- Default branch clearly indicated in output
+
+**ERROR HANDLING:**
+- Not found: Check owner/repo spelling and permissions
+- Access denied: Use ${TOOL_NAMES.GET_USER_ORGANIZATIONS} for permissions
+- If this tool fails, all subsequent file operations will fail
+
+**NEVER:**
+- Skip this step before any file operations
+- Assume default branch name without verification
+- Proceed with file operations if branch discovery fails
+- Use hardcoded branch names like 'main' or 'master' without verification`;
+
+function registerViewRepositoryTool(server) {
+    server.tool(TOOL_NAMES.VIEW_REPOSITORY, VIEW_REPOSITORY_DESCRIPTION, {
+        owner: z
+            .string()
+            .describe("Filter by repository owner/organization (e.g., 'example-org')"),
+        repo: z
+            .string()
+            .describe("The name of the GitHub repository to view (e.g. 'premium-ai-playground')"),
+    }, async (args) => {
+        try {
+            return await viewGitHubRepositoryInfo(args);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to view repository: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+const NPM_VIEW_DESCRIPTION = `Transform package names into GitHub repositories for code analysis.
+
+**WHEN TO USE:**
+- User mentions package names ("react", "lodash", "@types/node")
+- Code snippets with imports: import { useState } from 'react'
+- Dependency/module references in user queries
+
+**WORKFLOW:**
+1. Extract repository URL from package.json
+2. Parse owner/repo from GitHub URL formats
+3. Chain to ${TOOL_NAMES.VIEW_REPOSITORY} for branch discovery
+4. Continue to ${TOOL_NAMES.SEARCH_GITHUB_CODE} for implementations
+
+**OUTPUT:**
+Repository context + package metadata for intelligent code search
+
+**EXAMPLES:**
+- "react" → github.com/facebook/react → Code search in React repo
+- "lodash" → github.com/lodash/lodash → Extract utility implementations  
+- "@org/some-lib" → Private repo discovery → Organizational code analysis
+
+**SUCCESS CRITERIA:**
+Accurate repository mapping that enables battle-tested code extraction
+
+**DO NOT:**
+- Skip package-to-repository mapping when packages are mentioned
+- Assume package names without verification
+- Use for non-npm package references`;
+
+function registerNpmViewTool(server) {
+    server.tool(TOOL_NAMES.NPM_VIEW, NPM_VIEW_DESCRIPTION, {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to analyze (e.g., 'react', '@types/node', 'lodash')"),
+    }, async (args) => {
+        try {
+            return await npmView(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm package info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+const SEARCH_GITHUB_REPOS_DESCRIPTION = `GitHub repository search with progressive discovery methodology.
+- **RELATED TOOLS:**
+  - ${TOOL_NAMES.SEARCH_GITHUB_TOPICS}: Essential for topic-based search (e.g. "react", "typescript", "nodejs", "rag")  and more discovery
+
+**AUTO-TRIGGER CONDITIONS:**
+- Organization mentions: "I work at [Company Name]", "our team", "organization codebase"
+- Private repository indicators: "internal code", "team repositories"
+→ Auto-call ${TOOL_NAMES.GET_USER_ORGANIZATIONS}
+
+**SEARCH STRATEGY:**
+1. **Start Ultra-Lean**: Single technical terms ("react", "cli", "docker")
+2. **Gradual Expansion**: Add second term only if first yields too many/few results  
+3. **Specific Targeting**: Combine terms only when patterns emerge
+
+**SEARCH METHODOLOGY:**
+- Phase 1: Single keywords ("graphql", "kubernetes", "typescript")
+- Phase 2: Add context if needed ("graphql server", "kubernetes operator")
+- Phase 3: Specific combinations only when necessary
+
+**CONTEXT DETECTION:**
+- Organization context → Auto-call ${TOOL_NAMES.GET_USER_ORGANIZATIONS}
+- Package mentions → Use ${TOOL_NAMES.NPM_VIEW} first
+- General queries → Start without owner filter
+
+**FILTERING STRATEGY:**
+- Owner filter: Most effective for scoping results
+- Language filter: For technology-specific searches
+- Stars filter: ">100" for established, ">10" for active projects
+- Updated filter: Prioritize recent activity (">2023-01-01")
+
+**RESULT QUALITY TARGETS:**
+- 0 results: Broaden terms, remove filters except owner
+- 1-10: IDEAL - Deep dive analysis
+- 11-30: GOOD - Analyze patterns and select relevant
+- 31-100: Add specificity filters (language, stars, updated)
+- 100+: Too broad - use more specific single terms
+
+**DEFAULT BEHAVIOR:**
+- Sort by "updated" for active repositories first
+- Balance relevance with recency
+
+**DO NOT:**
+- Start with complex phrases like "react command line tools"
+- Use "react" when you mean single keyword search
+- Skip organization discovery when company context is clear`;
+
+function registerSearchGitHubReposTool(server) {
+    server.tool(TOOL_NAMES.SEARCH_GITHUB_REPOS, SEARCH_GITHUB_REPOS_DESCRIPTION, {
+        query: z.string().describe('Search query for repositories'),
+        owner: z.string().describe('Repository owner/organization'),
+        archived: z.boolean().optional().describe('Filter archived state'),
+        created: z.string().optional().describe('Filter by created date'),
+        followers: z.number().optional().describe('Filter by followers count'),
+        forks: z.number().optional().describe('Filter by forks count'),
+        goodFirstIssues: z
+            .number()
+            .optional()
+            .describe('Filter by good first issues count'),
+        helpWantedIssues: z
+            .number()
+            .optional()
+            .describe('Filter by help wanted issues count'),
+        includeForks: z
+            .enum(['false', 'true', 'only'])
+            .optional()
+            .describe('Include forks in results'),
+        language: z
+            .string()
+            .optional()
+            .describe('Filter by programming language'),
+        license: z.string().optional().describe('Filter by license type'),
+        limit: z
+            .number()
+            .optional()
+            .default(50)
+            .describe('Maximum results (default: 50)'),
+        match: z
+            .enum(['name', 'description', 'readme'])
+            .optional()
+            .describe('Search scope restriction'),
+        numberTopics: z.number().optional().describe('Filter by topics count'),
+        order: z
+            .enum(['asc', 'desc'])
+            .optional()
+            .default('desc')
+            .describe('Result order (default: desc for newest first)'),
+        size: z.string().optional().describe('Filter by size in KB'),
+        sort: z
+            .enum(['forks', 'help-wanted-issues', 'stars', 'updated', 'best-match'])
+            .optional()
+            .default('updated')
+            .describe('Sort criteria (default: updated for recent activity)'),
+        stars: z.number().optional().describe('Filter by stars count'),
+        topic: z.string().optional().describe('Filter by topic/tag'),
+        updated: z.string().optional().describe('Filter by last update date'),
+        visibility: z
+            .enum(['public', 'private', 'internal'])
+            .optional()
+            .describe('Filter by visibility'),
+    }, async (args) => {
+        try {
+            return await searchGitHubRepos(args);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to search GitHub repositories: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+const SEARCH_GITHUB_COMMITS_DESCRIPTION = `Advanced GitHub commits search for development history analysis.
+
+**CORE PURPOSE:**
+Track code evolution, debug issues, analyze contributor patterns, and understand development history.
+
+**SEARCH STRATEGY:**
+1. **Start Minimal**: Single keywords ("fix", "feature", "update") + owner/repo context
+2. **Progressive Expansion**: Add specific terms based on findings
+3. **Apply Filters**: Author, date ranges only when patterns emerge
+
+**SEARCH PATTERNS:**
+- **General exploration**: "fix" or "update" with owner/repo → activity overview
+- **Feature tracking**: Single feature keyword → expand with related terms
+- **Bug investigation**: "bug" or "fix" → narrow by time/author
+- **Attribution**: Keywords + author filter → contribution analysis
+
+**RESULT TARGETS:**
+- 0-5 results: Try broader terms, remove filters
+- 6-50 results: OPTIMAL - Extract insights
+- 51+ results: Add specific filters or narrow time ranges
+
+**CRITICAL LIMITATIONS:**
+- Large organizations may return org-wide results instead of repo-specific
+- If irrelevant results: Switch to alternative approaches (changelog files, PR search)
+
+**FALLBACK STRATEGY:**
+1. Commit search with minimal keywords
+2. Pull request searches for features/changes  
+3. Fetch changelog files (CHANGELOG.md, RELEASES.md)
+4. Repository structure exploration
+
+**BRANCH AWARENESS:** Verify default branch (main vs master) before file fetching
+
+**ERROR HANDLING:**
+- "Search text required" → Use minimal keywords ("fix", "update")
+- Irrelevant results → Switch to file-based approaches
+- Empty results → Broaden scope or remove repository filters
+
+**INTEGRATION:** Combine with ${TOOL_NAMES.FETCH_GITHUB_FILE_CONTENT} for complete change context.`;
+
+function registerSearchGitHubCommitsTool(server) {
+    server.tool(TOOL_NAMES.SEARCH_GITHUB_COMMITS, SEARCH_GITHUB_COMMITS_DESCRIPTION, {
+        query: z
+            .string()
+            .describe("The search query to find commits - start with single keyword (e.g., 'bug', 'refactor', 'feature'). Cannot be empty as GitHub requires search text for commit searches."),
+        owner: z
+            .string()
+            .optional()
+            .describe("Filter by repository owner/organization (e.g., 'example-org') obtained from the appropriate tool for fetching user organizations"),
+        repo: z
+            .string()
+            .optional()
+            .describe("Filter by repository name (e.g., 'cli/cli')"),
+        author: z.string().optional().describe('Filter by commit author'),
+        committer: z.string().optional().describe('Filter by committer'),
+        authorDate: z
+            .string()
+            .optional()
+            .describe("Filter based on authored date (e.g., '>2022-01-01', '<2023-12-31')"),
+        committerDate: z
+            .string()
+            .optional()
+            .describe("Filter based on committed date (e.g., '>2022-01-01', '<2023-12-31')"),
+        authorEmail: z.string().optional().describe('Filter on author email'),
+        authorName: z.string().optional().describe('Filter on author name'),
+        committerEmail: z
+            .string()
+            .optional()
+            .describe('Filter on committer email'),
+        committerName: z.string().optional().describe('Filter on committer name'),
+        merge: z.boolean().optional().describe('Filter on merge commits'),
+        hash: z.string().optional().describe('Filter by commit hash'),
+        parent: z.string().optional().describe('Filter by parent hash'),
+        tree: z.string().optional().describe('Filter by tree hash'),
+        visibility: z
+            .enum(['public', 'private', 'internal'])
+            .optional()
+            .describe('Filter based on repository visibility'),
+        limit: z
+            .number()
+            .optional()
+            .default(50)
+            .describe('Maximum number of commits to return (default: 50)'),
+        sort: z
+            .enum(['author-date', 'committer-date', 'best-match'])
+            .optional()
+            .default('best-match')
+            .describe('Sort commits by specified criteria (default: best-match)'),
+        order: z
+            .enum(['asc', 'desc'])
+            .optional()
+            .default('desc')
+            .describe('Order of commits returned (default: desc for newest first)'),
+    }, async (args) => {
+        try {
+            return await searchGitHubCommits(args);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to search GitHub commits: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+const SEARCH_GITHUB_PULL_REQUESTS_DESCRIPTION = `Advanced GitHub pull requests search for code review and feature analysis.
+
+**SEARCH STRATEGY:**
+1. **Single Keywords First**: "bug", "feature", "refactor" 
+2. **Then Combine**: "bug fix", "feature implementation" (only if needed)
+3. **Never Start Complex**: Avoid phrases like "comprehensive bug fix implementation"
+
+**CORE PURPOSE:**
+- Code review insights and team collaboration patterns
+- Feature implementation lifecycle tracking
+- Breaking changes and quality assurance analysis
+
+**SEARCH METHODOLOGY:**
+- **Phase 1**: Core discovery with fundamental terms ("authentication", "error")
+- **Phase 2**: Add context ("authentication JWT", "error handling")  
+- **Phase 3**: Solution focus ("authentication bug fixed")
+
+**RESULT TARGETS:**
+- 0 results: Try broader terms, remove filters
+- 1-20 results: IDEAL - Deep analysis of patterns and solutions
+- 21-100 results: GOOD - Add specificity or filters
+- 100+ results: Add specific terms or state/reviewer filters
+
+**FILTERING BEST PRACTICES:**
+- State filter: "open" for current issues, "closed" for resolved patterns
+- Author/reviewer filters: Understand team collaboration
+- Draft filter: Work-in-progress vs completed features
+- Branch filters: Release and feature branch workflows
+- Language filter: Focus on specific technology stacks
+
+**ADAPTIVE TACTICS:**
+- Start broad with feature keywords, narrow based on findings
+- Use owner/repo parameters when repository context is known
+- Widen scope if targeted searches yield insufficient results
+- Apply precise filters only after broader searches confirm patterns
+
+**CROSS-REFERENCE STRATEGY:**
+- Combine with ${TOOL_NAMES.SEARCH_GITHUB_COMMITS} for complete development understanding
+- Use with ${TOOL_NAMES.SEARCH_GITHUB_CODE} for current implementations
+- Cross-reference with ${TOOL_NAMES.SEARCH_GITHUB_REPOS} for similar patterns
+
+**QUALITY FOCUS:** Use review-related filters to find thoroughly vetted code examples.`;
+
+function registerSearchGitHubPullRequestsTool(server) {
+    server.tool(TOOL_NAMES.SEARCH_GITHUB_PULL_REQUESTS, SEARCH_GITHUB_PULL_REQUESTS_DESCRIPTION, {
+        query: z
+            .string()
+            .describe("The search query to find pull requests (e.g., 'bug fix', 'feature implementation', 'code review')"),
+        owner: z
+            .string()
+            .optional()
+            .describe(`Filter by repository owner/organization (e.g., 'example-org')`),
+        repo: z
+            .string()
+            .optional()
+            .describe("Filter by repository name (e.g., 'cli/cli')"),
+        author: z.string().optional().describe('Filter by pull request author'),
+        assignee: z.string().optional().describe('Filter by assignee'),
+        mentions: z.string().optional().describe('Filter based on user mentions'),
+        commenter: z
+            .string()
+            .optional()
+            .describe('Filter based on comments by user'),
+        involves: z
+            .string()
+            .optional()
+            .describe('Filter based on involvement of user'),
+        reviewedBy: z.string().optional().describe('Filter on user who reviewed'),
+        reviewRequested: z
+            .string()
+            .optional()
+            .describe('Filter on user or team requested to review'),
+        state: z
+            .enum(['open', 'closed', 'merged'])
+            .optional()
+            .describe('Filter based on state'),
+        head: z.string().optional().describe('Filter on head branch name'),
+        base: z.string().optional().describe('Filter on base branch name'),
+        language: z
+            .string()
+            .optional()
+            .describe('Filter based on the coding language'),
+        created: z
+            .string()
+            .optional()
+            .describe("Filter based on created at date (e.g., '>2022-01-01', '<2023-12-31')"),
+        updated: z.string().optional().describe('Filter on last updated at date'),
+        merged: z.string().optional().describe('Filter on merged at date'),
+        closed: z.string().optional().describe('Filter on closed at date'),
+        draft: z.boolean().optional().describe('Filter based on draft state'),
+        limit: z
+            .number()
+            .optional()
+            .default(50)
+            .describe('Maximum number of pull requests to return (default: 50)'),
+        sort: z
+            .enum([
+            'comments',
+            'reactions',
+            'reactions-+1',
+            'reactions--1',
+            'reactions-smile',
+            'reactions-thinking_face',
+            'reactions-heart',
+            'reactions-tada',
+            'interactions',
+            'created',
+            'updated',
+        ])
+            .optional()
+            .describe('Sort pull requests by specified criteria'),
+        order: z
+            .enum(['asc', 'desc'])
+            .optional()
+            .default('desc')
+            .describe('Order of results returned (default: desc)'),
+    }, async (args) => {
+        try {
+            return await searchGitHubPullRequests(args);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to search GitHub pull requests: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+const GET_USER_ORGANIZATIONS_DESCRIPTION = `Get list of GitHub organizations for the authenticated user to enable private repository discovery.
+
+**AUTOMATIC TRIGGERS:**
+Auto-trigger when users mention:
+- Company/employer context: "I work at [Company Name]", "our team", "company codebase"
+- Private repositories: "internal code", "team repositories"  
+- Enterprise context: "at work", "enterprise setup"
+
+**ORGANIZATION MATCHING Examples:**
+- "Facebook" → "facebook", "meta"
+- "Google" → "google", "googlecloudplatform"
+- "Microsoft" → "microsoft", "azure"
+
+**WORKFLOW:**
+1. Call this tool first when organizational context detected
+2. Match user's company to found organizations
+3. Use selected organization as 'owner' parameter in subsequent searches
+4. Fallback to public search if no organizational results
+
+**USAGE PRIORITY:**
+- Essential for private repository access
+- Critical for enterprise GitHub setups
+- Use before repository searches fail due to permissions
+- Combine with npmView for private organization packages
+
+**DO NOT:**
+- Skip organization-scoped search when company context is clear
+- Use public search first when private repositories are likely
+- Ignore organizational context in user queries`;
+
+function registerGetUserOrganizationsTool(server) {
+    server.tool(TOOL_NAMES.GET_USER_ORGANIZATIONS, GET_USER_ORGANIZATIONS_DESCRIPTION, {
+        limit: z
+            .number()
+            .optional()
+            .default(50)
+            .describe('Maximum number of organizations to list (default: 50)'),
+    }, async (args) => {
+        try {
+            return await getUserOrganizations(args);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get user organizations: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+const NPM_SEARCH_DESCRIPTION = `Search NPM registry for packages by keywords using "npm search <term>".
+
+**SEARCH STRATEGY:**
+1. Start with single technology terms ("react", "cli")  
+2. Add specificity only if needed ("react-hooks", "typescript-cli")
+3. Avoid complex phrases - they yield zero results
+
+**WHEN TO USE:**
+- Pure discovery of packages on NPM registry by keyword
+- More direct than discovering packages mentioned in code
+- Finding alternatives to known packages
+
+**SEARCH PATTERNS:**
+- Good: "react" → "cli" → "react cli" (if specific combination needed)
+- Poor: "react command line interface tools" (too complex, likely zero results)
+
+**RESULT OPTIMIZATION:**
+- 0 results: Try broader, single-word terms
+- 1-20 results: IDEAL - analyze thoroughly
+- 21-100 results: GOOD - filter by popularity/relevance  
+- 100+ results: Too broad - use more specific single terms
+
+**OUTPUT FORMAT:**
+JSON format with package metadata including name, description, version, and popularity metrics
+
+**CONSTRAINTS:**
+- Maximum 50 results by default
+- Supports regex patterns when query starts with /
+- Multiple space-separated terms supported but use sparingly`;
+
+function registerNpmSearchTool(server) {
+    server.tool(TOOL_NAMES.NPM_SEARCH, NPM_SEARCH_DESCRIPTION, {
+        query: z
+            .string()
+            .describe("The search term(s) to find packages on NPM. Multiple terms can be space-separated (e.g., 'react query client'). Supports regex if term starts with /."),
+        json: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe('Output search results in JSON format. Defaults to true.'),
+        searchlimit: z
+            .number()
+            .optional()
+            .default(50)
+            .describe('Maximum number of search results to return. Defaults to 50.'),
+    }, async (args) => {
+        try {
+            return await npmSearch(args);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to search NPM: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+const VIEW_REPOSITORY_STRUCTURE_DESCRIPTION = `Strategic repository exploration for code analysis.
+
+**CRITICAL REQUIREMENT:**
+**MANDATORY:** Must use ${TOOL_NAMES.VIEW_REPOSITORY} FIRST to get branch. **NEVER** explore repository structure without explicit branch discovery.
+
+**EXPLORATION PHASES:**
+1. **Root Analysis**: Project type (package.json, requirements.txt), README, docs, config files
+2. **Source Discovery**: Navigate src/, lib/, components/, utils/, types/  
+3. **Validation**: Explore test/, examples/, demos/ directories
+
+**DIRECTORY PRIORITIES:**
+- HIGH: src/, lib/, components/, utils/, types/ (Core implementations)
+- MEDIUM: docs/, examples/, config/ (Context/documentation) 
+- TEST: test/, __tests__/, spec/ (Quality/patterns)
+
+**NAVIGATION STRATEGY:**
+- Start with root for project overview
+- Target core implementation directories
+- Extract promising files via ${TOOL_NAMES.FETCH_GITHUB_FILE_CONTENT}
+- Cross-reference with tests for usage patterns
+
+**RESULT TARGETS:**
+- 1-10 results: IDEAL - Focused exploration
+- 11-50 results: MANAGEABLE - Prioritize by conventions
+- 50+ results: TOO BROAD - Explore subdirectories
+
+**ENHANCED BRANCH FALLBACK:** 
+Automatically tries multiple fallback strategies:
+1. Specified branch → main → master → develop → trunk (with ref parameter)
+2. If all fail: Try without ref parameter (uses repository default branch)
+Handles branch discovery failures gracefully with comprehensive error reporting.
+
+**OUTPUT:** Architectural map to guide intelligent code extraction.
+
+**NEVER:**
+- Explore without calling ${TOOL_NAMES.VIEW_REPOSITORY} first
+- Use hardcoded branch names without verification
+- Assume default branch names across repositories`;
+
+function registerViewRepositoryStructureTool(server) {
+    server.tool(TOOL_NAMES.VIEW_REPOSITORY_STRUCTURE, VIEW_REPOSITORY_STRUCTURE_DESCRIPTION, {
+        owner: z
+            .string()
+            .describe(`Specify the repository owner/organization. This can be obtained using the appropriate tool for fetching user organizations.`),
+        repo: z.string().describe('The name of the GitHub repository'),
+        branch: z
+            .string()
+            .describe(`MANDATORY: Specify the branch to explore (e.g., 'main', 'master', 'develop'). Must be obtained from ${TOOL_NAMES.VIEW_REPOSITORY} first. Never explore without explicit branch specification.`),
+        path: z
+            .string()
+            .optional()
+            .default('')
+            .describe('The path within the repository to view the structure from. Defaults to the root of the repository. Allows for iterative exploration of the repository structure.'),
+    }, async (args) => {
+        try {
+            return await viewRepositoryStructure(args);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to view repository structure: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+const SEARCH_GITHUB_ISSUES_DESCRIPTION = `Advanced GitHub issues search for problem discovery and solution research.
+
+**SEARCH STRATEGY:**
+1. **Single Keywords First**: "bug", "feature", "documentation"
+2. **Then Combine**: "bug fix", "feature request" (only if needed)
+3. **Never Start Complex**: Avoid "critical performance bug in production"
+
+**CORE PURPOSE:**
+- Problem discovery and existing issue research
+- Solution research and community insights
+- Development planning and quality assurance
+
+**SEARCH METHODOLOGY:**
+- **Phase 1**: Core discovery ("authentication", "error") → understand patterns
+- **Phase 2**: Context expansion ("authentication JWT", "error handling")
+- **Phase 3**: Solution focus ("authentication bug resolved")
+
+**RESULT TARGETS:**
+- 0 results: Try broader terms, remove filters
+- 1-20 results: IDEAL - Deep analysis of patterns and solutions
+- 21-100 results: GOOD - Add specificity or filters
+- 100+ results: Add specific terms or state/label filters
+
+**TERM SELECTION:**
+- Actual error messages: "TypeError", "404", "connection refused"
+- Status indicators: "open", "closed", "resolved", "duplicate"
+- Impact levels: "critical", "bug", "enhancement", "question"
+- Component names: "API", "frontend", "database", "deployment"
+
+**FILTERING STRATEGY:**
+- State filter: "open" for current issues, "closed" for resolved patterns
+- Label filter: Severity ("bug", "enhancement", "documentation")
+- Assignee filter: Issues handled by specific maintainers
+- Author filter: Track issues from particular users
+- Date filters: Recent issues or historical analysis
+
+**CROSS-REFERENCE APPROACH:**
+- Combine with ${TOOL_NAMES.SEARCH_GITHUB_CODE} for implementation details
+- Use with ${TOOL_NAMES.SEARCH_GITHUB_COMMITS} for fix implementations
+- Cross-reference with ${TOOL_NAMES.SEARCH_GITHUB_PULL_REQUESTS} for solutions
+- Explore ${TOOL_NAMES.SEARCH_GITHUB_DISCUSSIONS} for community insights
+
+**PATTERN ANALYSIS:** Focus on issue resolution patterns and community feedback for development insights.`;
+
+function registerSearchGitHubIssuesTool(server) {
+    server.tool(TOOL_NAMES.SEARCH_GITHUB_ISSUES, SEARCH_GITHUB_ISSUES_DESCRIPTION, {
+        query: z
+            .string()
+            .describe("The search query to find issues (e.g., 'bug fix', 'feature request', 'documentation')"),
+        owner: z
+            .string()
+            .describe("Filter by repository owner/organization (e.g., 'example-org')"),
+        repo: z
+            .string()
+            .optional()
+            .describe("Filter by specific repository name (e.g., 'cli/cli'). Note: Always do exploratory search without repo filter first"),
+        app: z.string().optional().describe('Filter by GitHub App author'),
+        archived: z
+            .boolean()
+            .optional()
+            .describe('Filter based on the repository archived state'),
+        assignee: z.string().optional().describe('Filter by assignee'),
+        author: z.string().optional().describe('Filter by issue author'),
+        closed: z.string().optional().describe('Filter on closed at date'),
+        commenter: z
+            .string()
+            .optional()
+            .describe('Filter based on comments by user'),
+        comments: z.number().optional().describe('Filter on number of comments'),
+        created: z
+            .string()
+            .optional()
+            .describe("Filter based on created at date (e.g., '>2022-01-01', '<2023-12-31')"),
+        includePrs: z
+            .boolean()
+            .optional()
+            .describe('Include pull requests in results'),
+        interactions: z
+            .number()
+            .optional()
+            .describe('Filter on number of reactions and comments'),
+        involves: z
+            .string()
+            .optional()
+            .describe('Filter based on involvement of user'),
+        labels: z
+            .string()
+            .optional()
+            .describe("Filter by labels (e.g., 'bug', 'enhancement', 'documentation')"),
+        language: z
+            .string()
+            .optional()
+            .describe('Filter based on the coding language'),
+        locked: z
+            .boolean()
+            .optional()
+            .describe('Filter on locked conversation status'),
+        match: z
+            .enum(['title', 'body', 'comments'])
+            .optional()
+            .describe('Restrict search to specific field of issue'),
+        mentions: z.string().optional().describe('Filter based on user mentions'),
+        milestone: z.string().optional().describe('Filter by milestone title'),
+        noAssignee: z.boolean().optional().describe('Filter on missing assignee'),
+        noLabel: z.boolean().optional().describe('Filter on missing label'),
+        noMilestone: z
+            .boolean()
+            .optional()
+            .describe('Filter on missing milestone'),
+        noProject: z.boolean().optional().describe('Filter on missing project'),
+        project: z
+            .string()
+            .optional()
+            .describe('Filter on project board owner/number'),
+        reactions: z
+            .number()
+            .optional()
+            .describe('Filter on number of reactions'),
+        state: z
+            .enum(['open', 'closed'])
+            .optional()
+            .describe('Filter based on issue state'),
+        teamMentions: z
+            .string()
+            .optional()
+            .describe('Filter based on team mentions'),
+        updated: z.string().optional().describe('Filter on last updated at date'),
+        visibility: z
+            .enum(['public', 'private', 'internal'])
+            .optional()
+            .describe('Filter based on repository visibility'),
+        limit: z
+            .number()
+            .optional()
+            .default(50)
+            .describe('Maximum number of issues to return (default: 50)'),
+        sort: z
+            .enum([
+            'comments',
+            'created',
+            'interactions',
+            'reactions',
+            'reactions-+1',
+            'reactions--1',
+            'reactions-heart',
+            'reactions-smile',
+            'reactions-tada',
+            'reactions-thinking_face',
+            'updated',
+            'best-match',
+        ])
+            .optional()
+            .describe('Sort issues by specified criteria'),
+        order: z
+            .enum(['asc', 'desc'])
+            .optional()
+            .default('desc')
+            .describe('Order of results returned (default: desc)'),
+    }, async (args) => {
+        try {
+            return await searchGitHubIssues(args);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to search GitHub issues: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+const SEARCH_GITHUB_DISCUSSIONS_DESCRIPTION = `GitHub discussions search for community knowledge discovery.
+
+**CORE PURPOSE:**
+Access community Q&A, tutorials, and best practices for learning and problem-solving.
+
+**DISCOVERY WORKFLOW:**
+1. Use ${TOOL_NAMES.NPM_VIEW} for packages → get repo URL
+2. Use ${TOOL_NAMES.SEARCH_GITHUB_REPOS} for projects → get owner/repo  
+3. Search discussions with discovered owner/repo context
+
+**SEARCH STRATEGY:**
+1. **Start Lean**: Single keywords ("help", "tutorial", "authentication")
+2. **Build Complexity**: Combinations if needed ("help deployment")
+3. **Avoid Complex**: Don't start with full phrases
+
+**RESULT TARGETS:**
+- 1-15 results: IDEAL - Deep analysis opportunities
+- 16-50 results: GOOD - Manageable scope
+- 51-100 results: BROAD - Add category filters
+- 100+ results: TOO GENERIC - Refine terms
+
+**KEY FILTERS:**
+- **Answered**: True for validated solutions
+- **Category**: Q&A, General, Show and Tell
+- **Author/maintainer**: For authoritative responses
+- **Date filters**: Recent vs historical discussions
+
+**SEARCH PATTERNS:**
+- **Problem solving**: "deployment help", "authentication tutorial"
+- **Best practices**: "testing patterns", "architecture decisions"
+- **Community insights**: "performance tips", "migration guide"
+
+**QUALITY INDICATORS:**
+- Answered discussions for validated solutions
+- Maintainer participation for authoritative guidance
+- Recent activity for current relevance
+
+**FALLBACK STRATEGY:**
+If no discussions found, try ${TOOL_NAMES.SEARCH_GITHUB_ISSUES} for alternative community insights.
+
+**OUTPUT:** Community-validated knowledge and solutions for development challenges.`;
+
+function registerSearchGitHubDiscussionsTool(server) {
+    server.tool(TOOL_NAMES.SEARCH_GITHUB_DISCUSSIONS, SEARCH_GITHUB_DISCUSSIONS_DESCRIPTION, {
+        query: z
+            .string()
+            .describe("The search query to find discussions (e.g., 'deployment help', 'authentication tutorial', 'best practices')"),
+        owner: z
+            .string()
+            .describe("Filter by repository owner/organization (e.g., 'example-org')"),
+        repo: z
+            .string()
+            .optional()
+            .describe("Filter by specific repository name (e.g., 'cli/cli'). Note: Always do exploratory search without repo filter first"),
+        author: z.string().optional().describe('Filter by discussion author'),
+        assignee: z.string().optional().describe('Filter by assignee'),
+        mentions: z.string().optional().describe('Filter based on user mentions'),
+        commenter: z
+            .string()
+            .optional()
+            .describe('Filter based on comments by user'),
+        involves: z
+            .string()
+            .optional()
+            .describe('Filter based on involvement of user'),
+        category: z
+            .string()
+            .optional()
+            .describe("Filter by discussion category (e.g., 'Q&A', 'General', 'Show and Tell')"),
+        answered: z
+            .boolean()
+            .optional()
+            .describe('Filter by answered state (true for answered discussions only)'),
+        created: z
+            .string()
+            .optional()
+            .describe("Filter based on created date (e.g., '>2022-01-01', '<2023-12-31')"),
+        updated: z.string().optional().describe('Filter on last updated date'),
+        limit: z
+            .number()
+            .optional()
+            .default(50)
+            .describe('Maximum number of discussions to return (default: 50)'),
+        sort: z
+            .enum([
+            'comments',
+            'reactions',
+            'reactions-+1',
+            'reactions--1',
+            'reactions-smile',
+            'reactions-thinking_face',
+            'reactions-heart',
+            'reactions-tada',
+            'interactions',
+            'created',
+            'updated',
+        ])
+            .optional()
+            .describe('Sort discussions by specified criteria'),
+        order: z
+            .enum(['asc', 'desc'])
+            .optional()
+            .default('desc')
+            .describe('Order of results returned (default: desc)'),
+    }, async (args) => {
+        try {
+            return await searchGitHubDiscussions(args);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to search GitHub discussions: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+const SEARCH_GITHUB_TOPICS_DESCRIPTION = `**VITAL FOUNDATION TOOL** for effective GitHub discovery - provides semantic context that makes all other GitHub searches targeted and successful.
+
+**WHY ESSENTIAL:**
+- **Term Discovery**: Find correct terminology and keywords before searching repositories
+- **Quality Signals**: Featured/curated topics = community-validated, battle-tested projects
+- **Repository Filters**: Use topic names directly in ${TOOL_NAMES.SEARCH_GITHUB_REPOS} for precise targeting
+- **Ecosystem Mapping**: Understand technology landscapes with 100M+ repositories of production code
+
+**CRITICAL WORKFLOW - Topics → Repositories:**
+1. **Search topics first** → discover proper terminology (e.g., "machine-learning" not "AI")
+2. **Use topic names as filters** → in ${TOOL_NAMES.SEARCH_GITHUB_REPOS} for targeted results
+3. **Quality validation** → featured topics = GitHub-promoted, curated = community-maintained
+
+**SEARCH STRATEGY:**
+- Start simple: "react", "docker", "cli"
+- Combine when needed: "machine-learning python"
+- Avoid complex phrases: keep focused and discoverable
+
+**EXAMPLES:**
+- Search "javascript" → find topics like "typescript", "nodejs", "frontend"
+- Use discovered topics → search repos with topic:"typescript" for quality examples
+- Featured topics → guaranteed high-quality repository collections
+
+**RESULT OPTIMIZATION:**
+- 1-10 results: IDEAL for deep analysis
+- 10+ results: Add featured/curated filters
+- Use repository count as maturity indicator (>10K = established, 1K-10K = growing)
+
+**OUTPUT:** Strategic foundation for all GitHub discovery - transforms random searches into targeted, quality-focused repository discovery.`;
+
+function registerSearchGitHubTopicsTool(server) {
+    server.tool(TOOL_NAMES.SEARCH_GITHUB_TOPICS, SEARCH_GITHUB_TOPICS_DESCRIPTION, {
+        query: z
+            .string()
+            .describe("The search query to find topics (e.g., 'machine learning', 'react', 'devops', 'blockchain')"),
+        owner: z
+            .string()
+            .describe("Filter by repository owner/organization (e.g., 'example-org') obtained from the appropriate tool for fetching user organizations"),
+        featured: z
+            .boolean()
+            .optional()
+            .describe('Filter for featured topics curated by GitHub'),
+        curated: z
+            .boolean()
+            .optional()
+            .describe('Filter for topics curated by the GitHub community'),
+        repositories: z
+            .string()
+            .optional()
+            .describe("Filter by number of repositories using this topic (e.g., '>1000', '<500')"),
+        created: z
+            .string()
+            .optional()
+            .describe("Filter based on topic creation date (e.g., '>2022-01-01', '<2023-12-31')"),
+        limit: z
+            .number()
+            .optional()
+            .default(50)
+            .describe('Maximum number of topics to return (default: 50)'),
+        sort: z
+            .enum(['featured', 'repositories', 'created', 'updated'])
+            .optional()
+            .describe('Sort topics by specified criteria (default: best-match)'),
+        order: z
+            .enum(['asc', 'desc'])
+            .optional()
+            .default('desc')
+            .describe('Order of results returned (default: desc)'),
+    }, async (args) => {
+        try {
+            return await searchGitHubTopics(args);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to search GitHub topics: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+const SEARCH_GITHUB_USERS_DESCRIPTION = `Advanced GitHub users and organizations search for developer discovery.
+
+**SEARCH STRATEGY:**
+1. **Single Criteria First**: "react", "python", location
+2. **Then Combine**: "react javascript", location + language
+3. **Never Start Complex**: Avoid "senior react typescript developer with 5+ years"
+
+**CORE PURPOSE:**
+- Expert discovery and community building
+- Collaboration and learning opportunities
+- Recruitment and network expansion
+
+**SEARCH METHODOLOGY:**
+- **Phase 1**: Technology terms ("react", "python", "kubernetes") → analyze activity
+- **Phase 2**: Add context (location filters, experience indicators)
+- **Phase 3**: Specialized search (specific skills + activity filters)
+
+**RESULT TARGETS:**
+- 0 results: Try broader terms, remove filters
+- 1-20 results: IDEAL - Analyze profiles for expertise
+- 21-100 results: GOOD - Add location or activity filters
+- 100+ results: Add specific terms or increase follower/repo filters
+
+**TERM SELECTION:**
+- Technology: "javascript", "python", "golang", "rust"
+- Frameworks: "react", "vue", "django", "spring"
+- Roles: "devops", "frontend", "backend", "fullstack"
+- Context: "startup", "enterprise", "opensource"
+
+**FILTERING STRATEGY:**
+- Type: "user" for individuals, "org" for organizations
+- Location: Find developers in specific regions
+- Language: Search by primary programming language
+- Followers: Find influential developers (">100", ">1000")
+- Repos: Find active contributors (">10", ">50")
+- Date: Recent activity or long-standing members
+
+**DISCOVERY PATTERNS:**
+- **Technology Experts**: Language + high follower count
+- **Local Developers**: Location + technology
+- **Open Source Contributors**: High repo count + specific tech
+- **Industry Leaders**: Follower count + years of activity
+
+**CROSS-REFERENCE STRATEGY:**
+- Find repository contributors and maintainers
+- Combine with ${TOOL_NAMES.SEARCH_GITHUB_REPOS} for project involvement
+- Explore user repositories for learning opportunities
+
+**OUTPUT:** Developer and organization discovery for networking, learning, and collaboration.`;
+
+function registerSearchGitHubUsersTool(server) {
+    server.tool(TOOL_NAMES.SEARCH_GITHUB_USERS, SEARCH_GITHUB_USERS_DESCRIPTION, {
+        query: z
+            .string()
+            .describe("The search query to find users/organizations (e.g., 'react developer', 'python', 'machine learning')"),
+        owner: z
+            .string()
+            .describe("Filter by repository owner/organization (e.g., 'example-org') obtained from the appropriate tool for fetching user organizations"),
+        type: z
+            .enum(['user', 'org'])
+            .optional()
+            .describe('Filter by account type (user for individuals, org for organizations)'),
+        location: z
+            .string()
+            .optional()
+            .describe("Filter by location (e.g., 'San Francisco', 'London', 'Remote')"),
+        language: z
+            .string()
+            .optional()
+            .describe("Filter by primary programming language (e.g., 'javascript', 'python', 'java')"),
+        followers: z
+            .string()
+            .optional()
+            .describe("Filter by follower count (e.g., '>100', '>1000' for influential users)"),
+        repos: z
+            .string()
+            .optional()
+            .describe("Filter by repository count (e.g., '>10', '>50' for active contributors)"),
+        created: z
+            .string()
+            .optional()
+            .describe("Filter based on account creation date (e.g., '>2020-01-01', '<2023-12-31')"),
+        limit: z
+            .number()
+            .optional()
+            .default(50)
+            .describe('Maximum number of users to return (default: 50)'),
+        sort: z
+            .enum(['followers', 'repositories', 'joined'])
+            .optional()
+            .describe('Sort users by specified criteria (default: best-match)'),
+        order: z
+            .enum(['asc', 'desc'])
+            .optional()
+            .default('desc')
+            .describe('Order of results returned (default: desc)'),
+    }, async (args) => {
+        try {
+            return await searchGitHubUsers(args);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to search GitHub users: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+function registerAllTools(server) {
+    // Register all tools
+    registerSearchGitHubCodeTool(server);
+    registerFetchGitHubFileContentTool(server);
+    registerViewRepositoryTool(server);
+    registerNpmViewTool(server);
+    registerSearchGitHubReposTool(server);
+    registerSearchGitHubCommitsTool(server);
+    registerSearchGitHubPullRequestsTool(server);
+    registerGetUserOrganizationsTool(server);
+    registerNpmSearchTool(server);
+    registerViewRepositoryStructureTool(server);
+    registerSearchGitHubIssuesTool(server);
+    registerSearchGitHubDiscussionsTool(server);
+    registerSearchGitHubTopicsTool(server);
+    registerSearchGitHubUsersTool(server);
+}
+
+const server = new McpServer({
+    name: 'octocode-mcp',
+    version: '1.0.0',
+    description: `Code question assistant: Find, analyze, and explore any code in GitHub repositories and npm packages.
+       Use for code examples, implementations, debugging, and understanding how libraries work.`,
+}, {
+    capabilities: {
+        tools: {},
+    },
+    instructions: `
+    #PROMPT_SYSTEM_PROMPT
+    ${PROMPT_SYSTEM_PROMPT}`,
+});
+// Register all tools
+registerAllTools(server);
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.on('SIGINT', async () => {
+    process.exit(0);
+});
+process.stdin.on('close', async () => {
+    server.close();
+});