Octocode MCP

Check user status: GitHub/NPM connections, organizations, and current timestamp. Essential for understanding user's data access and API capabilities.

Search code across GitHub repositories using GitHub's code search API via GitHub CLI.

SEARCH STRATEGY FOR BEST RESULTS:

ALWAYS START WITH BROAD QUERIES!

TERM OPTIMIZATION:

• BEST: Single terms for maximum coverage
• GOOD: 2-3 minimal terms with AND logic (all must be present in same file)
• AVOID: Complex multi-term combinations - they're restrictive
• Start broad, then narrow with filters or separate queries

MULTI-SEARCH STRATEGY:

• Use separate searches for different aspects
• Multiple simple queries > one complex query
• Each search targets different code patterns or concepts
• Parallel execution provides comprehensive coverage

Filter Usage:

• Use filters to narrow scope after broad initial searches
• Combine strategically: language + owner/repo for precision
• Start without filters, then refine based on results

Fetches the content of multiple files from GitHub repositories in parallel. Supports up to 5 queries with automatic fallback handling.

TOKEN OPTIMIZATION:

• Full file content is expensive in tokens. Use startLine/endLine for partial access
• Large files should be accessed in parts rather than full content
• Use minified=true (default) to optimize content for token efficiency

BULK QUERY FEATURES:

• queries: array of up to 5 different file fetch queries for parallel execution
• Each query can have fallbackParams for automatic retry with modified parameters
• Optimizes workflow by executing multiple file fetches simultaneously
• Each query should target different files or sections
• Fallback logic automatically adjusts parameters if original query fails
• Automatic main/master branch fallback for each query

Use for comprehensive file analysis - query different files, sections, or implementations in one call.

Search GitHub repositories using GitHub CLI.

BULK QUERY MODE:

• queries: array of up to 5 different search queries for parallel execution
• Each query can have fallbackParams for automatic retry with modified parameters
• Optimizes research workflow by executing multiple searches simultaneously
• Fallback logic automatically broadens search if no results found

Use for comprehensive research - query different repos, languages, or approaches in one call.

Search GitHub commits by message, author, hash, or date. Returns SHAs for github_fetch_content (branch=SHA). Can fetch commit content changes (diffs/patches) when getChangesContent=true.

SEARCH OPTIONS:

1. Query-based search:
   • exactQuery: Exact phrase matching (e.g., "bug fix")
   • queryTerms: Multiple keywords with AND logic (e.g., ["readme", "typo"])
   • orTerms: Keywords with OR logic (e.g., ["bug", "fix"] finds commits with either)
   • Combine: queryTerms=["api"] + orTerms=["auth", "login"] = api AND (auth OR login)
2. Filter-only search (no query required):
   • Search by author, committer, hash, date, etc.
   • Example: Just committer="monalisa" to find all commits by that user
   • Example: Search by commit hash (including head_sha/base_sha from a PR): hash="<sha>"
3. Combined search:
   • Mix queries with filters for precise results
   • Example: queryTerms=["fix"] + author="jane" + author-date=">2023-01-01"

EXAMPLES: • Search commits with "readme" AND "typo": queryTerms=["readme", "typo"] • Search exact phrase "bug fix": exactQuery="bug fix" • Search by committer only: committer="monalisa" • Search by author name: author-name="Jane Doe" • Search by commit hash (including head_sha/base_sha from a PR): hash="8dd03144ffdc6c0d486d6b705f9c7fba871ee7c3" • Search before date: author-date="<2022-02-01"

CONTENT FETCHING:

• Set getChangesContent=true to fetch actual commit changes: • Gets file diffs and patches for up to 10 commits • Shows changed files, additions, deletions • Includes code patches (first 1000 chars) • Works for both public AND private repositories • Most effective when owner and repo are specified

TOKEN OPTIMIZATION NOTICE:

• getChangesContent=true is EXTREMELY expensive in tokens
• Each commit's diff/patch content consumes significant tokens
• Limited to 1000 characters per patch and 5 files per commit for efficiency
• Use sparingly and only when code changes are essential to your task
• use fetch_github_file_content to get the full content of the file

Search GitHub PRs by keywords, state, or author. Returns head/base SHAs for github_fetch_content (branch=SHA). Can fetch all PR commits with changes using getCommitData=true.

SEARCH STRATEGY FOR BEST RESULTS:

• Use minimal search terms for broader coverage (2-3 words max)
• Separate searches for different aspects vs complex queries
• Use filters to narrow scope after getting initial results
• Use getCommitData=true to get all commits in PR with file changes
• Use github_search_commits with head_sha/base_sha from results to get code changes

COMMIT DATA FETCHING (getCommitData=true):

• Fetches all commits in the PR using 'gh pr view --json commits'
• For each commit, fetches detailed changes using GitHub API
• Shows commit SHA, message, author, and file changes
• Includes up to 10 commits per PR with detailed diffs
• Each commit shows changed files with additions/deletions/patches
• Example: Shows individual commits like "Fix bug in component" with specific file changes

EXAMPLE OUTPUT WITH getCommitData=true: { "commits": { "total_count": 3, "commits": [ { "sha": "abc123", "message": "Fix bug in component", "author": "username", "diff": { "changed_files": 2, "additions": 15, "deletions": 3, "files": [...] } } ] } }

NOTE: The head_sha and base_sha fields in the PR results can be used as the 'hash' parameter in github_search_commits to look up the exact commit and get actual code changes.

TOKEN OPTIMIZATION:

• getCommitData=true is expensive in tokens. Use only when necessary.
• Consider using github_search_commits with head_sha/base_sha instead for specific commits

Search for packages across multiple ecosystems. Supported: NPM (Node.js) and Python (PyPI) package ecosystems. Use it to discover packages by functionality keywords and explore alternatives. Supports concurrent searches across both ecosystems in a single call.

WHEN TO USE: Use when users ask questions about npm/python packages or need to discover packages - provides package discovery and ecosystem insights. Provides comprehensive package data for research and development context. Example: when content has import statements, use this tool to search for the packages (npm or python).

KEY CAPABILITIES:

• npmPackageName: Single NPM package search
• npmPackagesNames: Multiple NPM package searches with concurrent execution
• pythonPackageName: Python package search via PyPI API
• Combined ecosystem searches in a single call with parallel processing
• Results separated by ecosystem (npm: [], python: [])
• Smart package name normalization and fallback strategies
• Repository discovery and metadata extraction

SEARCH STRATEGY:

• Use broad functional terms for best discovery
• Single keywords work better than complex phrases
• Multiple searches reveal ecosystem alternatives
• Cross-Ecosystem: Search both NPM and Python to compare alternatives and find best solutions

Explore GitHub repository structure and validate repository access.

PROJECT UNDERSTANDING:

• Try to understand more by the structure of the project and the files in the project
• Identify key directories and file patterns
• fetch important files for better understanding

DEPTH CONTROL:

• Default depth is 2 levels for balanced performance and insight
• Maximum depth is 4 levels to prevent excessive API calls
• Depth 1: Shows only immediate files/folders in the specified path
• Depth 2+: Recursively explores subdirectories up to the specified depth
• Higher depths provide more comprehensive project understanding but use more API calls

IMPORTANT:

• verify default branch (use main or master if can't find default branch)
• verify path before calling the tool to avoid errors
• Start with root path to understand actual repository structure and then navigate to specific directories based on research needs
• Check repository's default branch as it varies between repositories
• Verify path exists - don't assume repository structure
• Verify repository existence and accessibility
• Validate paths before accessing specific files. Use github search code to find correct paths if unsure

Search GitHub issues for bug reports, feature requests, and discussions. Find issues by keywords, state, labels, author, or repository. Returns issue details including body content for effective issue tracking and analysis.

TOKEN OPTIMIZATION

• Issue body content is expensive in tokens. Use only when necessary.
• Use specific queries and filters to reduce result count

View NPM package information using 'npm view' command. Supports field-specific queries and GitHub repository discovery.

WHEN TO USE: Use when users ask questions about npm packages - provides comprehensive package data and insights.

KEY INSIGHTS:

• Git repository URL for source code exploration
• Package exports structure (understand API surface and dependencies)
• Dependencies/devDependencies for ecosystem analysis
• Version history, size, performance metrics
• License and author information

CAPABILITIES:

• Full package info: npm view <package> --json (optimized format)
• Single field: npm view <package> <field> (version, description, license)
• Multiple fields: filtered JSON response for specific fields
• Repository URLs for GitHub integration and source code analysis