code-graph-context 2.13.3 → 2.14.0

package/README.md

@@ -162,7 +162,7 @@ If you prefer to edit the config files directly:
     "code-graph-context": {
       "command": "code-graph-context",
       "env": {
-        "OPENAI_ENABLED": "true",
+        "OPENAI_EMBEDDINGS_ENABLED": "true",
         "OPENAI_API_KEY": "sk-your-key-here"
       }
     }
@@ -194,8 +194,8 @@ If you prefer to edit the config files directly:
 | `EMBEDDING_SIDECAR_PORT` | No | `8787` | Port for local embedding server |
 | `EMBEDDING_DEVICE` | No | auto (`mps`/`cpu`) | Device for embeddings. Auto-detects MPS on Apple Silicon |
 | `EMBEDDING_HALF_PRECISION` | No | `false` | Set `true` for float16 (uses ~0.5x memory) |
-| `OPENAI_ENABLED` | No | `false` | Set `true` to use OpenAI instead of local |
-| `OPENAI_API_KEY` | No* | - | Required when `OPENAI_ENABLED=true` |
+| `OPENAI_EMBEDDINGS_ENABLED` | No | `false` | Set `true` to use OpenAI instead of local embeddings |
+| `OPENAI_API_KEY` | No* | - | Required when `OPENAI_EMBEDDINGS_ENABLED=true`; also enables `natural_language_to_cypher` |
 
 ---
 
@@ -582,7 +582,7 @@ If you prefer OpenAI embeddings (higher quality, requires API key):
 
 ```bash
 claude mcp add --scope user code-graph-context \
-  -e OPENAI_ENABLED=true \
+  -e OPENAI_EMBEDDINGS_ENABLED=true \
   -e OPENAI_API_KEY=sk-your-key-here \
   -- code-graph-context
 ```
@@ -626,7 +626,7 @@ claude mcp add --scope user code-graph-context \
 ```bash
 claude mcp remove code-graph-context
 claude mcp add --scope user code-graph-context \
-  -e OPENAI_ENABLED=true \
+  -e OPENAI_EMBEDDINGS_ENABLED=true \
   -e OPENAI_API_KEY=sk-your-key-here \
   -- code-graph-context
 ```

package/dist/cli/cli.js

@@ -82,7 +82,7 @@ ${c.bold}Next steps:${c.reset}
 
      ${c.dim}Local embeddings are used by default (no API key needed).
      To use OpenAI instead, add:
-       "OPENAI_ENABLED": "true",
+       "OPENAI_EMBEDDINGS_ENABLED": "true",
        "OPENAI_API_KEY": "sk-..."${c.reset}
 
   3. Restart Claude Code
@@ -199,7 +199,7 @@ const setupSidecar = async () => {
     if (!pythonVersion) {
         log(sym.err, 'Python 3 is not installed');
         console.log(`\n  Install Python 3.10+: ${c.cyan}https://www.python.org/downloads/${c.reset}`);
-        console.log(`  ${c.dim}Or use OpenAI embeddings instead: set OPENAI_ENABLED=true${c.reset}\n`);
+        console.log(`  ${c.dim}Or use OpenAI embeddings instead: set OPENAI_EMBEDDINGS_ENABLED=true${c.reset}\n`);
         return;
     }
     log(sym.ok, `${pythonVersion}`);
@@ -250,7 +250,7 @@ const setupSidecar = async () => {
     verifySpinner.stop(verified, verified ? 'sentence-transformers OK' : 'sentence-transformers import failed');
     if (!verified) {
         console.log(`\n  ${c.dim}Try: ${python} -c "from sentence_transformers import SentenceTransformer"${c.reset}`);
-        console.log(`  ${c.dim}Or use OpenAI embeddings instead: set OPENAI_ENABLED=true${c.reset}\n`);
+        console.log(`  ${c.dim}Or use OpenAI embeddings instead: set OPENAI_EMBEDDINGS_ENABLED=true${c.reset}\n`);
         return;
     }
     // Pre-download the embedding model so first real use is fast

package/dist/core/embeddings/embedding-sidecar.js

@@ -160,7 +160,7 @@ export class EmbeddingSidecar {
                 reject(new Error('python3 not found. Local embeddings require Python 3.10+.\n\n' +
                     'Install Python and the sidecar dependencies:\n' +
                     '  pip install -r sidecar/requirements.txt\n\n' +
-                    'Or set OPENAI_ENABLED=true to use OpenAI instead.'));
+                    'Or set OPENAI_EMBEDDINGS_ENABLED=true to use OpenAI instead.'));
             });
             check.on('close', (code) => {
                 if (code !== 0) {

package/dist/core/embeddings/embeddings.service.js

@@ -2,10 +2,10 @@
  * Embeddings Service — barrel module
  *
  * Exports a common interface and a factory. Consumers do `new EmbeddingsService()`
- * and get the right implementation based on OPENAI_ENABLED.
+ * and get the right implementation based on OPENAI_EMBEDDINGS_ENABLED.
  *
- *   OPENAI_ENABLED=true  → OpenAI text-embedding-3-large (requires OPENAI_API_KEY)
- *   default              → Local Python sidecar with Qwen3-Embedding-0.6B
+ *   OPENAI_EMBEDDINGS_ENABLED=true  → OpenAI text-embedding-3-large (requires OPENAI_API_KEY)
+ *   default                         → Local Python sidecar with Qwen3-Embedding-0.6B
  */
 import { LocalEmbeddingsService } from './local-embeddings.service.js';
 import { OpenAIEmbeddingsService } from './openai-embeddings.service.js';
@@ -33,8 +33,21 @@ export const EMBEDDING_DIMENSIONS = {
     'nomic-ai/nomic-embed-text-v1.5': 768,
 };
 export const isOpenAIEnabled = () => {
-    return process.env.OPENAI_ENABLED?.toLowerCase() === 'true';
+    if (process.env.OPENAI_EMBEDDINGS_ENABLED?.toLowerCase() === 'true') {
+        return true;
+    }
+    // Backward-compat: OPENAI_ENABLED is deprecated in favour of OPENAI_EMBEDDINGS_ENABLED
+    if (process.env.OPENAI_ENABLED?.toLowerCase() === 'true') {
+        console.error(JSON.stringify({
+            level: 'warn',
+            message: '[code-graph-context] OPENAI_ENABLED is deprecated. Use OPENAI_EMBEDDINGS_ENABLED=true instead.',
+        }));
+        return true;
+    }
+    return false;
 };
+/** Returns true when OPENAI_API_KEY is present, regardless of embedding provider. */
+export const isOpenAIAvailable = () => !!process.env.OPENAI_API_KEY;
 /**
  * Get the vector dimensions for the active embedding provider.
  * For known models, returns a static value. For unknown local models,
@@ -50,7 +63,7 @@ export const getEmbeddingDimensions = () => {
     return EMBEDDING_DIMENSIONS[model] ?? 1536;
 };
 /**
- * Factory that returns the correct service based on OPENAI_ENABLED.
+ * Factory that returns the correct service based on OPENAI_EMBEDDINGS_ENABLED.
  * Drop-in replacement everywhere `new EmbeddingsService()` was used.
  */
 export class EmbeddingsService {

package/dist/core/embeddings/natural-language-to-cypher.service.js

@@ -10,22 +10,23 @@ export class NaturalLanguageToCypherService {
     messageInstructions = `
 === THE SCHEMA FILE IS THE SOURCE OF TRUTH ===
 ALWAYS read neo4j-apoc-schema.json FIRST before generating any query. It contains:
-1. rawSchema: All node labels (keys), their properties, and relationships from Neo4j APOC
-2. discoveredSchema (if available): Dynamically discovered nodeTypes, relationshipTypes, semanticTypes, commonPatterns
+- nodeTypes: All node labels with counts and property keys
+- relationshipTypes: All relationship types with counts and connection patterns (from → to)
+- semanticTypes: Framework-specific classifications with which label they appear on
+- commonPatterns: Relationship patterns between node types with counts
 
-=== LABEL TYPES - TWO CATEGORIES ===
-Check rawSchema keys for ALL valid labels. Labels fall into two categories:
+=== VALID NODE LABELS ===
+Use ONLY labels found in nodeTypes[].label. Labels fall into two categories:
 
 1. CORE LABELS (base TypeScript AST):
    SourceFile, Class, Function, Method, Interface, Property, Parameter, Constructor, Import, Export, Decorator, Enum, Variable, TypeAlias
 
-2. FRAMEWORK LABELS (from framework enhancements - check rawSchema keys):
-   These REPLACE the core label for enhanced nodes. Check rawSchema keys for available framework labels in this project.
-   A node with a framework label was originally a Class but got enhanced - always use the actual label from rawSchema.
+2. FRAMEWORK LABELS (from framework enhancements - check nodeTypes):
+   These REPLACE the core label for enhanced nodes. A node with a framework label was originally a Class but got enhanced.
 
 === AST TYPE NAME MAPPING ===
 AST type names are NOT valid labels. Always map them:
-- ClassDeclaration → Class (or a framework label from rawSchema if enhanced)
+- ClassDeclaration → Class (or a framework label if enhanced)
 - FunctionDeclaration → Function
 - MethodDeclaration → Method
 - InterfaceDeclaration → Interface
@@ -35,8 +36,7 @@ AST type names are NOT valid labels. Always map them:
 === FINDING SPECIFIC NODES ===
 Class/entity names are property values, NOT labels:
 WRONG: (n:MyClassName) - using class names as labels
-CORRECT: (n:Class {name: 'MyClassName'}) - use label from rawSchema, name as property
-CORRECT: (n:LabelFromSchema {name: 'EntityName'}) - always check rawSchema for valid labels
+CORRECT: (n:Class {name: 'MyClassName'}) - use label from nodeTypes, name as property
 
 Examples:
 - "Count all classes" -> MATCH (n:Class) WHERE n.projectId = $projectId RETURN count(n)
@@ -58,22 +58,19 @@ Do NOT include projectId in parameters - it's injected automatically.
 
 Query Generation Process - FOLLOW THIS EXACTLY:
 1. SEARCH THE SCHEMA FILE FIRST: Use file_search to read neo4j-apoc-schema.json BEFORE generating any query
-2. EXTRACT VALID LABELS: The keys in rawSchema ARE the valid labels (e.g., "Class", "Method", "Function", etc.)
-   - rawSchema is ALWAYS available and contains all labels currently in the graph
-   - discoveredSchema.nodeTypes (if available) provides counts and sample properties
-3. CHECK RELATIONSHIPS: Look at rawSchema[label].relationships for each label to see available relationship types
-4. CHECK SEMANTIC TYPES: Look at discoveredSchema.semanticTypes (if available) for framework-specific classifications
-   - semanticTypes are PROPERTY values stored in n.semanticType, NOT labels - check discoveredSchema for valid values
-5. REVIEW PATTERNS: Check discoveredSchema.commonPatterns (if available) for frequent relationship patterns
-6. EXAMINE PROPERTIES: Use rawSchema[label].properties for exact property names and types
-7. GENERATE QUERY: Write the Cypher query using ONLY labels, relationships, and properties from the schema
-8. VALIDATE LABELS: Double-check that every label in your query exists as a key in rawSchema
-9. ADD PROJECT FILTER: Always include WHERE n.projectId = $projectId for every node pattern in the query
+2. EXTRACT VALID LABELS: nodeTypes[].label contains all valid labels. nodeTypes[].properties lists available property keys per label.
+3. CHECK RELATIONSHIPS: relationshipTypes[].type lists all relationship types. Each entry includes connections[] showing which node types they connect (from → to).
+4. CHECK SEMANTIC TYPES: semanticTypes[].type lists framework classifications. Each entry includes label showing which node type it appears on.
+   - semanticTypes are PROPERTY values stored in n.semanticType, NOT labels
+5. REVIEW PATTERNS: commonPatterns[] shows from→relationship→to triples with counts
+6. GENERATE QUERY: Write the Cypher query using ONLY labels, relationships, and properties from the schema
+7. VALIDATE LABELS: Double-check that every label in your query exists in nodeTypes
+8. ADD PROJECT FILTER: Always include WHERE n.projectId = $projectId for every node pattern in the query
 
 Critical Rules:
 - ALWAYS filter by projectId on every node in the query (e.g., WHERE n.projectId = $projectId)
 - Use the schema information from the file_search tool - do not guess node labels or relationships
-- Use ONLY node labels and properties found in the schema
+- Use ONLY node labels and relationships found in the schema
 - For nested JSON data in properties, use: apoc.convert.fromJsonMap(node.propertyName)
 - Use parameterized queries with $ syntax for any dynamic values
 - Return only the data relevant to the user's request
@@ -90,9 +87,9 @@ Critical Rules:
 - DECORATED_WITH: Node has a Decorator (use for "decorated with", "has decorator", "@SomeDecorator")
 
 === FRAMEWORK RELATIONSHIPS ===
-Framework-specific relationships are defined in rawSchema. Check rawSchema[label].relationships for each label to discover:
+Check relationshipTypes and commonPatterns in the schema file for framework-specific relationships:
 - What relationship types exist (e.g., INJECTS, EXPOSES, MODULE_IMPORTS, INTERNAL_API_CALL, etc.)
-- Direction (in/out) and target labels for each relationship
+- commonPatterns shows which node types they connect and how frequently
 - These vary by project - ALWAYS check the schema file for available relationships
 
 CRITICAL: Do NOT confuse EXTENDS (inheritance) with HAS_MEMBER (composition). "extends" always means EXTENDS relationship.
@@ -105,31 +102,18 @@ The arrow points FROM child TO parent. The child "extends" toward the parent.
 Examples:
 - "Classes extending X" -> MATCH (c:Class)-[:EXTENDS]->(p:Class {name: 'X'}) WHERE c.projectId = $projectId RETURN c
 - "What extends Y" -> MATCH (c:Class)-[:EXTENDS]->(p:Class {name: 'Y'}) WHERE c.projectId = $projectId RETURN c
-- "Classes that extend X with >5 methods" ->
-  MATCH (c:Class)-[:EXTENDS]->(p:Class {name: 'X'})
-  WHERE c.projectId = $projectId
-  WITH c
-  MATCH (c)-[:HAS_MEMBER]->(m:Method)
-  WITH c, count(m) AS methodCount
-  WHERE methodCount > 5
-  RETURN c, methodCount
 
 === SEMANTIC TYPES (Framework Classifications) - PRIMARY QUERY METHOD ===
-*** MOST QUERIES SHOULD USE SEMANTIC TYPES - CHECK discoveredSchema.semanticTypes FIRST ***
+*** MOST QUERIES SHOULD USE SEMANTIC TYPES - CHECK semanticTypes FIRST ***
 
-Semantic types are the PRIMARY way to find framework-specific nodes. They are stored in:
-  discoveredSchema.semanticTypes -> Array of all semantic type values in this project
+Semantic types are the PRIMARY way to find framework-specific nodes:
+  semanticTypes[].type -> semantic type value
+  semanticTypes[].label -> which node label this type appears on
 
 The semanticType is a PROPERTY on nodes, not a label. Query patterns:
 - EXACT MATCH: MATCH (c) WHERE c.projectId = $projectId AND c.semanticType = 'ExactTypeFromSchema' RETURN c
 - PARTIAL MATCH: MATCH (c) WHERE c.projectId = $projectId AND c.semanticType CONTAINS 'Pattern' RETURN c
 
-Common semantic type patterns (verify against discoveredSchema.semanticTypes):
-- Controllers: types containing 'Controller'
-- Services: types containing 'Service', 'Provider', or 'Injectable'
-- Repositories: types containing 'Repository', 'DAL', or 'DAO'
-- Modules: types containing 'Module'
-
 FALLBACK - If semantic type doesn't exist, use name patterns:
 - "Find all controllers" -> MATCH (c:Class) WHERE c.projectId = $projectId AND c.name CONTAINS 'Controller' RETURN c
 - "Find all services" -> MATCH (c:Class) WHERE c.projectId = $projectId AND c.name CONTAINS 'Service' RETURN c
@@ -144,37 +128,25 @@ Use filePath property for location-based queries:
 - "in account module" -> WHERE n.filePath CONTAINS '/account/'
 - "in auth folder" -> WHERE n.filePath CONTAINS '/auth/'
 
-Examples:
-- "Items in account folder" ->
-  MATCH (c:Class) WHERE c.projectId = $projectId AND c.filePath CONTAINS '/account/' RETURN c
-- FALLBACK (if no framework labels):
-  MATCH (c:Class) WHERE c.projectId = $projectId AND c.name CONTAINS 'Service' AND c.filePath CONTAINS '/account/' RETURN c
-
 === FRAMEWORK-SPECIFIC PATTERNS ===
 
 Backend Projects (decorator-based frameworks):
-- Check rawSchema for framework labels that REPLACE the Class label
-- Use framework relationships (INJECTS, EXPOSES, etc.) from rawSchema[label].relationships
-- Check discoveredSchema.semanticTypes for framework classifications
+- Check nodeTypes for framework labels that REPLACE the Class label
+- Use framework relationships from relationshipTypes and commonPatterns
+- Check semanticTypes for framework classifications
 
 Frontend Projects (React, functional):
 - React components are typically Function nodes, NOT Class nodes
 - Hooks are Function nodes (useAuth, useState, etc.)
 - Example: "Find UserProfile component" -> MATCH (f:Function {name: 'UserProfile'}) WHERE f.projectId = $projectId RETURN f
 
-Tip: Check rawSchema keys to understand if project uses framework labels or just core TypeScript labels.
-
 IMPORTANT - Cypher Syntax (NOT SQL):
 - Cypher does NOT use GROUP BY. Aggregation happens automatically in RETURN.
 - WRONG (SQL): RETURN label, count(n) GROUP BY label
 - CORRECT (Cypher): RETURN labels(n) AS label, count(n) AS count
-- For grouping, non-aggregated values in RETURN automatically become grouping keys
 - Use labels(n) to get node labels as an array
 - Use collect() for aggregating into lists
 - Use count(), sum(), avg(), min(), max() for aggregations
-- Common patterns:
-  - Count by type: MATCH (n) RETURN labels(n)[0] AS type, count(n) AS count
-  - Group with collect: MATCH (n)-[:REL]->(m) RETURN n.name, collect(m.name) AS related
 
 Provide ONLY the JSON response with no additional text, markdown formatting, or explanations outside the JSON structure.
 `;
@@ -252,20 +224,19 @@ Provide ONLY the JSON response with no additional text, markdown formatting, or
         try {
             const content = fs.readFileSync(this.schemaPath, 'utf-8');
             const schema = JSON.parse(content);
-            if (!schema.discoveredSchema) {
-                return 'No discovered schema available.';
+            if (!schema || !schema.nodeTypes) {
+                return 'No schema available.';
             }
-            const ds = schema.discoveredSchema;
             // Format node types
-            const nodeTypes = ds.nodeTypes?.map((n) => n.label).join(', ') ?? 'none';
+            const nodeTypes = schema.nodeTypes?.map((n) => n.label).join(', ') ?? 'none';
             // Get function count vs class count to hint at framework
-            const functionCount = ds.nodeTypes?.find((n) => n.label === 'Function')?.count ?? 0;
-            const classCount = ds.nodeTypes?.find((n) => n.label === 'Class')?.count ?? 0;
-            const decoratorCount = ds.nodeTypes?.find((n) => n.label === 'Decorator')?.count ?? 0;
+            const functionCount = schema.nodeTypes?.find((n) => n.label === 'Function')?.count ?? 0;
+            const classCount = schema.nodeTypes?.find((n) => n.label === 'Class')?.count ?? 0;
+            const decoratorCount = schema.nodeTypes?.find((n) => n.label === 'Decorator')?.count ?? 0;
             // Format relationship types
-            const relTypes = ds.relationshipTypes?.map((r) => r.type).join(', ') ?? 'none';
+            const relTypes = schema.relationshipTypes?.map((r) => r.type).join(', ') ?? 'none';
             // Format semantic types and categorize them
-            const semanticTypeList = ds.semanticTypes?.map((s) => s.type) ?? [];
+            const semanticTypeList = schema.semanticTypes?.map((s) => s.type) ?? [];
             const semTypes = semanticTypeList.length > 0 ? semanticTypeList.join(', ') : 'none';
             // Cache categorized semantic types for dynamic example generation
             this.cachedSemanticTypes = this.categorizeSemanticTypes(semanticTypeList);
@@ -521,7 +492,7 @@ Remember to include WHERE n.projectId = $projectId for all node patterns.
     }
     /**
      * Load valid labels dynamically from the schema file.
-     * Returns all keys from rawSchema AND discoveredSchema.nodeTypes which represent actual Neo4j labels.
+     * Returns all labels from nodeTypes in the discovered schema.
      */
     loadValidLabelsFromSchema() {
         // Fallback to core TypeScript labels if schema not available
@@ -550,14 +521,8 @@ Remember to include WHERE n.projectId = $projectId for all node patterns.
             const content = fs.readFileSync(this.schemaPath, 'utf-8');
             const schema = JSON.parse(content);
             const allLabels = new Set(coreLabels);
-            // Extract labels from rawSchema keys
-            if (schema.rawSchema?.records?.[0]?._fields?.[0]) {
-                const schemaLabels = Object.keys(schema.rawSchema.records[0]._fields[0]);
-                schemaLabels.forEach((label) => allLabels.add(label));
-            }
-            // Also extract labels from discoveredSchema.nodeTypes (includes framework labels)
-            if (schema.discoveredSchema?.nodeTypes) {
-                for (const nodeType of schema.discoveredSchema.nodeTypes) {
+            if (schema?.nodeTypes) {
+                for (const nodeType of schema.nodeTypes) {
                     if (nodeType.label) {
                         allLabels.add(nodeType.label);
                     }

package/dist/core/embeddings/openai-embeddings.service.js

@@ -1,7 +1,7 @@
 /**
  * OpenAI Embeddings Service
  * Uses OpenAI's text-embedding API. Requires OPENAI_API_KEY.
- * Opt-in via OPENAI_ENABLED=true.
+ * Opt-in via OPENAI_EMBEDDINGS_ENABLED=true.
  */
 import OpenAI from 'openai';
 import { debugLog } from '../../mcp/utils.js';

package/dist/core/utils/file-utils.js

@@ -6,9 +6,23 @@ export const hashFile = async (filePath) => {
     const content = await fs.readFile(filePath);
     return crypto.createHash('sha256').update(content).digest('hex');
 };
+const serializeForLog = (data) => {
+    if (data instanceof Error) {
+        return { name: data.name, message: data.message, stack: data.stack };
+    }
+    if (data !== null && typeof data === 'object') {
+        const result = {};
+        for (const key of Object.keys(data)) {
+            result[key] = serializeForLog(data[key]);
+        }
+        return result;
+    }
+    return data;
+};
 export const debugLog = async (message, data) => {
     const timestamp = new Date().toISOString();
-    const logEntry = `[${timestamp}] ${message}\n${data ? JSON.stringify(data, null, LOG_CONFIG.jsonIndent) : ''}\n${LOG_CONFIG.separator}\n`;
+    const serialized = data !== undefined ? serializeForLog(data) : undefined;
+    const logEntry = `[${timestamp}] ${message}\n${serialized !== undefined ? JSON.stringify(serialized, null, LOG_CONFIG.jsonIndent) : ''}\n${LOG_CONFIG.separator}\n`;
     try {
         await fs.appendFile(path.join(process.cwd(), LOG_CONFIG.debugLogFile), logEntry);
     }

package/dist/mcp/constants.js

@@ -418,7 +418,7 @@ export const WATCH = {
 export const MESSAGES = {
     errors: {
         noRelevantCode: 'No relevant code found.',
-        serviceNotInitialized: 'ERROR: Natural Language to Cypher service is not initialized yet. Please try again in a few moments.',
+        serviceNotInitialized: 'natural_language_to_cypher requires OPENAI_API_KEY. Set it and restart the MCP server to enable this tool.',
         connectionTestFailed: 'Connection test failed',
         neo4jRequirement: 'Note: This server requires Neo4j with APOC plugin installed',
         genericError: 'ERROR:',

package/dist/mcp/service-init.js

@@ -5,7 +5,8 @@
 import fs from 'fs/promises';
 import { join } from 'path';
 import { ensureNeo4jRunning, isDockerInstalled, isDockerRunning } from '../cli/neo4j-docker.js';
-import { isOpenAIEnabled, getEmbeddingDimensions } from '../core/embeddings/embeddings.service.js';
+import { isOpenAIEnabled, isOpenAIAvailable, getEmbeddingDimensions } from '../core/embeddings/embeddings.service.js';
+import { LIST_PROJECTS_QUERY } from '../core/utils/project-id.js';
 import { Neo4jService, QUERIES } from '../storage/neo4j/neo4j.service.js';
 import { FILE_PATHS, LOG_CONFIG } from './constants.js';
 import { initializeNaturalLanguageService } from './tools/natural-language-to-cypher.tool.js';
@@ -22,24 +23,24 @@ const checkConfiguration = async () => {
         message: `[code-graph-context] Embedding provider: ${provider} (${dims} dimensions)`,
     }));
     await debugLog('Embedding configuration', { provider, dimensions: dims });
-    if (openai && !process.env.OPENAI_API_KEY) {
+    if (openai && !isOpenAIAvailable()) {
         console.error(JSON.stringify({
             level: 'warn',
-            message: '[code-graph-context] OPENAI_ENABLED=true but OPENAI_API_KEY not set. Embedding calls will fail.',
+            message: '[code-graph-context] OPENAI_EMBEDDINGS_ENABLED=true but OPENAI_API_KEY not set. Embedding calls will fail.',
         }));
-        await debugLog('Configuration warning', { warning: 'OPENAI_ENABLED=true but OPENAI_API_KEY not set' });
+        await debugLog('Configuration warning', { warning: 'OPENAI_EMBEDDINGS_ENABLED=true but OPENAI_API_KEY not set' });
     }
     if (!openai) {
         console.error(JSON.stringify({
             level: 'info',
             message: '[code-graph-context] Using local embeddings (Python sidecar). Starts on first embedding request.',
         }));
-        if (!process.env.OPENAI_API_KEY) {
-            console.error(JSON.stringify({
-                level: 'info',
-                message: '[code-graph-context] natural_language_to_cypher requires OPENAI_API_KEY and is unavailable.',
-            }));
-        }
+    }
+    if (!isOpenAIAvailable()) {
+        console.error(JSON.stringify({
+            level: 'info',
+            message: '[code-graph-context] natural_language_to_cypher unavailable: OPENAI_API_KEY not set.',
+        }));
     }
 };
 /**
@@ -87,26 +88,34 @@ export const initializeServices = async () => {
     await ensureNeo4j();
     // Initialize services sequentially - schema must be written before NL service reads it
     await initializeNeo4jSchema();
-    await initializeNaturalLanguageService();
+    if (isOpenAIAvailable()) {
+        await initializeNaturalLanguageService();
+    }
+    else {
+        console.error(JSON.stringify({
+            level: 'info',
+            message: '[code-graph-context] natural_language_to_cypher unavailable: OPENAI_API_KEY not set',
+        }));
+    }
 };
 /**
  * Dynamically discover schema from the actual graph contents.
  * This is framework-agnostic - it discovers what's actually in the graph.
  */
-const discoverSchemaFromGraph = async (neo4jService) => {
+const discoverSchemaFromGraph = async (neo4jService, projectId) => {
     try {
         // Discover actual node types, relationships, and patterns from the graph
         const [nodeTypes, relationshipTypes, semanticTypes, commonPatterns] = await Promise.all([
-            neo4jService.run(QUERIES.DISCOVER_NODE_TYPES),
-            neo4jService.run(QUERIES.DISCOVER_RELATIONSHIP_TYPES),
-            neo4jService.run(QUERIES.DISCOVER_SEMANTIC_TYPES),
-            neo4jService.run(QUERIES.DISCOVER_COMMON_PATTERNS),
+            neo4jService.run(QUERIES.DISCOVER_NODE_TYPES, { projectId }),
+            neo4jService.run(QUERIES.DISCOVER_RELATIONSHIP_TYPES, { projectId }),
+            neo4jService.run(QUERIES.DISCOVER_SEMANTIC_TYPES, { projectId }),
+            neo4jService.run(QUERIES.DISCOVER_COMMON_PATTERNS, { projectId }),
         ]);
         return {
             nodeTypes: nodeTypes.map((r) => ({
                 label: r.label,
                 count: typeof r.nodeCount === 'object' ? r.nodeCount.toNumber() : r.nodeCount,
-                properties: r.sampleProperties ?? [],
+                properties: r.properties ?? [],
             })),
             relationshipTypes: relationshipTypes.map((r) => ({
                 type: r.relationshipType,
@@ -115,6 +124,7 @@ const discoverSchemaFromGraph = async (neo4jService) => {
             })),
             semanticTypes: semanticTypes.map((r) => ({
                 type: r.semanticType,
+                label: r.nodeLabel,
                 count: typeof r.count === 'object' ? r.count.toNumber() : r.count,
             })),
             commonPatterns: commonPatterns.map((r) => ({
@@ -136,13 +146,11 @@ const discoverSchemaFromGraph = async (neo4jService) => {
 const initializeNeo4jSchema = async () => {
     try {
         const neo4jService = new Neo4jService();
-        const rawSchema = await neo4jService.getSchema();
+        // Find the most recently updated project to scope discovery queries
+        const projects = await neo4jService.run(LIST_PROJECTS_QUERY, {});
+        const projectId = projects.length > 0 ? projects[0].projectId : null;
         // Dynamically discover what's actually in the graph
-        const discoveredSchema = await discoverSchemaFromGraph(neo4jService);
-        const schema = {
-            rawSchema,
-            discoveredSchema,
-        };
+        const schema = projectId ? await discoverSchemaFromGraph(neo4jService, projectId) : null;
         const schemaPath = join(process.cwd(), FILE_PATHS.schemaOutput);
         await fs.writeFile(schemaPath, JSON.stringify(schema, null, LOG_CONFIG.jsonIndentation));
         await debugLog('Neo4j schema cached successfully', { schemaPath });

package/dist/mcp/tools/natural-language-to-cypher.tool.js

@@ -6,7 +6,7 @@ import { join } from 'path';
 import { z } from 'zod';
 import { NaturalLanguageToCypherService } from '../../core/embeddings/natural-language-to-cypher.service.js';
 import { Neo4jService } from '../../storage/neo4j/neo4j.service.js';
-import { TOOL_NAMES, TOOL_METADATA, MESSAGES, FILE_PATHS } from '../constants.js';
+import { TOOL_NAMES, TOOL_METADATA, FILE_PATHS } from '../constants.js';
 import { createErrorResponse, createSuccessResponse, formatQueryResults, debugLog, resolveProjectIdOrError, } from '../utils.js';
 // Service instance - initialized asynchronously
 let naturalLanguageToCypherService = null;
@@ -45,7 +45,7 @@ export const createNaturalLanguageToCypherTool = (server) => {
             const resolvedProjectId = projectResult.projectId;
             if (!naturalLanguageToCypherService) {
                 await debugLog('Natural language service not available', { projectId: resolvedProjectId, query });
-                return createSuccessResponse(MESSAGES.errors.serviceNotInitialized);
+                return createSuccessResponse('natural_language_to_cypher requires OPENAI_API_KEY. Set it and restart the MCP server to enable this tool.');
             }
             const cypherResult = await naturalLanguageToCypherService.promptToQuery(query, resolvedProjectId);
             // Validate Cypher syntax using EXPLAIN (no execution, just parse)

package/dist/storage/neo4j/neo4j.service.js

@@ -48,29 +48,6 @@ export class Neo4jService {
     getDriver() {
         return this.driver;
     }
-    async getSchema() {
-        const session = this.driver.session();
-        const timeoutConfig = getTimeoutConfig();
-        try {
-            return await session.run(QUERIES.APOC_SCHEMA, {}, {
-                timeout: timeoutConfig.neo4j.queryTimeoutMs,
-            });
-        }
-        catch (error) {
-            console.error('Error fetching schema:', error);
-            throw error;
-        }
-        finally {
-            // Wrap session close in try-catch to avoid masking the original error
-            try {
-                await session.close();
-            }
-            catch (closeError) {
-                // Log but don't re-throw to preserve original error
-                console.warn('Error closing Neo4j session:', closeError);
-            }
-        }
-    }
     /**
      * Close the Neo4j driver connection.
      * Should be called when the service is no longer needed to release resources.
@@ -82,10 +59,6 @@ export class Neo4jService {
     }
 }
 export const QUERIES = {
-    APOC_SCHEMA: `
-    CALL apoc.meta.schema() YIELD value
-      RETURN value as schema
-    `,
     // Project-scoped deletion - only deletes nodes for the specified project
     // Uses APOC batched deletion to avoid transaction memory limits on large projects
     CLEAR_PROJECT: `
@@ -444,65 +417,67 @@ export const QUERIES = {
     // DYNAMIC SCHEMA DISCOVERY QUERIES
     // ============================================
     /**
-     * Get all distinct node labels with counts and sample properties
+     * Get all distinct node labels with counts, property keys, and property types.
+     * Samples up to 10 nodes per label to collect comprehensive property info.
      */
     DISCOVER_NODE_TYPES: `
     CALL db.labels() YIELD label
     CALL {
       WITH label
       MATCH (n) WHERE label IN labels(n) AND n.projectId = $projectId
-      WITH n LIMIT 1
-      RETURN keys(n) AS sampleProperties
+      RETURN count(n) AS nodeCount
     }
     CALL {
       WITH label
       MATCH (n) WHERE label IN labels(n) AND n.projectId = $projectId
-      RETURN count(n) AS nodeCount
+      WITH n LIMIT 10
+      UNWIND keys(n) AS key
+      WITH DISTINCT key, n[key] AS val
+      RETURN collect(DISTINCT key) AS properties
     }
-    RETURN label, nodeCount, sampleProperties
+    RETURN label, nodeCount, properties
     ORDER BY nodeCount DESC
   `,
     /**
-     * Get all distinct relationship types with counts and which node types they connect
+     * Get all distinct relationship types with counts and all connection patterns
      */
     DISCOVER_RELATIONSHIP_TYPES: `
     CALL db.relationshipTypes() YIELD relationshipType
     CALL {
       WITH relationshipType
       MATCH (a)-[r]->(b) WHERE type(r) = relationshipType AND a.projectId = $projectId AND b.projectId = $projectId
-      WITH labels(a)[0] AS fromLabel, labels(b)[0] AS toLabel
-      RETURN fromLabel, toLabel
-      LIMIT 10
+      RETURN count(r) AS relCount
     }
     CALL {
       WITH relationshipType
-      MATCH (a)-[r]->(b) WHERE type(r) = relationshipType AND a.projectId = $projectId
-      RETURN count(r) AS relCount
+      MATCH (a)-[r]->(b) WHERE type(r) = relationshipType AND a.projectId = $projectId AND b.projectId = $projectId
+      WITH DISTINCT labels(a)[0] AS fromLabel, labels(b)[0] AS toLabel
+      RETURN collect({from: fromLabel, to: toLabel}) AS connections
     }
-    RETURN relationshipType, relCount, collect(DISTINCT {from: fromLabel, to: toLabel}) AS connections
+    RETURN relationshipType, relCount, connections
     ORDER BY relCount DESC
   `,
     /**
-     * Get sample nodes of each semantic type for context
+     * Get semantic types with counts and which label they appear on
      */
     DISCOVER_SEMANTIC_TYPES: `
     MATCH (n)
     WHERE n.semanticType IS NOT NULL AND n.projectId = $projectId
-    WITH n.semanticType AS semanticType, count(*) AS count
+    WITH n.semanticType AS semanticType, labels(n)[0] AS nodeLabel, count(*) AS count
+    RETURN semanticType, nodeLabel, count
     ORDER BY count DESC
-    RETURN semanticType, count
   `,
     /**
-     * Get example query patterns based on actual graph structure
+     * Get all relationship patterns between node types
      */
     DISCOVER_COMMON_PATTERNS: `
     MATCH (a)-[r]->(b)
     WHERE a.projectId = $projectId AND b.projectId = $projectId
     WITH labels(a)[0] AS fromType, type(r) AS relType, labels(b)[0] AS toType, count(*) AS count
-    WHERE count > 5
+    WHERE count > 2
     RETURN fromType, relType, toType, count
     ORDER BY count DESC
-    LIMIT 20
+    LIMIT 50
   `,
     // ============================================
     // IMPACT ANALYSIS QUERIES

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-graph-context",
-  "version": "2.13.3",
+  "version": "2.14.0",
   "description": "MCP server that builds code graphs to provide rich context to LLMs",
   "type": "module",
   "homepage": "https://github.com/drewdrewH/code-graph-context#readme",