code-graph-context 2.13.3 → 2.14.1

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

@@ -7,176 +7,31 @@ export class NaturalLanguageToCypherService {
     MODEL = 'gpt-4o'; // GPT-4o for better Cypher generation accuracy
     schemaPath = null;
     cachedSemanticTypes = null;
-    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
-
-=== LABEL TYPES - TWO CATEGORIES ===
-Check rawSchema keys for ALL valid labels. 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.
-
-=== AST TYPE NAME MAPPING ===
-AST type names are NOT valid labels. Always map them:
-- ClassDeclaration → Class (or a framework label from rawSchema if enhanced)
-- FunctionDeclaration → Function
-- MethodDeclaration → Method
-- InterfaceDeclaration → Interface
-- PropertyDeclaration → Property
-- ParameterDeclaration → Parameter
-
-=== 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
-
-Examples:
-- "Count all classes" -> MATCH (n:Class) WHERE n.projectId = $projectId RETURN count(n)
-- "Find class by name" -> MATCH (n:Class {name: 'ClassName'}) WHERE n.projectId = $projectId RETURN n
-- "Methods in a class" -> MATCH (c:Class {name: 'ClassName'})-[:HAS_MEMBER]->(m:Method) WHERE c.projectId = $projectId RETURN m
-
-=== PROJECT ISOLATION (REQUIRED) ===
-ALL queries MUST filter by projectId on every node pattern:
-WHERE n.projectId = $projectId
-
-=== RESPONSE FORMAT ===
-Return ONLY valid JSON:
-{
-  "cypher": "MATCH (n:Label) WHERE n.projectId = $projectId RETURN n",
-  "parameters": { "param": "value" } | null,
-  "explanation": "What this query does"
-}
-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
-
-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
-- 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
-
-=== CORE RELATIONSHIPS ===
-- CONTAINS: SourceFile contains declarations (use for "in file", "declared in", "defined in")
-- HAS_MEMBER: Class/Interface has methods/properties (use for "has method", "contains property", "members")
-- HAS_PARAMETER: Method/Function has parameters (use for "takes parameter", "accepts")
-- EXTENDS: Class/Interface extends parent (use for "extends", "inherits from", "parent class", "subclass")
-- IMPLEMENTS: Class implements Interface (use for "implements", "conforms to")
-- IMPORTS: SourceFile imports another (use for "imports", "depends on", "requires")
-- TYPED_AS: Parameter/Property has type annotation (use for "typed as", "has type", "returns")
-- CALLS: Method/Function calls another (use for "calls", "invokes", "uses")
-- 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:
-- What relationship types exist (e.g., INJECTS, EXPOSES, MODULE_IMPORTS, INTERNAL_API_CALL, etc.)
-- Direction (in/out) and target labels for each relationship
-- 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.
-
-EXTENDS DIRECTION - CRITICAL:
-The arrow points FROM child TO parent. The child "extends" toward the parent.
-- CORRECT: (child:Class)-[:EXTENDS]->(parent:Class {name: 'ParentClassName'})
-- WRONG: (parent:Class {name: 'ParentClassName'})-[:EXTENDS]->(child:Class)
-
-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 ***
-
-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
-
-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
-
-=== DECORATOR QUERIES ===
-Use DECORATED_WITH relationship to find nodes with specific decorators:
-- "Classes with @X" -> MATCH (c:Class)-[:DECORATED_WITH]->(d:Decorator {name: 'X'}) WHERE c.projectId = $projectId RETURN c
-- "Methods with @Y" -> MATCH (m:Method)-[:DECORATED_WITH]->(d:Decorator {name: 'Y'}) WHERE m.projectId = $projectId RETURN m
-
-=== MODULE/DIRECTORY QUERIES ===
-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
-
-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.
+    /**
+     * System instructions for the assistant (set once at creation time).
+     * Kept focused on Cypher rules and output format — schema data is injected per-query.
+     */
+    assistantInstructions = `You are a Neo4j Cypher query generator. You receive a schema and a natural language request, and you return a single JSON object. No prose, no markdown, no explanation outside the JSON.
+
+OUTPUT FORMAT (strict):
+{"cypher": "...", "parameters": null, "explanation": "..."}
+
+- "cypher": valid Neo4j Cypher query
+- "parameters": object of extra parameters or null (NEVER include projectId — it is injected automatically)
+- "explanation": one sentence describing what the query does
+
+RULES:
+1. ALL node patterns MUST include: WHERE n.projectId = $projectId
+2. Use ONLY node labels listed in the schema's nodeTypes[].label
+3. Entity names are PROPERTY values, NOT labels: (n:Class {name: 'MyService'}) not (n:MyService)
+4. AST type names are NOT labels: ClassDeclaration → Class, MethodDeclaration → Method, InterfaceDeclaration → Interface, FunctionDeclaration → Function, PropertyDeclaration → Property, ParameterDeclaration → Parameter
+5. semanticType is a PROPERTY, not a label: WHERE n.semanticType = 'NestController'
+6. EXTENDS direction: child → parent. (child:Class)-[:EXTENDS]->(parent:Class)
+7. Cypher has no GROUP BY — aggregation is automatic in RETURN
+8. Use $-prefixed parameters for dynamic values
+
+CORE RELATIONSHIPS:
+CONTAINS (file→declaration), HAS_MEMBER (class→method/property), HAS_PARAMETER (method→param), EXTENDS (child→parent), IMPLEMENTS (class→interface), IMPORTS (file→file), TYPED_AS (node→type), CALLS (caller→callee), DECORATED_WITH (node→decorator)
 `;
     constructor() {
         const apiKey = process.env.OPENAI_API_KEY;
@@ -191,121 +46,79 @@ Provide ONLY the JSON response with no additional text, markdown formatting, or
         });
     }
     async getOrCreateAssistant(schemaPath) {
-        // Store schema path for later use in prompt injection
+        // Store schema path for later use — schema is injected directly into each prompt
         this.schemaPath = schemaPath;
         if (process.env.OPENAI_ASSISTANT_ID) {
             this.assistantId = process.env.OPENAI_ASSISTANT_ID;
             console.error(`Using existing assistant with ID: ${this.assistantId}`);
             return this.assistantId;
         }
-        const schemaFile = await this.openai.files.create({
-            file: fs.createReadStream(schemaPath),
-            purpose: 'assistants',
-        });
-        // Create a vector store for the schema file
-        const vectorStore = await this.openai.vectorStores.create({
-            name: 'Neo4j APOC Schema Vector Store',
-            file_ids: [schemaFile.id],
-            metadata: { type: 'neo4j_apoc_schema' },
-        });
-        const vectorStoreId = vectorStore.id;
-        // Create a new assistant
-        const assistantConfig = {
-            name: 'Neo4j Cypher Query Agent',
-            description: 'An agent that helps convert natural language to Neo4j Cypher queries',
+        const assistant = await this.openai.beta.assistants.create({
+            name: 'Neo4j Cypher Query Generator',
+            description: 'Converts natural language to Neo4j Cypher queries. Returns JSON only.',
             model: this.MODEL,
-            instructions: `
-      You are a specialized assistant that helps convert natural language requests into Neo4j Cypher queries.
-      When users ask questions about their codebase data, you'll analyze their intent and generate appropriate
-      Cypher queries based on the Neo4j schema provided in files.
-  ${this.messageInstructions}
-`,
-            tools: [
-                {
-                    type: 'code_interpreter',
-                },
-                {
-                    type: 'file_search',
-                },
-            ],
-            tool_resources: {
-                code_interpreter: {
-                    file_ids: [schemaFile.id],
-                },
-                file_search: {
-                    vector_store_ids: [vectorStoreId],
-                },
-            },
-        };
-        const assistant = await this.openai.beta.assistants.create(assistantConfig);
+            instructions: this.assistantInstructions,
+            response_format: { type: 'json_object' },
+            // No tools — schema is injected directly into each message
+            tools: [],
+        });
         this.assistantId = assistant.id;
+        console.error(`Created assistant with ID: ${this.assistantId}`);
         return this.assistantId;
     }
     /**
-     * Load and format the schema context for direct injection into prompts.
-     * This supplements the file_search tool by providing explicit schema information.
+     * Load the schema and format it for direct injection into the user message.
+     * This is the ONLY way the LLM sees the schema — no file_search.
      */
     loadSchemaContext() {
         if (!this.schemaPath) {
-            return 'No schema available. Use node types from file_search.';
+            return 'No schema available.';
         }
         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';
-            // 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;
-            // Format relationship types
-            const relTypes = ds.relationshipTypes?.map((r) => r.type).join(', ') ?? 'none';
-            // Format semantic types and categorize them
-            const semanticTypeList = ds.semanticTypes?.map((s) => s.type) ?? [];
-            const semTypes = semanticTypeList.length > 0 ? semanticTypeList.join(', ') : 'none';
+            // Format node types with properties
+            const nodeTypeLines = schema.nodeTypes
+                ?.map((n) => `  ${n.label} (${n.count} nodes) — properties: ${(n.properties ?? []).join(', ')}`)
+                .join('\n') ?? 'none';
+            // Format relationship types with connection patterns
+            const relTypeLines = schema.relationshipTypes
+                ?.map((r) => {
+                const conns = (r.connections ?? []).map((c) => `${c.from}→${c.to}`).join(', ');
+                return `  ${r.type} (${r.count}) — ${conns}`;
+            })
+                .join('\n') ?? 'none';
+            // Format semantic types
+            const semanticTypeList = schema.semanticTypes?.map((s) => s.type) ?? [];
+            const semTypeLines = schema.semanticTypes
+                ?.map((s) => `  ${s.type} (on ${s.label}, ${s.count} nodes)`)
+                .join('\n') ?? 'none';
+            // Format common patterns
+            const patternLines = schema.commonPatterns
+                ?.map((p) => `  (${p.from})-[:${p.relationship}]->(${p.to}) × ${p.count}`)
+                .join('\n') ?? 'none';
             // Cache categorized semantic types for dynamic example generation
             this.cachedSemanticTypes = this.categorizeSemanticTypes(semanticTypeList);
-            // Framework hint based on graph composition
-            let frameworkHint = '';
-            if (decoratorCount > 10 && classCount > functionCount) {
-                // Use discovered semantic types instead of assuming NestJS
-                const sampleType = this.cachedSemanticTypes?.controller[0] ?? this.cachedSemanticTypes?.service[0] ?? 'YourSemanticType';
-                frameworkHint = `\nFRAMEWORK DETECTED: Decorator-based codebase. Use Class nodes with semanticType property (e.g., semanticType = "${sampleType}").`;
-            }
-            else if (functionCount > classCount) {
-                frameworkHint = '\nFRAMEWORK DETECTED: React/functional codebase. Use Function nodes for components.';
-            }
-            return `
-=== VALID NODE LABELS (use ONLY these after the colon) ===
-${nodeTypes}
+            return `SCHEMA:
 
-=== VALID RELATIONSHIP TYPES ===
-${relTypes}
+NODE LABELS (use ONLY these):
+${nodeTypeLines}
 
-=== SEMANTIC TYPES - USE THESE FOR FRAMEWORK QUERIES ===
-Available semantic types in this project: ${semTypes}
+RELATIONSHIP TYPES:
+${relTypeLines}
 
-*** SEMANTIC TYPES ARE THE PRIMARY WAY TO QUERY FRAMEWORK-SPECIFIC NODES ***
-Query pattern: WHERE n.semanticType = 'TypeFromListAbove'
-Example: MATCH (n:Class) WHERE n.projectId = $projectId AND n.semanticType = '${semanticTypeList[0] ?? 'SemanticType'}' RETURN n
-${frameworkHint}
+SEMANTIC TYPES (query via WHERE n.semanticType = 'value'):
+${semTypeLines}
 
-=== CRITICAL RULES ===
-1. Use ONLY the labels listed above after the colon (:Label)
-2. Semantic types are PROPERTY values, NOT labels - use WHERE n.semanticType = 'Type'
-3. Class/entity names are PROPERTY values, NOT labels - use WHERE n.name = 'Name'
-4. WRONG: (n:ClassName) - using names as labels
-5. CORRECT: (n:Class {name: 'ClassName'}) or (n:LabelFromSchema {name: 'Name'})
-6. CORRECT: (n:Class) WHERE n.semanticType = 'TypeFromSemanticTypesList'
-`.trim();
+COMMON PATTERNS:
+${patternLines}`;
         }
         catch (error) {
             console.warn('Failed to load schema for prompt injection:', error);
-            return 'Schema load failed. Use file_search for schema information.';
+            return 'Schema load failed.';
         }
     }
     /**
@@ -409,14 +222,14 @@ FALLBACK PATTERNS (use when semantic types don't exist):
         // Generate dynamic examples based on discovered semantic types
         const dynamicSemanticExamples = this.cachedSemanticTypes
             ? this.generateDynamicSemanticExamples(this.cachedSemanticTypes)
-            : '\nNo semantic types discovered. Use name patterns for all queries (e.g., c.name CONTAINS "Controller").\n';
-        const prompt = `Please convert this request to a valid Neo4j Cypher query: ${userPrompt}.
+            : '';
+        const prompt = `Convert to Cypher: ${userPrompt}
 
 ${schemaContext}
 ${dynamicSemanticExamples}
-The query will be scoped to project: ${projectId}
-Remember to include WHERE n.projectId = $projectId for all node patterns.
-`;
+Project: ${projectId} — add WHERE n.projectId = $projectId on every node pattern.
+
+Respond with ONLY a JSON object: {"cypher": "...", "parameters": null, "explanation": "..."}`;
         // SECURITY: Only log prompt length, not full content which may contain sensitive data
         console.error(`NL-to-Cypher: Processing prompt (${prompt.length} chars) for project ${projectId}`);
         const run = await this.openai.beta.threads.createAndRunPoll({
@@ -465,10 +278,10 @@ Remember to include WHERE n.projectId = $projectId for all node patterns.
         }
         // SECURITY: Don't log the full text value which may contain sensitive queries
         console.error(`NL-to-Cypher: Parsing response (${textValue.length} chars)`);
-        // Parse the response with proper error handling
+        // Extract JSON from the LLM response, handling markdown fences and prose preamble
         let result;
         try {
-            result = JSON.parse(textValue);
+            result = JSON.parse(this.extractJson(textValue));
         }
         catch (parseError) {
             const message = parseError instanceof Error ? parseError.message : String(parseError);
@@ -481,6 +294,38 @@ Remember to include WHERE n.projectId = $projectId for all node patterns.
         this.validateLabelUsage(result.cypher);
         return result;
     }
+    /**
+     * Extracts JSON from an LLM response that may contain markdown fences or prose preamble.
+     * Tries in order: raw parse, markdown fence extraction, first `{...}` block extraction.
+     */
+    extractJson(text) {
+        const trimmed = text.trim();
+        // 1. Already valid JSON — return as-is
+        if (trimmed.startsWith('{')) {
+            return trimmed;
+        }
+        // 2. Wrapped in markdown code fences: ```json ... ``` or ``` ... ```
+        const fenceMatch = trimmed.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
+        if (fenceMatch) {
+            return fenceMatch[1].trim();
+        }
+        // 3. JSON object embedded in prose — find the first top-level { ... }
+        const startIdx = trimmed.indexOf('{');
+        if (startIdx !== -1) {
+            let depth = 0;
+            for (let i = startIdx; i < trimmed.length; i++) {
+                if (trimmed[i] === '{')
+                    depth++;
+                else if (trimmed[i] === '}')
+                    depth--;
+                if (depth === 0) {
+                    return trimmed.substring(startIdx, i + 1);
+                }
+            }
+        }
+        // 4. Give up — return original text so JSON.parse produces a useful error
+        return trimmed;
+    }
     /**
      * Validates that the generated Cypher query contains projectId filters.
      * This is a security measure to ensure project isolation is maintained
@@ -521,7 +366,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 +395,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.1",
   "description": "MCP server that builds code graphs to provide rich context to LLMs",
   "type": "module",
   "homepage": "https://github.com/drewdrewH/code-graph-context#readme",