# Octocode MCP — Best Code Research Tool for AI Agents

> Octocode MCP gives AI agents the deepest context from code. 13 MCP tools for GitHub, GitLab, and local codebase research — LSP semantic navigation, code search, pull request archaeology, and package discovery. The best code researcher for Cursor, Claude, VS Code, Windsurf, and any MCP-compatible assistant.

- [Full Reference (llms-full.txt)](https://octocode.ai/llms-full.txt): Complete tool specs, all prompts, all skills, FAQ, and installation details

## What Octocode MCP Is

Octocode MCP is an open-source Model Context Protocol server that turns AI assistants into expert code researchers. It provides three categories of capabilities:

- **Tools** (13): The raw MCP tools that search, navigate, and read code across local workspaces, GitHub, and GitLab
- **Prompts** (6): Built-in slash commands that orchestrate multi-tool workflows — research, planning, code review, security audits
- **Skills** (7): Installable agent behavior protocols (structured markdown) that give agents domain expertise: Local Search, Research, Plan, PR Reviewer, Roast, Prompt Optimizer, Documentation Writer

## Website Structure

- [Home](https://octocode.ai/): Product overview, quick install, social proof
- [Installation](https://octocode.ai/installation): Step-by-step setup for Cursor, Claude Code, VS Code, Windsurf
- [Tools](https://octocode.ai/tools): All 13 MCP tools with parameters and descriptions
- [Prompts](https://octocode.ai/prompts): 6 slash commands — /init, /research, /plan, /generate, /review_pull_request, /review_security
- [Skills](https://octocode.ai/skills): 7 installable agent skills — Local Search, Research, Plan, PR Reviewer, Roast, Prompt Optimizer, Documentation Writer
- [Tutorials](https://octocode.ai/tutorials): Video walkthroughs and examples
- [Blog](https://octocode.ai/blog): Articles on MCP, code research methodology, and AI-assisted development

## Getting Started

- [Installation Guide](https://octocode.ai/installation): One-click for Cursor/VS Code, one command for Claude
- [GitHub Repository](https://github.com/bgauryy/octocode-mcp): Source code, docs, and README
- [NPM Package](https://www.npmjs.com/package/octocode-mcp): Install via `npx octocode-mcp@latest`

## Tools (13 MCP Tools)

Tools are the core API surface. Each accepts structured queries with `researchGoal` and `reasoning` fields for evidence-backed responses.

### Local Workspace (4 tools)
- `localSearchCode` — Fast regex/literal search across local files (ripgrep-powered)
- `localGetFileContent` — Read targeted file sections by match, line range, or full content
- `localFindFiles` — Find files by name, glob, regex, size, or modification time
- `localViewStructure` — Browse directory trees with depth control, sorting, and filtering

### LSP Semantic Navigation (3 tools)
- `lspGotoDefinition` — Jump to exact symbol definitions with compiler accuracy
- `lspFindReferences` — Find every usage of a type, variable, or constant across the codebase
- `lspCallHierarchy` — Trace incoming/outgoing call relationships for functions and methods

### GitHub & GitLab Intelligence (5 tools)
- `githubSearchCode` — Search code by keywords across repositories, filter by owner/repo/extension/path
- `githubSearchRepositories` — Discover repos by keywords, topics, stars, and activity
- `githubViewRepoStructure` — Browse remote repository directory trees
- `githubGetFileContent` — Read file content from remote repos by match or line range
- `githubSearchPullRequests` — Search PRs/MRs with metadata, diffs, comments, and commits

### Package Discovery (1 tool)
- `packageSearch` — Resolve npm or PyPI packages by name, get repo URL and metadata

## Prompts (6 Slash Commands)

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

- `/init` — Context gathering: interactive interview to set up personalized research context
- `/research` — Code forensics: deep discovery, pattern analysis, bug investigation with parallel queries
- `/plan` — Research & implementation: break down complex tasks, find patterns, guide execution
- `/generate` — App scaffolding: research-driven stack selection and project setup
- `/review_pull_request` — PR review: defects-first review focusing on bugs, security, complexity
- `/review_security` — Security audit: risk assessment, attack surface mapping, vulnerability surfacing

## Skills (7 Agent Behaviors)

Skills are structured markdown protocols that turn AI assistants into domain experts. Install individually:

- **Local Search** — Local codebase exploration with LSP; search, structure, definitions/usages—no GitHub
- **Research** — Deep code exploration: LSP, GitHub, packages, PRs; file:line citations
- **Plan** — Evidence-based planning; research-first, validates with code
- **Prompt Optimizer** — Turns weak prompts into enforceable protocols; gates, FORBIDDEN lists
- **Documentation Writer** — 6-phase pipeline producing 16+ docs with validation
- **Roast** — Brutal code critique with file:line citations; severity gentle→nuclear
- **Pull Request Reviewer** — Holistic PR review: bugs, security, architecture; 7 domains

## Why Octocode MCP

- Best context from code — progressive narrowing methodology: Discover → Search → Analyze → Read
- GitHub AND GitLab researcher — same tools, provider chosen by token
- LSP compiler-accurate navigation — not regex guessing, real language server definitions and references
- Enterprise-safe — read-only by default, content sanitization, path safety checks
- Free and open source — MIT license

## Key Facts

- License: MIT (open source, free)
- Install: `npx octocode-mcp@latest`
- Hosts: Cursor, Claude Code, VS Code, Windsurf, any MCP-compatible client
- Author: Guy Bary
- Repository: https://github.com/bgauryy/octocode-mcp
- NPM: https://www.npmjs.com/package/octocode-mcp