Docdex

🚀 Docdex

Docdex is a lightweight, local documentation indexer/search daemon. It runs per-project, maintains an on - disk index of your markdown/text docs, and provides top - k snippets via HTTP or CLI for any coding assistant or tool. No external services or uploads are required.

🚀 Quick Start

# install (npm)
npm i -g docdex
# or use once
npx docdex --version

# full index for a repo/workspace
docdexd index --repo /path/to/repo

# serve HTTP API with live file watching (secure mode requires an auth token)
docdexd serve --repo /path/to/repo --host 127.0.0.1 --port 46137 --log info --auth-token <token>
# for local, token-free use, add --secure-mode=false
# docdexd serve --repo /path/to/repo --host 127.0.0.1 --port 46137 --log info --secure-mode=false

# ad-hoc search via CLI (JSON)
docdexd query --repo /path/to/repo --query "otp flow" --limit 5

✨ Features

• Per - repo Local Indexing: Conducts local indexing of Markdown/text files (backed by tantivy; no network calls).
• Unified Index for HTTP and CLI: The HTTP API (/search, /snippet, /healthz) and CLI (query, ingest, self - check) share the same index.
• Live File Watching: Enables live file watching during serving for incremental updates.
• Security Features: Offers security knobs such as TLS (manual certs or Certbot), auth token requirement by default (disable with --secure - mode=false), loopback - only allowlist by default, default rate limiting, request - size limits, strict state - dir perms, audit log, and chroot/privilege drop/unshare net (Unix).
• Coding Assistant - Ready Output: Provides output ready for coding assistants, including summaries, snippets, and doc metadata.
• AI - Friendly: GET /ai - help returns a JSON playbook (endpoints, CLI commands, limits, best practices) for agents.

📦 Installation

• Prerequisite: Requires Node.js >= 18.
• Installation Command: npm i -g docdex (or run npx docdex --version to verify).
• Command Execution: docdex (alias docdexd) downloads the appropriate binary for your platform from the matching GitHub release.
• Supported Platforms: macOS (arm64, x64), Linux glibc (arm64, x64), Linux musl (arm64, x64), Windows (x64, arm64); the installer fetches the matching platform release asset.
• Forked Repo Installation: If you publish from a fork, set DOCDEX_DOWNLOAD_REPO=<owner/repo> before installing so the downloader fetches your release assets.
• Distribution: Binaries are stored in GitHub Releases (small npm package); post - install fetches docdexd - <platform>.tar.gz matching the npm version.
• Publishing: Uses npm Trusted Publishing (OIDC) — no NPM token needed; see .github/workflows/release.yml.

💻 Usage Examples

Basic Usage

# Install Docdex
npm i -g docdex

# Index a repository
docdexd index --repo /path/to/repo

# Serve the HTTP API
docdexd serve --repo /path/to/repo --host 127.0.0.1 --port 46137 --log info --auth-token <token>

# Query via CLI
docdexd query --repo /path/to/repo --query "otp flow" --limit 5

Advanced Usage

# Serve with TLS using Certbot
docdexd serve --repo /path/to/repo --host 0.0.0.0 --port 46137 --certbot-domain docs.example.com

# Run as an MCP tool provider
docdexd mcp --repo /path/to/repo --log warn --max-results 8

📚 Documentation

What it does

• Local Indexing: Indexes Markdown/text docs within a repo and stores them locally (tantivy - based index under <repo>/.docdex/index by default).
• Unified Access: Serves the same index via HTTP (/search, /snippet, /healthz) and CLI (query, ingest, self - check), allowing automation and interactive use to share one dataset.
• Incremental Updates: Watches files during serving to incrementally ingest changes.
• Hardened Defaults: Has loopback binding, enforces TLS on non - loopback, requires an auth token by default (disable with --secure - mode=false), has a loopback - only allowlist and default rate limit (60 req/min) in secure mode, enables audit logging, and enforces strict state - dir permissions.

How it works

1. docdexd index builds the on - disk index for your repo (or reuses a legacy .gpt - creator/docdex/index if present).
2. docdexd serve loads the index, starts a file watcher for incremental updates, and exposes the HTTP API.
3. HTTP clients or the CLI (docdexd query) read from the same index; ingest can update a single file without full reindexing.
4. Optional TLS/auth/rate - limit settings secure remote access; audit logging can record access actions.

TL;DR for agents

• Index and Serve: Use Docdex for repo docs by running docdexd index --repo . once, then either docdexd serve --repo . --host 127.0.0.1 --port 46137 for HTTP, or docdexd mcp --repo . --log warn for MCP.
• Git Ignore: Add .docdex/ to .gitignore so indexes aren't committed.
• MCP - aware Use: When MCP - aware, register a server named docdex that runs docdexd mcp --repo . --log warn --max - results 8, then call docdex_search before coding and docdex_index when results are stale.
• Best Practices: Prefer summary - first (snippets=false), fetch specific snippets only when needed, keep queries short, and respect token estimates.

Usage cheat sheet

• Build Index: docdexd index --repo <path> (add --exclude - * to skip paths).
• Serve with Watcher: docdexd serve --repo <path> --host 127.0.0.1 --port 46137 --log warn --auth - token <token> (secure mode also allowlists loopback and rate - limits by default; add --allow - ip/--secure - mode=false/--rate - limit - per - min as needed for remote use).
• Secure Serving: Add --auth - token <token> (required by default); use TLS with --tls - cert/--tls - key or --certbot - domain <domain>.
• Single - file Ingest: docdexd ingest --repo <path> --file docs/new.md (honors excludes).
• Query via CLI: docdexd query --repo <path> --query "term" --limit 4.
• Git Hygiene: Add .docdex/ (and especially .docdex/index/) to your repo's .gitignore so index artifacts are not committed.
• Health Check: curl http://127.0.0.1:46137/healthz.
• Summary - only Search: curl "http://127.0.0.1:46137/search?q=foo&snippets=false"; fetch snippets only for top hits.
• Token Budgets: curl "http://127.0.0.1:46137/search?q=foo&max_tokens=800" to drop hits that exceed your prompt budget; pair with snippets=false then fetch 1–2 snippets you need.
• Text - only Snippets: Append text_only=true to /snippet/:doc_id or start serve with --strip - snippet - html (or --disable - snippet - text to return metadata only).
• Compact Requests: The defaults enforce max_query_bytes = 4096 and max_request_bytes = 16384; keep queries short and set --max - limit low (default 8) to avoid oversized responses.
• Prompt Hygiene: In agent prompts, normalize whitespace and include only rel_path, summary, and trimmed snippet (omit score/token_estimate/doc_id).
• Trim Noise: Use --exclude - dir and --exclude - prefix to keep vendor/build/cache/secrets out of the index so snippets stay relevant and short.
• Quiet Logging: Run docdexd serve --log warn --access - log=false if you process responses elsewhere to reduce log overhead.
• Client - side Caching: Store doc_id ↔ rel_path ↔ summary to avoid repeated snippet calls; fetch snippets only for new doc_ids.
• Agent Help: curl http://127.0.0.1:46137/ai - help (requires auth if configured; include Authorization: Bearer <token> when you've set --auth - token). The response includes a short MCP registration recipe.

Versioning

• Semantic Versioning: Follows semantic versioning with tagged releases (vX.Y.Z). The Rust crate and npm package share the same version.
• Release Process: Conventional Commits drive release notes via Release Please; it opens release PRs that bump Cargo.toml and npm/package.json, update changelogs, and create the tag/release on merge.
• Version Pinning: Pin to a released version when integrating (e.g., in scripts or Dockerfiles) so upgrades are explicit and reversible.
• Source Build: If you build from source, the version comes from Cargo.toml in this repo; the npm wrapper uses the matching version to fetch binaries.

Paths and defaults

• State/Index Directory: <repo>/.docdex/index (if missing but legacy <repo>/.gpt - creator/docdex/index exists, Docdex will reuse it and issue a warning). The directory is created with 0700 permissions by default.
• HTTP API: Defaults to 127.0.0.1:46137 when serving.
• Data and Logs: Docdex data and logs are stored within the repo; no external services are involved.

Configuration knobs

A variety of configuration options are available to customize Docdex's behavior, such as setting paths, enabling security features, and controlling logging. For details, please refer to the following options:

• --repo <path>: workspace root to index (defaults to .).
• --state - dir <path> / DOCDEX_STATE_DIR: override index storage path (relative paths are resolved under repo).
• --exclude - prefix a,b,c / DOCDEX_EXCLUDE_PREFIXES: extra relative prefixes to skip.
• --exclude - dir a,b,c / DOCDEX_EXCLUDE_DIRS: extra directory names to skip anywhere in the tree.
• --auth - token <token> / DOCDEX_AUTH_TOKEN: bearer token required in secure mode (default); omit only when starting with --secure - mode=false.
• --secure - mode <true|false> / DOCDEX_SECURE_MODE: default true; when enabled, requires an auth token, has a loopback - only allowlist by default, and applies a default rate limit (60 req/min).
• --allow - ip a,b,c / DOCDEX_ALLOW_IPS: optional comma - separated IPs/CIDRs allowed to access the HTTP API (default: loopback - only in secure mode; allow all when secure mode is disabled).
• --tls - cert / DOCDEX_TLS_CERT and --tls - key / DOCDEX_TLS_KEY: serve HTTPS with the provided cert/key. With TLS enforcement on, non - loopback binds must use HTTPS unless you explicitly opt out.
• --certbot - domain <domain> / DOCDEX_CERTBOT_DOMAIN: point TLS at /etc/letsencrypt/live/<domain>/{fullchain.pem,privkey.pem} (Certbot). Conflicts with manual --tls - *.
• --certbot - live - dir <path> / DOCDEX_CERTBOT_LIVE_DIR: use a specific Certbot live dir containing fullchain.pem and privkey.pem.
• --require - tls <true|false> / DOCDEX_REQUIRE_TLS: default true. Enforce TLS for non - loopback binds; set to false when TLS is already terminated by a trusted proxy.
• --insecure / DOCDEX_INSECURE_HTTP=true: allow plain HTTP on non - loopback binds even when TLS is enforced (only use behind a trusted proxy).
• --max - limit <n> / DOCDEX_MAX_LIMIT: clamp HTTP limit to at most n (default: 8).
• --max - query - bytes <n> / DOCDEX_MAX_QUERY_BYTES: reject requests whose query string exceeds n bytes (default: 4096).
• --max - request - bytes <n> / DOCDEX_MAX_REQUEST_BYTES: reject requests whose Content - Length or size hint exceeds n bytes (default: 16384).
• --rate - limit - per - min <n> / DOCDEX_RATE_LIMIT_PER_MIN: per - IP request budget per minute (default 60 in secure mode when unset/0; 0 disables when secure mode is off).
• --rate - limit - burst <n> / DOCDEX_RATE_LIMIT_BURST: optional burst capacity for the rate limiter (defaults to per - minute limit when 0).
• --audit - log - path <path> / DOCDEX_AUDIT_LOG_PATH: write audit log JSONL to this path (default: <state - dir>/audit.log).
• --audit - max - bytes <n> / DOCDEX_AUDIT_MAX_BYTES: rotate audit log after this many bytes (default: 5_000_000).
• --audit - max - files <n> / DOCDEX_AUDIT_MAX_FILES: keep at most this many rotated audit files (default: 5).
• --audit - disable / DOCDEX_AUDIT_DISABLE=true: disable audit logging entirely.
• --strip - snippet - html / DOCDEX_STRIP_SNIPPET_HTML=true: omit snippet.html in responses to force text - only snippets (HTML is sanitized by default when present).
• --disable - snippet - text / DOCDEX_DISABLE_SNIPPET_TEXT=true: omit snippet text/html in responses entirely (only doc metadata is returned).
• --access - log <true|false> / DOCDEX_ACCESS_LOG: emit minimal structured access logs with query values redacted (default: true).
• --run - as - uid / DOCDEX_RUN_AS_UID, --run - as - gid / DOCDEX_RUN_AS_GID: (Unix) drop privileges to the provided UID/GID after startup prep.
• --chroot <path> / DOCDEX_CHROOT: (Unix) chroot into path before serving; repo/state paths must exist inside that jail.
• --unshare - net / DOCDEX_UNSHARE_NET=true: (Linux only) unshare the network namespace before serving (requires CAP_SYS_ADMIN/root); no - op on other platforms.
• Logging: --log <level> on serve (defaults to info), or RUST_LOG=docdexd=debug style filters.
• Secure Mode Defaults: When --secure - mode=true (default), docdex requires an auth token, allows only loopback IPs unless overridden, and applies a 60 req/min rate limit. Set --secure - mode=false to opt out for local dev and adjust --allow - ip/rate limits as needed.

Indexing rules (see index/mod.rs)

• File types: .md, .markdown, .mdx, .txt (extend DEFAULT_EXTENSIONS to add more).
• Skipped directories: A wide range of VCS/build/cache/vendor folders across different ecosystems are skipped, such as .git, .hg, .svn, node_modules, .pnpm - store, .yarn*, .nx, .rollup - cache, .webpack - cache, .tsbuildinfo, .next, .nuxt, .svelte - kit, .mypy_cache, .ruff_cache, .venv, target, go - build, .gradle, .mvn, pods, .dart_tool, .android, .serverless, .vercel, .netlify, _build, _opam, .stack - work, elm - stuff, library, intermediate, .godot, etc. See DEFAULT_EXCLUDED_DIR_NAMES for the full list.
• Skipped relative prefixes: logs/, .docdex/, .docdex/logs/, .docdex/tmp/, .gpt - creator/logs/, .gpt - creator/tmp/, .mastercoda/logs/, .mastercoda/tmp/, docker/.data/, docker - data/, .docker/.
• Snippet sizing: Summaries are approximately 360 characters (up to 4 segments); snippets are approximately 420 characters.

HTTP API

• GET /healthz — returns ok; this endpoint is unauthenticated and not rate - limited (IP allowlist still applies).
• GET /search?q=<text>&limit=<n>&snippets=<bool>&max_tokens=<u64> — returns { hits: [...] } with doc id, rel path, summary, snippet, score, token estimate. Set snippets=false for summary - only responses; set max_tokens to drop hits above your budget.
• GET /snippet/:doc_id?window=<lines>&q=<query>&text_only=<bool>&max_tokens=<u64> — returns { doc, snippet } with an optional highlighted snippet; falls back to preview when query highlighting is empty (default window: 40 lines). Set text_only=true to remove HTML and reduce payload size; set max_tokens to omit the snippet if the doc exceeds your budget.
• GET /ai - help — returns a JSON quickstart for agents (endpoints, CLI commands, limits, best practices).
• GET /metrics — returns Prometheus - style counters for rate - limit/auth/error metrics.
• If --auth - token is set, include Authorization: Bearer <token> in HTTP calls (including /ai - help).

CLI commands

• serve --repo <path> [--host 127.0.0.1] [--port 46137] [--log info] — start HTTP API with file watching for incremental updates.
• index --repo <path> — rebuild the entire index.
• ingest --repo <path> --file <file> — reindex a single file.
• query --repo <path> --query "<text>" [--limit 8] — run a search and print JSON hits.
• self - check --repo <path> --terms "foo,bar" [--limit 5] — scan the index for sensitive terms before enabling access (fails with non - zero exit if any are found; reports sample hits and if more exist). Includes built - in token/password patterns by default; disable with --include - default - patterns=false if you only want your provided terms.

Help and command discovery

• List Commands/Flags: docdexd --help.
• Dump Subcommand Help: docdexd help - all.
• Serve Options: docdexd serve --help (TLS, auth, rate limits, watcher).
• Indexing Options: docdexd index --help (exclude paths, custom state dir).
• Ad - hoc Queries: docdexd query --help.
• Self - check Scanner Options: docdexd self - check --help.
• Agent Help Endpoint: curl http://127.0.0.1:46137/ai - help (include Authorization: Bearer <token> if --auth - token is set) for a JSON listing of endpoints, limits, and best practices.
• MCP Help/Registration: docdexd mcp --help lists MCP flags; register with your client using docdexd mcp --repo <repo> --log warn. Example Codex config snippet:

  {
    "mcpServers": {
      "docdex": {
        "command": "docdexd",
        "args": ["mcp", "--repo", ".", "--log", "warn", "--max - results", "8"],
        "env": {}
      }
    }
  }
  

• MCP Quick Add Commands:
  • Docdex helper: docdex mcp - add --repo /path/to/repo --log warn --max - results 8 auto - detects supported agents; add --all to attempt every known client and print manual steps for UI - only ones, or --remove to uninstall.
  • Codex CLI: codex mcp add docdex -- docdexd mcp --repo /path/to/repo --log warn --max - results 8.
  • Generic JSON config (Cursor, Continue, Windsurf, Cline, Claude Desktop devtools): add the mcpServers.docdex block above to your MCP config file (paths vary by client; most accept the command/args schema shown).
  • Manual/stdio - only clients: start docdexd mcp --repo /path/to/repo --log warn --max - results 8 yourself and point the client at that command/binary.
• Tools Exposed:
  • docdex_search — args: { "query": "<text>", "limit": <int optional>, "project_root": "<path optional>" }. Returns { "results": [...], "repo_root": "...", "state_dir": "...", "limit": <int>, "project_root": "...", "meta": {...} }.
  • docdex_index — args: { "paths": ["relative/or/absolute"], "project_root": "<path optional>" }. Empty paths reindexes everything; otherwise ingests the listed files.
  • docdex_files — args: { "limit": <int optional, default 200, max 1000>, "offset": <int optional, default 0>, "project_root": "<path optional>" }. Returns { "results": [{ "doc_id", "rel_path", "summary", "token_estimate" }], "total", "limit", "offset", "repo_root", "project_root" }.
  • docdex_open — args: { "path": "<relative file>", "start_line": <int optional>, "end_line": <int optional>, "project_root": "<path optional>" }. Returns { "path", "start_line", "end_line", "total_lines", "content", "repo_root", "project_root" } (rejects paths outside repo and large files).
  • docdex_stats — args: { "project_root": "<path optional>" }. Returns { "num_docs", "state_dir", "index_size_bytes", "segments", "avg_bytes_per_doc", "generated_at_epoch_ms", "last_updated_epoch_ms", "repo_root", "project_root" }.
• Example calls:
  • Initialize: {"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
  • Initialize with workspace root: {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"workspace_root":"/path/to/repo"}} (must match the server repo; sets default project_root for later calls)
  • List tools: {"jsonrpc":"2.0","id":2,"method":"tools/list"}
  • Reindex: {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"docdex_index","arguments":{"paths":[]}}}
  • Search: {"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"docdex_search","arguments":{"query":"payment auth flow","limit":3,"project_root":"/repo"}}}
  • List files: {"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"docdex_files","arguments":{"limit":10,"offset":0}}}
  • Open file: {"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"docdex_open","arguments":{"path":"docs/readme.md","start_line":1,"end_line":20}}}
  • Stats: {"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"docdex_stats","arguments":{}}}
• Errors: invalid JSON → code - 32700; unsupported/missing jsonrpc → - 32600; unknown tool/method → - 32601; invalid params (empty query, bad args, project_root mismatch) → - 32602; internal errors include a reason string in error.data.
• Agent guidance: Call docdex_search with concise queries before coding; fetch only a few hits; if results look stale, call docdex_index; keep using HTTP/CLI if your stack isn't MCP - aware.
• Help: docdexd mcp --help shows MCP flags and defaults; docdexd help - all includes an MCP section listing tools and usage.

Troubleshooting

• Stale Index: Re - run docdexd index --repo <path>.
• Port Conflicts: Change --host/--port.

Security considerations

• Default Bind: The default bind is 127.0.0.1; keep it unless you are behind a trusted reverse proxy/firewall. Avoid --host 0.0.0.0 on untrusted networks.
• TLS Requirements: By default, non - loopback binds require TLS; opt out only with --require - tls=false or --insecure when traffic is already terminating at a trusted proxy.
• External Exposure: If exposing externally, place a reverse proxy in front, terminate TLS, and require auth (basic/OAuth/mTLS) plus IP/VPN allowlisting. Example (nginx):

  server {
    listen 443 ssl;
    server_name docdex.example.com;
    ssl_certificate /path/fullchain.pem;
    ssl_certificate_key /path/privkey.pem;
    auth_basic "Protected";
    auth_basic_user_file /etc/nginx/.htpasswd; # or hook OAuth/mTLS instead
    allow 10.0.0.0/8;
    allow 192.168.0.0/16;
    deny all;
    location / {
      proxy_pass http://127.0.0.1:46137;
      proxy_set_header Host $host;
    }
  }
  

• Corpus Trimming: Prefer a curated staging directory, or use --exclude - dir / --exclude - prefix to keep secrets/private paths out before indexing; the watcher will ingest any in - scope file change under repo.
• Logging: Avoid verbose logging in production if snippets/paths are sensitive; reverse - proxy access logs can also capture query terms and paths.
• Least Privilege: Run docdex under a low - privilege user/container and keep the state dir on a path with restricted permissions.
• Validation: Run docdexd query for sensitive keywords to confirm no hits; store indexes on encrypted disks if required.
• Optional Hardening: Require an auth token on the HTTP API (or proxy); enforce TLS when not on localhost (default) or explicitly opt out with --require - tls=false/--insecure only behind a trusted proxy; enable rate limiting (--rate - limit - per - min) and clamp limit/request sizes (--max - limit, --max - query - bytes, --max - request - bytes); escape/sanitize snippet HTML if embedding or disable snippets entirely with --disable - snippet - text; state dir is created 0700 by default—keep it under an unprivileged user, optionally --run - as - uid/--run - as - gid, --chroot, or containerize; keep access logging minimal/redacted (--access - log), and run self - check for sensitive terms before exposing the service; for at - rest confidentiality, place the state dir on encrypted storage or use host - level disk encryption.

Integrating with LLM tools

Docdex is tool - agnostic. Here's a guide for integrating with agents/codegen tools:

• Initial Setup: Start once per repo: docdexd index --repo <repo> then docdexd serve --repo <repo> --host 127.0.0.1 --port 46137 --log warn (or use the CLI directly without serving).
• Configuration via Env: DOCDEX_STATE_DIR (index location), DOCDEX_EXCLUDE_PREFIXES, DOCDEX_EXCLUDE_DIRS, RUST_LOG=docdexd=debug (optional verbose logs).
• HTTP Query: GET /search?q=<text>&limit=<n> returns {"hits":[{"doc_id","rel_path","score","summary","snippet","token_estimate"}...]}; GET /snippet/:doc_id fetches a focused snippet plus doc metadata.
• CLI Query: docdexd query --repo <repo> --query "<text>" --limit 8 (JSON to stdout).
• Health Check: GET /healthz should return ok before issuing search requests.
• Snippet Injection:

"You are building features for this repo. Use the following documentation snippets for context. If a snippet cites a path, keep that path in your response. Snippets:\n<insert docdex snippets here>\nQuestion: <your question>"

MCP (optional stdio server for MCP - aware clients)

Docdex can operate as an MCP tool provider over stdio; it does not replace the HTTP daemon—choose the option that suits your agent/editor. If your MCP client supports resource templates, Docdex advertises a docdex_file template (docdex://{path}) which delegates to docdex_open.

• Running MCP: docdexd mcp --repo /path/to/repo --log warn --max - results 8 (alias: --mcp - max - results 8).
• Env Override: DOCDEX_MCP_MAX_RESULTS limits docdex_search results (min 1).
• Packaging: The MCP server is integrated into the main docdexd binary (invoked via docdexd mcp or docdex mcp from the npm bin); no separate docdex - mcp download is required.
• Registration with MCP Clients: Add a server named docdex that runs docdexd mcp --repo <repo> --log warn. Example Codex config snippet:

  {
    "mcpServers": {
      "docdex": {
        "command": "docdexd",
        "args": ["mcp", "--repo", ".", "--log", "warn", "--max - results", "8"],
        "env": {}
      }
    }
  }
  

• MCP Quick Add Commands:
  • Docdex helper: docdex mcp - add --repo /path/to/repo --log warn --max - results 8 auto - detects supported agents; add --all to attempt every known client and print manual steps for UI - only ones, or --remove to uninstall.
  • Codex CLI: codex mcp add docdex -- docdexd mcp --repo /path/to/repo --log warn --max - results 8.
  • Generic JSON config (Cursor, Continue, Windsurf, Cline, Claude Desktop devtools): add the mcpServers.docdex block above to your MCP config file (paths vary by client; most accept the command/args schema shown).
  • Manual/stdio - only clients: start docdexd mcp --repo /path/to/repo --log warn --max - results 8 yourself and point the client at that command/binary.
• Tools Exposed:
  • docdex_search — args: { "query": "<text>", "limit": <int optional>, "project_root": "<path optional>" }. Returns { "results": [...], "repo_root": "...", "state_dir": "...", "limit": <int>, "project_root": "...", "meta": {...} }.
  • docdex_index — args: { "paths": ["relative/or/absolute"], "project_root": "<path optional>" }. Empty paths reindexes everything; otherwise ingests the listed files.
  • docdex_files — args: { "limit": <int optional, default 200, max 1000>, "offset": <int optional, default 0>, "project_root": "<path optional>" }. Returns { "results": [{ "doc_id", "rel_path", "summary", "token_estimate" }], "total", "limit", "offset", "repo_root", "project_root" }.
  • docdex_open — args: { "path": "<relative file>", "start_line": <int optional>, "end_line": <int optional>, "project_root": "<path optional>" }. Returns { "path", "start_line", "end_line", "total_lines", "content", "repo_root", "project_root" } (rejects paths outside repo and large files).
  • docdex_stats — args: { "project_root": "<path optional>" }. Returns { "num_docs", "state_dir", "index_size_bytes", "segments", "avg_bytes_per_doc", "generated_at_epoch_ms", "last_updated_epoch_ms", "repo_root", "project_root" }.
• Example Calls:
  • Initialize: {"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
  • Initialize with workspace root: {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"workspace_root":"/path/to/repo"}} (must match the server repo; sets default project_root for later calls)
  • List tools: {"jsonrpc":"2.0","id":2,"method":"tools/list"}
  • Reindex: {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"docdex_index","arguments":{"paths":[]}}}
  • Search: {"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"docdex_search","arguments":{"query":"payment auth flow","limit":3,"project_root":"/repo"}}}
  • List files: {"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"docdex_files","arguments":{"limit":10,"offset":0}}}
  • Open file: {"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"docdex_open","arguments":{"path":"docs/readme.md","start_line":1,"end_line":20}}}
  • Stats: {"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"docdex_stats","arguments":{}}}
• Errors: invalid JSON → code - 32700; unsupported/missing jsonrpc → - 32600; unknown tool/method → - 32601; invalid params (empty query, bad args, project_root mismatch) → - 32602; internal errors include a reason string in error.data.
• Agent Guidance: Call docdex_search with concise queries before coding; fetch only a few hits; if results look stale, call docdex_index; keep using HTTP/CLI if your stack isn't MCP - aware.
• Help: docdexd mcp --help shows MCP flags and defaults; docdexd help - all includes an MCP section listing tools and usage.

HTTPS and Certbot

• TLS Key Compatibility: TLS accepts PKCS8, PKCS1/RSA, and SEC1/EC private keys (compatible with Certbot output).
• Manual Cert/Key: docdexd serve --repo <repo> --tls - cert /path/fullchain.pem --tls - key /path/privkey.pem.
• Certbot Helper: docdexd serve --repo <repo> --host 0.0.0.0 --port 46137 --certbot - domain docs.example.com (uses /etc/letsencrypt/live/docs.example.com/{fullchain.pem,privkey.pem}), or pass --certbot - live - dir /custom/live/dir.
• Renewal Hook: When using Certbot, set a deploy hook to restart/reload docdex after renewals (e.g., certbot renew --deploy - hook "systemctl restart docdexd.service" or kill - HUP your process supervisor).
• Port 443 Binding: If binding to 443 directly, you need appropriate privileges; otherwise, keep docdex on 127.0.0.1 and let a reverse proxy terminate TLS.