npm - octocode-cli - Versions diffs - 1.2.7 → 1.2.9 - Mend

octocode-cli 1.2.7 → 1.2.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (282) hide show

package/skills/octocode-research/README.md CHANGED Viewed

@@ -1,10 +1,9 @@
 <div align="center">
   <img src="https://github.com/bgauryy/octocode-mcp/raw/main/packages/octocode-mcp/assets/logo_white.png" width="400px" alt="Octocode Logo">
-  <h1> Octocode Research Skill</h1>
+  <h1>Octocode Research Skill</h1>
-  <p><strong>Turn your agent into a code research powerhouse</strong></p>
-  <p>Zero-config MCP tools • Intent-driven workflows • Smart discovery</p>
+  <p>HTTP server wrapping 13 Octocode MCP tools with intent-based prompt selection</p>
   [![Skill](https://img.shields.io/badge/skill-agentskills.io-purple)](https://agentskills.io/what-are-skills)
   [![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/bgauryy/octocode-mcp/blob/main/LICENSE)
@@ -14,353 +13,152 @@
 ---
-## The Problem
+Unified HTTP interface for local filesystem, LSP, GitHub, and package registry tools. The agent sends a question, the server selects a prompt, and tool responses include hints that guide the next call.
-agents struggle with code research because:
-- **Too many tools** — Which one do I use? In what order?
-- **No context** — Tools work in isolation, losing research continuity
-- **Manual orchestration** — You have to chain tools yourself
-- **Different APIs** — Local, GitHub, LSP tools all work differently
-## The Solution
-**Octocode Research** gives your agent:
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  🎯 Intent Detection  →  📋 Auto-Select Prompt  →  🔧 Smart Tool Chaining  │
-│                                                                             │
-│     "How does React                  research              GitHub + LSP    │
-│      useState work?"         ──────────────────►          tool chain       │
-│                                                                             │
-│     "Review PR #123"                 reviewPR              Diff analysis   │
-│                              ──────────────────►          + code review    │
-│                                                                             │
-│     "Trace auth flow                 research_local        LSP semantic    │
-│      in our app"             ──────────────────►          analysis         │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
+https://github.com/user-attachments/assets/d1260dbc-e7b6-4bec-909f-232ebee91ce9
+---
+## Why a Server?
-https://github.com/user-attachments/assets/d1260dbc-e7b6-4bec-909f-232ebee91ce9
+The server is not just a pass-through — it provides a persistent runtime layer that makes research faster and more reliable:
+| Capability | What it does |
+|---|---|
+| **MCP Cache** | Loads tool metadata, schemas, and system prompt once at startup. Every request reads from memory instead of re-initializing the MCP client. |
+| **Circuit Breakers** | Per-service circuits (GitHub search, GitHub content, LSP navigation, LSP hierarchy, local, package) stop cascading failures. An open circuit fails fast instead of waiting for timeouts. |
+| **Retry + Backoff** | Transient errors (rate limits, LSP cold starts, busy files) retry automatically with exponential backoff before surfacing to the agent. |
+| **Request Timeout** | Every tool call is wrapped with a hard timeout (30–60s) to prevent hangs from blocking the agent. |
+| **Detached Daemon** | The server runs as a detached process — no client owns it. Multiple agents/IDEs share one server instance. A PID file at `~/.octocode/research-server-{PORT}.pid` enables explicit stop. |
+| **Idle Self-Stop** | After 30 minutes of inactivity the server exits on its own, freeing memory. The next `server-init` call spawns a fresh instance. |
+| **Session Telemetry** | Tracks tool calls, repos accessed, and error rates per session for diagnostics (de-identified, opt-out with `LOG=false`). |
+| **Readiness Gate** | Routes return **503** during MCP init (~1–3s), so agents never get partial data. `npm start` polls until ready. |
 ---
-## 🚀 Quick Start
-### Installation
+## Quick Start
 ```bash
 npx add-skill https://github.com/bgauryy/octocode-mcp/tree/main/skills/octocode-research
 ```
-> **Important**: Make sure you are authenticated with GitHub!
-> See [Authentication Setup](https://github.com/bgauryy/octocode-mcp/blob/main/packages/octocode-mcp/docs/AUTHENTICATION_SETUP.md) in the main README.
+> Requires GitHub auth. See [Authentication Setup](https://github.com/bgauryy/octocode-mcp/blob/main/packages/octocode-mcp/docs/AUTHENTICATION_SETUP.md).
-### Option 2: Manual Setup
+Or manually:
 ```bash
 cd skills/octocode-research
 npm install && npm start
-> By default the server listens on `localhost:1987`. You can override this with:
-> - `OCTOCODE_RESEARCH_HOST` (default: `localhost`)
-> - `OCTOCODE_RESEARCH_PORT` (default: `1987`)
-# Verify it's running (defaults to localhost:1987)
 curl http://localhost:1987/health
 ```
----
-## ✨ Key Features
-### 1. All MCP Tools Work Out of the Box
-No configuration. No token setup. Just ask your question.
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                         13 TOOLS • ONE INTERFACE                            │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│   LOCAL TOOLS              LSP TOOLS              EXTERNAL TOOLS            │
-│   ────────────             ─────────              ──────────────            │
-│   localSearchCode          lspGotoDefinition      githubSearchCode          │
-│   localGetFileContent      lspFindReferences      githubGetFileContent      │
-│   localFindFiles           lspCallHierarchy       githubViewRepoStructure   │
-│   localViewStructure                              githubSearchRepositories  │
-│                                                   githubSearchPullRequests  │
-│                                                   packageSearch             │
-│                                                                             │
-│   ──────────────────────────────────────────────────────────────────────    │
-│   All tools: POST /tools/call/:toolName  { "queries": [...] }               │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-### 2. Smart Tool & Prompt Discovery
-Your agent discovers what's available at runtime:
-```bash
-# List available tools
-GET /tools/list
-# Get tool schema BEFORE calling (required!)
-GET /tools/info/localSearchCode
-# List available prompts
-GET /prompts/list
-# Get prompt content by intent
-GET /prompts/info/research
-```
-### 3. Intent-Driven Prompt Selection
-The skill auto-selects the right workflow based on your question:
-| Your Intent | Auto-Selected Prompt | What Happens |
-|-------------|---------------------|--------------|
-| *"How does React useState work?"* | `research` | GitHub repo exploration, source code analysis |
-| *"Trace the auth flow in our app"* | `research_local` | LSP-powered semantic analysis, call hierarchies |
-| *"Review PR #123"* | `reviewPR` | Diff analysis, code review, change impact |
-| *"Plan adding caching to the API"* | `plan` | Architecture design, implementation steps |
-### 4. Production-Ready Resilience
-Built-in protection against failures:
-```
-┌──────────────────────────────────────────────────────────────────┐
-│                    RESILIENCE PATTERNS                           │
-├──────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│  CIRCUIT BREAKER          RETRY + BACKOFF         THROTTLING     │
-│  ───────────────          ───────────────         ──────────     │
-│                                                                  │
-│  CLOSED ──► OPEN          Attempt 1 ────►         50 req/min     │
-│    │         │            wait 1s                 then gradual   │
-│    │    [timeout]         Attempt 2 ────►         slowdown       │
-│    │         │            wait 3s                                │
-│    ▼         ▼            Attempt 3 ────►                        │
-│  HALF-OPEN ◄─┘            success/fail                           │
-│                                                                  │
-│  Per-service configs:     GitHub: 3 attempts, 30s max            │
-│  GitHub: 60s timeout      LSP: 3 attempts, 5s max                │
-│  LSP: 10s timeout         Local: 2 attempts, 1s max              │
-│                                                                  │
-└──────────────────────────────────────────────────────────────────┘
-```
+Override defaults with `OCTOCODE_RESEARCH_HOST` / `OCTOCODE_RESEARCH_PORT`.
 ---
-## 🔄 The Research Flow
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                          OCTOCODE RESEARCH FLOW                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-  USER QUESTION                                                    ANSWER
-       │                                                              ▲
-       ▼                                                              │
-┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
-│              │    │              │    │              │    │              │
-│  1. INIT     │───►│  2. CONTEXT  │───►│  3. PLAN     │───►│  4. RESEARCH │
-│              │    │              │    │              │    │              │
-│  Health      │    │  System      │    │  Create      │    │  Execute     │
-│  check       │    │  prompt      │    │  research    │    │  tool        │
-│  /health     │    │  /tools/     │    │  plan with   │    │  chains      │
-│              │    │  system      │    │  tasks       │    │              │
-│              │    │              │    │              │    │  Follow      │
-│              │    │  Select      │    │              │    │  hints       │
-│              │    │  prompt by   │    │              │    │              │
-│              │    │  intent      │    │              │    │  Iterate     │
-│              │    │  /prompts/   │    │              │    │              │
-│              │    │  info/:name  │    │              │    │              │
-└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
-```
-### Phase 1: INIT
-```bash
-# Check server is ready
-curl http://localhost:1987/health
-# → {"status":"ok","port":1987,"uptime":123,...}
-```
-### Phase 2: CONTEXT
-```bash
-# Load system prompt (ALWAYS FIRST)
-curl http://localhost:1987/tools/system
+## Prompt Selection
-# Select prompt by user intent
-curl http://localhost:1987/prompts/info/research
-```
-### Phase 3: PLAN
-- Analyze user's question
-- Create research plan with tasks
-- Determine which tools to use
+The server picks a prompt based on what the agent asks:
-### Phase 4: RESEARCH
-```bash
-# Execute tools with research context
-curl -X POST http://localhost:1987/tools/call/localSearchCode \
-  -H "Content-Type: application/json" \
-  -d '{
-    "queries": [{
-      "mainResearchGoal": "Understand authentication flow",
-      "researchGoal": "Find auth middleware location",
-      "reasoning": "Need to locate entry point before tracing",
-      "pattern": "authenticate",
-      "path": "/Users/me/project/src"
-    }]
-  }'
-```
+| Question | Prompt | Scope |
+|---|---|---|
+| "How does React useState work?" | `research` | GitHub repos, packages |
+| "Trace auth flow in our app" | `research_local` | Local codebase via LSP |
+| "Review PR #123" | `reviewPR` | Diff + code review |
+| "Plan adding caching" | `plan` | Architecture + steps |
 ---
-## 📡 API Reference
+## API
-### Discovery Endpoints
+### Discovery
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `GET` | `/health` | Server health, memory, circuit states |
-| `GET` | `/tools/list` | List all tools (concise) |
-| `GET` | `/tools/info/:toolName` | **Get tool schema (call BEFORE using!)** |
-| `GET` | `/tools/system` | **System prompt (load FIRST!)** |
-| `GET` | `/prompts/list` | List all prompts |
-| `GET` | `/prompts/info/:promptName` | Get prompt content |
-### Execution Endpoint
+**Load order:** Call **`GET /tools/initContext`** first — it returns the system prompt and all tool JSON Schemas in one response. Use **`GET /tools/system`** when you only need the instructions.
 | Method | Endpoint | Description |
-|--------|----------|-------------|
-| `POST` | `/tools/call/:toolName` | **Execute any tool** |
-### Request Format
-All tool calls use the same structure:
+|---|---|---|
+| `GET` | `/health` | Health, uptime, memory, circuit breaker states |
+| `GET` | `/tools/initContext` | **Load first** — system prompt + all tool schemas |
+| `GET` | `/tools/system` | System instructions only |
+| `GET` | `/tools/list` | All 13 tools (concise) |
+| `GET` | `/tools/info` | All tools with full descriptions |
+| `GET` | `/tools/info/:toolName` | One tool — JSON Schema + description + hints |
+| `GET` | `/tools/metadata` | Raw metadata: instruction summary, tool/prompt counts |
+| `GET` | `/tools/schemas` | All tool JSON Schemas (bulk) |
+| `GET` | `/prompts/list` | All 7 prompts |
+| `GET` | `/prompts/info/:promptName` | Prompt content and arguments |
+### Execution
+**`POST /tools/call/:toolName`** — every tool uses this single endpoint.
 ```json
 {
   "queries": [{
-    "mainResearchGoal": "Overall research objective",
-    "researchGoal": "This specific query's goal",
-    "reasoning": "Why this approach helps",
-    // ... tool-specific parameters
+    "id": "unique-query-id",
+    "mainResearchGoal": "Overall objective",
+    "researchGoal": "This query's goal",
+    "reasoning": "Why this approach"
   }]
 }
 ```
-### Response Format
-```json
-{
-  "tool": "localSearchCode",
-  "success": true,
-  "data": { /* tool results */ },
-  "hints": [
-    "Use lineHint for LSP tools",
-    "Consider narrowing search with path filter"
-  ],
-  "research": {
-    "mainResearchGoal": "...",
-    "researchGoal": "...",
-    "reasoning": "..."
-  }
-}
-```
-> **Critical**: Every response includes `hints` — **always read and follow them** for optimal research flow!
+- `id` is required on every query (alphanumeric, dots, underscores, dashes).
+- `mainResearchGoal` is required for GitHub/package tools; local/LSP tools need `researchGoal` + `reasoning`.
+- Up to **3 queries** per request (bulk). Responses include `hints` — follow them.
 ---
-## 🛠 Available Tools
-### LSP Tools (Semantic Analysis)
-| Tool | Purpose | Use When |
-|------|---------|----------|
-| `lspGotoDefinition` | Jump to symbol definition | "Where is X defined?" |
-| `lspFindReferences` | Find all usages | "Who uses X?" |
-| `lspCallHierarchy` | Trace call flow | "Who calls X? What does X call?" |
-### Local Tools (Filesystem)
-| Tool | Purpose | Use When |
-|------|---------|----------|
-| `localSearchCode` | Ripgrep search | "Find pattern X in codebase" |
-| `localGetFileContent` | Read file content | "Show me file X" |
-| `localFindFiles` | Find by pattern/metadata | "Find all *.ts files" |
-| `localViewStructure` | Directory tree | "What's in this folder?" |
-### GitHub Tools (External)
-| Tool | Purpose | Use When |
-|------|---------|----------|
-| `githubSearchCode` | Search code in repos | "Find X in React repo" |
-| `githubGetFileContent` | Read file from repo | "Show React's useState" |
-| `githubViewRepoStructure` | View repo tree | "What's in facebook/react?" |
-| `githubSearchRepositories` | Search repos | "Find auth libraries" |
-| `githubSearchPullRequests` | Search PRs | "Find PR that added X" |
-### Package Tools
-| Tool | Purpose | Use When |
-|------|---------|----------|
-| `packageSearch` | Search npm/PyPI | "Find the lodash package" |
+## Tools
+| Tool | Category | What it does |
+|---|---|---|
+| `localSearchCode` | Local | Ripgrep code search |
+| `localGetFileContent` | Local | Read file content |
+| `localFindFiles` | Local | Find files by pattern/metadata |
+| `localViewStructure` | Local | Directory tree |
+| `lspGotoDefinition` | LSP | Jump to definition |
+| `lspFindReferences` | LSP | All usages of a symbol |
+| `lspCallHierarchy` | LSP | Incoming/outgoing calls |
+| `githubSearchCode` | GitHub | Search code across repos |
+| `githubGetFileContent` | GitHub | Read file from repo |
+| `githubViewRepoStructure` | GitHub | Repo directory tree |
+| `githubSearchRepositories` | GitHub | Search repos |
+| `githubSearchPullRequests` | GitHub | Search PRs |
+| `packageSearch` | Package | npm / PyPI lookup |
 ---
-## 🎯 Example: How React Implements useState
+## Example
+Find where React defines `useState`, then read it:
 ```bash
-# 1. Search for useState in React repo
 curl -X POST http://localhost:1987/tools/call/githubSearchCode \
   -H "Content-Type: application/json" \
   -d '{
     "queries": [{
+      "id": "find-useState",
       "mainResearchGoal": "Understand React useState implementation",
-      "researchGoal": "Find useState source code location",
-      "reasoning": "Need to locate the hook definition first",
+      "researchGoal": "Find useState source location",
+      "reasoning": "Locate the hook definition first",
       "owner": "facebook",
       "repo": "react",
       "keywordsToSearch": ["useState", "function"],
       "match": "file"
     }]
   }'
+```
-# 2. View repository structure
-curl -X POST http://localhost:1987/tools/call/githubViewRepoStructure \
-  -H "Content-Type: application/json" \
-  -d '{
-    "queries": [{
-      "mainResearchGoal": "Understand React useState implementation",
-      "researchGoal": "Find packages directory structure",
-      "reasoning": "Hooks likely in react-reconciler or react package",
-      "owner": "facebook",
-      "repo": "react",
-      "branch": "main",
-      "path": "packages/react/src",
-      "depth": 2
-    }]
-  }'
-# 3. Read the implementation file
+```bash
 curl -X POST http://localhost:1987/tools/call/githubGetFileContent \
   -H "Content-Type: application/json" \
   -d '{
     "queries": [{
+      "id": "read-useState",
       "mainResearchGoal": "Understand React useState implementation",
-      "researchGoal": "Read useState hook source code",
-      "reasoning": "Found location, now reading implementation",
+      "researchGoal": "Read useState source",
+      "reasoning": "Found location, reading implementation",
       "owner": "facebook",
       "repo": "react",
       "path": "packages/react/src/ReactHooks.js",
@@ -371,124 +169,40 @@ curl -X POST http://localhost:1987/tools/call/githubGetFileContent \
 ---
-## 🏗 Architecture
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                          AGENT (Claude, GPT, etc.)                       │
-└─────────────────────────────────────────────────────────────────────────────┘
-                                      │
-                                      ▼
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                      OCTOCODE RESEARCH SERVER (:1987)                       │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  ┌───────────────┐   ┌───────────────┐   ┌───────────────────────────────┐  │
-│  │   PROMPTS     │   │    TOOLS      │   │      SYSTEM CONTEXT           │  │
-│  │               │   │               │   │                               │  │
-│  │  research     │   │  GitHub API   │   │  Decision guides              │  │
-│  │  research_    │   │  Local FS     │   │  Tool chaining rules          │  │
-│  │   local       │   │  LSP Server   │   │  Error recovery               │  │
-│  │  reviewPR     │   │  Package APIs │   │  Best practices               │  │
-│  │  plan         │   │               │   │                               │  │
-│  └───────────────┘   └───────────────┘   └───────────────────────────────┘  │
-│                                                                             │
-│  ┌───────────────────────────────────────────────────────────────────────┐  │
-│  │                     RESILIENCE LAYER                                  │  │
-│  │  Circuit Breaker  •  Retry + Backoff  •  Throttling  •  Error Queue   │  │
-│  └───────────────────────────────────────────────────────────────────────┘  │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-                                      │
-              ┌───────────────────────┼───────────────────────┐
-              ▼                       ▼                       ▼
-        ┌──────────┐           ┌──────────┐           ┌──────────┐
-        │ Your     │           │ GitHub   │           │ npm/PyPI │
-        │ Codebase │           │ Repos    │           │ Registry │
-        └──────────┘           └──────────┘           └──────────┘
-```
+## Resilience
----
-## 📊 Bulk Queries
-Execute up to 3 queries in parallel:
-```bash
-curl -X POST http://localhost:1987/tools/call/localSearchCode \
-  -H "Content-Type: application/json" \
-  -d '{
-    "queries": [
-      {
-        "mainResearchGoal": "Understand state management",
-        "researchGoal": "Find useState usages",
-        "reasoning": "Compare with useReducer",
-        "pattern": "useState",
-        "path": "/project/src"
-      },
-      {
-        "mainResearchGoal": "Understand state management",
-        "researchGoal": "Find useReducer usages",
-        "reasoning": "Compare with useState",
-        "pattern": "useReducer",
-        "path": "/project/src"
-      }
-    ]
-  }'
-```
+Per-service circuit breakers with retry and backoff:
-Response:
-```json
-{
-  "tool": "localSearchCode",
-  "bulk": true,
-  "success": true,
-  "results": [
-    { "id": 1, "status": "hasResults", "data": {...} },
-    { "id": 2, "status": "hasResults", "data": {...} }
-  ],
-  "hints": {
-    "hasResults": ["Use lineHint for LSP follow-up"],
-    "empty": ["Try broader pattern"]
-  },
-  "counts": { "total": 2, "hasResults": 2, "empty": 0, "error": 0 }
-}
-```
+| Circuit | Failure Threshold | Reset Timeout | Retries | Max Backoff |
+|---|---|---|---|---|
+| `github:search` | 2 | 60s | 3 | 30s |
+| `github:content` | 3 | 30s | 3 | 30s |
+| `github:pulls` | 2 | 60s | 3 | 30s |
+| `lsp:navigation` | 3 | 10s | 3 | 5s |
+| `lsp:hierarchy` | 2 | 15s | 3 | 5s |
+| `local` | 5 | 5s | 2 | 1s |
+| `package` | 3 | 45s | 3 | 15s |
 ---
-## 🔒 Privacy & Telemetry
+## Privacy
-We collect **de-identified** telemetry to improve the tool:
-- Command usage counts
-- Error rates
-- **Never** source code, env vars, or PII
+Collects de-identified telemetry (usage counts, error rates). Never collects source code, env vars, or PII. Opt out: `export LOG=false`. Local logs at `~/.octocode/logs/` are not uploaded.
-Opt-out anytime:
-```bash
-export LOG=false
-```
-Local logs stored at `~/.octocode/logs/` for your debugging — **never uploaded**.
-See [Privacy Policy](https://github.com/bgauryy/octocode-mcp/blob/main/PRIVACY.md) and [Terms](https://github.com/bgauryy/octocode-mcp/blob/main/TERMS.md).
+[Privacy Policy](https://github.com/bgauryy/octocode-mcp/blob/main/PRIVACY.md) &middot; [Terms](https://github.com/bgauryy/octocode-mcp/blob/main/TERMS.md)
 ---
-## 📚 Documentation
+## Docs
 | Document | Description |
-|----------|-------------|
+|---|---|
 | [SKILL.md](./SKILL.md) | Agent workflow guide |
-| [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Full architecture details |
-| [docs/API_REFERENCE.md](./docs/API_REFERENCE.md) | Complete API reference |
+| [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Architecture |
+| [docs/API_REFERENCE.md](./docs/API_REFERENCE.md) | Full API reference |
 | [docs/FLOWS.md](./docs/FLOWS.md) | Request flow diagrams |
-| [../../docs/TROUBLESHOOTING.md](https://github.com/bgauryy/octocode-mcp/blob/main/docs/TROUBLESHOOTING.md) | Common issues and solutions |
+| [Troubleshooting](https://github.com/bgauryy/octocode-mcp/blob/main/docs/TROUBLESHOOTING.md) | Common issues |
 ---
-## License
-MIT License © 2026 Octocode
-See [LICENSE](https://github.com/bgauryy/octocode-mcp/blob/main/LICENSE) for details.
+MIT &copy; 2026 Octocode &mdash; [LICENSE](https://github.com/bgauryy/octocode-mcp/blob/main/LICENSE)