octocode-mcp

Executes natural language queries against public and private GitHub/GitLab repositories using the GitHub Search API and GitLab API, translating user intent into optimized code search queries. Implements a 6-level token resolution priority chain (environment variables, OAuth tokens, personal access tokens) evaluated on every API call without caching, enabling dynamic permission-based access control. Supports both GitHub Cloud and GitHub Enterprise Server via configurable GITHUB_API_URL, with per-tool circuit breakers preventing cascading failures during rate limiting.

Exposes repository directory trees and file hierarchies via the viewRepoStructure tool, parsing GitHub/GitLab API responses into nested JSON structures representing the full codebase organization. Implements lazy-loading patterns to handle large monorepos by returning paginated results, with configurable depth limits to prevent token exhaustion. Integrates with LSP (Language Server Protocol) tools for semantic understanding of file relationships and import dependencies.

Provides extensibility mechanism via skills marketplace enabling developers to create custom tools and workflows extending the core 13-tool registry. Implements skill packaging format with metadata (name, description, tools, permissions), skill discovery via marketplace API, and dynamic tool registration at runtime. Each skill includes self-contained tool implementations with schema validation and error handling, enabling community contributions without core codebase changes.

Optimizes multiple sequential API calls into batched requests where possible, reducing round-trip latency and API rate limit consumption. Implements query optimization combining multiple filter conditions into single GitHub Search API calls, and bulk file retrieval via GitHub API tree endpoint. Supports concurrent tool execution with configurable concurrency limits (default 5 concurrent requests) and exponential backoff for rate-limited responses.

Tracks research sessions with unique identifiers, recording tool execution history, API call metrics, and error events. Implements session persistence via octocode-shared infrastructure enabling session resumption and audit trails. Collects telemetry including API latency, rate limit usage, tool success rates, and error frequencies, with optional reporting to telemetry backend for usage analytics and debugging.

Implements per-tool circuit breakers preventing cascading failures when APIs become unavailable or rate-limited. Uses exponential backoff strategy for transient errors (429, 503) with configurable retry limits (default 3 retries). Implements timeout protection (default 30 seconds per request) and graceful degradation returning partial results when possible. Includes detailed error classification (transient vs permanent) enabling intelligent retry logic.

Provides VS Code Extension implementing OAuth flow for token acquisition without manual PAT creation, and server process launcher managing octocode-mcp lifecycle within VS Code. Implements token synchronization between VS Code Extension and MCP server via encrypted credential storage, and configuration management for VS Code-specific settings (tools, token preferences). Integrates with VS Code's built-in authentication provider API for seamless OAuth experience.

Fetches raw file contents from GitHub/GitLab repositories using the getFileContent tool, implementing content-aware streaming for large files (>1MB) to prevent token overflow in LLM contexts. Uses GitHub's raw content API endpoints for efficient delivery, with optional base64 encoding for binary files. Integrates with the content processing pipeline to apply syntax highlighting metadata and language detection before returning to clients.

Searches GitHub/GitLab pull requests and issues using the searchPullRequests tool, translating natural language queries into GitHub Search API syntax with support for advanced filters (state, author, labels, date ranges). Implements query optimization to reduce API calls by combining multiple filter conditions into single requests. Returns structured metadata including PR/issue status, author information, and linked commits for context-aware analysis.

Provides local filesystem access via LSP (Language Server Protocol) tools, enabling semantic analysis of code structure without cloning repositories. Implements per-language LSP server management (Python, TypeScript, Go, Rust, etc.) with automatic server lifecycle management (start, stop, restart on failure). Supports symbol queries (definitions, references, hover information) and diagnostic analysis (linting, type errors) through standardized LSP protocol, with results cached per-session to reduce redundant analysis.

Searches npm, PyPI, and other package registries via the packageSearch tool, translating natural language queries into registry-specific API calls. Implements provider abstraction layer supporting multiple registries with unified query interface, returning structured metadata (versions, dependencies, maintainers, download stats). Integrates with dependency resolution to identify transitive dependencies and version compatibility issues.

Registers 13 discrete tools (searchCode, getFileContent, viewRepoStructure, etc.) with the Model Context Protocol via stdio, implementing tool metadata and hints system for client discovery. Each tool includes JSON Schema validation for inputs, with per-tool circuit breakers and resilience wrappers preventing cascading failures. Tool registry supports dynamic registration enabling extensibility via skills marketplace, with self-check protocol validating tool availability before execution.

Orchestrates multi-step research workflows via the octocode-research HTTP server, implementing a formal 5-phase sequential pipeline (Planning, Exploration, Analysis, Synthesis, Validation) with checkpoint support for resumable research. Each phase executes atomic tool calls with self-check protocol validating results before proceeding to next phase. Implements context management with configurable token budgets per phase, circuit breakers preventing infinite loops, and telemetry tracking research progress.

Implements 6-level dynamic token resolution priority chain evaluated on every API call: environment variables → OAuth tokens → personal access tokens → GitHub App tokens → GitLab tokens → fallback to unauthenticated. Uses encrypted credential storage via octocode-shared infrastructure with per-platform encryption (macOS Keychain, Windows Credential Manager, Linux secret-tool). Supports OAuth flow via VS Code Extension for interactive token acquisition without manual PAT creation.

Manages MCP server process lifecycle across multiple IDEs (Claude Desktop, Cursor, Windsurf, VS Code Copilot) via the octocode-cli and VS Code Extension. Implements server initialization with stdio protocol, automatic restart on failure, and graceful shutdown with resource cleanup. Supports multi-IDE configuration via MCP configuration files (claude_desktop_config.json, .cursor/settings.json, etc.) with per-IDE token and tool configuration.