code-graph-context 2.14.1 → 3.0.1

package/dist/mcp/handlers/swarm/queries.js

@@ -0,0 +1,140 @@
+/**
+ * Shared Cypher queries for swarm task handlers.
+ *
+ * Queries that are used by multiple handlers live here.
+ * Handler-specific queries stay in their handler files.
+ */
+/**
+ * Get current task state — used by all handlers for diagnostic error messages.
+ */
+export const GET_TASK_STATE_QUERY = `
+  MATCH (t:SwarmTask {id: $taskId, projectId: $projectId})
+  RETURN t.id as id,
+         t.title as title,
+         t.status as status,
+         t.claimedBy as claimedBy,
+         t.claimedAt as claimedAt,
+         t.startedAt as startedAt,
+         t.abandonCount as abandonCount,
+         t.previousClaimedBy as previousClaimedBy
+`;
+/**
+ * Claim a specific task by ID.
+ * Uses APOC locking for atomic claim under concurrency.
+ * Shared by claim-by-id and claim-and-start-by-id flows.
+ */
+export const CLAIM_TASK_BY_ID_QUERY = `
+  MATCH (t:SwarmTask {id: $taskId, projectId: $projectId})
+  WHERE t.status IN ['available', 'blocked']
+
+  // Check if dependencies are complete
+  OPTIONAL MATCH (t)-[:DEPENDS_ON]->(dep:SwarmTask)
+  WHERE dep.status <> 'completed'
+  WITH t, count(dep) as incompleteDeps
+
+  // Only claim if all dependencies are complete
+  WHERE incompleteDeps = 0
+
+  // Acquire exclusive lock to prevent race conditions
+  CALL apoc.lock.nodes([t])
+
+  // Double-check status after acquiring lock
+  WITH t WHERE t.status IN ['available', 'blocked']
+
+  // Atomic claim
+  SET t.status = $targetStatus,
+      t.claimedBy = $agentId,
+      t.claimedAt = timestamp(),
+      t.startedAt = CASE WHEN $targetStatus = 'in_progress' THEN timestamp() ELSE null END,
+      t.updatedAt = timestamp()
+
+  // Return task details with target info
+  WITH t
+  OPTIONAL MATCH (t)-[:TARGETS]->(target)
+  RETURN t.id as id,
+         t.projectId as projectId,
+         t.swarmId as swarmId,
+         t.title as title,
+         t.description as description,
+         t.type as type,
+         t.priority as priority,
+         t.priorityScore as priorityScore,
+         t.status as status,
+         t.targetNodeIds as targetNodeIds,
+         t.targetFilePaths as targetFilePaths,
+         t.dependencies as dependencies,
+         t.claimedBy as claimedBy,
+         t.claimedAt as claimedAt,
+         t.startedAt as startedAt,
+         t.createdBy as createdBy,
+         t.metadata as metadata,
+         collect(DISTINCT {
+           id: target.id,
+           type: labels(target)[0],
+           name: target.name,
+           filePath: target.filePath
+         }) as targets
+`;
+/**
+ * Claim the highest priority available task matching criteria.
+ * Uses APOC locking for atomic claim under concurrency.
+ * Supports both 'claimed' and 'in_progress' target states.
+ */
+export const CLAIM_NEXT_TASK_QUERY = `
+  // Find available or blocked tasks (blocked tasks may have deps completed now)
+  MATCH (t:SwarmTask {projectId: $projectId, swarmId: $swarmId})
+  WHERE t.status IN ['available', 'blocked']
+    AND ($types IS NULL OR size($types) = 0 OR t.type IN $types)
+    AND ($minPriority IS NULL OR t.priorityScore >= $minPriority)
+
+  // Exclude tasks with incomplete dependencies
+  OPTIONAL MATCH (t)-[:DEPENDS_ON]->(dep:SwarmTask)
+  WHERE dep.status <> 'completed'
+  WITH t, count(dep) as incompleteDeps
+  WHERE incompleteDeps = 0
+
+  // Re-establish context for ordering (required by Cypher syntax)
+  WITH t
+  ORDER BY t.priorityScore DESC, t.createdAt ASC
+  LIMIT 1
+
+  // Acquire exclusive lock to prevent race conditions
+  CALL apoc.lock.nodes([t])
+
+  // Double-check status after acquiring lock (another worker may have claimed it)
+  WITH t WHERE t.status IN ['available', 'blocked']
+
+  // Atomic claim - supports both claim and claim_and_start via $targetStatus
+  SET t.status = $targetStatus,
+      t.claimedBy = $agentId,
+      t.claimedAt = timestamp(),
+      t.startedAt = CASE WHEN $targetStatus = 'in_progress' THEN timestamp() ELSE null END,
+      t.updatedAt = timestamp()
+
+  // Return task details with target info
+  WITH t
+  OPTIONAL MATCH (t)-[:TARGETS]->(target)
+  RETURN t.id as id,
+         t.projectId as projectId,
+         t.swarmId as swarmId,
+         t.title as title,
+         t.description as description,
+         t.type as type,
+         t.priority as priority,
+         t.priorityScore as priorityScore,
+         t.status as status,
+         t.targetNodeIds as targetNodeIds,
+         t.targetFilePaths as targetFilePaths,
+         t.dependencies as dependencies,
+         t.claimedBy as claimedBy,
+         t.claimedAt as claimedAt,
+         t.startedAt as startedAt,
+         t.createdBy as createdBy,
+         t.metadata as metadata,
+         collect(DISTINCT {
+           id: target.id,
+           type: labels(target)[0],
+           name: target.name,
+           filePath: target.filePath
+         }) as targets
+`;

package/dist/mcp/handlers/swarm/release.handler.js

@@ -0,0 +1,41 @@
+import { GET_TASK_STATE_QUERY } from './queries.js';
+/**
+ * Query to release a claimed task (unclaim it)
+ */
+const RELEASE_TASK_QUERY = `
+  MATCH (t:SwarmTask {id: $taskId, projectId: $projectId})
+  WHERE t.status IN ['claimed', 'in_progress'] AND t.claimedBy = $agentId
+
+  SET t.status = 'available',
+      t.claimedBy = null,
+      t.claimedAt = null,
+      t.startedAt = null,
+      t.updatedAt = timestamp(),
+      t.releaseReason = $reason
+
+  RETURN t.id as id,
+         t.title as title,
+         t.status as status
+`;
+export class SwarmReleaseHandler {
+    neo4jService;
+    constructor(neo4jService) {
+        this.neo4jService = neo4jService;
+    }
+    async release(projectId, taskId, agentId, reason) {
+        const result = await this.neo4jService.run(RELEASE_TASK_QUERY, {
+            taskId,
+            projectId,
+            agentId,
+            reason: reason || 'No reason provided',
+        });
+        if (result.length === 0) {
+            const stateResult = await this.neo4jService.run(GET_TASK_STATE_QUERY, {
+                taskId,
+                projectId,
+            });
+            return { error: true, data: stateResult[0] };
+        }
+        return { error: false, data: result[0] };
+    }
+}

package/dist/mcp/handlers/swarm-worker.handler.js

@@ -47,13 +47,12 @@ swarm_sense({
 \`\`\`
 
 ### 2. Claim a Task
-Claim the highest-priority available task:
+Claim and start the highest-priority available task:
 \`\`\`
 swarm_claim_task({
   projectId: "${config.projectId}",
   swarmId: "${config.swarmId}",
-  agentId: "${agentId}",
-  action: "claim"
+  agentId: "${agentId}"
 })
 \`\`\`
 
@@ -80,16 +79,6 @@ swarm_pheromone({
 })
 \`\`\`
 
-### 4. Start the Task
-\`\`\`
-swarm_claim_task({
-  projectId: "${config.projectId}",
-  taskId: "<claimed task id>",
-  agentId: "${agentId}",
-  action: "start"
-})
-\`\`\`
-
 ### 5. Execute the Task
 Read the task description carefully and execute it:
 - Use Read tool to understand the current code

package/dist/mcp/tools/detect-dead-code.tool.js

@@ -6,7 +6,7 @@ import { z } from 'zod';
 import { toNumber, isUIComponent, isPackageExport, isExcludedByPattern, getShortPath, } from '../../core/utils/shared-utils.js';
 import { Neo4jService, QUERIES } from '../../storage/neo4j/neo4j.service.js';
 import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
-import { createErrorResponse, createSuccessResponse, debugLog, resolveProjectIdOrError } from '../utils.js';
+import { autoResolveProjectId, createErrorResponse, createSuccessResponse, debugLog } from '../utils.js';
 // Default file patterns to exclude
 const DEFAULT_ENTRY_POINT_FILE_PATTERNS = [
     // Common entry points
@@ -94,67 +94,42 @@ export const createDetectDeadCodeTool = (server) => {
         title: TOOL_METADATA[TOOL_NAMES.detectDeadCode].title,
         description: TOOL_METADATA[TOOL_NAMES.detectDeadCode].description,
         inputSchema: {
-            projectId: z.string().describe('Project ID, name, or path (e.g., "backend" or "proj_a1b2c3d4e5f6")'),
-            excludePatterns: z
-                .array(z.string())
+            projectId: z
+                .string()
                 .optional()
-                .describe('Additional file patterns to exclude as entry points (e.g., ["*.config.ts", "*.seed.ts"])'),
-            excludeSemanticTypes: z
-                .array(z.string())
-                .optional()
-                .describe('Additional semantic types to exclude (e.g., ["EntityClass", "DTOClass"])'),
+                .describe('Project ID, name, or path (auto-resolves if only one project exists)'),
+            excludePatterns: z.array(z.string()).optional().describe('Additional file patterns to exclude as entry points'),
+            excludeSemanticTypes: z.array(z.string()).optional().describe('Additional semantic types to exclude'),
             includeEntryPoints: z
                 .boolean()
                 .optional()
-                .describe('Include excluded entry points in a separate audit section for review (default: true). ' +
-                'Entry points are always excluded from main results.')
+                .describe('Include excluded entry points in audit section')
                 .default(true),
             minConfidence: z
                 .enum(['LOW', 'MEDIUM', 'HIGH'])
                 .optional()
-                .describe('Minimum confidence level to include in results (default: LOW)')
+                .describe('Minimum confidence threshold for results')
                 .default('LOW'),
-            summaryOnly: z
-                .boolean()
-                .optional()
-                .describe('Return only summary statistics without full dead code list (default: false)')
-                .default(false),
-            limit: z
-                .number()
-                .int()
-                .min(1)
-                .max(500)
-                .optional()
-                .describe('Maximum number of dead code items to return per page (default: 100)')
-                .default(100),
-            offset: z
-                .number()
-                .int()
-                .min(0)
-                .optional()
-                .describe('Number of items to skip for pagination (default: 0)')
-                .default(0),
+            summaryOnly: z.boolean().optional().describe('Return summary statistics only, no item list').default(false),
+            limit: z.number().int().min(1).max(500).optional().describe('Max dead code items per page').default(100),
+            offset: z.number().int().min(0).optional().describe('Items to skip for pagination').default(0),
             filterCategory: z
                 .enum(['library-export', 'ui-component', 'internal-unused', 'all'])
                 .optional()
-                .describe('Filter by category: library-export, ui-component, internal-unused, or all (default: all)')
+                .describe('Filter results to a specific category')
                 .default('all'),
             excludeLibraryExports: z
                 .boolean()
                 .optional()
-                .describe('Exclude all items from packages/* directories (default: false)')
+                .describe('Exclude items from packages/* directories')
                 .default(false),
-            excludeCoreTypes: z
-                .array(z.string())
-                .optional()
-                .describe('Exclude specific core types from results (e.g., ["InterfaceDeclaration", "TypeAliasDeclaration"] to skip type definitions)')
-                .default([]),
+            excludeCoreTypes: z.array(z.string()).optional().describe('Core types to exclude from results').default([]),
         },
-    }, async ({ projectId, excludePatterns = [], excludeSemanticTypes = [], includeEntryPoints = true, minConfidence = 'LOW', summaryOnly = false, limit = 100, offset = 0, filterCategory = 'all', excludeLibraryExports = false, excludeCoreTypes = [], }) => {
+    }, async ({ projectId = undefined, excludePatterns = [], excludeSemanticTypes = [], includeEntryPoints = true, minConfidence = 'LOW', summaryOnly = false, limit = 100, offset = 0, filterCategory = 'all', excludeLibraryExports = false, excludeCoreTypes = [], }) => {
         const neo4jService = new Neo4jService();
         try {
             // Resolve project ID
-            const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
+            const projectResult = await autoResolveProjectId(projectId, neo4jService);
             if (!projectResult.success)
                 return projectResult.error;
             const resolvedProjectId = projectResult.projectId;
@@ -340,36 +315,31 @@ export const createDetectDeadCodeTool = (server) => {
                 .sort((a, b) => b[1] - a[1])
                 .slice(0, 20)
                 .map(([file, count]) => ({ file, count }));
+            // Always-included summary stats
+            const summaryStats = {
+                summary,
+                riskLevel,
+                totalCount: filteredItems.length,
+                totalBeforeFilter: deadCodeItems.length,
+                byConfidence,
+                byCategory,
+                byType,
+                affectedFiles,
+                topFilesByDeadCode,
+                excludedEntryPointsCount,
+            };
             // Build result based on summaryOnly flag
             let result;
             if (summaryOnly) {
-                // Summary mode: statistics only, no full arrays
-                result = {
-                    summary,
-                    riskLevel,
-                    totalCount: filteredItems.length,
-                    totalBeforeFilter: deadCodeItems.length,
-                    byConfidence,
-                    byCategory,
-                    byType,
-                    affectedFiles,
-                    topFilesByDeadCode,
-                    excludedEntryPointsCount,
-                };
+                // Summary mode: statistics only, no item list
+                result = summaryStats;
             }
             else {
-                // Paginated mode: apply limit/offset
+                // Paginated mode: apply limit/offset, include both stats and items
                 const paginatedItems = filteredItems.slice(offset, offset + limit);
                 const hasMore = offset + limit < filteredItems.length;
                 result = {
-                    summary,
-                    riskLevel,
-                    totalCount: filteredItems.length,
-                    totalBeforeFilter: deadCodeItems.length,
-                    byConfidence,
-                    byCategory,
-                    byType,
-                    topFilesByDeadCode,
+                    ...summaryStats,
                     deadCode: paginatedItems,
                     pagination: {
                         offset,
@@ -377,10 +347,8 @@ export const createDetectDeadCodeTool = (server) => {
                         returned: paginatedItems.length,
                         hasMore,
                     },
-                    excludedEntryPointsCount,
                     // Only include full entry points array on first page
                     ...(offset === 0 && includeEntryPoints ? { excludedEntryPoints } : {}),
-                    affectedFiles,
                 };
             }
             return createSuccessResponse(JSON.stringify(result, null, 2));

package/dist/mcp/tools/detect-duplicate-code.tool.js

@@ -6,7 +6,7 @@ import { z } from 'zod';
 import { toNumber, isUIComponent, getMonorepoAppName, getShortPath, truncateSourceCode, } from '../../core/utils/shared-utils.js';
 import { Neo4jService, QUERIES } from '../../storage/neo4j/neo4j.service.js';
 import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
-import { createErrorResponse, createSuccessResponse, debugLog, resolveProjectIdOrError } from '../utils.js';
+import { autoResolveProjectId, createEmptyResponse, createErrorResponse, createSuccessResponse, debugLog, } from '../utils.js';
 /**
  * Determine confidence based on duplicate characteristics.
  */
@@ -91,63 +91,49 @@ export const createDetectDuplicateCodeTool = (server) => {
         title: TOOL_METADATA[TOOL_NAMES.detectDuplicateCode].title,
         description: TOOL_METADATA[TOOL_NAMES.detectDuplicateCode].description,
         inputSchema: {
-            projectId: z.string().describe('Project ID, name, or path (e.g., "backend" or "proj_a1b2c3d4e5f6")'),
+            projectId: z
+                .string()
+                .optional()
+                .describe('Project ID, name, or path (auto-resolves if only one project exists)'),
             type: z
                 .enum(['structural', 'semantic', 'all'])
                 .optional()
-                .describe('Detection approach: structural (AST hash), semantic (embeddings), or all (default: all)')
+                .describe('Detection approach: structural (AST hash), semantic (embeddings), or all')
                 .default('all'),
             minSimilarity: z
                 .number()
                 .min(0.5)
                 .max(1.0)
                 .optional()
-                .describe('Minimum similarity for semantic duplicates (0.5-1.0, default: 0.80)')
+                .describe('Minimum similarity threshold for semantic duplicates')
                 .default(0.8),
-            includeCode: z
-                .boolean()
-                .optional()
-                .describe('Include source code snippets in results (default: false)')
-                .default(false),
-            maxResults: z
-                .number()
-                .int()
-                .min(1)
-                .max(100)
-                .optional()
-                .describe('Maximum number of duplicate groups to return (default: 20)')
-                .default(20),
+            includeCode: z.boolean().optional().describe('Include source code snippets in results').default(false),
+            maxResults: z.number().int().min(1).max(100).optional().describe('Max duplicate groups to return').default(20),
             scope: z
                 .enum(['methods', 'functions', 'classes', 'all'])
                 .optional()
-                .describe('Node types to analyze (default: all)')
+                .describe('Node types to analyze')
                 .default('all'),
             summaryOnly: z
                 .boolean()
                 .optional()
-                .describe('Return only summary statistics without full duplicates list (default: false)')
+                .describe('Return summary statistics only, no duplicates list')
                 .default(false),
-            offset: z
-                .number()
-                .int()
-                .min(0)
-                .optional()
-                .describe('Number of groups to skip for pagination (default: 0)')
-                .default(0),
+            offset: z.number().int().min(0).optional().describe('Groups to skip for pagination').default(0),
             vectorNeighbors: z
                 .number()
                 .int()
                 .min(10)
                 .max(200)
                 .optional()
-                .describe('Number of vector neighbors to search per node for semantic duplicates (default: 50, higher = more thorough)')
+                .describe('Vector neighbors per node (higher = more thorough)')
                 .default(50),
         },
     }, async ({ projectId, type = 'all', minSimilarity = 0.8, includeCode = false, maxResults = 20, scope = 'all', summaryOnly = false, offset = 0, vectorNeighbors = 50, }) => {
         const neo4jService = new Neo4jService();
         try {
             // Resolve project ID
-            const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
+            const projectResult = await autoResolveProjectId(projectId, neo4jService);
             if (!projectResult.success)
                 return projectResult.error;
             const resolvedProjectId = projectResult.projectId;
@@ -352,49 +338,55 @@ export const createDetectDuplicateCodeTool = (server) => {
                     };
                 }
             }
+            // Early return for zero results
+            if (totalGroups === 0) {
+                return createEmptyResponse('No duplicate code found', semanticDiagnostic
+                    ? `Semantic analysis note: ${semanticDiagnostic}. Try lowering minSimilarity or changing scope.`
+                    : 'Try lowering minSimilarity or broadening scope.');
+            }
             // Build summary with warning if no embeddings
-            let summary = totalGroups === 0
-                ? 'No duplicate code found'
-                : `Found ${totalGroups} duplicate code groups across ${affectedFiles.length} files`;
+            let summary = `Found ${totalGroups} duplicate code groups across ${affectedFiles.length} files`;
             if (semanticQueryError) {
                 summary += ` (Warning: ${semanticQueryError})`;
             }
             else if ((type === 'semantic' || type === 'all') && embeddingCount === 0 && allSemanticGroups.length === 0) {
                 summary += ' (Warning: No embeddings for semantic detection)';
             }
+            // Build summary stats (always included)
+            const fileDuplicateCounts = {};
+            for (const group of duplicateGroups) {
+                for (const item of group.items) {
+                    const shortPath = getShortPath(item.filePath);
+                    fileDuplicateCounts[shortPath] = (fileDuplicateCounts[shortPath] ?? 0) + 1;
+                }
+            }
+            const topFilesByDuplicates = Object.entries(fileDuplicateCounts)
+                .sort((a, b) => b[1] - a[1])
+                .slice(0, 20)
+                .map(([file, count]) => ({ file, count }));
+            const stats = {
+                totalGroups,
+                totalDuplicates,
+                byType,
+                affectedFiles,
+                topFilesByDuplicates,
+            };
             // Build result based on summaryOnly flag
             let result;
             if (summaryOnly) {
-                // Summary mode: statistics only, no full arrays
-                const fileDuplicateCounts = {};
-                for (const group of duplicateGroups) {
-                    for (const item of group.items) {
-                        const shortPath = getShortPath(item.filePath);
-                        fileDuplicateCounts[shortPath] = (fileDuplicateCounts[shortPath] ?? 0) + 1;
-                    }
-                }
-                const topFilesByDuplicates = Object.entries(fileDuplicateCounts)
-                    .sort((a, b) => b[1] - a[1])
-                    .slice(0, 20)
-                    .map(([file, count]) => ({ file, count }));
+                // Summary mode: statistics only, no groups list
                 result = {
                     summary,
-                    totalGroups,
-                    totalDuplicates,
-                    byType,
-                    affectedFiles,
-                    topFilesByDuplicates,
+                    ...stats,
                 };
             }
             else {
-                // Paginated mode: apply offset/maxResults
+                // Paginated mode: apply offset/maxResults, include stats AND groups
                 const paginatedGroups = duplicateGroups.slice(offset, offset + maxResults);
                 const hasMore = offset + maxResults < duplicateGroups.length;
                 result = {
                     summary,
-                    totalGroups,
-                    totalDuplicates,
-                    byType,
+                    ...stats,
                     duplicates: paginatedGroups,
                     pagination: {
                         offset,
@@ -402,7 +394,6 @@ export const createDetectDuplicateCodeTool = (server) => {
                         returned: paginatedGroups.length,
                         hasMore,
                     },
-                    affectedFiles,
                 };
             }
             // Add pre-computed diagnostic to result

package/dist/mcp/tools/impact-analysis.tool.js

@@ -66,7 +66,7 @@ export const createImpactAnalysisTool = (server) => {
                 .min(1)
                 .max(6)
                 .optional()
-                .describe('Maximum depth to traverse for transitive dependents (default: 4)')
+                .describe('Maximum depth for transitive dependent traversal')
                 .default(4),
             frameworkConfig: FrameworkConfigSchema.optional().describe('Framework-specific configuration for risk scoring. Includes relationshipWeights (e.g., {"INJECTS": 0.9}), highRiskTypes (e.g., ["Controller", "Service"]), and optional name.'),
         },

package/dist/mcp/tools/index.js

@@ -12,11 +12,12 @@ import { createListWatchersTool } from './list-watchers.tool.js';
 import { createNaturalLanguageToCypherTool } from './natural-language-to-cypher.tool.js';
 import { createParseTypescriptProjectTool } from './parse-typescript-project.tool.js';
 import { createSearchCodebaseTool } from './search-codebase.tool.js';
-import { createRestoreSessionBookmarkTool, createSaveSessionBookmarkTool } from './session-bookmark.tool.js';
 import { createCleanupSessionTool } from './session-cleanup.tool.js';
-import { createRecallSessionNotesTool, createSaveSessionNoteTool } from './session-note.tool.js';
+import { createSessionRecallTool } from './session-recall.tool.js';
+import { createSessionSaveTool } from './session-save.tool.js';
 import { createStartWatchProjectTool } from './start-watch-project.tool.js';
 import { createStopWatchProjectTool } from './stop-watch-project.tool.js';
+import { createSwarmAdvanceTaskTool } from './swarm-advance-task.tool.js';
 import { createSwarmClaimTaskTool } from './swarm-claim-task.tool.js';
 import { createSwarmCleanupTool } from './swarm-cleanup.tool.js';
 import { createSwarmCompleteTaskTool } from './swarm-complete-task.tool.js';
@@ -24,6 +25,7 @@ import { createSwarmGetTasksTool } from './swarm-get-tasks.tool.js';
 import { createSwarmMessageTool } from './swarm-message.tool.js';
 import { createSwarmPheromoneTool } from './swarm-pheromone.tool.js';
 import { createSwarmPostTaskTool } from './swarm-post-task.tool.js';
+import { createSwarmReleaseTaskTool } from './swarm-release-task.tool.js';
 import { createSwarmSenseTool } from './swarm-sense.tool.js';
 import { createTestNeo4jConnectionTool } from './test-neo4j-connection.tool.js';
 import { createTraverseFromNodeTool } from './traverse-from-node.tool.js';
@@ -72,16 +74,14 @@ export const registerAllTools = (server) => {
     // Register swarm task tools (blackboard for explicit task management)
     createSwarmPostTaskTool(server);
     createSwarmClaimTaskTool(server);
+    createSwarmAdvanceTaskTool(server);
+    createSwarmReleaseTaskTool(server);
     createSwarmCompleteTaskTool(server);
     createSwarmGetTasksTool(server);
     // Register swarm messaging tools (direct agent-to-agent communication)
     createSwarmMessageTool(server);
-    // Register session bookmark tools (cross-session context continuity)
-    createSaveSessionBookmarkTool(server);
-    createRestoreSessionBookmarkTool(server);
-    // Register session note tools (durable observations and decisions)
-    createSaveSessionNoteTool(server);
-    createRecallSessionNotesTool(server);
-    // Register session cleanup tool
+    // Register session tools (unified save/recall + cleanup)
+    createSessionSaveTool(server);
+    createSessionRecallTool(server);
     createCleanupSessionTool(server);
 };

package/dist/mcp/tools/list-projects.tool.js

@@ -5,7 +5,7 @@
 import { LIST_PROJECTS_QUERY } from '../../core/utils/project-id.js';
 import { Neo4jService } from '../../storage/neo4j/neo4j.service.js';
 import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
-import { createErrorResponse, createSuccessResponse, debugLog } from '../utils.js';
+import { createEmptyResponse, createErrorResponse, createSuccessResponse, debugLog } from '../utils.js';
 export const createListProjectsTool = (server) => {
     server.registerTool(TOOL_NAMES.listProjects, {
         title: TOOL_METADATA[TOOL_NAMES.listProjects].title,
@@ -16,7 +16,7 @@ export const createListProjectsTool = (server) => {
         try {
             const results = await neo4jService.run(LIST_PROJECTS_QUERY, {});
             if (results.length === 0) {
-                return createSuccessResponse('No projects found. Use parse_typescript_project to add a project first.');
+                return createEmptyResponse('No projects found in the database', 'Use parse_typescript_project to add a project first.');
             }
             const projects = results.map((r) => ({
                 projectId: r.projectId,

package/dist/mcp/tools/list-watchers.tool.js

@@ -4,7 +4,7 @@
  */
 import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
 import { watchManager } from '../services/watch-manager.js';
-import { createErrorResponse, createSuccessResponse, debugLog } from '../utils.js';
+import { createEmptyResponse, createErrorResponse, createSuccessResponse, debugLog } from '../utils.js';
 export const createListWatchersTool = (server) => {
     server.registerTool(TOOL_NAMES.listWatchers, {
         title: TOOL_METADATA[TOOL_NAMES.listWatchers].title,
@@ -14,10 +14,7 @@ export const createListWatchersTool = (server) => {
         try {
             const watchers = watchManager.listWatchers();
             if (watchers.length === 0) {
-                return createSuccessResponse('No active file watchers.\n\n' +
-                    'To start watching a project:\n' +
-                    '- Use start_watch_project with a projectId\n' +
-                    '- Or use parse_typescript_project with watch: true (requires async: false)');
+                return createEmptyResponse('No active file watchers', 'Use start_watch_project to begin watching, or parse_typescript_project with watch=true.');
             }
             const header = `Found ${watchers.length} active watcher(s):\n\n`;
             const watcherList = watchers

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

@@ -7,7 +7,7 @@ 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, FILE_PATHS } from '../constants.js';
-import { createErrorResponse, createSuccessResponse, formatQueryResults, debugLog, resolveProjectIdOrError, } from '../utils.js';
+import { createEmptyResponse, 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('natural_language_to_cypher requires OPENAI_API_KEY. Set it and restart the MCP server to enable this tool.');
+                return createEmptyResponse('natural_language_to_cypher requires OPENAI_API_KEY', 'Set OPENAI_API_KEY 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)