Octocode MCP Server: AI GitHub & NPM Insights

Overview

Octocode MCP Server implements the Model Context Protocol (MCP) to surface contextual information from GitHub and the NPM registry so you can ask natural-language questions about code, packages, and project structure. It collects and correlates metadata (repository files, package manifests, README content, dependency graphs and search results) and returns concise, searchable context that is easy to feed to an LLM or other downstream tooling.

The server is designed for fast, low-friction exploration: out of the box it works with public GitHub and NPM data (zero-config auth) and can be optionally configured with tokens to increase rate limits or access private resources. Developers and teams use it to discover architecture patterns, trace dependency relationships, and quickly locate examples or authoritative sources across many repositories and packages.

Features

• Natural-language queries across GitHub repositories and the NPM ecosystem
• Aggregated context: README, package.json, dependency lists, key files and search snippets
• Zero-config public access; optional tokens for higher rate limits / private data
• MCP-compliant API designed to provide LLM-friendly context blocks
• Lightweight HTTP server that runs locally or in a container
• Pluggable providers (GitHub, NPM) and simple configuration
• JSON API suitable for integration with chat assistants, code search, and automation

Installation / Configuration

Prerequisites: Node.js 16+ or Docker.

Clone and run locally:

git clone https://github.com/bgauryy/octocode-mcp.git
cd octocode-mcp
npm install
npm run start
# Server listens on default port 3366

Environment variables (example .env):

PORT=3366
GITHUB_TOKEN=ghp_xxx   # optional: increases GitHub rate limits / private repo access
NPM_TOKEN=xxxx         # optional: for private NPM registry access
LOG_LEVEL=info

Run with Docker:

# build
docker build -t octocode-mcp .

# run with optional tokens
docker run -p 3366:3366 \
  -e GITHUB_TOKEN=ghp_xxx \
  -e NPM_TOKEN=xxxx \
  octocode-mcp

Configuration table

Available Resources

• GitHub repository: https://github.com/bgauryy/octocode-mcp
• HTTP API (default): http://localhost:3366 — exposes MCP-compatible endpoints for requesting contextual blocks to feed LLMs
• Provider integrations: GitHub (search, repo files, commit metadata), NPM (package.json, versions, dependency tree)
• Example queries and integration snippets in the repository under examples/

Use Cases

1. Find architecture examples across repos

• Goal: “Show examples of microservice directory layout and where configuration lives”
• How: POST a natural-language query to the MCP server. The server returns matching README sections, key files, and small code snippets that demonstrate directory structure and config usage.
• Example (curl):

curl -sS -X POST http://localhost:3366/mcp \
  -H "Content-Type: application/json" \
  -d '{"question":"Show examples of microservice directory layout and where config files are stored","providers":["github"]}'

2. Trace dependency chains between packages

• Goal: “Which packages depend on @scope/core and what versions are most common?”
• How: Query the NPM provider and correlated GitHub references to produce a ranked list of dependents and common version ranges.
• Example:

curl -X POST http://localhost:3366/mcp \
  -H "Content-Type: application/json" \
  -d '{"question":"Find projects depending on @scope/core and list version ranges","providers":["npm","github"]}'

3. Locate concrete code patterns (e.g., plugin systems, factory patterns)

• Goal: “Find implementations of a plugin registry pattern in JavaScript or TypeScript repos”
• How: The server returns snippets, file paths, and repo links that match pattern heuristics (exports named ‘register’, plugin directories, or typical manifest entries).

4. Quick code provenance for incidents or upgrades

• Goal: “Where is package X used across our organization and which repos still use v1.x?”
• How: Provide a GITHUB_TOKEN for private org access and run queries to gather usage and version information.

Tips for Developers

• Start without tokens to explore public data; add GITHUB_TOKEN / NPM_TOKEN when you need private access or more requests.
• Use the server as a context provider for LLM prompts: request focused context blocks to keep prompt size manageable.
• Combine provider scopes (github + npm) to correlate package metadata with real-world usage and source code examples.

For command examples, API schema, and sample integrations, see the examples folder in the GitHub repository: https://github.com/bgauryy/octocode-mcp.