@henrychong-ai/mcp-neo4j-knowledge-graph 2.4.1 → 2.6.0

package/dist/retrieval/RerankerService.js

@@ -0,0 +1,117 @@
+import axios from 'axios';
+import { logger } from '../utils/logger.js';
+function intEnv(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+/**
+ * Thin client for a cross-encoder reranker (default: Cloudflare Workers AI
+ * `@cf/baai/bge-reranker-base`). OpenAI-style/native HTTP; reuses `axios`.
+ *
+ * The service itself MAY throw (transport/parse errors) — callers are expected
+ * to fail open (return the pre-rerank order). It never enables itself without a
+ * resolved endpoint + API key.
+ */
+export class RerankerService {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    get enabled() {
+        return this.cfg.enabled;
+    }
+    get topN() {
+        return this.cfg.topN;
+    }
+    get topK() {
+        return this.cfg.topK;
+    }
+    get model() {
+        return this.cfg.model;
+    }
+    /**
+     * Build a reranker from environment variables. Returns a DISABLED instance
+     * unless `RERANK_ENABLED=true` AND an endpoint + API key resolve.
+     *
+     * Env: RERANK_ENABLED, RERANK_MODEL (default @cf/baai/bge-reranker-base),
+     * RERANK_ENDPOINT (or derived from RERANK_ACCOUNT_ID/CF_ACCOUNT_ID + model),
+     * RERANK_API_KEY (falls back to EMBEDDING_API_KEY), RERANK_TOP_N (20),
+     * RERANK_TOP_K (10), RERANK_MAX_PASSAGE_CHARS (2000), RERANK_TIMEOUT_MS (5000).
+     */
+    static fromEnv() {
+        const requested = process.env.RERANK_ENABLED === 'true';
+        const model = process.env.RERANK_MODEL || '@cf/baai/bge-reranker-base';
+        const apiKey = process.env.RERANK_API_KEY || process.env.EMBEDDING_API_KEY || '';
+        let endpoint = process.env.RERANK_ENDPOINT || '';
+        const accountId = process.env.RERANK_ACCOUNT_ID || process.env.CF_ACCOUNT_ID;
+        if (!endpoint && accountId) {
+            endpoint = `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/run/${model}`;
+        }
+        const enabled = requested && endpoint.length > 0 && apiKey.length > 0;
+        if (requested && !enabled) {
+            logger.warn('RerankerService: RERANK_ENABLED=true but endpoint or API key could not be resolved — ' +
+                'reranking DISABLED (fail-open). Set RERANK_ENDPOINT (or RERANK_ACCOUNT_ID) and RERANK_API_KEY.');
+        }
+        else if (enabled) {
+            logger.info(`RerankerService: enabled (model ${model})`);
+        }
+        return new RerankerService({
+            enabled,
+            endpoint,
+            model,
+            apiKey,
+            topN: intEnv('RERANK_TOP_N', 20),
+            topK: intEnv('RERANK_TOP_K', 10),
+            maxPassageChars: intEnv('RERANK_MAX_PASSAGE_CHARS', 2000),
+            timeoutMs: intEnv('RERANK_TIMEOUT_MS', 5000),
+        });
+    }
+    /**
+     * Rerank `passages` against `query`. Returns candidate indices reordered
+     * descending by relevance, length <= topK. THROWS on transport/parse error —
+     * the caller fail-opens.
+     *
+     * @param query - Search query
+     * @param passages - Candidate passages (index-aligned with the caller's results)
+     * @returns Indices into `passages`, best-first
+     */
+    async rerank(query, passages) {
+        const contexts = passages
+            .slice(0, this.cfg.topN)
+            .map(text => ({ text: (text || '').slice(0, this.cfg.maxPassageChars) }));
+        const response = await axios.post(this.cfg.endpoint, { query: query.slice(0, this.cfg.maxPassageChars), contexts }, {
+            headers: {
+                Authorization: `Bearer ${this.cfg.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            timeout: this.cfg.timeoutMs,
+        });
+        const ranked = response.data?.result?.response;
+        if (!Array.isArray(ranked)) {
+            throw new Error('Reranker returned a malformed response (missing result.response array)');
+        }
+        // Defensive: keep only integer, in-range, UNIQUE ids (CF returns request-array indices).
+        // Fractional / duplicate / out-of-range ids are dropped so a malformed-but-arrayed response
+        // can't corrupt ordering or duplicate results — the caller still fully fail-opens on a throw.
+        const seen = new Set();
+        const indices = [];
+        for (const row of ranked) {
+            const id = row?.id;
+            if (typeof id === 'number' &&
+                Number.isInteger(id) &&
+                id >= 0 &&
+                id < contexts.length &&
+                !seen.has(id)) {
+                seen.add(id);
+                indices.push(id);
+                if (indices.length >= this.cfg.topK)
+                    break;
+            }
+        }
+        return indices;
+    }
+}
+//# sourceMappingURL=RerankerService.js.map

package/dist/retrieval/RerankerService.js.map

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

package/dist/server/setup.d.ts

@@ -1,4 +1,14 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+/**
+ * Resolve the package version from package.json at runtime — the single source
+ * of truth (no hardcoded literal to drift). Runtime read (not a static JSON
+ * import) because tsconfig rootDir=src excludes package.json from the build;
+ * `../../package.json` resolves identically from src/server/ (dev) and
+ * dist/server/ (published package).
+ *
+ * @returns The package.json version string
+ */
+export declare function getPackageVersion(): string;
 /**
  * Sets up and configures the MCP server with the appropriate request handlers.
  *

package/dist/server/setup.js

@@ -1,7 +1,22 @@
+import { createRequire } from 'node:module';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { handleCallToolRequest } from './handlers/callToolHandler.js';
 import { handleListToolsRequest } from './handlers/listToolsHandler.js';
+const require = createRequire(import.meta.url);
+/**
+ * Resolve the package version from package.json at runtime — the single source
+ * of truth (no hardcoded literal to drift). Runtime read (not a static JSON
+ * import) because tsconfig rootDir=src excludes package.json from the build;
+ * `../../package.json` resolves identically from src/server/ (dev) and
+ * dist/server/ (published package).
+ *
+ * @returns The package.json version string
+ */
+export function getPackageVersion() {
+    const { version } = require('../../package.json');
+    return version;
+}
 /**
  * Sets up and configures the MCP server with the appropriate request handlers.
  *
@@ -13,7 +28,7 @@ export function setupServer(knowledgeGraphManager) {
     // Create server instance
     const server = new Server({
         name: 'mcp-neo4j-knowledge-graph',
-        version: '2.3.2',
+        version: getPackageVersion(),
     }, {
         capabilities: {
             tools: {},

package/dist/server/setup.js.map

@@ -1 +1 @@
-{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/server/setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAEnG,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAExE;;;;;GAKG;AACH,8DAA8D;AAC9D,MAAM,UAAU,WAAW,CAAC,qBAA0B;IACpD,yBAAyB;IACzB,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB;QACE,IAAI,EAAE,2BAA2B;QACjC,OAAO,EAAE,OAAO;KACjB,EACD;QACE,YAAY,EAAE;YACZ,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,EAAE;SACZ;KACF,CACF,CAAC;IAEF,4BAA4B;IAC5B,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,EAAC,QAAQ,EAAC,EAAE;QAChE,OAAO,MAAM,sBAAsB,EAAE,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAC,OAAO,EAAC,EAAE;QAC9D,OAAO,MAAM,qBAAqB,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/server/setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAEnG,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAExE,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/C;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,oBAAoB,CAAwB,CAAC;IACzE,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,8DAA8D;AAC9D,MAAM,UAAU,WAAW,CAAC,qBAA0B;IACpD,yBAAyB;IACzB,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB;QACE,IAAI,EAAE,2BAA2B;QACjC,OAAO,EAAE,iBAAiB,EAAE;KAC7B,EACD;QACE,YAAY,EAAE;YACZ,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,EAAE;SACZ;KACF,CACF,CAAC;IAEF,4BAA4B;IAC5B,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,EAAC,QAAQ,EAAC,EAAE;QAChE,OAAO,MAAM,sBAAsB,EAAE,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAC,OAAO,EAAC,EAAE;QAC9D,OAAO,MAAM,qBAAqB,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/storage/neo4j/Neo4jStorageProvider.d.ts

@@ -237,6 +237,16 @@ export declare class Neo4jStorageProvider implements StorageProvider {
      * @returns Array of entity names that need an embedding job scheduled.
      */
     getEntityNamesMissingEmbeddings(): Promise<string[]>;
+    /**
+     * Guard: reject embedding vectors whose length does not match the configured
+     * vector index dimension (`NEO4J_VECTOR_DIMENSIONS`). A mismatched write —
+     * e.g. a 1536-dim vector into a 1024-dim index — can never be indexed and
+     * silently corrupts semantic search. Throwing turns silent corruption into a
+     * loud failed job. Inert when `vectorDimensions` is unset.
+     *
+     * @param vector The embedding vector about to be persisted
+     */
+    private assertEmbeddingDimension;
     /**
      * Store or update the embedding vector for an entity
      * @param entityName The name of the entity to update

package/dist/storage/neo4j/Neo4jStorageProvider.js

@@ -40,23 +40,38 @@ export class Neo4jStorageProvider {
         this.connectionManager = options?.connectionManager || new Neo4jConnectionManager(this.config);
         // Set up schema manager
         this.schemaManager = new Neo4jSchemaManager(this.connectionManager, this.config, false);
-        // Set up vector store
+        // Set up vector store — dimensions MUST follow the configured index dimension
+        // (was hardcoded 1536, which would create a wrong-sized index on non-1536 deployments)
         this.vectorStore = new Neo4jVectorStore({
             connectionManager: this.connectionManager,
             indexName: this.config.vectorIndexName,
-            dimensions: 1536,
+            dimensions: this.config.vectorDimensions,
             similarityFunction: 'cosine',
             entityNodeLabel: 'Entity',
         });
         logger.debug('Neo4jStorageProvider: Initializing embedding service');
         try {
-            // Set up embedding service
-            this.embeddingService = EmbeddingServiceFactory.createFromEnvironment();
-            logger.debug('Neo4jStorageProvider: Embedding service initialized successfully', {
-                provider: this.embeddingService.getProviderInfo().provider,
-                model: this.embeddingService.getProviderInfo().model,
-                dimensions: this.embeddingService.getProviderInfo().dimensions,
-            });
+            // Set up embedding service — same provider/production gates as index.ts, so the
+            // storage provider's DIRECT write paths (createEntities/createEntitiesBatch)
+            // can never generate random/mock vectors when no real provider is configured.
+            if (!EmbeddingServiceFactory.hasEmbeddingProvider()) {
+                logger.info('Neo4jStorageProvider: no embedding provider configured — entity writes will persist with NULL embeddings');
+            }
+            else {
+                const service = EmbeddingServiceFactory.createFromEnvironment();
+                if (!EmbeddingServiceFactory.shouldWriteEmbeddings(service)) {
+                    logger.error('Neo4jStorageProvider: refusing random/mock embedding service under NODE_ENV=production — ' +
+                        'entity writes will persist with NULL embeddings');
+                }
+                else {
+                    this.embeddingService = service;
+                    logger.debug('Neo4jStorageProvider: Embedding service initialized successfully', {
+                        provider: this.embeddingService.getProviderInfo().provider,
+                        model: this.embeddingService.getProviderInfo().model,
+                        dimensions: this.embeddingService.getProviderInfo().dimensions,
+                    });
+                }
+            }
         }
         catch (error) {
             logger.error('Neo4jStorageProvider: Failed to initialize embedding service', error);
@@ -595,11 +610,15 @@ export class Neo4jStorageProvider {
                                     : '';
                                 // Generate embedding using the instance's embedding service
                                 embedding = await this.embeddingService.generateEmbedding(text);
+                                // Wrong-dimension vectors must never be persisted — throw into the
+                                // catch below so the entity is still created, with embedding=NULL.
+                                this.assertEmbeddingDimension(embedding);
                                 logger.info(`Generated embedding for entity: ${entity.name}`);
                             }
                             catch (error) {
                                 logger.error(`Failed to generate embedding for entity: ${entity.name}`, error);
                                 // Continue without embedding if generation fails
+                                embedding = null;
                             }
                         }
                         else {
@@ -1682,6 +1701,29 @@ export class Neo4jStorageProvider {
       `, {});
         return result.records.map(r => String(r.get('name')));
     }
+    /**
+     * Guard: reject embedding vectors whose length does not match the configured
+     * vector index dimension (`NEO4J_VECTOR_DIMENSIONS`). A mismatched write —
+     * e.g. a 1536-dim vector into a 1024-dim index — can never be indexed and
+     * silently corrupts semantic search. Throwing turns silent corruption into a
+     * loud failed job. Inert when `vectorDimensions` is unset.
+     *
+     * @param vector The embedding vector about to be persisted
+     */
+    assertEmbeddingDimension(vector) {
+        const expected = this.config.vectorDimensions;
+        // Number.isFinite (not truthiness): parseInt of a malformed env value yields
+        // NaN, which is falsy and would otherwise silently disable the guard.
+        if (typeof expected === 'number' &&
+            Number.isFinite(expected) &&
+            expected > 0 &&
+            Array.isArray(vector) &&
+            vector.length !== expected) {
+            throw new Error(`Embedding dimension mismatch: got ${vector.length}, vector index expects ${expected} ` +
+                `(NEO4J_VECTOR_DIMENSIONS). Ensure EMBEDDING_MODEL's native output dimension and ` +
+                `EMBEDDING_DIMENSIONS both match the index — refusing to write a corrupt vector.`);
+        }
+    }
     /**
      * Store or update the embedding vector for an entity
      * @param entityName The name of the entity to update
@@ -1689,6 +1731,7 @@ export class Neo4jStorageProvider {
      */
     async updateEntityEmbedding(entityName, embedding) {
         try {
+            this.assertEmbeddingDimension(embedding.vector);
             // Verify that the entity exists
             const entity = await this.getEntity(entityName);
             if (!entity) {
@@ -2342,9 +2385,13 @@ export class Neo4jStorageProvider {
                                 ? entity.observations.join('\n')
                                 : '';
                             embedding = await this.embeddingService.generateEmbedding(text);
+                            // Same write-path dimension guard as createEntities: a mismatched
+                            // vector throws into the catch and the entity persists with NULL.
+                            this.assertEmbeddingDimension(embedding);
                         }
                         catch (error) {
                             logger.warn(`Failed to generate embedding for entity: ${entity.name}`, error);
+                            embedding = null;
                         }
                     }
                     const now = Date.now();