Octocode

Name: Octocode
Author: bgauryy

@bgauryy

About Octocode

Advanced AI code assistant that intelligently searches and discovers connections across GitHub repositories and NPM packages. Features zero-config authentication, smart fallbacks, and LLM-optimized content delivery. Ask natural language questions to understand code architectures,

#code-search #code-discovery #ai-assistant

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "octocode": {
      "command": "npx",
      "args": [
        "octocode-mcp"
      ]
    }
  }
}

Tools

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 CLI. Choose one search method: - exactQuery: exact phrase matching - queryTerms: array of terms (space-separated, AND logic) Use filters to narrow results after initial broad searches.

Fetches the content of a file from a GitHub repository. Automatically falls back between main/master branches if not found.

Search GitHub repositories using gh search repos CLI. THREE SEARCH APPROACHES: - exactQuery: Single exact phrase/word search - queryTerms: Multiple search terms (broader coverage) - topic: Find repositories by technology/subject BEST PRACTICES: - Use exactQuery for specific repository names - Use queryTerms with minimal words for broader results - Use topic for technology/subject discovery - Use owner for organization exploration - Use filters (language, stars, forks) for refinement Multiple focused searches work better than complex single queries.

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

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.

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 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.

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

Overview

What is Octocode?

Octocode is an AI-powered code assistant that provides advanced search and discovery across GitHub and NPM ecosystems. It uses heuristic algorithms with smart fallbacks to understand connections between repositories and NPM packages across public, private, and organization repositories. It is designed for developers and technical researchers who want to explore code intelligently.

How to use Octocode?

Install Node.js 18.12+ and GitHub CLI, then authenticate with gh auth login (and optionally npm login). Add "octocode-mcp" to your MCP configuration with npx octocode-mcp. Octocode automatically works with your repositories — just ask natural language questions. It is also available as a Desktop Extension (DXT) for Claude Desktop.

Key features of Octocode

AI-powered search with heuristic pattern recognition and automatic fallbacks
Connection mapping between NPM packages and GitHub repositories
Zero-config security using GitHub CLI OAuth — no tokens needed
Universal access to public, private, and organization repositories
Advanced content minification reduces LLM token usage by 80‑90%
10 specialized tools for discovery, analysis, activity, and content

Use cases of Octocode

Understand how popular libraries implement specific patterns (e.g., React concurrent rendering)
Find authentication patterns in frameworks like Next.js
Compare implementations across projects (e.g., React vs Vue.js rendering)
Analyze code from specific commits, PRs, or historical versions
Build tutorials or examples by discovering real-world code snippets

FAQ from Octocode

How does Octocode authenticate?

It uses GitHub CLI (gh) OAuth flow — no personal access tokens needed. Works with SSO, 2FA, and organization access.

What are the runtime requirements?

Node.js 18.12+ and GitHub CLI. NPM login is optional for package research.

Where does my data live?

Octocode runs 100% locally on your machine — no data collection or telemetry is transmitted.

How does Octocode differ from other GitHub MCPs?

While others focus on project management or basic operations, Octocode provides AI-powered code discovery and deep technical research across the entire GitHub and NPM ecosystem.

What transport and auth does Octocode use?

It uses the MCP protocol via command-line transport (npx). Authentication is handled entirely through the GitHub CLI, with no separate tokens or configuration needed.