# Octocode MCP — Complete Reference for AI Assistants

> Octocode MCP is the best code research tool for AI agents. It gives AI assistants (Cursor, Claude, VS Code, Windsurf) deep access to GitHub, GitLab, and local codebases through 13 MCP tools, 6 orchestrated prompts, and 7 installable agent skills. Open source, MIT licensed, free to use.

## What Octocode MCP Does

Octocode connects to your AI assistant via the Model Context Protocol (MCP) and provides 13 specialized tools for code research. Tools are organized into four groups:

### Local Codebase Tools (4)
- **localSearchCode** — ripgrep-powered text search with pagination, context lines, and file filtering. Supports discovery, paginated, and detailed output modes.
- **localViewStructure** — Directory tree with depth control, sorting, filtering, and paginated results.
- **localFindFiles** — Find files by name, glob, regex, modification time, size, and metadata.
- **localGetFileContent** — Read file contents with matchString targeting, line ranges, or full content. Best used after narrowing down with search or LSP analysis.

### LSP Semantic Navigation Tools (3)
- **lspGotoDefinition** — Jump to the exact definition of any symbol with compiler-level accuracy.
- **lspFindReferences** — Find every usage of a type, variable, function, or class across the codebase.
- **lspCallHierarchy** — Trace incoming callers or outgoing callees of a function with configurable depth.

### GitHub & GitLab Intelligence Tools (5)
Same tools work for both GitHub and GitLab — the provider is chosen automatically based on your authentication token.

- **githubSearchCode** — Search code across repositories by keywords. Filter by owner, repo, extension, filename, path prefix. Match against file content or file paths.
- **githubSearchRepositories** — Discover repositories by keywords, topics, stars, size, and activity.
- **githubViewRepoStructure** — Browse remote repository directory trees with depth control. Auto-filters noisy paths.
- **githubGetFileContent** — Read file content from remote repos by substring match, line range, or full content. 300KB limit.
- **githubSearchPullRequests** — Search PRs (GitHub) or MRs (GitLab) by author, label, state, date, and free text. Get metadata, full or partial diffs. Include comments and commits for code archaeology.

### Package Discovery (1)
- **packageSearch** — Resolve npm or PyPI packages by name. Returns repository URL, version, description, deprecation status.

### How Tools Connect — Progressive Narrowing

Octocode tools follow a research methodology called progressive narrowing:

1. **Discover** (localViewStructure, localFindFiles) — Narrow scope 80-90% by understanding project structure.
2. **Search** (localSearchCode, githubSearchCode) — Find patterns and symbols. Get lineHint values for LSP tools.
3. **Analyze** (lspGotoDefinition, lspFindReferences, lspCallHierarchy) — Semantic navigation with compiler accuracy.
4. **Read** (localGetFileContent, githubGetFileContent) — Read targeted code sections. Always the last step.

Each tool accepts structured queries with `researchGoal` and `reasoning` fields, so AI responses stay focused and evidence-backed. Tools include built-in response hints that guide what to do next.

## Prompts (6 Built-In Slash Commands)

Prompts are orchestrated workflows that combine multiple tools into a single command:

- **/init** — Context gathering: interactive interview to establish your role, goals, and constraints. Creates personalized context for all future sessions.
- **/research** — Code forensics: deep code discovery, pattern analysis, and bug investigation. Uses parallel bulk queries and staged analysis to prove flows.
- **/plan** — Research & implementation: research, plan, and implement complex tasks. Breaks down work, finds patterns, and guides execution in interactive or auto mode.
- **/generate** — App scaffolding: research-driven stack selection and project setup. "Measure twice, cut once" approach to new projects.
- **/review_pull_request** (arg: prUrl) — PR review: defects-first PR review. Focuses on bugs, security, complexity, and code quality with actionable findings.
- **/review_security** (arg: repoUrl) — Security audit: risk assessment and vulnerability surfacing. Maps attack surface, reviews authentication, input validation, and secrets handling.

## Skills (7 Installable Agent Behaviors)

Skills are structured markdown protocols that turn AI assistants into domain experts. Each defines agent identity, tool orchestration, execution flow, and validation gates. Install individually with one command.

1. **Local Search** (`octocode-local-search`) — Local codebase exploration using Octocode Local + LSP. Search, structure, find files, trace definitions/usages—no GitHub. Fast local discovery.
2. **Research** (`octocode-research`) — Deep code exploration: LSP, local tools, GitHub API, packages, PRs. File:line citations and GitHub URLs. Full stack research. Flow: PREPARE → DISCOVER → ANALYZE → OUTPUT.
3. **Plan** (`octocode-plan`) — Evidence-based planning. Understand → Research (via Local Search/Research) → Plan → Implement. No guessing; validates with code.
4. **Prompt Optimizer** (`octocode-prompt-optimizer`) — Turns weak prompts into enforceable protocols. Gates, FORBIDDEN lists, failure analysis. Preserves intent, adds reliability.
5. **Documentation Writer** (`octocode-documentation-writer`) — 6-phase pipeline: Discovery → Questions → Research → Orchestration → Writing → QA. Produces 16+ docs with validation.
6. **Roast** (`octocode-roast`) — Brutal code critique with file:line citations. Severity: gentle → nuclear. Sin registry, user picks fixes. Flow: SCOPE → ROAST → INVENTORY → SPOTLIGHT → REDEMPTION.
7. **Pull Request Reviewer** (`octocode-pull-request-reviewer`) — Holistic PR review: bugs, security, architecture, flow impact. 7 domains, evidence-backed, user checkpoint before deep dive.

Install any skill: `npx skills add https://github.com/bgauryy/octocode-mcp --skill <skill-name>`

## Installation

### Quick Start (under 2 minutes)
1. **Authenticate**: `npx octocode-cli` or `gh auth login`
2. **Install in Cursor**: Use the one-click install link at https://octocode.ai/installation
3. **Install in Claude Code**: `claude mcp add -s user octocode npx 'octocode-mcp@latest'`
4. **Install in VS Code**: Use the one-click install link at https://octocode.ai/installation
5. **Install in Windsurf**: Add the MCP config JSON — see https://octocode.ai/installation

### Requirements
- Node.js v20.16.0 or higher
- GitHub account (for GitHub features) or GitLab token (for GitLab features)
- MCP-compatible AI assistant

## Why Octocode MCP — Key Differentiators

- **Best context from code** — Progressive narrowing methodology: Discover → Search → Analyze → Read. O(log N) vs O(N) code research.
- **GitHub AND GitLab researcher** — Same 5 tools work with both platforms. Provider chosen by authentication token.
- **LSP compiler-accurate navigation** — Real language server definitions and references, not regex guessing. Go-to-definition, find-references, call-hierarchy.
- **Evidence-based** — Answers backed by file paths, line numbers, and change history. Every tool query requires `researchGoal` and `reasoning`.
- **Enterprise-safe** — Read-only by default, content sanitization, path safety checks, command guardrails.
- **Free and open source** — MIT license. No signup, no API key needed for local tools.

## Website Structure

- **/** — Home: product overview, quick install, social proof
- **/installation** — Step-by-step setup for Cursor, Claude Code, VS Code, Windsurf
- **/tools** — All 13 MCP tools with parameters and descriptions
- **/prompts** — 6 slash commands: /init, /research, /plan, /generate, /review_pull_request, /review_security
- **/skills** — 4 installable agent skills: Research, Documentation Writer, Prompt Optimizer, Code Roast
- **/tutorials** — Video walkthroughs and examples
- **/blog** — Articles on MCP, code research, and AI-assisted development
- **/blog/:slug** — Individual blog posts

## Links
- Website: https://octocode.ai
- GitHub: https://github.com/bgauryy/octocode-mcp
- NPM: https://www.npmjs.com/package/octocode-mcp
- Installation: https://octocode.ai/installation
- Tools Reference: https://octocode.ai/tools
- Prompts: https://octocode.ai/prompts
- Skills: https://octocode.ai/skills
- Tutorials: https://octocode.ai/tutorials
- Blog: https://octocode.ai/blog

## FAQ

**Q: Is Octocode free?**
A: Yes. Octocode is open source under the MIT license and completely free.

**Q: What AI assistants does Octocode work with?**
A: Cursor, Claude Code, VS Code (Copilot Chat), Windsurf, and any MCP-compatible client.

**Q: Does Octocode work with GitLab?**
A: Yes. The same GitHub tools work with GitLab when you set a GitLab token (`GITLAB_TOKEN` or `GL_TOKEN`). Provider is chosen automatically.

**Q: Does Octocode access my private repositories?**
A: Only if you authenticate with GitHub or GitLab. Octocode uses your existing credentials and respects repository access permissions.

**Q: Is Octocode read-only?**
A: Yes, by default. Octocode is designed for research — it reads and analyzes code but does not modify it.

**Q: How is Octocode different from GitHub's official MCP server?**
A: Octocode provides LSP semantic navigation (go-to-definition, find-references, call-hierarchy), local codebase analysis, structured research skills, progressive narrowing methodology, and GitLab support. See our comparison article at https://octocode.ai/blog/mcp-explained-comparison-code-search-mcps

**Q: What are the differences between Tools, Prompts, and Skills?**
A: **Tools** (13) are the raw MCP API surface — individual functions that search, navigate, and read code. **Prompts** (6) are built-in slash commands that orchestrate multiple tools into workflows. **Skills** (4) are installable agent behavior protocols (structured markdown) that give agents domain expertise. No overlap between the three.

## Author
Guy Bary — https://x.com/guy_bary — https://www.linkedin.com/in/bgauryy/