docdex 0.2.24 → 0.2.26

package/README.md

@@ -3,7 +3,6 @@
 ![GitHub License](https://img.shields.io/github/license/bekirdag/docdex)
 ![GitHub Release](https://img.shields.io/github/v/release/bekirdag/docdex)
 ![Made with Rust](https://img.shields.io/badge/Made%20with-Rust-orange?logo=rust)
-[![MCP Badge](https://lobehub.com/badge/mcp/bekirdag-docdex)](https://lobehub.com/mcp/bekirdag-docdex)
 
 <a href="https://glama.ai/mcp/servers/@bekirdag/docdex">
   <img width="380" height="200" src="https://glama.ai/mcp/servers/@bekirdag/docdex/badge" />
@@ -108,7 +107,23 @@ flowchart LR
 
 ```
 
-Use the daemon HTTP/SSE endpoint.
+Use the daemon HTTP/SSE endpoint. For sandboxed clients, Docdex can also serve MCP over local IPC
+(Unix socket or Windows named pipe), while HTTP/SSE remains the default for most MCP clients.
+
+### Stdio MCP (Smithery/stdio-only clients)
+
+If your client requires a stdio MCP server (e.g., Smithery), use the bundled stdio bridge:
+
+```bash
+npx docdex docdex-mcp-stdio
+```
+
+The bridge reads newline-delimited JSON-RPC from stdin and forwards to Docdex. You can force IPC or
+override endpoints with:
+
+```bash
+DOCDEX_MCP_TRANSPORT=ipc DOCDEX_MCP_SOCKET_PATH=/path/to/mcp.sock npx docdex docdex-mcp-stdio
+```
 
 ### Manual Configuration
 

package/assets/agents.md

@@ -1,10 +1,16 @@
+---- START OF DOCDEX INFO V0.2.26 ----
+Docdex URL: http://127.0.0.1:28491
+Use this base URL for Docdex HTTP endpoints.
+Health check endpoint: `GET /healthz` (not `/v1/health`).
+
 ## Priority Directives (Mandatory)
 
 - Always use both memory lobes early: docdex_get_profile + docdex_memory_recall; save new facts via docdex_memory_save and new preferences via docdex_save_preference.
 - Maintain agent-specific profile memory: use your agent_id with docdex_get_profile/docdex_save_preference; store generic self-knowledge (role, tooling, preferences).
-- Use impact analysis for every code change: call HTTP /v1/graph/impact?file=... and account for inbound/outbound deps; if unavailable, state it and proceed cautiously.
+- Use impact analysis for every code change: prefer MCP tools `docdex_impact_graph` / `docdex_dag_export` (IPC/HTTP). If shell networking is blocked, do not use curl; use MCP/IPC instead. If unavailable, state it and proceed cautiously.
 - Apply DAG reasoning for planning: prefer dependency graph facts (impact results and /v1/dag/export) to choose the right change order and scope.
 - Use Docdex tools intentionally: docdex_search/symbols/ast for repo truth; docdex_stats/files/repo_inspect/index for index health.
+- For folder structure, use docdex_tree instead of raw `rg --files`/`find` to avoid noisy folders.
 - When you do not know something, run docdex_web_research (force_web=true). Web research is encouraged by default for non-repo facts and external APIs.
 
 # Docdex Agent Usage Instructions
@@ -65,7 +71,8 @@ Precision tools for structural analysis. Do not rely on text search for definiti
 | docdex_symbols | Get exact definitions/signatures for a file. |
 | docdex_ast | Specific AST nodes (e.g., "Find all class definitions"). |
 | docdex_impact_diagnostics | Check for broken/dynamic imports. |
-| HTTP /v1/graph/impact | Impact Analysis: "What breaks if I change this?" Returns inbound/outbound dependencies. |
+| docdex_impact_graph | Impact Analysis: "What breaks if I change this?" Returns inbound/outbound dependencies. |
+| docdex_dag_export | Export the dependency DAG for change ordering and scope. |
 
 ### C. Memory Operations
 
@@ -76,6 +83,31 @@ Precision tools for structural analysis. Do not rely on text search for definiti
 | docdex_save_preference | Store a global user preference (Style, Tooling, Constraint). |
 | docdex_get_profile | Retrieve global preferences. |
 
+### D. Local Delegation (Cheap Models)
+
+Use local delegation for low-complexity, code-generation-oriented tasks to reduce paid-model usage.
+
+| MCP Tool / HTTP | Purpose |
+| --- | --- |
+| docdex_local_completion | Delegate small tasks to a local model with strict output formats. |
+| HTTP /v1/delegate | HTTP endpoint for delegated completions with structured responses. |
+
+Required fields: `task_type`, `instruction`, `context`. Optional: `max_tokens`, `timeout_ms`, `mode` (`draft_only` or `draft_then_refine`), `agent` (local agent id/slug).
+Expensive model library: `docs/expensive_models.json` (match by `agent_id`, `agent_slug`, `model`, or adapter type; case-insensitive).
+
+### E. Index Health + File Access
+
+Use these to verify index coverage, repo binding, and to read precise file slices.
+
+| MCP Tool | Purpose |
+| --- | --- |
+| docdex_repo_inspect | Confirm normalized repo root/identity (resolve missing_repo). |
+| docdex_stats | Index size/last update; detect stale indexes. |
+| docdex_files | Indexed file coverage; confirm a file is in the index. |
+| docdex_index | Reindex full repo or ingest specific files when stale/missing. |
+| docdex_open | Read exact file slices after you identify targets. |
+| docdex_tree | Render a repo folder tree with standard excludes (avoid noisy folders). |
+
 ## Quick Tool Map (Often Missed)
 
 - docdex_files: List indexed docs with rel_path/doc_id/token_estimate; use to verify indexing coverage.
@@ -84,8 +116,145 @@ Precision tools for structural analysis. Do not rely on text search for definiti
 - docdex_index: Reindex the full repo or ingest specific files when stale.
 - docdex_search diff: Limit search to working tree, staged, or ref ranges; filter by paths.
 - docdex_web_research knobs: force_web, skip_local_search, repo_only, no_cache, web_limit, llm_filter_local_results, llm_model.
-- HTTP /v1/initialize: Bind a default repo root for MCP when clients omit project_root.
-- HTTP /v1/dag/export: Export the dependency graph for external analysis.
+- docdex_open: Read narrow file slices after targets are identified.
+- docdex_tree: Render a filtered folder tree (prefer this over `rg --files` / `find`).
+- docdex_impact_diagnostics: Scan dynamic imports when imports are unclear or failing.
+- docdex_local_completion: Delegate low-complexity codegen tasks (tests, docstrings, boilerplate, simple refactors).
+- docdex_ast: Use AST queries for precise structure (class/function definitions, call sites, imports).
+- docdex_symbols: Use symbols to confirm exact signatures/locations before edits.
+- docdex_impact_graph: Mandatory before code changes to review inbound/outbound deps (use MCP/IPC if shell networking is blocked).
+- docdex_dag_export: Export dependency graph to plan change order.
+- HTTP /v1/initialize: Mount/bind a repo for HTTP daemon mode. Request JSON uses rootUri/root_uri (NOT repo_root).
+
+## CLI Fallbacks (when MCP/IPC is unavailable)
+Use these only when MCP tools cannot be called (e.g., blocked sandbox networking). Prefer MCP/IPC otherwise.
+
+- `docdexd repo init --repo <path>`: initialize repo in daemon and return repo_id JSON.
+- `docdexd repo id --repo <path>`: compute repo fingerprint locally.
+- `docdexd repo status --repo <path>` / `docdexd repo dirty --exit-code`: git working tree status.
+- `docdexd impact-graph --repo <path> --file <rel>`: impact graph (HTTP/local).
+- `docdexd dag export --repo <path> <session_id>`: DAG export alias.
+- `docdexd search --repo <path> --query "<q>"`: /search equivalent (HTTP/local).
+- `docdexd open --repo <path> --file <rel>`: safe file slice read (head/start/end/clamp).
+- `docdexd file ensure-newline|write --repo <path> --file <rel>`: minimal file edits.
+- `docdexd test run-node --repo <path> --file <rel> --args "..."`: run Node scripts.
+
+## Docdex Usage Cookbook (Mandatory, Exact Schemas)
+
+This section is the authoritative source for how to call Docdex. Do not guess field names or payloads.
+
+### 0) Base URL + daemon modes
+
+- Default HTTP base URL: http://127.0.0.1:28491 (override with DOCDEX_HTTP_BASE_URL).
+- Single-repo HTTP daemon: `docdexd serve --repo /abs/path`. /v1/initialize is NOT used. repo_id is optional, but must match the serving repo if provided.
+- Multi-repo HTTP daemon: `docdexd daemon`. You MUST call /v1/initialize before repo-scoped HTTP endpoints. When multiple repos are mounted, repo_id is required on every repo-scoped request.
+
+### 1) Initialize (HTTP) - exact request payload
+
+POST /v1/initialize
+
+Request JSON (exact field names):
+
+```json
+{ "rootUri": "file:///abs/path/to/repo" }
+```
+
+Alias accepted:
+
+```json
+{ "root_uri": "/abs/path/to/repo" }
+```
+
+Rules:
+- Do NOT send `repo_root` in the request. `repo_root` is a response field.
+- Use file:// URIs when possible; plain absolute paths are also accepted.
+- Response returns `repo_id`, `status`, and `repo_root`. Use that repo_id for subsequent HTTP calls.
+
+### 2) Repo scoping (HTTP)
+
+- Send repo_id via header `x-docdex-repo-id: <repo_id>` or query param `repo_id=<repo_id>`.
+- If the daemon is single-repo, do not send a repo_id for a different repo (you will get `unknown_repo`).
+- If the daemon is multi-repo and more than one repo is mounted, repo_id is required.
+
+### 3) Search (HTTP)
+
+`GET /search`
+
+Required:
+- `q` (query string).
+
+Common params:
+- `limit`, `snippets`, `max_tokens`, `include_libs`, `force_web`, `skip_local_search`, `no_cache`,
+  `max_web_results`, `llm_filter_local_results`, `diff_mode`, `diff_base`, `diff_head`, `diff_path`,
+  `dag_session_id`, `repo_id`.
+
+Notes:
+- `skip_local_search=true` effectively forces web discovery (Tier 2).
+- If DOCDEX_WEB_ENABLED=1, web discovery can be slow; plan timeouts accordingly.
+
+### 4) Snippet (HTTP)
+
+`GET /snippet/:doc_id`
+
+Common params:
+- `window`, `q`, `text_only`, `max_tokens`, `repo_id`.
+
+### 5) Impact graph (HTTP)
+
+`GET /v1/graph/impact?file=<repo-relative-path>`
+
+Rules:
+- `file` must be a path relative to the repo root (not an absolute path).
+- Include repo_id header/query when required by daemon mode.
+
+### 6) DAG export (HTTP)
+
+`GET /v1/dag/export?session_id=<id>`
+
+Query params:
+- `session_id` (required)
+- `format` (optional: json/text/dot; default json)
+- `max_nodes` (optional)
+- `repo_id` (required when multiple repos are mounted)
+
+### 7) MCP over HTTP/SSE
+
+- SSE: `/v1/mcp/sse` + `/v1/mcp/message`. When multiple repos are mounted, initialize with `rootUri` first.
+- HTTP: `/v1/mcp` accepts repo context in the payload or via prior initialize.
+- If HTTP/SSE is unreachable (sandboxed clients), fall back to local IPC: configure `transport = "ipc"` with `socket_path` (Unix) or `pipe_name` (Windows) and send MCP JSON-RPC to `/v1/mcp` over IPC.
+- For stdio-only clients (e.g., Smithery), use the `docdex-mcp-stdio` entrypoint to bridge stdio JSON-RPC to Docdex MCP.
+- For impact/DAG in sandboxed shells, prefer MCP/IPC tools over `curl` to `/v1/graph/impact` or `/v1/dag/export`.
+- MCP tools: `docdex_impact_graph` (impact traversal) and `docdex_dag_export` (DAG export).
+
+### 8) MCP tools (local) - required fields
+
+Do not guess fields; use these canonical shapes.
+
+- `docdex_search`: `{ project_root, query, limit?, diff?, repo_only?, force_web? }`
+- `docdex_open`: `{ project_root, path, start_line?, end_line?, head?, clamp? }` (range must be valid unless clamp/head used)
+- `docdex_files`: `{ project_root, limit?, offset? }`
+- `docdex_stats`: `{ project_root }`
+- `docdex_repo_inspect`: `{ project_root }`
+- `docdex_index`: `{ project_root, paths? }` (paths empty => full reindex)
+- `docdex_symbols`: `{ project_root, path }`
+- `docdex_ast`: `{ project_root, path, max_nodes? }`
+- `docdex_impact_diagnostics`: `{ project_root, file? }`
+- `docdex_impact_graph`: `{ project_root, file, max_edges?, max_depth?, edge_types? }`
+- `docdex_dag_export`: `{ project_root, session_id, format?, max_nodes? }`
+- `docdex_memory_save`: `{ project_root, text }`
+- `docdex_memory_recall`: `{ project_root, query, top_k? }`
+- `docdex_get_profile`: `{ agent_id }`
+- `docdex_save_preference`: `{ agent_id, category, content }`
+- `docdex_local_completion`: `{ task_type, instruction, context, max_tokens?, timeout_ms?, mode?, max_context_chars?, agent? }`
+- `docdex_web_research`: `{ project_root, query, force_web, skip_local_search?, web_limit?, no_cache? }`
+
+### 9) Common error fixes (do not guess)
+
+- `unknown_repo`: You are talking to a daemon that does not know that repo. Fix by:
+  - Starting a single-repo server for that repo (`docdexd serve --repo /abs/path`), OR
+  - Calling `/v1/initialize` on the multi-repo daemon with `rootUri`, then using the returned repo_id.
+- `missing_repo`: Supply repo_id (HTTP) or project_root (MCP), or call /v1/initialize.
+- `invalid_range` (docdex_open): Adjust start/end line to fit total_lines.
 
 ## Interaction Patterns
 
@@ -96,9 +265,76 @@ When answering a complex coding query, follow this "Reasoning Trace":
 1. Retrieve Profile: Call docdex_get_profile to load user style/constraints (e.g., "Use functional components").
 2. Search Code: Call docdex_search or docdex_symbols to find the relevant code.
 3. Check Memory: Call docdex_memory_recall for project-specific caveats (e.g., "Auth logic was refactored last week").
-4. Synthesize: Generate code that matches the Repo Truth while adhering to the Profile Style.
+4. Validate structure: Use docdex_ast/docdex_symbols to confirm targets before editing.
+5. Read context: Use docdex_open to fetch minimal file slices after locating targets.
+6. Plan with DAG: Use /v1/dag/export or /v1/graph/impact to order changes by dependencies.
+7. Synthesize: Generate code that matches the Repo Truth while adhering to the Profile Style.
+
+### 2. Memory Capture (Mandatory)
+
+Save more memories for both lobes during the task, not just at the end.
+
+1. Repo memory: After each meaningful discovery or code change, save at least one durable fact (file location, behavior, config, gotcha) via `docdex_memory_save`.
+2. Profile memory: When the user expresses a preference, constraint, or workflow correction, call `docdex_save_preference` immediately with the right category.
+3. Keep it crisp: 1-3 short sentences, include file paths when relevant, avoid raw code blobs.
+4. Safety: Never store secrets, tokens, or sensitive user data. Skip transient or speculative info.
+
+### 3. Index Health + Diff-Aware Search (Mandatory)
+
+Use these when results look incomplete or when the task is about recent changes.
+
+1. Confirm repo binding: Use docdex_repo_inspect or /v1/initialize when repo_id is missing/ambiguous.
+2. Check index coverage: Use docdex_stats + docdex_files before assuming code is missing.
+3. Reindex if needed: Run docdex_index (or advise it) when stale_index/missing files appear.
+4. Use diff search: For change-specific tasks, use docdex_search with diff mode (working tree/staged/range).
+
+### 4. Local Delegation Workflow (Cheap Models)
+
+When you are an expensive/paid model, delegate eligible low-complexity tasks first unless the user opts out.
+Delegation is mandatory for eligible tasks. If you are expensive and delegation is enabled (explicitly or auto-enabled with local candidates), you MUST attempt local delegation before doing the work yourself. Only skip when delegation is disabled, no local candidate exists, or local output fails validation after a retry/fallback.
+
+#### Mandatory Delegation Triggers
+
+- The work fits a delegation task type or can be split into sub-tasks that do.
+- The change is small, localized, or mechanical (boilerplate, formatting, docstrings, small refactors).
+- The task can be fully expressed in a capsule with explicit context and output rules.
+
+#### Reasons to Delegate (Non-Optional)
+
+- Cuts paid-token usage and cost.
+- Lowers latency and avoids rate-limit pressure on premium models.
+- Keeps expensive models focused on complex reasoning and multi-step planning.
+- Uses tuned prompts that reduce drift for repetitive edits.
+- Enforces the product's cost-control policy; skipping delegation is a regression.
+
+1. Determine if you are expensive: load `docs/expensive_models.json` and match your `agent_id`, `agent_slug`, `model`, or adapter type. If you match, continue; if not and you are clearly local/cheap, skip delegation. If unsure, default to expensive.
+2. Check config: Only delegate when `[llm.delegation].enabled` is true or `auto_enable` is true with an eligible local model/agent (and `task_type` is allowed). If uncertain, attempt delegation and handle the error.
+3. Choose task type: Use one of `GENERATE_TESTS`, `WRITE_DOCSTRING`, `SCAFFOLD_BOILERPLATE`, `REFACTOR_SIMPLE`, `FORMAT_CODE`.
+4. Call the tool: `docdex_local_completion` with `task_type`, `instruction`, and minimal `context` (smallest necessary snippet).
+5. Validate output: If the local output is invalid or empty, fall back to the primary agent or handle with the paid model.
+6. Optional refine: If mode is `draft_then_refine`, refine the draft with the primary agent and return a final result.
+
+#### Delegation Handoff Package (Required)
+
+Local models cannot call tools. The leading agent must provide a complete, minimal capsule.
+
+1. Task capsule: `task_type`, goal, success criteria, output format, and constraints (tests to update, style rules).
+2. Context payload: file paths plus the exact snippets from docdex_open; include symbol signatures/AST findings.
+3. Dependency notes: summarize impact analysis and any DAG ordering that affects the change.
+4. Boundaries: explicit files allowed to edit vs read-only; no new dependencies unless allowed.
+5. Guardrails: ask for clarification if context is insufficient; do not invent missing APIs; return only the requested format.
+
+### 5. Graph + AST Usage (Mandatory for Code Changes)
+
+For any code change, use both AST and graph tools to reduce drift and hidden coupling.
+
+1. Use `docdex_ast` or `docdex_symbols` to locate exact definitions and call sites.
+2. Call HTTP `/v1/graph/impact?file=...` before edits and summarize inbound/outbound deps.
+3. For multi-file changes, export the DAG (`/v1/dag/export`) and order edits by dependency direction.
+4. Use docdex_impact_diagnostics when imports are dynamic or unresolved.
+5. If graph endpoints are unavailable, state it and proceed cautiously with extra local search.
 
-### 2. Handling Corrections (Learning)
+### 6. Handling Corrections (Learning)
 
 If the user says: "I told you, we do not use Moment.js here, use date-fns!"
 
@@ -107,21 +343,21 @@ If the user says: "I told you, we do not use Moment.js here, use date-fns!"
 - content: "Do not use Moment.js; prefer date-fns."
 - agent_id: "default" (or active agent ID)
 
-### 3. Impact Analysis
+### 7. Impact Analysis
 
 If the user asks: "Safe to delete getUser?"
 
 - Action: Call GET /v1/graph/impact?file=src/user.ts
 - Output: Analyze the inbound edges. If the list is not empty, it is unsafe.
 
-### 4. Non-Repo Real-World Queries (Web First)
+### 8. Non-Repo Real-World Queries (Web First)
 
 If the user asks a non-repo, real-world question (weather, news, general facts), immediately call docdex_web_research with force_web=true.
 - Resolve relative dates ("yesterday", "last week") using system time by default.
 - Do not run docdex_search unless the user explicitly wants repo-local context.
 - Assume web access is allowed unless the user forbids it; if the web call fails, report the failure and ask for a source or permission.
 
-### 5. Failure Handling (Missing Results or Errors)
+### 9. Failure Handling (Missing Results or Errors)
 
 - Ensure project_root or repo_path is set, or call /v1/initialize to bind a default root.
 - Use docdex_repo_inspect to confirm repo identity and normalized root.
@@ -151,3 +387,4 @@ Docdex adapts to the host.
 
 - Project Mapping: On constrained hardware, docdex uses a "Spotlight Heuristic" to show you only a skeletal file tree based on your role keywords, rather than the full file system.
 - LLM: It may be running a quantized model (e.g., phi3.5) or a heavy model (llama3.1:70b) depending on VRAM. Trust the daemon's token limits; it handles truncation.
+---- END OF DOCDEX INFO -----

package/bin/docdex-mcp-stdio.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+"use strict";
+
+const { runBridge } = require("../lib/mcp_stdio_bridge");
+
+async function main() {
+  try {
+    await runBridge({
+      stdin: process.stdin,
+      stdout: process.stdout,
+      stderr: process.stderr
+    });
+  } catch (err) {
+    process.stderr.write(`[docdex-mcp-stdio] fatal: ${err}\n`);
+    process.exit(1);
+  }
+}
+
+main();

package/lib/mcp_stdio_bridge.js

@@ -0,0 +1,236 @@
+"use strict";
+
+const http = require("node:http");
+const https = require("node:https");
+const readline = require("node:readline");
+const { URL } = require("node:url");
+
+const DEFAULT_HTTP_BASE = "http://127.0.0.1:28491";
+
+function trimEnv(value) {
+  if (!value) return "";
+  const trimmed = String(value).trim();
+  return trimmed;
+}
+
+function jsonRpcError(message, id, code = -32000, data) {
+  const payload = {
+    jsonrpc: "2.0",
+    id: typeof id === "undefined" ? null : id,
+    error: {
+      code,
+      message
+    }
+  };
+  if (data !== undefined) {
+    payload.error.data = data;
+  }
+  return payload;
+}
+
+function extractIds(payload) {
+  if (Array.isArray(payload)) {
+    return payload
+      .map((item) => (item && Object.prototype.hasOwnProperty.call(item, "id") ? item.id : undefined))
+      .filter((value) => value !== undefined);
+  }
+  if (payload && Object.prototype.hasOwnProperty.call(payload, "id")) {
+    return [payload.id];
+  }
+  return [];
+}
+
+function normalizePipeName(name) {
+  if (!name) return "";
+  if (name.startsWith("\\\\.\\pipe\\")) return name;
+  return `\\\\.\\pipe\\${name}`;
+}
+
+function defaultUnixSocketPath() {
+  const runtime = trimEnv(process.env.XDG_RUNTIME_DIR);
+  if (runtime) {
+    return `${runtime.replace(/\/$/, "")}/docdex/mcp.sock`;
+  }
+  const home = trimEnv(process.env.HOME);
+  if (!home) return "";
+  return `${home.replace(/\/$/, "")}/.docdex/run/mcp.sock`;
+}
+
+function readTransportEnv() {
+  const transport = trimEnv(process.env.DOCDEX_MCP_TRANSPORT).toLowerCase();
+  if (transport && transport !== "http" && transport !== "ipc") {
+    throw new Error(`invalid DOCDEX_MCP_TRANSPORT: ${transport}`);
+  }
+  return transport;
+}
+
+function resolveIpcConfig(transport) {
+  const socketPathEnv = trimEnv(process.env.DOCDEX_MCP_SOCKET_PATH);
+  const pipeNameEnv = trimEnv(process.env.DOCDEX_MCP_PIPE_NAME);
+  const explicitIpc = transport === "ipc" || socketPathEnv || pipeNameEnv;
+  if (!explicitIpc) return null;
+
+  if (process.platform === "win32") {
+    const pipeName = normalizePipeName(pipeNameEnv || "docdex-mcp");
+    return { type: "pipe", pipeName };
+  }
+
+  const socketPath = socketPathEnv || defaultUnixSocketPath();
+  if (!socketPath) {
+    throw new Error("DOCDEX_MCP_SOCKET_PATH not set and HOME/XDG_RUNTIME_DIR unavailable");
+  }
+  return { type: "unix", socketPath };
+}
+
+function resolveHttpBaseUrl() {
+  const base = trimEnv(process.env.DOCDEX_HTTP_BASE_URL) || DEFAULT_HTTP_BASE;
+  return base;
+}
+
+function buildHttpEndpoint(baseUrl) {
+  const parsed = new URL(baseUrl);
+  const endpoint = new URL("/v1/mcp", parsed);
+  return endpoint;
+}
+
+function requestJson({ url, payload, socketPath }) {
+  const data = JSON.stringify(payload);
+  const isHttps = url.protocol === "https:";
+  const requestFn = isHttps ? https.request : http.request;
+  const options = {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "content-length": Buffer.byteLength(data)
+    }
+  };
+  if (socketPath) {
+    options.socketPath = socketPath;
+    options.path = url.pathname;
+  } else {
+    options.hostname = url.hostname;
+    options.port = url.port || (isHttps ? 443 : 80);
+    options.path = url.pathname;
+  }
+
+  return new Promise((resolve, reject) => {
+    const req = requestFn(options, (res) => {
+      let body = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => {
+        body += chunk;
+      });
+      res.on("end", () => {
+        resolve({
+          status: res.statusCode || 0,
+          body
+        });
+      });
+    });
+    req.on("error", reject);
+    req.write(data);
+    req.end();
+  });
+}
+
+async function forwardRequest(payload, stderr) {
+  const transport = readTransportEnv();
+  const httpBase = resolveHttpBaseUrl();
+  const endpoint = buildHttpEndpoint(httpBase);
+  const ipcConfig = resolveIpcConfig(transport);
+
+  const tryHttp = async () => requestJson({ url: endpoint, payload });
+  const tryIpc = async () => {
+    if (!ipcConfig) {
+      throw new Error("IPC transport not configured");
+    }
+    const ipcUrl = new URL("http://localhost/v1/mcp");
+    const socketPath = ipcConfig.type === "unix" ? ipcConfig.socketPath : ipcConfig.pipeName;
+    return requestJson({ url: ipcUrl, payload, socketPath });
+  };
+
+  if (transport === "ipc") {
+    return await tryIpc();
+  }
+  if (transport === "http") {
+    return await tryHttp();
+  }
+
+  try {
+    return await tryHttp();
+  } catch (err) {
+    if (ipcConfig) {
+      stderr.write(`[docdex-mcp-stdio] HTTP failed, falling back to IPC: ${err}\n`);
+      return await tryIpc();
+    }
+    throw err;
+  }
+}
+
+async function writeLine(stdout, line) {
+  if (!line.endsWith("\n")) {
+    line += "\n";
+  }
+  if (!stdout.write(line)) {
+    await new Promise((resolve) => stdout.once("drain", resolve));
+  }
+}
+
+async function handlePayload(payload, stdout, stderr) {
+  const ids = extractIds(payload);
+  let response;
+  try {
+    const result = await forwardRequest(payload, stderr);
+    if (result.body) {
+      try {
+        response = JSON.parse(result.body);
+      } catch (err) {
+        response = jsonRpcError("invalid json response from docdex", ids[0], -32001, {
+          status: result.status,
+          body: result.body
+        });
+      }
+    } else if (ids.length === 1) {
+      response = { jsonrpc: "2.0", id: ids[0], result: null };
+    } else if (ids.length > 1) {
+      response = ids.map((id) => ({ jsonrpc: "2.0", id, result: null }));
+    } else {
+      response = null;
+    }
+  } catch (err) {
+    response = jsonRpcError("transport error", ids[0], -32002, {
+      error: String(err)
+    });
+  }
+  if (response !== null) {
+    await writeLine(stdout, JSON.stringify(response));
+  }
+}
+
+async function runBridge({ stdin, stdout, stderr }) {
+  readTransportEnv();
+  const rl = readline.createInterface({
+    input: stdin,
+    crlfDelay: Infinity
+  });
+
+  for await (const line of rl) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    let payload;
+    try {
+      payload = JSON.parse(trimmed);
+    } catch (err) {
+      const response = jsonRpcError("parse error", null, -32700, { error: String(err) });
+      await writeLine(stdout, JSON.stringify(response));
+      continue;
+    }
+    await handlePayload(payload, stdout, stderr);
+  }
+}
+
+module.exports = {
+  runBridge
+};

package/lib/postinstall_setup.js

@@ -26,6 +26,7 @@ const SETUP_PENDING_MARKER = "setup_pending.json";
 const AGENTS_DOC_FILENAME = "agents.md";
 const DOCDEX_INFO_START_PREFIX = "---- START OF DOCDEX INFO V";
 const DOCDEX_INFO_END = "---- END OF DOCDEX INFO -----";
+const DOCDEX_INFO_END_LEGACY = "---- END OF DOCDEX INFO ----";
 
 function defaultConfigPath() {
   return path.join(os.homedir(), ".docdex", "config.toml");
@@ -353,9 +354,14 @@ function docdexBlockStart(version) {
   return `${DOCDEX_INFO_START_PREFIX}${version} ----`;
 }
 
+function docdexInfoEndPattern() {
+  return `(?:${escapeRegExp(DOCDEX_INFO_END)}|${escapeRegExp(DOCDEX_INFO_END_LEGACY)})`;
+}
+
 function buildDocdexInstructionBlock(instructions) {
   const next = normalizeInstructionText(instructions);
   if (!next) return "";
+  if (hasDocdexBlock(next)) return next;
   const version = resolvePackageVersion();
   return `${docdexBlockStart(version)}\n${next}\n${DOCDEX_INFO_END}`;
 }
@@ -363,9 +369,7 @@ function buildDocdexInstructionBlock(instructions) {
 function extractDocdexBlockBody(text) {
   const match = String(text || "").match(
     new RegExp(
-      `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\r\\n]* ----\\r?\\n([\\s\\S]*?)\\r?\\n${escapeRegExp(
-        DOCDEX_INFO_END
-      )}`
+      `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\r\\n]* ----\\r?\\n([\\s\\S]*?)\\r?\\n${docdexInfoEndPattern()}`
     )
   );
   return match ? normalizeInstructionText(match[1]) : "";
@@ -383,11 +387,17 @@ function hasDocdexBlockVersion(text, version) {
   return String(text || "").includes(docdexBlockStart(version));
 }
 
+function hasDocdexBlock(text) {
+  const source = String(text || "");
+  return (
+    source.includes(DOCDEX_INFO_START_PREFIX) &&
+    (source.includes(DOCDEX_INFO_END) || source.includes(DOCDEX_INFO_END_LEGACY))
+  );
+}
+
 function stripDocdexBlocks(text) {
   const re = new RegExp(
-    `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\r\\n]* ----\\r?\\n[\\s\\S]*?\\r?\\n${escapeRegExp(
-      DOCDEX_INFO_END
-    )}\\r?\\n?`,
+    `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\r\\n]* ----\\r?\\n[\\s\\S]*?\\r?\\n${docdexInfoEndPattern()}\\r?\\n?`,
     "g"
   );
   return String(text || "").replace(re, "").trim();
@@ -397,9 +407,7 @@ function stripDocdexBlocksExcept(text, version) {
   if (!version) return stripDocdexBlocks(text);
   const source = String(text || "");
   const re = new RegExp(
-    `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\r\\n]* ----\\r?\\n[\\s\\S]*?\\r?\\n${escapeRegExp(
-      DOCDEX_INFO_END
-    )}\\r?\\n?`,
+    `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\r\\n]* ----\\r?\\n[\\s\\S]*?\\r?\\n${docdexInfoEndPattern()}\\r?\\n?`,
     "g"
   );
   let result = "";
@@ -432,7 +440,7 @@ function stripLegacyDocdexBody(text, body) {
   if (!body) return String(text || "");
   const source = String(text || "").replace(/\r\n/g, "\n");
   const re = new RegExp(
-    `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\n]* ----\\n[\\s\\S]*?\\n${escapeRegExp(DOCDEX_INFO_END)}\\n?`,
+    `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\n]* ----\\n[\\s\\S]*?\\n${docdexInfoEndPattern()}\\n?`,
     "g"
   );
   let result = "";
@@ -493,6 +501,18 @@ function upsertPromptFile(pathname, instructions, { prepend = false } = {}) {
   return writeTextFile(pathname, merged);
 }
 
+function removePromptFile(pathname) {
+  if (!fs.existsSync(pathname)) return false;
+  const current = fs.readFileSync(pathname, "utf8");
+  const stripped = stripDocdexBlocks(current);
+  if (normalizeInstructionText(stripped) === normalizeInstructionText(current)) return false;
+  if (!stripped) {
+    fs.unlinkSync(pathname);
+    return true;
+  }
+  return writeTextFile(pathname, stripped);
+}
+
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -554,13 +574,7 @@ function upsertYamlInstruction(pathname, key, instructions) {
 }
 
 function upsertClaudeInstructions(pathname, instructions) {
-  const { value } = readJson(pathname);
-  if (typeof value !== "object" || value == null || Array.isArray(value)) return false;
-  const merged = mergeInstructionText(value.instructions, instructions);
-  if (!merged || merged === value.instructions) return false;
-  value.instructions = merged;
-  writeJson(pathname, value);
-  return true;
+  return upsertPromptFile(pathname, instructions);
 }
 
 function upsertContinueJsonInstructions(pathname, instructions) {
@@ -731,7 +745,7 @@ function rewriteContinueYamlRules(source, instructions, addDocdex) {
 
   const keptItems = items.filter((item) => {
     const text = item.join("\n");
-    return !(text.includes(DOCDEX_INFO_START_PREFIX) && text.includes(DOCDEX_INFO_END));
+    return !hasDocdexBlock(text);
   });
 
   if (addDocdex) {
@@ -786,45 +800,43 @@ function upsertVsCodeInstructionKey(value, key, instructions) {
   return true;
 }
 
-function upsertVsCodeInstructionLocations(value, instructionsDir) {
-  const key = "chat.instructionsFilesLocations";
-  const location = String(instructionsDir);
-  if (value[key] && typeof value[key] === "object" && !Array.isArray(value[key])) {
-    if (value[key][location] === true) return false;
-    value[key][location] = true;
-    return true;
-  }
-  if (Array.isArray(value[key])) {
-    if (value[key].some((entry) => entry === location)) return false;
-    value[key].push(location);
+function removeVsCodeInstructionKey(value, key, instructions, { legacyPath } = {}) {
+  if (typeof value[key] !== "string") return false;
+  const current = value[key];
+  const stripped = stripDocdexBlocks(current);
+  if (normalizeInstructionText(stripped) !== normalizeInstructionText(current)) {
+    if (!stripped) {
+      delete value[key];
+    } else {
+      value[key] = stripped;
+    }
     return true;
   }
-  if (typeof value[key] === "string") {
-    if (value[key] === location) return false;
-    value[key] = [value[key], location];
+  const normalized = normalizeInstructionText(instructions);
+  if (current === normalized || (legacyPath && current === legacyPath)) {
+    delete value[key];
     return true;
   }
-  value[key] = { [location]: true };
-  return true;
+  return false;
 }
 
-function upsertVsCodeInstructions(pathname, instructions, instructionsDir) {
+function upsertVsCodeInstructions(pathname, instructions, legacyPath) {
   const { value } = readJson(pathname);
   if (typeof value !== "object" || value == null || Array.isArray(value)) return false;
   const normalized = normalizeInstructionText(instructions);
   if (!normalized) return false;
   let updated = false;
-  if (upsertVsCodeInstructionKey(value, "github.copilot.chat.codeGeneration.instructions", instructions)) {
-    updated = true;
-  }
-  if (upsertVsCodeInstructionKey(value, "copilot.chat.codeGeneration.instructions", instructions)) {
+  if (upsertVsCodeInstructionKey(value, "chat.instructions", instructions)) {
     updated = true;
   }
-  if (value["github.copilot.chat.codeGeneration.useInstructionFiles"] !== true) {
-    value["github.copilot.chat.codeGeneration.useInstructionFiles"] = true;
+  if (removeVsCodeInstructionKey(value, "github.copilot.chat.codeGeneration.instructions", instructions)) {
     updated = true;
   }
-  if (upsertVsCodeInstructionLocations(value, instructionsDir)) {
+  if (
+    removeVsCodeInstructionKey(value, "copilot.chat.codeGeneration.instructions", instructions, {
+      legacyPath
+    })
+  ) {
     updated = true;
   }
   if (!updated) return false;
@@ -1169,11 +1181,18 @@ function clientInstructionPaths() {
   const aiderConfig = path.join(home, ".aider.conf.yml");
   const gooseConfig = path.join(home, ".config", "goose", "config.yaml");
   const openInterpreterConfig = path.join(home, ".openinterpreter", "profiles", "default.yaml");
+  const geminiInstructions = path.join(userProfile, ".gemini", "GEMINI.md");
+  const claudeInstructions = path.join(userProfile, ".claude", "CLAUDE.md");
+  const cursorAgents = path.join(userProfile, ".cursor", "agents.md");
+  const cursorAgentsUpper = path.join(userProfile, ".cursor", "AGENTS.md");
   const codexAgents = path.join(userProfile, ".codex", "AGENTS.md");
   switch (process.platform) {
     case "win32":
       return {
-        claude: path.join(appData, "Claude", "claude_desktop_config.json"),
+        gemini: geminiInstructions,
+        claude: claudeInstructions,
+        cursorAgents,
+        cursorAgentsUpper,
         continue: continueJson,
         continueYaml,
         continueYml,
@@ -1192,7 +1211,10 @@ function clientInstructionPaths() {
       };
     case "darwin":
       return {
-        claude: path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json"),
+        gemini: geminiInstructions,
+        claude: claudeInstructions,
+        cursorAgents,
+        cursorAgentsUpper,
         continue: continueJson,
         continueYaml,
         continueYml,
@@ -1211,7 +1233,10 @@ function clientInstructionPaths() {
       };
     default:
       return {
-        claude: path.join(home, ".config", "Claude", "claude_desktop_config.json"),
+        gemini: geminiInstructions,
+        claude: claudeInstructions,
+        cursorAgents,
+        cursorAgentsUpper,
         continue: continueJson,
         continueYaml,
         continueYml,
@@ -1295,18 +1320,22 @@ function applyAgentInstructions({ logger } = {}) {
   };
 
   if (paths.vscodeGlobalInstructions) {
-    safeApply("vscode-global", () =>
-      upsertPromptFile(paths.vscodeGlobalInstructions, instructions, { prepend: true })
-    );
+    safeApply("vscode-global-cleanup", () => removePromptFile(paths.vscodeGlobalInstructions));
   }
   if (paths.vscodeInstructionsFile) {
-    safeApply("vscode-instructions-file", () =>
-      upsertPromptFile(paths.vscodeInstructionsFile, instructions, { prepend: true })
+    safeApply("vscode-instructions-file-cleanup", () =>
+      removePromptFile(paths.vscodeInstructionsFile)
     );
   }
-  if (paths.vscodeSettings && paths.vscodeInstructionsDir) {
+  if (paths.cursorAgents) {
+    safeApply("cursor-legacy-cleanup", () => removePromptFile(paths.cursorAgents));
+  }
+  if (paths.cursorAgentsUpper) {
+    safeApply("cursor-legacy-upper-cleanup", () => removePromptFile(paths.cursorAgentsUpper));
+  }
+  if (paths.vscodeSettings) {
     safeApply("vscode-settings", () =>
-      upsertVsCodeInstructions(paths.vscodeSettings, instructions, paths.vscodeInstructionsDir)
+      upsertVsCodeInstructions(paths.vscodeSettings, instructions, paths.vscodeGlobalInstructions)
     );
   }
   if (paths.windsurfGlobalRules) {
@@ -1321,6 +1350,9 @@ function applyAgentInstructions({ logger } = {}) {
   if (paths.claude) {
     safeApply("claude", () => upsertClaudeInstructions(paths.claude, instructions));
   }
+  if (paths.gemini) {
+    safeApply("gemini", () => upsertPromptFile(paths.gemini, instructions));
+  }
   const continueYamlExists =
     (paths.continueYaml && fs.existsSync(paths.continueYaml)) ||
     (paths.continueYml && fs.existsSync(paths.continueYml));

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "docdex",
-  "version": "0.2.24",
+  "version": "0.2.26",
   "mcpName": "io.github.bekirdag/docdex",
   "description": "Local-first documentation and code indexer with HTTP/MCP search, AST, and agent memory.",
   "bin": {
     "docdex": "bin/docdex.js",
-    "docdexd": "bin/docdex.js"
+    "docdexd": "bin/docdex.js",
+    "docdex-mcp-stdio": "bin/docdex-mcp-stdio.js"
   },
   "files": [
     "bin",