embarsy-qdrant-mcp 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# embarsy-qdrant-mcp
+
+Codebase-indexing MCP server for **[Embarsy](https://github.com/arsenyganov-pixel/embarsy-embedder)** — semantic code search for Claude Code and Codex, backed by a local Qdrant + OpenAI-compatible embeddings stack.
+
+It indexes a directory of source into Qdrant and exposes a `search_code` MCP tool. Everything runs through Embarsy's proxy on `localhost:8000`, so the API keys are honored and both the embedding **and** Qdrant counters move in Embarsy → Monitoring. Pure JS — no native build.
+
+## Install
+
+```bash
+npm install -g embarsy-qdrant-mcp
+```
+
+Provides two commands: `embarsy-index` (index a codebase) and `embarsy-mcp` (the MCP server + config helpers).
+
+## Configuration
+
+Set via environment variables. Only the two API keys are required — everything else defaults to Embarsy.
+
+| Variable | Default | Notes |
+|---|---|---|
+| `OPENAI_API_KEY` | — | **required** — Embarsy → Status → API Key |
+| `QDRANT_API_KEY` | — | **required** — Embarsy → Status → Qdrant API Key |
+| `QDRANT_COLLECTION_NAME` | `embarsy-<dir>` | collection name (or `--collection`) |
+| `OPENAI_BASE_URL` | `http://localhost:8000/v1` | OpenAI-compatible embeddings endpoint |
+| `EMBEDDING_MODEL` | `qwen3-embedding` | |
+| `EMBEDDING_DIMENSION` | `1024` | must match the model |
+| `QDRANT_URL` | `http://localhost:8000/qdrant` | Qdrant REST (Embarsy proxy) |
+
+## Index a codebase
+
+```bash
+OPENAI_API_KEY=<API Key> QDRANT_API_KEY=<Qdrant API Key> \
+  embarsy-index ~/projects/my-app --collection my-app
+```
+
+Re-run any time — it's incremental (unchanged files are skipped, deleted files are pruned), respects `.gitignore`, and skips vendored/binary/oversized files.
+
+## Wire it into your editor
+
+The setup helpers write the config with **absolute** `node` + script paths, so the desktop apps (which don't inherit your shell `PATH`) can always launch the server.
+
+**Codex** — appends to `~/.codex/config.toml`:
+
+```bash
+OPENAI_API_KEY=<API Key> QDRANT_API_KEY=<Qdrant API Key> \
+QDRANT_COLLECTION_NAME=my-app embarsy-mcp --setup-codex
+```
+
+Restart Codex, run `/mcp` → `embarsy-qdrant` appears.
+
+**Claude Code** — run in your project folder (writes `.mcp.json`):
+
+```bash
+OPENAI_API_KEY=<API Key> QDRANT_API_KEY=<Qdrant API Key> \
+QDRANT_COLLECTION_NAME=my-app embarsy-mcp --setup-claude
+```
+
+## MCP tools
+
+- **`search_code`** — semantic search; returns the most relevant chunks with `file:line` and a snippet.
+- **`index_status`** — how many chunks are indexed in the collection.
+
+## License
+
+PolyForm Strict 1.0.0 — see the Embarsy repository.

package/dist/bin/index.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { loadConfig, requireConfig } from "../config.js";
+import { indexRepo } from "../indexer.js";
+function usage() {
+    process.stdout.write(`embarsy-index — index a codebase into Embarsy's Qdrant for semantic search.
+
+Usage:
+  embarsy-index <path> [--collection <name>]
+
+Options:
+  --collection <name>   Qdrant collection (default: $QDRANT_COLLECTION_NAME, else embarsy-<dir>).
+  -h, --help            Show this help.
+
+Configuration (env, with Embarsy defaults):
+  OPENAI_BASE_URL       default http://localhost:8000/v1
+  OPENAI_API_KEY        Embarsy → Status → API Key            (required)
+  EMBEDDING_MODEL       default qwen3-embedding
+  EMBEDDING_DIMENSION   default 1024
+  QDRANT_URL            default http://localhost:8000/qdrant
+  QDRANT_API_KEY        Embarsy → Status → Qdrant API Key      (required)
+`);
+}
+function sanitize(name) {
+    return name.replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase() || "project";
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    let target;
+    let collection;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "-h" || a === "--help") {
+            usage();
+            return;
+        }
+        if (a === "--collection") {
+            collection = argv[++i];
+            continue;
+        }
+        if (a.startsWith("--collection=")) {
+            collection = a.slice("--collection=".length);
+            continue;
+        }
+        if (!a.startsWith("-") && target === undefined) {
+            target = a;
+            continue;
+        }
+    }
+    if (!target) {
+        usage();
+        process.exitCode = 2;
+        return;
+    }
+    const rootAbs = path.resolve(target);
+    const finalCollection = collection || process.env.QDRANT_COLLECTION_NAME || `embarsy-${sanitize(path.basename(rootAbs))}`;
+    const cfg = loadConfig({ collection: finalCollection });
+    requireConfig(cfg, { needCollection: true });
+    process.stdout.write(`Indexing ${rootAbs}\n  collection: ${cfg.collection}\n  embeddings: ${cfg.openaiBaseUrl} (${cfg.embeddingModel}, dim ${cfg.embeddingDimension})\n  qdrant:     ${cfg.qdrantUrl}\n\n`);
+    const started = Date.now();
+    const result = await indexRepo(rootAbs, cfg, { onProgress: (m) => process.stdout.write(m + "\n") });
+    const secs = ((Date.now() - started) / 1000).toFixed(1);
+    process.stdout.write(`\nDone in ${secs}s — ${result.indexed} indexed, ${result.skipped} unchanged, ${result.removed} removed; ${result.chunks} chunks upserted into "${cfg.collection}".\n`);
+}
+main().catch((err) => {
+    process.stderr.write(`\nembarsy-index failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+});

package/dist/bin/mcp.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { loadConfig, requireConfig } from "../config.js";
+import { runMcpServer } from "../mcp-server.js";
+import { setupCodex, setupClaude } from "../setup.js";
+// NOTE: stdout is the MCP transport — never write logs there. Errors go to stderr.
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes("-h") || args.includes("--help")) {
+        process.stdout.write(`embarsy-mcp — MCP server exposing semantic code search over Embarsy's Qdrant.
+
+Usage:
+  embarsy-mcp                 Run the MCP stdio server (this is what editors spawn).
+  embarsy-mcp --setup-codex   Write the server into ~/.codex/config.toml (absolute paths).
+  embarsy-mcp --setup-claude  Write the server into ./.mcp.json for Claude Code (run in your project).
+
+Both setup commands read the current OPENAI_API_KEY / QDRANT_API_KEY / QDRANT_COLLECTION_NAME
+(and the OPENAI_BASE_URL / QDRANT_URL defaults) and bake them into the editor config.
+`);
+        return;
+    }
+    // Setup helpers write the editor config with absolute node + script paths, so the desktop
+    // apps (which don't inherit your shell PATH) can always launch the server.
+    const doCodex = args.includes("--setup-codex");
+    const doClaude = args.includes("--setup-claude");
+    if (doCodex || doClaude) {
+        const cfg = loadConfig();
+        requireConfig(cfg, { needCollection: true });
+        if (doCodex) {
+            const file = await setupCodex(cfg);
+            process.stdout.write(`✓ Added [mcp_servers.embarsy-qdrant] to ${file}\n  Restart Codex, then run /mcp — "embarsy-qdrant" should appear.\n`);
+        }
+        if (doClaude) {
+            const file = await setupClaude(cfg);
+            process.stdout.write(`✓ Wrote embarsy-qdrant server to ${file}\n  Open this project in Claude Code and approve the MCP server when prompted.\n`);
+        }
+        return;
+    }
+    const cfg = loadConfig();
+    requireConfig(cfg, { needCollection: true });
+    await runMcpServer(cfg);
+}
+main().catch((err) => {
+    process.stderr.write(`embarsy-mcp failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/chunker.js

@@ -0,0 +1,61 @@
+/**
+ * Line-oriented chunking with a character budget and overlap. Chunks prefer to start at a
+ * "definition-ish" line (function/class/etc.) when the current chunk is already sizeable, so
+ * chunks tend to align with logical code boundaries. Pure-JS, no native parser.
+ */
+const BOUNDARY = /^\s*(export\s+)?(async\s+)?(function|class|struct|enum|interface|trait|impl|def|func|fn|type|module|namespace|public|private|protected|static)\b/;
+export function chunkFile(content, cfg) {
+    const lines = content.split(/\r?\n/);
+    const chunks = [];
+    const maxChars = Math.max(400, cfg.chunkMaxChars);
+    const overlapChars = Math.max(0, Math.min(cfg.chunkOverlapChars, maxChars - 100));
+    let startIdx = 0; // 0-based line index where the current chunk starts
+    let curChars = 0;
+    let i = 0;
+    const flush = (endIdxExclusive) => {
+        if (endIdxExclusive <= startIdx)
+            return;
+        const slice = lines.slice(startIdx, endIdxExclusive);
+        const text = slice.join("\n").trim();
+        if (text.length > 0) {
+            chunks.push({ startLine: startIdx + 1, endLine: endIdxExclusive, text: slice.join("\n") });
+        }
+    };
+    while (i < lines.length) {
+        const line = lines[i] ?? "";
+        const lineChars = line.length + 1;
+        // Break BEFORE a definition line if the current chunk already has real content.
+        if (i > startIdx && curChars >= maxChars * 0.5 && BOUNDARY.test(line)) {
+            flush(i);
+            startIdx = backfillOverlap(lines, i, overlapChars);
+            curChars = charsBetween(lines, startIdx, i);
+        }
+        curChars += lineChars;
+        i++;
+        if (curChars >= maxChars) {
+            flush(i);
+            startIdx = backfillOverlap(lines, i, overlapChars);
+            curChars = charsBetween(lines, startIdx, i);
+        }
+    }
+    flush(lines.length);
+    return chunks;
+}
+/** Walk back from `idx` to include ~overlapChars of trailing context; returns new start index. */
+function backfillOverlap(lines, idx, overlapChars) {
+    if (overlapChars <= 0)
+        return idx;
+    let chars = 0;
+    let j = idx;
+    while (j > 0 && chars < overlapChars) {
+        j--;
+        chars += (lines[j]?.length ?? 0) + 1;
+    }
+    return j;
+}
+function charsBetween(lines, from, to) {
+    let c = 0;
+    for (let k = from; k < to; k++)
+        c += (lines[k]?.length ?? 0) + 1;
+    return c;
+}

package/dist/config.js

@@ -0,0 +1,39 @@
+function intEnv(value, fallback) {
+    if (value === undefined || value.trim() === "")
+        return fallback;
+    const n = Number.parseInt(value, 10);
+    return Number.isFinite(n) ? n : fallback;
+}
+const stripTrailingSlash = (s) => s.replace(/\/+$/, "");
+export function loadConfig(overrides = {}) {
+    const env = process.env;
+    return {
+        openaiBaseUrl: stripTrailingSlash(env.OPENAI_BASE_URL ?? "http://localhost:8000/v1"),
+        openaiApiKey: env.OPENAI_API_KEY ?? "",
+        embeddingModel: env.EMBEDDING_MODEL ?? "qwen3-embedding",
+        embeddingDimension: intEnv(env.EMBEDDING_DIMENSION, 1024),
+        qdrantUrl: stripTrailingSlash(env.QDRANT_URL ?? "http://localhost:8000/qdrant"),
+        qdrantApiKey: env.QDRANT_API_KEY ?? "",
+        collection: env.QDRANT_COLLECTION_NAME ?? env.QDRANT_COLLECTION ?? "",
+        chunkMaxChars: intEnv(env.EMBARSY_CHUNK_CHARS, 1500),
+        chunkOverlapChars: intEnv(env.EMBARSY_CHUNK_OVERLAP, 200),
+        embedBatch: intEnv(env.EMBARSY_EMBED_BATCH, 64),
+        maxFileBytes: intEnv(env.EMBARSY_MAX_FILE_BYTES, 1_000_000),
+        ...overrides,
+    };
+}
+/** Throw a clear, actionable error if a required value is missing. */
+export function requireConfig(cfg, opts) {
+    const missing = [];
+    if (!cfg.openaiApiKey)
+        missing.push("OPENAI_API_KEY (Embarsy → Status → API Key)");
+    if (!cfg.qdrantApiKey)
+        missing.push("QDRANT_API_KEY (Embarsy → Status → Qdrant API Key)");
+    if (opts.needCollection && !cfg.collection) {
+        missing.push("QDRANT_COLLECTION_NAME (or pass --collection)");
+    }
+    if (missing.length > 0) {
+        throw new Error("Missing required configuration:\n  - " + missing.join("\n  - ") +
+            "\n\nSet them as environment variables. Copy the API keys from Embarsy → Status.");
+    }
+}

package/dist/embeddings.js

@@ -0,0 +1,36 @@
+import { requestJSON } from "./http.js";
+/**
+ * Embed a batch of texts through the OpenAI-COMPATIBLE endpoint (Embarsy's /v1 proxy).
+ * This is the piece other tools get wrong: we send a bearer API key and use the standard
+ * POST /v1/embeddings shape, so Embarsy authenticates the call and counts it in Monitoring.
+ */
+export async function embedBatch(texts, cfg) {
+    if (texts.length === 0)
+        return [];
+    const json = await requestJSON(`${cfg.openaiBaseUrl}/embeddings`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${cfg.openaiApiKey}`,
+        },
+        body: JSON.stringify({ model: cfg.embeddingModel, input: texts }),
+    }, { label: "embeddings" });
+    const data = json?.data;
+    if (!Array.isArray(data) || data.length !== texts.length) {
+        throw new Error(`Unexpected embeddings response (got ${Array.isArray(data) ? data.length : "no"} vectors for ${texts.length} inputs).`);
+    }
+    // Respect the `index` field so ordering is guaranteed to match the input.
+    const ordered = [...data].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+    return ordered.map((d) => {
+        const v = d?.embedding;
+        if (!Array.isArray(v))
+            throw new Error("Embeddings response item missing `embedding` array.");
+        return v;
+    });
+}
+export async function embedOne(text, cfg) {
+    const [v] = await embedBatch([text], cfg);
+    if (!v)
+        throw new Error("No embedding returned.");
+    return v;
+}

package/dist/http.js

@@ -0,0 +1,33 @@
+/** Small fetch wrapper: retries transient failures and surfaces the response body in errors. */
+export async function requestJSON(url, init, opts = {}) {
+    const retries = opts.retries ?? 2;
+    const label = opts.label ?? init.method ?? "request";
+    let lastErr;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            const res = await fetch(url, init);
+            const text = await res.text();
+            if (!res.ok) {
+                // 4xx are not retryable (bad key / bad request) — fail fast with the server's message.
+                const detail = text.slice(0, 500);
+                const err = new Error(`${label} → HTTP ${res.status} at ${url}\n${detail}`);
+                if (res.status >= 400 && res.status < 500)
+                    throw err;
+                lastErr = err;
+            }
+            else {
+                return text ? JSON.parse(text) : {};
+            }
+        }
+        catch (e) {
+            lastErr = e;
+            // Don't retry explicit 4xx errors we threw above.
+            if (e instanceof Error && /HTTP 4\d\d/.test(e.message))
+                throw e;
+        }
+        if (attempt < retries)
+            await sleep(300 * (attempt + 1));
+    }
+    throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/dist/indexer.js

@@ -0,0 +1,94 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { embedBatch } from "./embeddings.js";
+import { chunkFile } from "./chunker.js";
+import { discoverFiles } from "./walk.js";
+import { ensureCollection, upsertPoints, deleteByFilePath, scrollFileHashes, } from "./qdrant.js";
+import { sha256, pointId, languageForExtension } from "./util.js";
+/** Crude binary guard: a NUL byte early in the file means it isn't source text. */
+function looksBinary(s) {
+    const n = Math.min(s.length, 8192);
+    for (let i = 0; i < n; i++) {
+        if (s.charCodeAt(i) === 0)
+            return true;
+    }
+    return false;
+}
+/** Full/incremental index of a directory into the configured Qdrant collection. */
+export async function indexRepo(root, cfg, opts = {}) {
+    const log = opts.onProgress ?? (() => { });
+    const rootAbs = path.resolve(root);
+    await ensureCollection(cfg);
+    const files = await discoverFiles(rootAbs, cfg);
+    log(`Found ${files.length} indexable files in ${rootAbs}`);
+    const existing = await scrollFileHashes(cfg);
+    const seen = new Set();
+    const result = { files: files.length, indexed: 0, skipped: 0, removed: 0, chunks: 0 };
+    // Pending chunk buffer, flushed in embedding batches across files.
+    let pending = [];
+    const flush = async () => {
+        if (pending.length === 0)
+            return;
+        const vectors = await embedBatch(pending.map((p) => p.text), cfg);
+        const points = pending.map((p, i) => ({
+            id: pointId(p.key),
+            vector: vectors[i],
+            payload: p.payload,
+        }));
+        await upsertPoints(cfg, points);
+        result.chunks += points.length;
+        pending = [];
+    };
+    for (const file of files) {
+        seen.add(file.rel);
+        let content;
+        try {
+            content = await fs.readFile(file.abs, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (looksBinary(content))
+            continue;
+        const hash = sha256(content);
+        if (existing.get(file.rel) === hash) {
+            result.skipped++;
+            continue;
+        }
+        // Changed or new: drop the file's old points, then re-chunk.
+        if (existing.has(file.rel))
+            await deleteByFilePath(cfg, file.rel);
+        const ext = path.extname(file.rel).replace(/^\./, "").toLowerCase();
+        const language = languageForExtension(ext);
+        const chunks = chunkFile(content, cfg);
+        chunks.forEach((c, idx) => {
+            pending.push({
+                key: `${file.rel}:${idx}`,
+                text: `${file.rel}\n\n${c.text}`, // path gives the embedder useful context
+                payload: {
+                    file_path: file.rel,
+                    language,
+                    start_line: c.startLine,
+                    end_line: c.endLine,
+                    file_hash: hash,
+                    chunk_index: idx,
+                    text: c.text.length > 4000 ? c.text.slice(0, 4000) : c.text,
+                },
+            });
+        });
+        result.indexed++;
+        if (pending.length >= cfg.embedBatch)
+            await flush();
+        if (result.indexed % 25 === 0)
+            log(`  indexed ${result.indexed} files, ${result.chunks + pending.length} chunks…`);
+    }
+    await flush();
+    // Prune files that no longer exist on disk.
+    for (const rel of existing.keys()) {
+        if (!seen.has(rel)) {
+            await deleteByFilePath(cfg, rel);
+            result.removed++;
+        }
+    }
+    return result;
+}

package/dist/mcp-server.js

@@ -0,0 +1,45 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { embedOne } from "./embeddings.js";
+import { search, collectionInfo } from "./qdrant.js";
+/** Build and run the Embarsy MCP server over stdio (for Claude Code / Codex). */
+export async function runMcpServer(cfg) {
+    const server = new McpServer({ name: "embarsy-qdrant", version: "0.1.0" });
+    server.tool("search_code", "Semantic search over the indexed codebase. Returns the most relevant code chunks with " +
+        "their file path and line range. Use natural language (e.g. 'where is auth handled').", {
+        query: z.string().describe("Natural-language description of the code you are looking for."),
+        limit: z.number().int().min(1).max(50).optional().describe("Max results (default 8)."),
+        path_contains: z.string().optional().describe("Only return chunks whose file path contains this substring."),
+    }, async ({ query, limit, path_contains }) => {
+        const want = limit ?? 8;
+        const vector = await embedOne(query, cfg);
+        // Over-fetch and filter by path client-side (substring match works regardless of index type).
+        const raw = await search(cfg, vector, path_contains ? want * 6 : want);
+        const hits = (path_contains
+            ? raw.filter((h) => String(h.payload?.file_path ?? "").includes(path_contains))
+            : raw).slice(0, want);
+        if (hits.length === 0) {
+            return { content: [{ type: "text", text: "No matches. Has the codebase been indexed with `embarsy-index`?" }] };
+        }
+        const text = hits
+            .map((h, i) => {
+            const p = h.payload ?? {};
+            const loc = `${p.file_path}:${p.start_line}-${p.end_line}`;
+            const lang = p.language ? ` [${p.language}]` : "";
+            const snippet = String(p.text ?? "").trimEnd();
+            return `### ${i + 1}. ${loc}${lang}  (score ${h.score.toFixed(3)})\n\n\`\`\`\n${snippet}\n\`\`\``;
+        })
+            .join("\n\n");
+        return { content: [{ type: "text", text }] };
+    });
+    server.tool("index_status", "Report how many chunks are indexed in the current collection.", {}, async () => {
+        const info = await collectionInfo(cfg);
+        const text = info
+            ? `Collection "${cfg.collection}": ${info.pointsCount} indexed chunks.`
+            : `Collection "${cfg.collection}" does not exist yet. Run: embarsy-index <path> --collection ${cfg.collection}`;
+        return { content: [{ type: "text", text }] };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/qdrant.js

@@ -0,0 +1,86 @@
+import { requestJSON } from "./http.js";
+/** Qdrant authenticates with the `api-key` header; Embarsy's proxy validates the same header. */
+function headers(cfg) {
+    return { "Content-Type": "application/json", "api-key": cfg.qdrantApiKey };
+}
+function base(cfg) {
+    return `${cfg.qdrantUrl}/collections/${encodeURIComponent(cfg.collection)}`;
+}
+/** Create the collection (Cosine, configured dimension) if it doesn't exist; add a file_path index. */
+export async function ensureCollection(cfg) {
+    const res = await fetch(base(cfg), { headers: headers(cfg) });
+    if (res.status === 200) {
+        await res.text();
+        return;
+    }
+    const body = await res.text();
+    if (res.status !== 404) {
+        throw new Error(`Qdrant collection check failed → HTTP ${res.status}\n${body.slice(0, 300)}`);
+    }
+    await requestJSON(base(cfg), {
+        method: "PUT",
+        headers: headers(cfg),
+        body: JSON.stringify({ vectors: { size: cfg.embeddingDimension, distance: "Cosine" } }),
+    }, { label: "create collection", retries: 0 });
+    // Payload index on file_path enables fast delete-by-file for incremental reindex.
+    try {
+        await requestJSON(`${base(cfg)}/index`, {
+            method: "PUT",
+            headers: headers(cfg),
+            body: JSON.stringify({ field_name: "file_path", field_schema: "keyword" }),
+        }, { label: "create index", retries: 0 });
+    }
+    catch {
+        /* index is an optimization; ignore if the Qdrant build rejects it */
+    }
+}
+export async function upsertPoints(cfg, points) {
+    if (points.length === 0)
+        return;
+    await requestJSON(`${base(cfg)}/points?wait=true`, { method: "PUT", headers: headers(cfg), body: JSON.stringify({ points }) }, { label: "upsert" });
+}
+export async function search(cfg, vector, limit) {
+    const body = { vector, limit, with_payload: true };
+    const json = await requestJSON(`${base(cfg)}/points/search`, { method: "POST", headers: headers(cfg), body: JSON.stringify(body) }, { label: "search" });
+    return (json?.result ?? []);
+}
+export async function deleteByFilePath(cfg, filePath) {
+    await requestJSON(`${base(cfg)}/points/delete?wait=true`, {
+        method: "POST",
+        headers: headers(cfg),
+        body: JSON.stringify({ filter: { must: [{ key: "file_path", match: { value: filePath } }] } }),
+    }, { label: "delete points" });
+}
+/** Map of file_path -> file_hash for every indexed file, used to skip unchanged files. */
+export async function scrollFileHashes(cfg) {
+    const out = new Map();
+    let offset = undefined;
+    for (let guard = 0; guard < 10000; guard++) {
+        const body = {
+            limit: 256,
+            with_payload: { include: ["file_path", "file_hash"] },
+            with_vector: false,
+        };
+        if (offset !== undefined && offset !== null)
+            body.offset = offset;
+        const json = await requestJSON(`${base(cfg)}/points/scroll`, { method: "POST", headers: headers(cfg), body: JSON.stringify(body) }, { label: "scroll" });
+        const points = json?.result?.points ?? [];
+        for (const p of points) {
+            const fp = p?.payload?.file_path;
+            const fh = p?.payload?.file_hash;
+            if (typeof fp === "string" && typeof fh === "string" && !out.has(fp))
+                out.set(fp, fh);
+        }
+        offset = json?.result?.next_page_offset ?? null;
+        if (!offset)
+            break;
+    }
+    return out;
+}
+export async function collectionInfo(cfg) {
+    const res = await fetch(base(cfg), { headers: headers(cfg) });
+    if (res.status === 404)
+        return null;
+    const json = JSON.parse(await res.text());
+    return { pointsCount: json?.result?.points_count ?? 0 };
+}

package/dist/setup.js

@@ -0,0 +1,85 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * The editor apps (Codex / Claude Code desktop) spawn MCP servers with a minimal PATH that
+ * does NOT include nvm/homebrew bin dirs — so a bare `embarsy-mcp` command fails to launch.
+ * We sidestep that entirely by writing ABSOLUTE paths: the current `node` binary + the
+ * absolute path to this package's compiled mcp.js.
+ */
+function resolveSpawn() {
+    const mcpJs = fileURLToPath(new URL("./bin/mcp.js", import.meta.url));
+    return { command: process.execPath, args: [mcpJs] };
+}
+/** Env block written into the editor config so the server has everything it needs. */
+function serverEnv(cfg) {
+    return {
+        OPENAI_BASE_URL: cfg.openaiBaseUrl,
+        OPENAI_API_KEY: cfg.openaiApiKey,
+        EMBEDDING_MODEL: cfg.embeddingModel,
+        EMBEDDING_DIMENSION: String(cfg.embeddingDimension),
+        QDRANT_URL: cfg.qdrantUrl,
+        QDRANT_API_KEY: cfg.qdrantApiKey,
+        QDRANT_COLLECTION_NAME: cfg.collection,
+    };
+}
+const SERVER_NAME = "embarsy-qdrant";
+/** Append an `[mcp_servers.embarsy-qdrant]` block to ~/.codex/config.toml (respects $CODEX_HOME). */
+export async function setupCodex(cfg) {
+    const home = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+    await fs.mkdir(home, { recursive: true });
+    const file = path.join(home, "config.toml");
+    const existing = await readOrEmpty(file);
+    if (existing.includes(`[mcp_servers.${SERVER_NAME}]`)) {
+        throw new Error(`~/.codex/config.toml already has [mcp_servers.${SERVER_NAME}]. Remove it first to re-run setup.`);
+    }
+    const { command, args } = resolveSpawn();
+    const env = serverEnv(cfg);
+    const lines = [
+        "",
+        `[mcp_servers.${SERVER_NAME}]`,
+        `command = ${toml(command)}`,
+        `args = [${args.map(toml).join(", ")}]`,
+        "",
+        `[mcp_servers.${SERVER_NAME}.env]`,
+        ...Object.entries(env).map(([k, v]) => `${k} = ${toml(v)}`),
+        "",
+    ];
+    const next = (existing.trimEnd() + "\n" + lines.join("\n")).replace(/^\n+/, "");
+    await fs.writeFile(file, next, "utf8");
+    return file;
+}
+/** Merge an `embarsy-qdrant` server into ./.mcp.json (project-scoped Claude Code config). */
+export async function setupClaude(cfg) {
+    const file = path.resolve(".mcp.json");
+    let json = {};
+    const existing = await readOrEmpty(file);
+    if (existing.trim()) {
+        try {
+            json = JSON.parse(existing);
+        }
+        catch {
+            throw new Error(`${file} is not valid JSON — fix or remove it first.`);
+        }
+    }
+    if (typeof json !== "object" || json === null)
+        json = {};
+    json.mcpServers = json.mcpServers ?? {};
+    const { command, args } = resolveSpawn();
+    json.mcpServers[SERVER_NAME] = { command, args, env: serverEnv(cfg) };
+    await fs.writeFile(file, JSON.stringify(json, null, 2) + "\n", "utf8");
+    return file;
+}
+async function readOrEmpty(file) {
+    try {
+        return await fs.readFile(file, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+/** Minimal TOML basic-string quoting (JSON escaping is a valid superset for our values). */
+function toml(value) {
+    return JSON.stringify(value);
+}

package/dist/util.js

@@ -0,0 +1,23 @@
+import { createHash } from "node:crypto";
+export function sha256(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}
+/**
+ * Deterministic Qdrant point ID (UUID string) from a stable key, so re-indexing a chunk
+ * overwrites its previous point instead of piling up duplicates.
+ */
+export function pointId(key) {
+    const h = createHash("md5").update(key, "utf8").digest("hex"); // 32 hex chars
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
+}
+export function languageForExtension(ext) {
+    const map = {
+        ts: "TypeScript", tsx: "TypeScript", js: "JavaScript", jsx: "JavaScript", mjs: "JavaScript", cjs: "JavaScript",
+        py: "Python", rb: "Ruby", go: "Go", rs: "Rust", java: "Java", kt: "Kotlin", swift: "Swift",
+        c: "C", h: "C", cc: "C++", cpp: "C++", hpp: "C++", cs: "C#", php: "PHP", scala: "Scala",
+        sh: "Shell", bash: "Shell", zsh: "Shell", sql: "SQL", md: "Markdown", mdx: "Markdown",
+        json: "JSON", yaml: "YAML", yml: "YAML", toml: "TOML", html: "HTML", css: "CSS", scss: "CSS",
+        vue: "Vue", svelte: "Svelte", lua: "Lua", ex: "Elixir", exs: "Elixir", dart: "Dart", r: "R",
+    };
+    return map[ext.toLowerCase()] ?? (ext ? ext.toUpperCase() : "Text");
+}

package/dist/walk.js

@@ -0,0 +1,84 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import ignoreImport from "ignore";
+function createIgnorer() {
+    const f = ignoreImport;
+    return typeof f === "function" ? f() : f.default();
+}
+/** Directories never worth indexing (in addition to whatever .gitignore says). */
+const SKIP_DIRS = new Set([
+    ".git", ".hg", ".svn", "node_modules", ".venv", "venv", "__pycache__", ".mypy_cache",
+    ".pytest_cache", "dist", "build", "out", "target", ".next", ".nuxt", ".svelte-kit",
+    ".turbo", ".cache", "coverage", ".idea", ".vscode", ".gradle", "Pods", ".terraform",
+    "vendor", "bin", "obj", ".DS_Store",
+]);
+/** Extensions we treat as indexable source/text. */
+const CODE_EXT = new Set([
+    "ts", "tsx", "js", "jsx", "mjs", "cjs", "py", "rb", "go", "rs", "java", "kt", "kts",
+    "swift", "c", "h", "cc", "cpp", "hpp", "cs", "php", "scala", "sh", "bash", "zsh", "sql",
+    "md", "mdx", "json", "yaml", "yml", "toml", "html", "htm", "css", "scss", "sass", "less",
+    "vue", "svelte", "lua", "ex", "exs", "dart", "r", "pl", "pm", "proto", "graphql", "gql",
+    "tf", "gradle", "groovy", "m", "mm", "clj", "cljs", "edn", "elm", "erl", "hs", "ml", "nim",
+    "txt", "cfg", "ini", "env",
+]);
+export async function discoverFiles(root, cfg) {
+    const rootAbs = path.resolve(root);
+    const ig = createIgnorer();
+    await loadGitignore(ig, rootAbs);
+    const out = [];
+    await walk(rootAbs, rootAbs, ig, cfg, out);
+    out.sort((a, b) => a.rel.localeCompare(b.rel));
+    return out;
+}
+async function loadGitignore(ig, rootAbs) {
+    try {
+        const text = await fs.readFile(path.join(rootAbs, ".gitignore"), "utf8");
+        ig.add(text);
+    }
+    catch {
+        /* no .gitignore — fine */
+    }
+}
+async function walk(dir, rootAbs, ig, cfg, out) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const abs = path.join(dir, entry.name);
+        const rel = toPosix(path.relative(rootAbs, abs));
+        if (!rel || rel.startsWith(".."))
+            continue;
+        if (entry.isSymbolicLink())
+            continue;
+        if (entry.isDirectory()) {
+            if (SKIP_DIRS.has(entry.name))
+                continue;
+            if (ig.ignores(rel + "/"))
+                continue;
+            await walk(abs, rootAbs, ig, cfg, out);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        if (ig.ignores(rel))
+            continue;
+        const ext = path.extname(entry.name).replace(/^\./, "").toLowerCase();
+        // Allow dotfiles like ".env" (no extension but a known name) — otherwise require a known ext.
+        if (!CODE_EXT.has(ext))
+            continue;
+        try {
+            const st = await fs.stat(abs);
+            if (st.size > cfg.maxFileBytes || st.size === 0)
+                continue;
+        }
+        catch {
+            continue;
+        }
+        out.push({ abs, rel });
+    }
+}
+const toPosix = (p) => p.split(path.sep).join("/");

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "embarsy-qdrant-mcp",
+  "version": "0.1.0",
+  "description": "Codebase-indexing MCP server for Embarsy — semantic code search over a local Qdrant + OpenAI-compatible embeddings stack. Routes embeddings and Qdrant through Embarsy's proxy so auth and Monitoring counters just work.",
+  "type": "module",
+  "bin": {
+    "embarsy-index": "dist/bin/index.js",
+    "embarsy-mcp": "dist/bin/mcp.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "embarsy",
+    "mcp",
+    "qdrant",
+    "codebase",
+    "semantic-search",
+    "embeddings",
+    "claude-code",
+    "codex"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "ignore": "^5.3.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.6.2"
+  },
+  "license": "PolyForm-Strict-1.0.0",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}