docdex 0.2.25 → 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,14 +1,16 @@
----- START OF DOCDEX INFO V0.2.25 ----
+---- 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
@@ -69,8 +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. |
-| HTTP /v1/dag/export | Export the dependency DAG for change ordering and scope. |
+| 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
 
@@ -104,6 +106,7 @@ Use these to verify index coverage, repo binding, and to read precise file slice
 | 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)
 
@@ -114,13 +117,144 @@ Use these to verify index coverage, repo binding, and to read precise file slice
 - 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.
 - 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.
-- HTTP /v1/graph/impact: Mandatory before code changes to review inbound/outbound deps.
-- HTTP /v1/dag/export: Export dependency graph to plan change order.
-- HTTP /v1/initialize: Bind a default repo root for MCP when clients omit project_root.
+- 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
 

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/package.json

@@ -1,11 +1,12 @@
 {
   "name": "docdex",
-  "version": "0.2.25",
+  "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",