argustack 0.2.0 → 0.3.1

package/dist/mcp/tools/graph.js

@@ -1,23 +1,27 @@
 import { z } from 'zod/v4';
-import { loadWorkspace, createAdapters, textResponse, errorResponse, getErrorMessage, } from '../helpers.js';
+import { loadWorkspace, createAdapters, textResponse, errorResponse, workspaceNotFoundResponse, getErrorMessage, hasText, ANNOTATIONS, } from '../helpers.js';
+const workspaceIdParam = z.string().optional().describe('Workspace id or name (defaults to active workspace)');
 export function registerGraphTools(server) {
     server.registerTool('impact_analysis', {
-        description: 'Analyze impact of changing a file or module. Returns connected issues, developers, PRs via knowledge graph. Requires graph data — run `argustack graph build` if results are empty. Use before refactoring to assess risk and identify who to consult.',
+        title: 'Knowledge-graph impact analysis',
+        description: 'Impact analysis for a file/module via knowledge graph (entities, developers, PRs).',
         inputSchema: {
-            file_or_module: z.string().describe('File path or module name (e.g. "src/adapters/payment", "payment")'),
-            depth: z.number().optional().describe('Graph traversal depth (default: 2)'),
+            workspace_id: workspaceIdParam,
+            file_or_module: z.string().describe('File path or module name'),
+            depth: z.number().optional().describe('Traversal depth (default 2)'),
         },
-    }, async ({ file_or_module: target, depth }) => {
-        const ws = loadWorkspace();
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ workspace_id: workspaceIdInput, file_or_module: target, depth }) => {
+        const ws = await loadWorkspace(workspaceIdInput);
         if (!ws.ok) {
-            return errorResponse(`Workspace not found: ${ws.reason}`);
+            return workspaceNotFoundResponse(ws.reason);
         }
-        const { storage } = await createAdapters(ws.root);
+        const { storage, workspaceId } = await createAdapters(ws.workspaceId);
         try {
             await storage.initialize();
-            const result = await storage.queryGraph(target, depth ?? 2);
+            const result = await storage.queryGraph(workspaceId, target, depth ?? 2);
             if (result.entities.length === 0) {
-                return textResponse(`No graph data for "${target}". Run "argustack graph build" first.`);
+                return textResponse(`No graph data for "${target}". Run "argustack graph build --workspace ${workspaceId}".`);
             }
             const issues = result.entities.filter((e) => e.type === 'issue');
             const developers = result.entities.filter((e) => e.type === 'developer');
@@ -56,31 +60,32 @@ export function registerGraphTools(server) {
                 }
                 lines.push('');
             }
-            await storage.close();
             return textResponse(lines.join('\n'));
         }
         catch (err) {
-            await storage.close();
             return errorResponse(`Impact analysis failed: ${getErrorMessage(err)}`);
         }
     });
     server.registerTool('developer_expertise', {
-        description: 'Find developers who know a specific area. Ranks by commits, reviews, issue assignments via knowledge graph. If no Git data synced, falls back to Jira assignee-based ranking. Run `argustack graph build` if results are empty.',
+        title: 'Developer expertise ranking',
+        description: 'Rank developers for a topic via knowledge graph.',
         inputSchema: {
-            area: z.string().describe('Topic, module, or component name (e.g. "payment", "authentication")'),
-            limit: z.number().optional().describe('Max developers to return (default: 10)'),
+            workspace_id: workspaceIdParam,
+            area: z.string(),
+            limit: z.number().optional(),
         },
-    }, async ({ area, limit }) => {
-        const ws = loadWorkspace();
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ workspace_id: workspaceIdInput, area, limit }) => {
+        const ws = await loadWorkspace(workspaceIdInput);
         if (!ws.ok) {
-            return errorResponse(`Workspace not found: ${ws.reason}`);
+            return workspaceNotFoundResponse(ws.reason);
         }
-        const { storage } = await createAdapters(ws.root);
+        const { storage, workspaceId } = await createAdapters(ws.workspaceId);
         try {
             await storage.initialize();
-            const result = await storage.queryGraph(area, 2);
+            const result = await storage.queryGraph(workspaceId, area, 2);
             if (result.entities.length === 0) {
-                return textResponse(`No graph data for "${area}". Run "argustack graph build" first.`);
+                return textResponse(`No graph data for "${area}".`);
             }
             const developers = result.entities.filter((e) => e.type === 'developer');
             const ranked = developers.map((dev) => {
@@ -90,80 +95,73 @@ export function registerGraphTools(server) {
                 const assigned = rels.filter((r) => r.type === 'assigned_to').length;
                 return { name: dev.name, total: rels.length, commits, reviews, assigned };
             }).sort((a, b) => b.total - a.total).slice(0, limit ?? 10);
-            const lines = [
-                `# Developer Expertise: ${area}`,
-                '',
-            ];
+            const lines = [`# Developer Expertise: ${area}`, ''];
             for (let i = 0; i < ranked.length; i++) {
                 const dev = ranked[i];
-                if (!dev) {
+                if (dev === undefined) {
                     continue;
                 }
                 lines.push(`${String(i + 1)}. **${dev.name}** — ${String(dev.commits)} commits, ${String(dev.reviews)} reviews, ${String(dev.assigned)} assignments`);
             }
-            await storage.close();
             return textResponse(lines.join('\n'));
         }
         catch (err) {
-            await storage.close();
             return errorResponse(`Developer expertise failed: ${getErrorMessage(err)}`);
         }
     });
     server.registerTool('related_issues', {
-        description: 'Find issues related to a given issue via knowledge graph traversal — through commits, files, PRs, developers. Discovers connections beyond explicit Jira links.',
+        title: 'Related issues (graph)',
+        description: 'Issues related to a given issue via knowledge graph traversal.',
         inputSchema: {
-            issue_key: z.string().describe('Issue key (e.g. "ORG-16999")'),
-            depth: z.number().optional().describe('Traversal depth (default: 3)'),
+            workspace_id: workspaceIdParam,
+            issue_key: z.string(),
+            depth: z.number().optional(),
         },
-    }, async ({ issue_key: issueKey, depth }) => {
-        const ws = loadWorkspace();
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ workspace_id: workspaceIdInput, issue_key: issueKey, depth }) => {
+        const ws = await loadWorkspace(workspaceIdInput);
         if (!ws.ok) {
-            return errorResponse(`Workspace not found: ${ws.reason}`);
+            return workspaceNotFoundResponse(ws.reason);
         }
-        const { storage } = await createAdapters(ws.root);
+        const { storage, workspaceId } = await createAdapters(ws.workspaceId);
         try {
             await storage.initialize();
-            const result = await storage.queryGraph(issueKey, depth ?? 3);
+            const result = await storage.queryGraph(workspaceId, issueKey, depth ?? 3);
             const related = result.entities.filter((e) => e.type === 'issue' && e.name !== issueKey);
             if (related.length === 0) {
-                return textResponse(`No related issues found for ${issueKey}. Run "argustack graph build" first.`);
+                return textResponse(`No related issues for ${issueKey}.`);
             }
-            const lines = [
-                `# Related Issues: ${issueKey}`,
-                `Found ${String(related.length)} related issue(s)`,
-                '',
-            ];
+            const lines = [`# Related Issues: ${issueKey}`, `Found ${String(related.length)} related issue(s)`, ''];
             for (const issue of related.slice(0, 30)) {
                 const props = issue.properties;
                 const source = result.relationships.some((r) => (r.sourceId === issue.id || r.targetId === issue.id) && r.source === 'claude') ? ' (semantic)' : '';
                 lines.push(`- **${issue.name}**${source} — ${typeof props['status'] === 'string' ? props['status'] : '?'} | ${typeof props['summary'] === 'string' ? props['summary'] : ''}`);
             }
-            await storage.close();
             return textResponse(lines.join('\n'));
         }
         catch (err) {
-            await storage.close();
             return errorResponse(`Related issues failed: ${getErrorMessage(err)}`);
         }
     });
     server.registerTool('code_dependencies', {
-        description: 'Show code dependencies for a file or module — co-changed files (coupling), imports, package dependencies. Based on knowledge graph data.',
+        title: 'Code dependencies (graph)',
+        description: 'Code dependencies for a file/module.',
         inputSchema: {
-            file_or_module: z.string().describe('File path or module name'),
-            depth: z.number().optional().describe('Traversal depth (default: 2)'),
+            workspace_id: workspaceIdParam,
+            file_or_module: z.string(),
+            depth: z.number().optional(),
         },
-    }, async ({ file_or_module: target, depth }) => {
-        const ws = loadWorkspace();
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ workspace_id: workspaceIdInput, file_or_module: target, depth }) => {
+        const ws = await loadWorkspace(workspaceIdInput);
         if (!ws.ok) {
-            return errorResponse(`Workspace not found: ${ws.reason}`);
+            return workspaceNotFoundResponse(ws.reason);
         }
-        const { storage } = await createAdapters(ws.root);
+        const { storage, workspaceId } = await createAdapters(ws.workspaceId);
         try {
             await storage.initialize();
-            const result = await storage.queryGraph(target, depth ?? 2);
-            const coChanges = result.relationships
-                .filter((r) => r.type === 'co_changes')
-                .sort((a, b) => b.weight - a.weight);
+            const result = await storage.queryGraph(workspaceId, target, depth ?? 2);
+            const coChanges = result.relationships.filter((r) => r.type === 'co_changes').sort((a, b) => b.weight - a.weight);
             const imports = result.relationships.filter((r) => r.type === 'imports');
             const pkgDeps = result.relationships.filter((r) => r.type === 'depends_on_pkg');
             const lines = [`# Code Dependencies: ${target}`, ''];
@@ -171,7 +169,7 @@ export function registerGraphTools(server) {
                 lines.push('## Co-changed Modules (coupling)');
                 for (const rel of coChanges.slice(0, 15)) {
                     const other = result.entities.find((e) => e.id === rel.sourceId || e.id === rel.targetId);
-                    if (other) {
+                    if (other !== undefined) {
                         lines.push(`- ${other.name} (${String(rel.weight)}x together)`);
                     }
                 }
@@ -181,7 +179,7 @@ export function registerGraphTools(server) {
                 lines.push('## Imports');
                 for (const rel of imports.slice(0, 20)) {
                     const importedModule = result.entities.find((e) => e.id === rel.targetId);
-                    if (importedModule) {
+                    if (importedModule !== undefined) {
                         lines.push(`- ${importedModule.name}`);
                     }
                 }
@@ -191,39 +189,39 @@ export function registerGraphTools(server) {
                 lines.push('## Package Dependencies');
                 for (const rel of pkgDeps.slice(0, 20)) {
                     const pkg = result.entities.find((e) => e.id === rel.targetId);
-                    if (pkg) {
+                    if (pkg !== undefined) {
                         lines.push(`- ${pkg.name}`);
                     }
                 }
                 lines.push('');
             }
             if (coChanges.length === 0 && imports.length === 0 && pkgDeps.length === 0) {
-                await storage.close();
-                return textResponse(`No code dependency data for "${target}". Run "argustack graph build" first.`);
+                return textResponse(`No code dependency data for "${target}".`);
             }
-            await storage.close();
             return textResponse(lines.join('\n'));
         }
         catch (err) {
-            await storage.close();
             return errorResponse(`Code dependencies failed: ${getErrorMessage(err)}`);
         }
     });
     server.registerTool('business_context', {
-        description: 'Show business context for a topic — business processes, features, related issues. Based on semantic graph built by Claude. If graph is empty, falls back to keyword search across issues. Run `build_business_graph` first for richer results.',
+        title: 'Business context (graph)',
+        description: 'Business context for a topic from the workspace knowledge graph.',
         inputSchema: {
-            topic: z.string().describe('Business topic (e.g. "refund", "payment", "onboarding")'),
-            depth: z.number().optional().describe('Traversal depth (default: 2)'),
+            workspace_id: workspaceIdParam,
+            topic: z.string(),
+            depth: z.number().optional(),
         },
-    }, async ({ topic, depth }) => {
-        const ws = loadWorkspace();
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ workspace_id: workspaceIdInput, topic, depth }) => {
+        const ws = await loadWorkspace(workspaceIdInput);
         if (!ws.ok) {
-            return errorResponse(`Workspace not found: ${ws.reason}`);
+            return workspaceNotFoundResponse(ws.reason);
         }
-        const { storage } = await createAdapters(ws.root);
+        const { storage, workspaceId } = await createAdapters(ws.workspaceId);
         try {
             await storage.initialize();
-            const result = await storage.queryGraph(topic, depth ?? 2);
+            const result = await storage.queryGraph(workspaceId, topic, depth ?? 2);
             const processes = result.entities.filter((e) => e.type === 'business_process');
             const features = result.entities.filter((e) => e.type === 'feature');
             const issues = result.entities.filter((e) => e.type === 'issue');
@@ -257,148 +255,137 @@ export function registerGraphTools(server) {
                 lines.push('');
             }
             if (processes.length === 0 && features.length === 0 && issues.length === 0) {
-                await storage.close();
-                return textResponse('No business context for "' + topic + '". Run `build_business_graph` to have Claude analyze issue descriptions.');
+                return textResponse(`No business context for "${topic}". Run \`build_business_graph\`.`);
             }
-            await storage.close();
             return textResponse(lines.join('\n'));
         }
         catch (err) {
-            await storage.close();
             return errorResponse(`Business context failed: ${getErrorMessage(err)}`);
         }
     });
     server.registerTool('build_business_graph', {
-        description: 'Analyze synced issues to discover business processes and features. Returns entities and suggested relationships. NEXT STEP: review the results, then call add_relationship for each connection you confirm. Call add_observation to annotate entities with business context. No external API cost.',
+        title: 'Build business graph',
+        description: 'Analyse issues to discover business processes/features for further enrichment.',
         inputSchema: {
-            project: z.string().optional().describe('Project key to analyze (default: all)'),
-            batch_size: z.number().optional().describe('Issues per batch (default: 50)'),
+            workspace_id: workspaceIdParam,
+            project: z.string().optional(),
+            batch_size: z.number().optional(),
         },
-    }, async ({ project, batch_size: batchSize }) => {
-        const ws = loadWorkspace();
+        annotations: ANNOTATIONS.LOCAL_WRITE,
+    }, async ({ workspace_id: workspaceIdInput, project, batch_size: batchSize }) => {
+        const ws = await loadWorkspace(workspaceIdInput);
         if (!ws.ok) {
-            return errorResponse(`Workspace not found: ${ws.reason}`);
+            return workspaceNotFoundResponse(ws.reason);
         }
-        const { storage } = await createAdapters(ws.root);
+        const { storage, workspaceId } = await createAdapters(ws.workspaceId);
         try {
             await storage.initialize();
-            const projectFilter = project ? `WHERE project_key = $1` : '';
-            const params = project ? [project] : [];
-            const result = await storage.query(`SELECT issue_key, summary, description, issue_type, status FROM issues ${projectFilter} ORDER BY issue_key LIMIT ${String(batchSize ?? 50)}`, params);
+            const projectFilter = hasText(project) ? `AND project_key = $2` : '';
+            const params = hasText(project) ? [project] : [];
+            const result = await storage.queryForWorkspace(workspaceId, `SELECT issue_key, summary, description, issue_type, status FROM issues
+           WHERE workspace_id = $1 ${projectFilter}
+           ORDER BY issue_key LIMIT ${String(batchSize ?? 50)}`, params);
             if (result.rows.length === 0) {
-                await storage.close();
-                return textResponse('No issues found. Run `argustack sync jira` first.');
+                return textResponse('No issues found. Run `argustack sync` first.');
             }
             const issueList = result.rows.map((r) => {
                 const desc = r['description'] ?? '';
-                const preview = desc.length > 200 ? desc.slice(0, 200) + '...' : desc;
+                const preview = desc.length > 200 ? `${desc.slice(0, 200)}...` : desc;
                 return `**${r['issue_key']}** [${r['issue_type']}] ${r['summary']}\n${preview}`;
             }).join('\n\n');
-            await storage.close();
             return textResponse([
-                `# Business Graph Analysis`,
-                `Analyzed ${String(result.rows.length)} issues. Review and use add_relationship to save connections.`,
-                '',
-                '## Instructions',
-                'Read the issues below. Identify:',
-                '1. **Business Processes** (e.g. "Refund Flow", "ACH Processing", "User Onboarding")',
-                '2. **Features** (e.g. "Payment Redistribution", "LOC Account Management")',
-                '3. Which issues belong to which process/feature',
-                '4. Which processes affect each other',
-                '',
-                'Then call `add_relationship` for each connection found.',
-                'Call `add_observation` to record important business knowledge.',
-                '',
-                '---',
+                `# Business Graph Analysis — workspace ${workspaceId}`,
+                `Analysed ${String(result.rows.length)} issues. Use add_relationship to save connections.`,
                 '',
+                '---', '',
                 issueList,
             ].join('\n'));
         }
         catch (err) {
-            await storage.close();
             return errorResponse(`Build business graph failed: ${getErrorMessage(err)}`);
         }
     });
     server.registerTool('add_relationship', {
-        description: 'Add a relationship between two entities in the knowledge graph. Use after build_business_graph to save confirmed connections. Types: implements, depends_on, related_to, caused_by, co_changes, root_causes. Marked source=claude — survives graph rebuild.',
+        title: 'Add graph relationship',
+        description: 'Add a relationship between two graph entities (marked source=claude).',
         inputSchema: {
-            source_name: z.string().describe('Source entity name (e.g. "Refund Flow")'),
-            source_type: z.string().describe('Source entity type (e.g. "business_process", "feature", "issue", "developer", "module")'),
-            target_name: z.string().describe('Target entity name'),
-            target_type: z.string().describe('Target entity type'),
-            relationship_type: z.string().describe('Relationship type (e.g. "affects", "part_of_process", "implements_feature", "depends_on", "related_to")'),
-            description: z.string().optional().describe('Description of the relationship'),
+            workspace_id: workspaceIdParam,
+            source_name: z.string(),
+            source_type: z.string(),
+            target_name: z.string(),
+            target_type: z.string(),
+            relationship_type: z.string(),
+            description: z.string().optional(),
         },
-    }, async ({ source_name: srcName, source_type: srcType, target_name: tgtName, target_type: tgtType, relationship_type: relType, description: desc }) => {
-        const ws = loadWorkspace();
+        annotations: ANNOTATIONS.LOCAL_WRITE,
+    }, async ({ workspace_id: workspaceIdInput, source_name: srcName, source_type: srcType, target_name: tgtName, target_type: tgtType, relationship_type: relType, description: desc }) => {
+        const ws = await loadWorkspace(workspaceIdInput);
         if (!ws.ok) {
-            return errorResponse(`Workspace not found: ${ws.reason}`);
+            return workspaceNotFoundResponse(ws.reason);
         }
-        const { storage } = await createAdapters(ws.root);
+        const { storage, workspaceId } = await createAdapters(ws.workspaceId);
         try {
             await storage.initialize();
-            await storage.saveGraphEntities([
+            await storage.saveGraphEntities(workspaceId, [
                 { name: srcName, type: srcType, properties: {} },
                 { name: tgtName, type: tgtType, properties: {} },
             ]);
-            const entityResult = await storage.query('SELECT id, name, type FROM graph_entities WHERE (name = $1 AND type = $2) OR (name = $3 AND type = $4)', [srcName, srcType, tgtName, tgtType]);
+            const entityResult = await storage.queryForWorkspace(workspaceId, `SELECT id, name, type FROM graph_entities WHERE workspace_id = $1 AND ((name = $2 AND type = $3) OR (name = $4 AND type = $5))`, [srcName, srcType, tgtName, tgtType]);
             const srcEntity = entityResult.rows.find((r) => r['name'] === srcName && r['type'] === srcType);
             const tgtEntity = entityResult.rows.find((r) => r['name'] === tgtName && r['type'] === tgtType);
-            if (!srcEntity || !tgtEntity) {
-                await storage.close();
+            if (srcEntity === undefined || tgtEntity === undefined) {
                 return errorResponse('Failed to create entities');
             }
-            await storage.saveGraphRelationships([{
+            await storage.saveGraphRelationships(workspaceId, [{
                     sourceId: srcEntity['id'],
                     targetId: tgtEntity['id'],
                     type: relType,
                     weight: 1,
                     source: 'claude',
-                    properties: desc ? { description: desc } : {},
+                    properties: hasText(desc) ? { description: desc } : {},
                 }]);
-            await storage.close();
-            return textResponse(`Added: ${srcName} —[${relType}]→ ${tgtName}${desc ? ` (${desc})` : ''}`);
+            return textResponse(`Added: ${srcName} —[${relType}]→ ${tgtName}${hasText(desc) ? ` (${desc})` : ''}`);
         }
         catch (err) {
-            await storage.close();
             return errorResponse(`Add relationship failed: ${getErrorMessage(err)}`);
         }
     });
     server.registerTool('root_cause_analysis', {
-        description: 'Trace root cause chain for a bug. Returns confirmed causes (from Jira issue links), probable causes (from git timeline — PRs merged before bug creation that touched same modules), and Claude-identified causes. Requires graph data — run `argustack graph build` first.',
+        title: 'Root cause analysis',
+        description: 'Trace root cause chain for a bug — confirmed, probable, claude-identified causes.',
         inputSchema: {
-            issue_key: z.string().describe('Bug issue key (e.g. "PROJ-500")'),
+            workspace_id: workspaceIdParam,
+            issue_key: z.string(),
         },
-    }, async ({ issue_key: issueKey }) => {
-        const ws = loadWorkspace();
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ workspace_id: workspaceIdInput, issue_key: issueKey }) => {
+        const ws = await loadWorkspace(workspaceIdInput);
         if (!ws.ok) {
-            return errorResponse(`Workspace not found: ${ws.reason}`);
+            return workspaceNotFoundResponse(ws.reason);
         }
-        const { storage } = await createAdapters(ws.root);
+        const { storage, workspaceId } = await createAdapters(ws.workspaceId);
         try {
             await storage.initialize();
-            const entityResult = await storage.query('SELECT id FROM graph_entities WHERE name = $1 LIMIT 1', [issueKey]);
+            const entityResult = await storage.queryForWorkspace(workspaceId, `SELECT id FROM graph_entities WHERE workspace_id = $1 AND name = $2 LIMIT 1`, [issueKey]);
             if (entityResult.rows.length === 0) {
-                await storage.close();
-                return textResponse(`No graph data for "${issueKey}". Run "argustack graph build" first.`);
+                return textResponse(`No graph data for "${issueKey}".`);
             }
             const entityId = entityResult.rows[0]?.['id'];
-            const relsResult = await storage.query(`SELECT r.type, r.source, r.properties, r.weight,
+            const relsResult = await storage.queryForWorkspace(workspaceId, `SELECT r.type, r.source, r.properties, r.weight,
                   se.name AS source_name, se.type AS source_type, se.properties AS source_props
            FROM graph_relationships r
-           JOIN graph_entities se ON se.id = r.source_id
-           WHERE r.target_id = $1
+           JOIN graph_entities se ON se.workspace_id = r.workspace_id AND se.id = r.source_id
+           WHERE r.workspace_id = $1
+             AND r.target_id = $2
              AND r.type IN ('root_causes', 'probably_caused_by', 'blocked_by', 'caused_by')
            ORDER BY r.type, r.weight DESC`, [entityId]);
             const rows = relsResult.rows;
+            if (rows.length === 0) {
+                return textResponse(`No root cause data for "${issueKey}".`);
+            }
             const confirmed = rows.filter((r) => r.source === 'auto' && (r.type === 'root_causes' || r.type === 'blocked_by'));
             const probable = rows.filter((r) => r.source === 'auto' && r.type === 'probably_caused_by');
             const claudeIdentified = rows.filter((r) => r.source === 'claude');
-            if (rows.length === 0) {
-                await storage.close();
-                return textResponse(`No root cause data for "${issueKey}". ` +
-                    'Try: check issue links in Jira, or investigate with issue_timeline.');
-            }
             const lines = [`# Root Cause Analysis: ${issueKey}`, ''];
             const formatRow = (r) => {
                 const props = r.properties;
@@ -416,7 +403,7 @@ export function registerGraphTools(server) {
             }
             if (probable.length > 0) {
                 lines.push(`## Probable Causes (${String(probable.length)})`);
-                lines.push('*From git timeline — PRs merged shortly before bug creation*');
+                lines.push('*From git timeline*');
                 for (const r of probable) {
                     lines.push(formatRow(r));
                 }
@@ -430,41 +417,39 @@ export function registerGraphTools(server) {
                 }
                 lines.push('');
             }
-            await storage.close();
             return textResponse(lines.join('\n'));
         }
         catch (err) {
-            await storage.close();
             return errorResponse(`Root cause analysis failed: ${getErrorMessage(err)}`);
         }
     });
     server.registerTool('add_observation', {
-        description: 'Add a text note/observation to any entity in the knowledge graph. Append only — never overwrites existing observations. Use to record: key decisions with WHY, root cause analysis, business process descriptions, out-of-scope decisions. Survives graph rebuild.',
+        title: 'Add graph observation',
+        description: 'Append a note to a graph entity.',
         inputSchema: {
-            entity_name: z.string().describe('Entity name (e.g. "ORG-16999", "Refund Flow", "Dmitry Kislitsyn")'),
-            content: z.string().describe('Observation text (e.g. "After refund, must sync to OrgMeter within same business day")'),
+            workspace_id: workspaceIdParam,
+            entity_name: z.string(),
+            content: z.string(),
         },
-    }, async ({ entity_name: entityName, content }) => {
-        const ws = loadWorkspace();
+        annotations: ANNOTATIONS.LOCAL_WRITE,
+    }, async ({ workspace_id: workspaceIdInput, entity_name: entityName, content }) => {
+        const ws = await loadWorkspace(workspaceIdInput);
         if (!ws.ok) {
-            return errorResponse('Workspace not found: ' + ws.reason);
+            return workspaceNotFoundResponse(ws.reason);
         }
-        const { storage } = await createAdapters(ws.root);
+        const { storage, workspaceId } = await createAdapters(ws.workspaceId);
         try {
             await storage.initialize();
-            const entityResult = await storage.query('SELECT id FROM graph_entities WHERE name = $1 LIMIT 1', [entityName]);
+            const entityResult = await storage.queryForWorkspace(workspaceId, `SELECT id FROM graph_entities WHERE workspace_id = $1 AND name = $2 LIMIT 1`, [entityName]);
             if (entityResult.rows.length === 0) {
-                await storage.close();
-                return errorResponse('Entity "' + entityName + '" not found. Run "argustack graph build" first, or create it via add_relationship.');
+                return errorResponse(`Entity "${entityName}" not found in workspace ${workspaceId}.`);
             }
             const entityId = entityResult.rows[0]?.['id'];
-            await storage.saveGraphObservation(entityId, content, 'claude');
-            const allObs = await storage.getObservations(entityId);
-            await storage.close();
+            await storage.saveGraphObservation(workspaceId, entityId, content, 'claude');
+            const allObs = await storage.getObservations(workspaceId, entityId);
             return textResponse(`Added observation to "${entityName}". Total observations: ${String(allObs.length)}`);
         }
         catch (err) {
-            await storage.close();
             return errorResponse(`Add observation failed: ${getErrorMessage(err)}`);
         }
     });