purecontext-mcp 1.0.1

package/dist/semantic/vector-store.js

@@ -0,0 +1,157 @@
+/**
+ * VectorStore — coordinates embedding generation, HNSW indexing, and SQLite persistence.
+ *
+ * Lifecycle:
+ *   1. `indexSymbols(symbols)` — embed + add to HNSW + persist embeddings to SQLite
+ *   2. `searchSimilar(query, k)` — embed query → HNSW search → return SymbolRecords
+ *   3. `removeSymbols(ids)` — mark deleted in HNSW + delete from SQLite
+ *   4. `rebuild()` — load embeddings from SQLite and reconstruct the HNSW in-memory
+ *
+ * The HNSW index is held in memory. On startup, call `rebuild()` to restore from disk
+ * (SQLite embeddings are faster to reload than re-calling the embedding API).
+ *
+ * Index file: `~/.purecontext/indexes/{repoId}/hnsw.idx`
+ */
+import { join } from 'path';
+import { homedir } from 'os';
+import { PureContextError } from '../core/errors.js';
+import { logger } from '../core/logger.js';
+import { HNSWIndex } from './hnsw-index.js';
+import { prepareSymbolText } from './text-preparation.js';
+import { saveEmbeddings, loadEmbeddings, deleteEmbeddings, deleteAllEmbeddings, } from '../core/db/embedding-store.js';
+// ─── VectorStore ─────────────────────────────────────────────────────────────
+export class VectorStore {
+    repoId;
+    provider;
+    db;
+    indexPath;
+    maxElements;
+    M;
+    efConstruction;
+    efSearch;
+    hnsw;
+    constructor(repoId, provider, db, options = {}) {
+        this.repoId = repoId;
+        this.provider = provider;
+        this.db = db;
+        this.maxElements = options.maxElements ?? 200_000;
+        this.M = options.M ?? 16;
+        this.efConstruction = options.efConstruction ?? 200;
+        this.efSearch = options.efSearch ?? 100;
+        const indexDir = options.indexDir ?? join(homedir(), '.purecontext', 'indexes', repoId);
+        this.indexPath = join(indexDir, 'hnsw.idx');
+        this.hnsw = this.makeIndex();
+    }
+    makeIndex() {
+        return new HNSWIndex(this.provider.dimension, this.maxElements, this.M, this.efConstruction, this.efSearch);
+    }
+    // ─── Indexing ────────────────────────────────────────────────────────────
+    /**
+     * Embed `symbols` and add them to the HNSW index and SQLite embeddings table.
+     * Already-indexed symbols (by ID) are skipped.
+     */
+    async indexSymbols(symbols) {
+        if (symbols.length === 0)
+            return;
+        logger.info('VectorStore: embedding symbols', { repoId: this.repoId, count: symbols.length });
+        // Prepare texts
+        const texts = symbols.map((s) => prepareSymbolText(s, this.provider.maxTokens));
+        // Embed in one call (provider handles internal batching)
+        const vectors = await this.provider.embed(texts);
+        if (vectors.length !== symbols.length) {
+            throw new PureContextError(`VectorStore: provider returned ${vectors.length} vectors for ${symbols.length} symbols`);
+        }
+        // Add to HNSW
+        const ids = symbols.map((s) => s.id);
+        this.hnsw.add(ids, vectors);
+        // Persist to SQLite
+        const embeddingMap = new Map();
+        for (let i = 0; i < symbols.length; i++) {
+            embeddingMap.set(symbols[i].id, vectors[i]);
+        }
+        saveEmbeddings(this.db, this.repoId, this.provider.name, embeddingMap);
+        logger.info('VectorStore: indexed symbols', {
+            repoId: this.repoId,
+            indexed: symbols.length,
+            total: this.hnsw.size(),
+        });
+    }
+    // ─── Search ──────────────────────────────────────────────────────────────
+    /**
+     * Find the `k` most similar symbols to `query` text.
+     * Returns IDs sorted by ascending cosine distance (nearest first).
+     */
+    async searchSimilar(query, k) {
+        if (this.hnsw.size() === 0)
+            return [];
+        const [queryVec] = await this.provider.embed([query]);
+        if (!queryVec)
+            throw new PureContextError('VectorStore: embedding provider returned no vector for query');
+        return this.hnsw.search(queryVec, k);
+    }
+    // ─── Removal ─────────────────────────────────────────────────────────────
+    /**
+     * Remove symbols from the HNSW index and SQLite embeddings.
+     */
+    removeSymbols(ids) {
+        if (ids.length === 0)
+            return;
+        this.hnsw.remove(ids);
+        deleteEmbeddings(this.db, ids);
+        logger.debug('VectorStore: removed symbols', { count: ids.length });
+    }
+    // ─── Rebuild ─────────────────────────────────────────────────────────────
+    /**
+     * Reconstruct the in-memory HNSW index from embeddings stored in SQLite.
+     * Call this on startup instead of re-embedding all symbols.
+     */
+    async rebuild() {
+        logger.info('VectorStore: rebuilding HNSW from SQLite embeddings', { repoId: this.repoId });
+        const embeddings = loadEmbeddings(this.db, this.repoId);
+        if (embeddings.size === 0) {
+            logger.info('VectorStore: no embeddings found, starting fresh', { repoId: this.repoId });
+            return;
+        }
+        this.hnsw = this.makeIndex();
+        const ids = [...embeddings.keys()];
+        const vectors = [...embeddings.values()];
+        this.hnsw.add(ids, vectors);
+        logger.info('VectorStore: rebuilt HNSW', { repoId: this.repoId, size: this.hnsw.size() });
+    }
+    // ─── Persistence ─────────────────────────────────────────────────────────
+    /**
+     * Save the HNSW index to disk.
+     * Call after bulk indexing to avoid rebuilding on next startup.
+     */
+    saveIndex() {
+        this.hnsw.save(this.indexPath);
+    }
+    /**
+     * Load the HNSW index from disk (if it exists).
+     * Faster than `rebuild()` — no SQLite round-trip.
+     */
+    loadIndex() {
+        try {
+            this.hnsw = this.makeIndex();
+            this.hnsw.load(this.indexPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Full re-index: clear all embeddings and rebuild from scratch.
+     */
+    async fullReindex(symbols) {
+        deleteAllEmbeddings(this.db, this.repoId);
+        this.hnsw = this.makeIndex();
+        await this.indexSymbols(symbols);
+    }
+    // ─── Accessors ───────────────────────────────────────────────────────────
+    /** Number of live vectors in the HNSW index. */
+    get size() {
+        return this.hnsw.size();
+    }
+}
+//# sourceMappingURL=vector-store.js.map

package/dist/semantic/vector-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-store.js","sourceRoot":"","sources":["../../src/semantic/vector-store.ts"],"names":[],"mappings":"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"}

package/dist/server/admin-api.d.ts

@@ -0,0 +1,88 @@
+/**
+ * AdminApi — REST endpoints for managing tenants, API keys, and monitoring.
+ *
+ * All /admin/* routes require a valid API key with `admin` permission.
+ * This is enforced by the HTTP server before delegating to AdminApi.handle().
+ *
+ * Routes:
+ *   POST   /admin/tenants              — create tenant
+ *   GET    /admin/tenants              — list tenants
+ *   GET    /admin/tenants/:id          — get tenant
+ *   PATCH  /admin/tenants/:id          — update tenant
+ *   DELETE /admin/tenants/:id          — delete tenant + data
+ *   POST   /admin/tenants/:id/keys     — create API key
+ *   GET    /admin/tenants/:id/keys     — list API keys
+ *   DELETE /admin/keys/:prefix         — revoke API key
+ *   GET    /admin/stats                — global stats
+ *   GET    /admin/tenants/:id/stats    — per-tenant stats
+ */
+import { IncomingMessage, ServerResponse } from 'node:http';
+import Database from 'better-sqlite3';
+import type { AuthResult } from './auth/api-key.js';
+import { type RequestLogEntry } from '../core/db/request-log.js';
+export interface AdminApiOptions {
+    /** Central auth database (shared with TenantStore, ApiKeyStore, RequestLogStore). */
+    db: Database.Database;
+    /** Server start timestamp (epoch ms) — used to compute uptime. */
+    startTime: number;
+    /** Override the repo index directory. Defaults to ~/.purecontext/indexes. */
+    indexDir?: string;
+}
+export declare class AdminApi {
+    private readonly tenantStore;
+    private readonly keyStore;
+    private readonly validator;
+    private readonly logStore;
+    private readonly startTime;
+    private readonly indexDir;
+    constructor(opts: AdminApiOptions);
+    /**
+     * Log a request to the request_log table.
+     * Called by the HTTP server after each MCP tool call.
+     */
+    logRequest(entry: RequestLogEntry): void;
+    /**
+     * Handle an /admin/* request.
+     * Caller is responsible for verifying admin permission before calling this.
+     */
+    handle(req: IncomingMessage, res: ServerResponse, _authResult: AuthResult): Promise<void>;
+    private dispatch;
+    private createTenant;
+    private listTenants;
+    private getTenant;
+    private updateTenant;
+    private deleteTenant;
+    private deleteTenantRepoDatabases;
+    private createKey;
+    private listKeys;
+    private revokeKey;
+    private globalStats;
+    private tenantStats;
+    /**
+     * POST /admin/keys
+     * Create a new API key. Body: { tenant_id?, label?, permissions?, rate_limit_tier?, is_test? }
+     * When tenant_id is omitted, creates or reuses a 'default' tenant.
+     */
+    private createKeyFlat;
+    /**
+     * GET /admin/keys
+     * List all API keys across all tenants (hashes only — never raw values).
+     */
+    private listKeysFlat;
+    /**
+     * GET /admin/keys/:id
+     * GET /admin/keys/:id/usage
+     * Returns last_used_at and request count for a key, identified by its hash prefix.
+     */
+    private keyUsage;
+    private createWorkspace;
+    private listWorkspaces;
+    private getWorkspace;
+    private updateWorkspace;
+    private addWorkspaceMember;
+    private listWorkspaceMembers;
+    private removeWorkspaceMember;
+    private workspaceUsage;
+    private countRepoFiles;
+}
+//# sourceMappingURL=admin-api.d.ts.map

package/dist/server/admin-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-api.d.ts","sourceRoot":"","sources":["../../src/server/admin-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG5D,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,mBAAmB,CAAC;AAIhE,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAUlF,MAAM,WAAW,eAAe;IAC9B,qFAAqF;IACrF,EAAE,EAAE,QAAQ,CAAC,QAAQ,CAAC;IACtB,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAyLD,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,IAAI,EAAE,eAAe;IASjC;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAIxC;;;OAGG;IACG,MAAM,CACV,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,WAAW,EAAE,UAAU,GACtB,OAAO,CAAC,IAAI,CAAC;YAuBF,QAAQ;YAqCR,YAAY;IA2B1B,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,SAAS;YASH,YAAY;IAkC1B,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,yBAAyB;YA6BnB,SAAS;IAwCvB,OAAO,CAAC,QAAQ;IAWhB,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,WAAW;IAiBnB,OAAO,CAAC,WAAW;IAqBnB;;;;OAIG;YACW,aAAa;IA2C3B;;;OAGG;IACH,OAAO,CAAC,YAAY;IAepB;;;;OAIG;IACH,OAAO,CAAC,QAAQ;YA2BF,eAAe;IAuB7B,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,YAAY;YASN,eAAe;YA4Bf,kBAAkB;IA6BhC,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,cAAc;IAoBtB,OAAO,CAAC,cAAc;CAQvB"}