convez.ai
MCP ServerBusca & PesquisaIntermediário
bgauryy

Octocode: Pesquisa de Código para IA

bgauryy/octocode-mcp

Pesquise código como um Senior Engineer em qualquer codebase, em segundos.

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que transforma codebases em conhecimento otimizado para IA através de busca semântica local e em repositórios públicos/privados do GitHub. Combina ripgrep, LSP (go-to-definition, referências, call hierarchy) e integração com GitHub para fornecer contexto verificável e implementações reais. Funciona como servidor MCP integrado a assistentes IA ou como CLI autônoma.

Instalação

$npx convez-ai bgauryy/octocode-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
967
Forks
80
Acompanhando
7
Saúde
42%
Último commit
há 1 semana
Versão
9.1.1
Issues abertas
14
Contribuidores
7

Casos de uso

  • Buscar padrões de implementação em repositórios GitHub públicos e privados
  • Análise de dependências e rastreamento de chamadas em codebases locais com LSP
  • Pesquisa contextual para PR reviews e refatoração de código
  • Descoberta de pacotes npm/PyPI com resolução automática para repositórios fonte

Veredito

Ferramenta robusta que eleva significativamente a capacidade de pesquisa de código do Claude, essencial para análise profunda de projetos e discovery de padrões. Implementação técnica sólida (TypeScript, LSP, GitHub API), funcionalidade dual (MCP + CLI) bem executada, mas exige autenticação GitHub prévia para utilidade máxima.

README

A tradução para o português deste README ainda está na fila.

Octocode: Research Driven Development for AI


Two ways to run Octocode

🔌 As an MCP Server💻 As a CLI
ForYour AI assistant (Claude Code, Cursor, Claude Desktop, +13 more)Your terminal & scripts
Installnpx octocode-cli installbrew tap bgauryy/octocode → brew install octocode
You get14 research tools wired into your agentThe same 14 tools, runnable from the shell
Best forDeep agent research, planning, PR reviewQuick scripted lookups, CI, piping to other tools

Same engine, same tools, two surfaces. Pick one or use both.

Prerequisites: GitHub authentication for the GitHub-backed tools. Run octocode login, or see Authentication Setup.


🔌 As an MCP Server

Wire Octocode's tools into your AI assistant. The interactive installer handles GitHub OAuth, MCP server config, and the skills marketplace:

npx octocode-cli install

Pass --ide <client> for a non-interactive install (e.g. octocode install --ide cursor).

Add to your MCP configuration file:

{
  "mcpServers": {
    "octocode": {
      "command": "npx",
      "args": ["octocode-mcp@latest"]
    }
  }
}
npx add-skill https://github.com/bgauryy/octocode-mcp/tree/main/skills/octocode-research

The Octocode MCP Server connects your AI assistant to code:

  • GitHub: Search repositories, find usage patterns, read implementations, explore PRs
  • Local Tools: Search code (ripgrep), browse directories, find files in your local codebase
  • LSP Intelligence: Go to Definition, Find References, Call Hierarchy (compiler-level understanding)
  • Package Discovery: Resolve npm/PyPI packages to their source repos

https://github.com/user-attachments/assets/de8d14c0-2ead-46ed-895e-09144c9b5071


💻 As a CLI

The same 14 tools, straight from your terminal — no MCP server, no IDE required.

Install

# Homebrew (macOS / Linux) — recommended
brew install bgauryy/octocode/octocode

# or tap once, then use the short name
brew tap bgauryy/octocode
brew install octocode

# npm global
npm install -g octocode-cli

# or run once, no install
npx octocode-cli install

Node is pulled in automatically by Homebrew. The installed command is octocode (not octocode-cli).

Verify and sign in:

octocode --version   # → octocode v1.5.3
octocode login       # GitHub OAuth — required for the GitHub-backed tools

What you get

The CLI is two things in one binary:

  1. Setup wizard — install the MCP server + skills, manage GitHub OAuth, sync configs across 15 editors
  2. Standalone tool runner — call any of the 14 tools, pipe JSON to other tools, use in CI

Commands

CommandWhat it does
octocode login / logoutGitHub OAuth device flow (--hostname for Enterprise)
octocode install --ide <client>Configure octocode-mcp for an IDE/agent
octocode statusFull health check: auth + installed MCPs + cache
octocode tokenPrint the resolved GitHub token (--source, --validate)
octocode skillsSearch / install / remove / sync Agent Skills
octocode mcpMCP marketplace: list / install / remove / status
octocode syncSync MCP configs across all IDE clients (--dry-run, --status)
octocode cacheInspect / clean repos, skills, logs, and tool caches
octocode toolsList, inspect schema, or run a tool with --queries '<json>'
octocode instructionsPrint full MCP instructions + every tool schema

Top-level flags: --version/-v, --help/-h, --json/-j, --agent (agent bootstrap).

The 14 tools

Run any directly with octocode tools <name> --queries '<json>':

GroupTools
GitHubgithubSearchCode · githubSearchRepositories · githubSearchPullRequests · githubGetFileContent · githubViewRepoStructure · githubCloneRepo
LocallocalSearchCode (ripgrep) · localFindFiles · localGetFileContent · localViewStructure
LSPlspGotoDefinition · lspFindReferences · lspCallHierarchy
PackagepackageSearch (npm / PyPI → source repo)
octocode tools                                                              # list all
octocode tools localSearchCode                                              # inspect schema
octocode tools localSearchCode --queries '{"path":".","pattern":"TODO"}'   # run
octocode tools githubSearchCode --queries '{"keywordsToSearch":["useState"],"owner":"facebook","repo":"react"}'

Supported install targets: Cursor, Claude Code, Claude Desktop, Windsurf, Zed, Trae, Antigravity, Kiro, Codex, Opencode, Gemini CLI, Goose, VS Code Cline / Roo / Continue. Full reference: CLI Reference.


Packages

This is a yarn-workspaces monorepo. Each package has its own README.md; all setup/reference docs live in docs/, and all AI agent guidance lives in the root AGENTS.md.

PackagePurpose
octocode-mcpMCP server: 14 tools across GitHub, local FS, LSP
octocode-cliCLI: installer, tool runner, skills marketplace
octocode-vscodeVS Code extension: GitHub OAuth + multi-editor MCP install
octocode-sharedShared utilities: credentials, session, platform
octocode-security-utilsStandalone security utilities

Skills

Agent Skills are a lightweight, open format for extending AI agent capabilities. Skills index: skills/README.md

Research & Code Analysis

SkillWhat it does
ResearcherCode search & exploration: local LSP + external (GitHub, npm/PyPI)
ResearchMulti-phase research with sessions, checkpoints, state persistence
EngineerUnderstand, write, analyze, audit code: AST + LSP + dependency graph
BrainstormingIdea validation grounded in evidence: GitHub, npm/PyPI, web in parallel
NewsWhat's new in AI, dev tools, web platform, security, notable repos

Planning & Writing

SkillWhat it does
PlanEvidence-based planning: Understand > Research > Plan > Implement
RFC GeneratorFormal technical decisions with alternatives, trade-offs, and recommendations
Doc Writer6-phase pipeline producing 16+ validated docs
Prompt OptimizerTurn weak prompts into enforceable agent protocols
Agentic FlowThinking framework for designing/reviewing MCP & multi-agent workflows

Review & Critique

SkillWhat it does
PR ReviewerPR & local code review across 7 domains with LSP flow tracing
RoastBrutal code critique with file:line citations and severity levels

Build & Output

SkillWhat it does
SlidesPolished multi-file HTML presentations via 6-phase design flow
DesignDynamic DESIGN.md generator covering visual language, components, a11y
Chrome DevToolsCDP-level browser debugging: network, console, perf, DOM, screenshots

Tooling & Setup

SkillWhat it does
InstallInteractive step-by-step Octocode installer for macOS and Windows
CLIRun Octocode MCP tools from the terminal without wiring MCP
Search SkillFind, evaluate, install, refactor Agent Skills (SKILL.md format)
StatsLocal HTML dashboard from Octocode MCP usage stats

https://github.com/user-attachments/assets/5b630763-2dee-4c2d-b5c1-6335396723ec


Documentation

Full index: docs/README.md. All monorepo documentation lives in docs/ (no per-package docs/).

Docs map

  • docs/configuration/: install, auth providers, MCP clients, env/config, troubleshooting
  • docs/dev/: tool/API references, workflows, architecture, contributing, skills
  • docs/specs/: design specs and RFCs

Setup

Tool References

CLI & Skills

Shared Internals

Operations

The Manifest

"Code is Truth, but Context is the Map." Read the Manifest for Research Driven Development to understand the philosophy behind Octocode.


Contributing

See the Development Guide for monorepo setup, testing, and contribution guidelines.


Ver o original no GitHub

Bom para

Relacionados