devsmind-mcp 2.2.0 → 2.3.0

package/dist/mcp/server.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEVSMIND_PORT = void 0;
+exports.DEVSMIND_INSTRUCTIONS = exports.DEVSMIND_PORT = void 0;
 exports.runHttpMcpServer = runHttpMcpServer;
 exports.runStdioMcpServer = runStdioMcpServer;
 exports.runMcpServer = runMcpServer;
@@ -53,8 +53,31 @@ const visualizer_1 = require("./visualizer");
 const indexer_1 = require("../db/indexer");
 const scanner_1 = require("../utils/scanner");
 const staging_1 = require("../db/staging");
+const analyze_1 = require("../db/analyze");
+const workflow_import_1 = require("../db/workflow-import");
 // ─── Port: devs→D(4)E(5)=45 + mind→M(13)=13 → 4513 ─────────────────────────
 exports.DEVSMIND_PORT = 4513;
+/**
+ * Sent to every MCP client at connection time via the protocol's `instructions`
+ * field (part of the initialize handshake) — the single source of truth for the
+ * cross-cutting workflow contract, independent of whatever the user did or didn't
+ * paste into a `devsmind rule` output. Keep this crisp: unlike a tool's own
+ * `description` (resent every call), this is easy for a long session to lose
+ * track of too, so it should carry only what's genuinely cross-cutting.
+ */
+exports.DEVSMIND_INSTRUCTIONS = `DevsMind is this team's persistent shared code memory — not a personal tool you reach for only when asked to search something. Every teammate's AI agent, in every session, reads from the SAME graph you are about to write to. There is no "your copy."
+
+If you skip recording a change, you are not skipping a formality. You are leaving the whole team's graph stale for every other AI agent that queries this code later — tomorrow, on a different task, in a different session. And the reasoning behind your change (why it was made, what ticket drove it, what was broken before, what you tried and rejected) exists ONLY in this conversation, right now. It is not in the diff. It is not in the commit message. If it isn't captured this turn, it is gone forever — no reindex, no log, no git blame can recover it later.
+
+Non-negotiable workflow:
+1. Before any filesystem search or file read: call search_nodes first. It searches names/reasoning and automatically falls back to a full code-content search if nothing matches — one call covers both, never start with grep.
+2. To read one function/class: call get_node_code instead of opening the file. It parses live from disk, so it's cheaper and always current.
+3. Before touching any function's signature: call get_node_graph. Git shows you what changed; it never shows you what depends on it. Find out before you break something, not after.
+4. Before refactoring: call get_node_history. Git blame tells you who and when; it never tells you why. The actual decision context only exists here.
+5. Stage as you go: call stage_change the moment you finish editing a node — one call per node, not per file, and never batched for later. On a long task, call commit_changes at natural checkpoints too (not only once at the very end) — waiting until the whole task is "done" is how staged work gets left uncommitted when a session runs long.
+6. Scope: stage_change is for source code only (functions/classes/logic) and will be REJECTED for stylesheets, markup, JSON/config, docs, images, or any other non-code asset. Do not stage those files — they have no callers/callees to resolve and only bloat the graph.
+7. When you start work that might relate to a multi-session feature, call workflow_list first. If a paused workflow's description looks related to what you're about to do, ask the user whether to resume it (workflow_resume) instead of starting fresh and silently losing its decision history — git blame never shows you a paused feature's prior context, only this does.
+8. If a workflow is active, commit_changes already logs a step for you from what you staged — you do NOT need a separate workflow_add_step call for the normal case. Only call workflow_add_step directly for something a commit doesn't cover (a decision with no code change, or a pending_tasks note).`;
 // Shared node-type taxonomy description, reused by update_history and stage_change.
 const NODE_TYPE_DESCRIPTION = 'The type of node. Be highly specific and framework-aware. Choose from the taxonomy below (or use a custom value if nothing fits).\n\n' +
     'UNIVERSAL: function | method | class | abstract_class | interface | type_alias | enum | constant | variable | module | namespace | decorator\n\n' +
@@ -142,7 +165,10 @@ function cleanup() {
  * Stateless — every call receives devmind_path and opens the db from there.
  */
 function createMcpServer() {
-    const server = new index_js_1.Server({ name: 'devsmind-server', version: '1.0.0' }, { capabilities: { tools: {} } });
+    const server = new index_js_1.Server({ name: 'devsmind-server', version: '1.0.0' }, {
+        capabilities: { tools: {} },
+        instructions: exports.DEVSMIND_INSTRUCTIONS
+    });
     // ── Tool Definitions ────────────────────────────────────────────────────────
     server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
         return {
@@ -193,7 +219,7 @@ function createMcpServer() {
                 },
                 {
                     name: 'get_node_code',
-                    description: "Get a single node's CURRENT source code, parsed live from its file on disk — token-efficient, since it returns only that function/class/route rather than the whole file. Call this instead of reading a file whenever you need one specific entity. Response fields: `source: \"live\"` means the code was read from disk and is current. `source: \"cached\"` means the symbol could not be located in its file (not a TS/JS file, or it was renamed/moved/deleted) so a possibly-stale cached snapshot was returned — verify it against the file before relying on it. `snapshot_outdated: true` means the stored graph has drifted from disk; re-stage the node with stage_change + commit_changes to bring the brain back in sync. To fetch a whole call flow at once, prefer get_node_graph with include_code instead of calling this repeatedly.",
+                    description: "Get a single node's CURRENT source code, parsed live from its file on disk — token-efficient, since it returns only that function/class/route rather than the whole file. Call this instead of reading a file whenever you need one specific entity: reading the raw file instead means the graph never learns you looked at it, so drift between what's recorded and what's actually on disk goes undetected. Response fields: `source: \"live\"` means the code was read from disk and is current. `source: \"cached\"` means the symbol could not be located in its file (not a TS/JS file, or it was renamed/moved/deleted) so a possibly-stale cached snapshot was returned — verify it against the file before relying on it. `snapshot_outdated: true` means the stored graph has drifted from disk; re-stage the node with stage_change + commit_changes to bring the brain back in sync. To fetch a whole call flow at once, prefer get_node_graph with include_code instead of calling this repeatedly.",
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -270,7 +296,7 @@ function createMcpServer() {
                 },
                 {
                     name: 'stage_change',
-                    description: 'Stage ONE changed code node (function/class/method/etc.) into a buffer without writing to the graph yet. Call this once for EVERY file/entity you touched during a task — passing only the code and reasoning; you do NOT reason about connections here. When you are done with all the files, call commit_changes ONCE — it creates every node, writes every history entry, and resolves all connections between them via local AST in a single pass (so a call from one changed file into another resolves correctly no matter which order you staged them). Staging is buffered on disk, so it survives a context reset. ⚠️ YOU MUST CALL commit_changes at the end, or nothing is written to the graph.',
+                    description: `Stage ONE changed code node (function/class/method/etc.) into a buffer, right after you finish editing it — don't wait until the whole task is done. Call once per NODE, not once per file: a file with 3 changed functions is 3 calls. SCOPE: source code only — ${Array.from(scanner_1.INDEXABLE_EXTENSIONS).sort().join(', ')}. Rejected for stylesheets, markup, JSON/config, docs, or other non-code assets (no callers/callees to resolve). Pass only code + reasoning; connections are resolved automatically by commit_changes, not by you. The \`reasoning\` (why, goal, what was broken, what ticket) exists nowhere else — capture it now, while it's still in context, not after the fact. Staging is buffered on disk and survives a context reset, but is inert until commit_changes runs.`,
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -288,7 +314,7 @@ function createMcpServer() {
                                     requirement: { type: 'string', description: 'Ticket / issue / user request ID if applicable' },
                                     previous_state: { type: 'string', description: 'What the code looked like before and why it was a problem' },
                                     decision: { type: 'string', description: 'Architectural or implementation decision and why' },
-                                    developer: { type: 'string', description: 'Name of the developer' },
+                                    developer: { type: 'string', description: 'Name of the developer (optional — if this project has a configured developer identity from `devsmind init`, it always overrides whatever is passed here, since the agent has no reliable way to know who the human actually is)' },
                                     model: { type: 'string', description: 'AI model name used' }
                                 },
                                 required: ['what_changed', 'why', 'goal']
@@ -303,7 +329,7 @@ function createMcpServer() {
                 },
                 {
                     name: 'commit_changes',
-                    description: 'Commit all buffered stage_change entries in one atomic pass: creates/updates every staged node, writes every history snapshot, then resolves all connections between the staged nodes (and into the existing graph) via local AST — auto-creating any referenced-but-missing target nodes. Clears the buffer on success. Call this exactly once after you have finished staging every file you touched.',
+                    description: 'Flush all buffered stage_change entries in one atomic pass: creates/updates every staged node, writes every history snapshot, resolves all connections via local AST (auto-creating any referenced-but-missing nodes), then clears the buffer. If a workflow is currently active, this ALSO auto-records a step on its timeline from the staged entries\' reasoning — you do not need a separate workflow_add_step call for the normal case. Call commit_changes at natural checkpoints — after a batch of related nodes, or when switching context — not only once at the very end of a long task; a checkpoint commit can\'t be forgotten the way a single end-of-task one can. Always call it again before ending the turn if anything is still staged: an uncommitted turn leaves the whole team\'s graph stale, not just yours.',
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -326,7 +352,7 @@ function createMcpServer() {
                 },
                 {
                     name: 'get_node_history',
-                    description: 'Get the full version history of a code node, including all past code snapshots and change reasoning.',
+                    description: 'Get the full version history of a code node, including all past code snapshots and change reasoning. Git blame tells you who and when; it never tells you why — the actual decision, ticket, and what was rejected only exists here. Skip this before refactoring and you risk re-breaking a bug that was already fixed once, or undoing a decision made for a reason you never saw.',
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -338,7 +364,7 @@ function createMcpServer() {
                 },
                 {
                     name: 'get_node_graph',
-                    description: 'Get a node\'s dependency graph — connected nodes and the relationships between them. Set direction:"out" AND include_code:true to pull an ENTIRE CALL FLOW in a single call: the starting node plus everything it transitively calls, each with its current source code read from disk. Use that combination whenever you are tracing how a request, endpoint, or feature flows through the codebase — it replaces a long chain of get_node_code calls with one round trip. Use direction:"in" to find every caller of a node (impact analysis before a change). If `code_truncated` is true in the response, the character budget ran out and `nodes_without_code` nodes came back with metadata but no code — fetch those individually with get_node_code, or raise code_char_budget.',
+                    description: 'Get a node\'s dependency graph — connected nodes and the relationships between them. Set direction:"out" AND include_code:true to pull an ENTIRE CALL FLOW in a single call: the starting node plus everything it transitively calls, each with its current source code read from disk. Use that combination whenever you are tracing how a request, endpoint, or feature flows through the codebase — it replaces a long chain of get_node_code calls with one round trip. Use direction:"in" to find every caller of a node before you change its signature — git shows you what changed, never what depends on it, so this is the only way to know what breaks before a teammate hits it. If `code_truncated` is true in the response, the character budget ran out and `nodes_without_code` nodes came back with metadata but no code — fetch those individually with get_node_code, or raise code_char_budget.',
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -364,12 +390,14 @@ function createMcpServer() {
                 },
                 {
                     name: 'search_nodes',
-                    description: 'Search node names, identifiers, or reasoning logs matching a query.',
+                    description: 'Search for code by name/id/reasoning first; if nothing matches, automatically falls back to a full code-content search (regex or substring) over every node\'s current code — so this is the ONE search tool to call, in ONE turn, whether the term is an identifier or only appears in the code body. Each result is tagged `matched_via: "identifier"` or `matched_via: "code"` so you know how it was found; code matches also include line-level `matches`, `match_count`, and `match_ratio`. Prefer this over grep/filesystem search — a raw grep finds text, but misses every bit of recorded reasoning behind why that code looks the way it does.',
                     inputSchema: {
                         type: 'object',
                         properties: {
                             devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
-                            query: { type: 'string', description: 'Search term or query string' }
+                            query: { type: 'string', description: 'Search term, substring, or (with is_regex) regex pattern' },
+                            is_regex: { type: 'boolean', description: 'Treat query as a regex pattern when falling back to code search (default: false)' },
+                            case_insensitive: { type: 'boolean', description: 'Case-insensitive code-fallback search (default: true)' }
                         },
                         required: ['devmind_path', 'query']
                     }
@@ -450,23 +478,24 @@ function createMcpServer() {
                         required: ['devmind_path', 'query']
                     }
                 },
+                // NOTE: `search_code` is intentionally NOT listed here anymore. `search_nodes` now
+                // falls back to the same code-content search automatically when the identifier
+                // match is empty, so there is no longer a reason to advertise two search tools.
+                // The handler below is retained so any direct/legacy call still works.
                 {
-                    name: 'search_code',
-                    description: 'Regex or string search over cached codebase code snapshots. Returns matches grouped by DevsMind Node ID, file path, and matching lines, along with matching statistics (ratio, count). Prefer this over direct grep search.',
+                    name: 'get_orphaned_nodes',
+                    description: 'Find disconnected code nodes in the graph that have no incoming or outgoing connections.',
                     inputSchema: {
                         type: 'object',
                         properties: {
-                            devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
-                            query: { type: 'string', description: 'Regex or substring pattern to search for in code' },
-                            is_regex: { type: 'boolean', description: 'Whether the query is a regex pattern (default: false)' },
-                            case_insensitive: { type: 'boolean', description: 'Perform case-insensitive search (default: true)' }
+                            devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' }
                         },
-                        required: ['devmind_path', 'query']
+                        required: ['devmind_path']
                     }
                 },
                 {
-                    name: 'get_orphaned_nodes',
-                    description: 'Find disconnected code nodes in the graph that have no incoming or outgoing connections.',
+                    name: 'get_visualizer_url',
+                    description: 'Get local URLs to open the interactive 2D and 3D code graph visualizer pages.',
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -476,8 +505,50 @@ function createMcpServer() {
                     }
                 },
                 {
-                    name: 'get_visualizer_url',
-                    description: 'Get local URLs to open the interactive 2D and 3D code graph visualizer pages.',
+                    name: 'analyze_graph',
+                    description: 'Run a local, zero-token health check on the graph: god entities (high fan-in/out), circular dependency cycles, orphaned nodes, dangling edges, duplicate/case-collision ids, history missing developer attribution, empty code snapshots, spurious/built-in nodes, missing files, git-detected renames, and git-tracked code files with zero graph nodes. Purely local SQLite/filesystem/git queries — no LLM calls. Call this periodically (or when the graph feels stale/wrong) instead of guessing why context looks off. Set fix:true to auto-apply only the SAFE fixes (soft-deprecate dead nodes, remove dangling edges, migrate detected renames) — everything else is report-only and needs a human or agent decision.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
+                            fix: { type: 'boolean', description: 'If true, applies safe automatic fixes (default: false — dry run/report only)' },
+                            god_entity_threshold: { type: 'number', description: 'Connection-degree threshold to flag a god entity (default: 15)' }
+                        },
+                        required: ['devmind_path']
+                    }
+                },
+                {
+                    name: 'workflow_create',
+                    description: 'Start a new persistent, cross-session workflow for a multi-day feature (e.g. "Wallet Integration"). Becomes the active workflow — call workflow_add_step as you make progress so the timeline survives session/context resets. Auto-pauses whatever workflow was previously active.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
+                            name: { type: 'string', description: 'Short human-readable name for the feature/workflow' },
+                            description: { type: 'string', description: 'Brief description of the goal — used by you (the agent) to judge whether a later task relates to this workflow' }
+                        },
+                        required: ['devmind_path', 'name', 'description']
+                    }
+                },
+                {
+                    name: 'workflow_add_step',
+                    description: 'Record a step in the currently active (or specified) workflow\'s timeline — a short note of progress, linked to the history_ids already created via stage_change/commit_changes rather than duplicating any code or reasoning. NOTE: commit_changes already auto-records a step from its staged entries whenever a workflow is active — you do NOT need to call this after every commit. Only call it directly for something a commit doesn\'t cover: a decision made without a code change, a note on what\'s still pending (pending_tasks), or a custom summary richer than the auto-generated one.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
+                            workflow_id: { type: 'string', description: 'Workflow to add this step to (optional — defaults to the currently active workflow)' },
+                            summary: { type: 'string', description: 'Short summary of what this step accomplished' },
+                            pending_tasks: { type: 'string', description: 'Optional note on what is still left to do' },
+                            history_ids: { type: 'array', items: { type: 'string' }, description: 'Optional history row ids (from stage_change/commit_changes results) this step covers' },
+                            session_id: { type: 'string', description: 'Optional session id grouping this step with related history entries' }
+                        },
+                        required: ['devmind_path', 'summary']
+                    }
+                },
+                {
+                    name: 'workflow_pause',
+                    description: 'Pauses the currently active workflow and clears the active pointer — use when switching to unrelated work, so the next workflow_list call surfaces it as resumable instead of leaving it silently abandoned.',
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -485,6 +556,139 @@ function createMcpServer() {
                         },
                         required: ['devmind_path']
                     }
+                },
+                {
+                    name: 'workflow_resume',
+                    description: 'Resumes a paused workflow, making it active again (auto-pausing whatever was active before).',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
+                            workflow_id: { type: 'string', description: 'The workflow id to resume' }
+                        },
+                        required: ['devmind_path', 'workflow_id']
+                    }
+                },
+                {
+                    name: 'workflow_list',
+                    description: 'List workflows (optionally filtered by status). Call this when starting work that MIGHT relate to a paused, multi-session feature — if a description looks related to the current task, ask the user whether to resume it (workflow_resume) instead of silently starting fresh and losing its prior decision history.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
+                            status: { type: 'string', enum: ['active', 'paused', 'completed'], description: 'Optional status filter (default: all)' }
+                        },
+                        required: ['devmind_path']
+                    }
+                },
+                {
+                    name: 'workflow_get_context',
+                    description: 'Get a workflow\'s full timeline in one call — every step (in order) plus every reference artifact\'s metadata (and optionally content). Call this right after resuming a workflow to instantly regain the feature\'s full context. For large/long-running workflows, prefer workflow_get_steps (paginated) + workflow_read_artifact (per artifact) instead.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
+                            workflow_id: { type: 'string', description: 'The workflow id to fetch context for' },
+                            include_artifact_content: { type: 'boolean', description: 'If true, embeds each artifact\'s file content inline in the response (default: false). Only use for small/short workflows — large workflows should use workflow_read_artifact per artifact instead.' }
+                        },
+                        required: ['devmind_path', 'workflow_id']
+                    }
+                },
+                {
+                    name: 'workflow_add_artifact',
+                    description: 'Save reference material (a spec excerpt, ticket description, API doc, search-result snippet) to a workflow — written to disk under .devmind/workflows/<id>/ and linked in the DB. Use this for material that informed the work but isn\'t part of the code graph itself.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
+                            workflow_id: { type: 'string', description: 'The target workflow id' },
+                            step_id: { type: 'string', description: 'Optional step id this artifact relates to' },
+                            type: { type: 'string', description: 'Artifact type, e.g. pm_doc, api_spec, web_snippet' },
+                            source_name: { type: 'string', description: 'Title/filename of the artifact source' },
+                            content: { type: 'string', description: 'Text or markdown content to save' }
+                        },
+                        required: ['devmind_path', 'workflow_id', 'type', 'source_name', 'content']
+                    }
+                },
+                {
+                    name: 'workflow_sync_retroactive',
+                    description: 'Backfill a workflow\'s timeline after a whole session went by without using workflow_add_step. You already have the session\'s transcript in your own context — extract the steps yourself and pass them here as structured data. This does NOT accept raw transcript text; DevsMind never runs its own LLM calls, so extraction has to happen on your side, which you can already do for free since you already read it.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
+                            workflow_id: { type: 'string', description: 'The workflow id to sync into' },
+                            steps: {
+                                type: 'array',
+                                description: 'Steps you extracted from the session, oldest first',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        summary: { type: 'string' },
+                                        pending_tasks: { type: 'string' },
+                                        history_ids: { type: 'array', items: { type: 'string' } }
+                                    },
+                                    required: ['summary']
+                                }
+                            }
+                        },
+                        required: ['devmind_path', 'workflow_id', 'steps']
+                    }
+                },
+                {
+                    name: 'workflow_import',
+                    description: 'Import existing flow/architecture docs (markdown files describing a feature — title, summary, implementation details) as paused, resumable workflows, so reference material a team already wrote lives where you already look (workflow_get_context) instead of scattered elsewhere. Re-importing the same file updates its workflow in place rather than duplicating it.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
+                            folder_path: { type: 'string', description: 'Folder to import every .md file from (one workflow per file)' },
+                            file_path: { type: 'string', description: 'A single .md file to import instead of a folder' }
+                        },
+                        required: ['devmind_path']
+                    }
+                },
+                {
+                    name: 'workflow_search',
+                    description: 'Search across ALL workflows\' step summaries, pending_tasks notes, and artifact source names for a keyword or phrase. Returns matching steps and artifacts grouped by workflow. Use this when you don\'t know which workflow to look in — one call finds relevant context across the entire project history. Set include_artifact_content:true to also scan inside artifact files (slower but more thorough).',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
+                            query: { type: 'string', description: 'Keyword or phrase to search for' },
+                            status: { type: 'string', enum: ['active', 'paused', 'completed'], description: 'Optional: only search within workflows of this status' },
+                            include_artifact_content: { type: 'boolean', description: 'If true, also searches inside artifact file contents and includes a snippet of the matching text (default: false)' }
+                        },
+                        required: ['devmind_path', 'query']
+                    }
+                },
+                {
+                    name: 'workflow_read_artifact',
+                    description: 'Read the full content of a single workflow artifact file. Use this after workflow_get_context or workflow_search returns an artifact you want to read — pass the artifact id. This avoids loading the full context dump just to read one reference doc.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
+                            workflow_id: { type: 'string', description: 'The workflow id that owns the artifact' },
+                            artifact_id: { type: 'string', description: 'The artifact id to read (from workflow_get_context or workflow_search results)' }
+                        },
+                        required: ['devmind_path', 'workflow_id', 'artifact_id']
+                    }
+                },
+                {
+                    name: 'workflow_get_steps',
+                    description: 'Read steps from a workflow with pagination support. Use last_n to get only the most recent N steps (recommended when resuming a long-running workflow — read the tail to catch up, not the full history). Alternatively use limit+offset for forward pagination.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
+                            workflow_id: { type: 'string', description: 'The workflow id to read steps from' },
+                            last_n: { type: 'number', description: 'Return only the last N steps (most recent). Recommended for catching up on long workflows.' },
+                            limit: { type: 'number', description: 'Max steps to return (for forward pagination with offset)' },
+                            offset: { type: 'number', description: 'Step offset for forward pagination (default: 0)' }
+                        },
+                        required: ['devmind_path', 'workflow_id']
+                    }
                 }
             ]
         };
@@ -550,8 +754,23 @@ function createMcpServer() {
                 }
                 case 'update_history': {
                     const devmindPath = resolveDevmindPath(args.devmind_path);
-                    const filePath = String(args.file_path);
+                    const rawFilePath = String(args.file_path);
                     const db = getDatabase(devmindPath);
+                    const workspaceRoot = path.dirname(devmindPath);
+                    const filePath = path.isAbsolute(rawFilePath) ? path.resolve(rawFilePath) : path.resolve(workspaceRoot, rawFilePath);
+                    if (!db.isPathAllowed(filePath)) {
+                        return {
+                            isError: true,
+                            content: [{
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        success: false,
+                                        error: `file_path resolves outside the project's configured repos — nothing was written.`,
+                                        resolved_path: filePath
+                                    })
+                                }]
+                        };
+                    }
                     // Single-shot path: stage one entry and commit it immediately, so a lone edit still
                     // gets its node, history, AND outgoing edges resolved via the shared commit logic.
                     const entry = {
@@ -701,9 +920,42 @@ function createMcpServer() {
                 }
                 case 'stage_change': {
                     const devmindPath = resolveDevmindPath(args.devmind_path);
+                    const rawFilePath = String(args.file_path);
+                    const ext = path.extname(rawFilePath).toLowerCase();
+                    if (!scanner_1.INDEXABLE_EXTENSIONS.has(ext)) {
+                        return {
+                            isError: true,
+                            content: [{
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        staged: false,
+                                        error: `'${ext || '(no extension)'}' is not a supported node file type — nothing was staged.`,
+                                        reason: 'DevsMind models functions, classes, and logic entities in source code. Stylesheets (.css/.scss/.less), markup, JSON/config, docs, and other non-code assets are intentionally out of scope, not oversights — staging them would only bloat the graph with nodes that have no callers/callees to resolve. Do not retry this file.',
+                                        supported_extensions: Array.from(scanner_1.INDEXABLE_EXTENSIONS).sort()
+                                    })
+                                }]
+                        };
+                    }
+                    const workspaceRoot = path.dirname(devmindPath);
+                    const filePath = path.isAbsolute(rawFilePath) ? path.resolve(rawFilePath) : path.resolve(workspaceRoot, rawFilePath);
+                    const stageDb = getDatabase(devmindPath);
+                    if (!stageDb.isPathAllowed(filePath)) {
+                        return {
+                            isError: true,
+                            content: [{
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        staged: false,
+                                        error: `file_path resolves outside the project's configured repos — nothing was staged.`,
+                                        reason: 'stage_change only accepts paths inside a repo this project knows about, to prevent staging/reading files outside the project.',
+                                        resolved_path: filePath
+                                    })
+                                }]
+                        };
+                    }
                     const entry = {
                         node_id: String(args.node_id),
-                        file_path: String(args.file_path),
+                        file_path: filePath,
                         code_snapshot: String(args.code_snapshot),
                         reasoning: args.reasoning,
                         name: args.name ? String(args.name) : undefined,
@@ -735,14 +987,28 @@ function createMcpServer() {
                     }
                     const summary = (0, staging_1.commitStagedChanges)(db, devmindPath, entries);
                     (0, staging_1.clearStaged)(devmindPath);
+                    // If a workflow is active, auto-record this commit as a step — the agent doesn't
+                    // need a separate workflow_add_step call for the common case. Call workflow_add_step
+                    // directly only when you want to attach pending_tasks or a richer custom summary.
+                    let workflowStepId = null;
+                    const activeWorkflow = db.getActiveWorkflow();
+                    if (activeWorkflow) {
+                        const step = db.addWorkflowStep(activeWorkflow.id, {
+                            summary: (0, staging_1.summarizeEntriesForWorkflow)(entries),
+                            historyIds: summary.history_ids
+                        });
+                        workflowStepId = step.id;
+                    }
                     return {
                         content: [{
                                 type: 'text',
                                 text: JSON.stringify({
                                     committed: true,
                                     message: `✅ Committed ${summary.nodes} node(s), ${summary.history_entries} history entr(ies), ${summary.edges_added} connection(s) resolved` +
-                                        (summary.missing_filled > 0 ? `, ${summary.missing_filled} missing node(s) auto-created.` : '.'),
-                                    ...summary
+                                        (summary.missing_filled > 0 ? `, ${summary.missing_filled} missing node(s) auto-created.` : '.') +
+                                        (workflowStepId ? ` Logged as a step on active workflow "${activeWorkflow.name}".` : ''),
+                                    ...summary,
+                                    workflow_step_id: workflowStepId
                                 }, null, 2)
                             }]
                     };
@@ -806,7 +1072,8 @@ function createMcpServer() {
                 case 'get_node_graph': {
                     const devmindPath = resolveDevmindPath(args.devmind_path);
                     const nodeId = String(args.node_id);
-                    const maxDepth = args.max_depth ? Number(args.max_depth) : 6;
+                    const rawMaxDepth = args.max_depth ? Number(args.max_depth) : 6;
+                    const maxDepth = Number.isFinite(rawMaxDepth) ? Math.min(10, Math.max(1, Math.trunc(rawMaxDepth))) : 6;
                     const direction = args.direction === 'out' || args.direction === 'in' || args.direction === 'both'
                         ? args.direction
                         : 'both';
@@ -823,8 +1090,10 @@ function createMcpServer() {
                 case 'search_nodes': {
                     const devmindPath = resolveDevmindPath(args.devmind_path);
                     const query = String(args.query);
+                    const isRegex = args.is_regex === true;
+                    const caseInsensitive = args.case_insensitive !== false;
                     const db = getDatabase(devmindPath);
-                    const results = db.searchNodes(query);
+                    const results = db.searchNodes(query, { is_regex: isRegex, case_insensitive: caseInsensitive });
                     return {
                         content: [{ type: 'text', text: JSON.stringify(results, null, 2) }]
                     };
@@ -919,6 +1188,127 @@ function createMcpServer() {
                             }]
                     };
                 }
+                case 'analyze_graph': {
+                    const devmindPath = resolveDevmindPath(args.devmind_path);
+                    const workspaceRoot = path.dirname(devmindPath);
+                    const db = getDatabase(devmindPath);
+                    const godEntityThreshold = args.god_entity_threshold ? Number(args.god_entity_threshold) : undefined;
+                    const report = (0, analyze_1.runAnalysis)(db, workspaceRoot, {
+                        fix: args.fix === true,
+                        godEntityThreshold: Number.isFinite(godEntityThreshold) ? godEntityThreshold : undefined
+                    });
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(report, null, 2) }]
+                    };
+                }
+                case 'workflow_create': {
+                    const devmindPath = resolveDevmindPath(args.devmind_path);
+                    const db = getDatabase(devmindPath);
+                    const workflow = db.createWorkflow(String(args.name), String(args.description));
+                    return { content: [{ type: 'text', text: JSON.stringify({ status: 'created', workflow }, null, 2) }] };
+                }
+                case 'workflow_add_step': {
+                    const devmindPath = resolveDevmindPath(args.devmind_path);
+                    const db = getDatabase(devmindPath);
+                    const workflowId = args.workflow_id ? String(args.workflow_id) : db.getActiveWorkflow()?.id;
+                    if (!workflowId) {
+                        return {
+                            isError: true,
+                            content: [{ type: 'text', text: JSON.stringify({ error: 'No active workflow and no workflow_id given. Call workflow_create or workflow_resume first, or pass workflow_id explicitly.' }) }]
+                        };
+                    }
+                    const step = db.addWorkflowStep(workflowId, {
+                        summary: String(args.summary),
+                        pendingTasks: args.pending_tasks ? String(args.pending_tasks) : undefined,
+                        historyIds: Array.isArray(args.history_ids) ? args.history_ids.map(String) : undefined,
+                        sessionId: args.session_id ? String(args.session_id) : undefined
+                    });
+                    return { content: [{ type: 'text', text: JSON.stringify({ status: 'added', step }, null, 2) }] };
+                }
+                case 'workflow_pause': {
+                    const devmindPath = resolveDevmindPath(args.devmind_path);
+                    const db = getDatabase(devmindPath);
+                    const paused = db.pauseWorkflow();
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(paused ? { status: 'paused', workflow: paused } : { status: 'no_active_workflow' }, null, 2) }]
+                    };
+                }
+                case 'workflow_resume': {
+                    const devmindPath = resolveDevmindPath(args.devmind_path);
+                    const db = getDatabase(devmindPath);
+                    const workflow = db.resumeWorkflow(String(args.workflow_id));
+                    return { content: [{ type: 'text', text: JSON.stringify({ status: 'active', workflow }, null, 2) }] };
+                }
+                case 'workflow_list': {
+                    const devmindPath = resolveDevmindPath(args.devmind_path);
+                    const db = getDatabase(devmindPath);
+                    const status = args.status === 'active' || args.status === 'paused' || args.status === 'completed' ? args.status : undefined;
+                    const workflows = db.listWorkflows(status);
+                    return { content: [{ type: 'text', text: JSON.stringify({ workflows }, null, 2) }] };
+                }
+                case 'workflow_get_context': {
+                    const devmindPath = resolveDevmindPath(args.devmind_path);
+                    const db = getDatabase(devmindPath);
+                    const context = db.getWorkflowContext(String(args.workflow_id), {
+                        includeArtifactContent: args.include_artifact_content === true
+                    });
+                    return { content: [{ type: 'text', text: JSON.stringify(context, null, 2) }] };
+                }
+                case 'workflow_add_artifact': {
+                    const devmindPath = resolveDevmindPath(args.devmind_path);
+                    const db = getDatabase(devmindPath);
+                    const artifact = db.addWorkflowArtifact(String(args.workflow_id), {
+                        stepId: args.step_id ? String(args.step_id) : undefined,
+                        type: String(args.type),
+                        sourceName: String(args.source_name),
+                        content: String(args.content)
+                    });
+                    return { content: [{ type: 'text', text: JSON.stringify({ status: 'added', artifact }, null, 2) }] };
+                }
+                case 'workflow_sync_retroactive': {
+                    const devmindPath = resolveDevmindPath(args.devmind_path);
+                    const db = getDatabase(devmindPath);
+                    const workflowId = String(args.workflow_id);
+                    const stepsInput = Array.isArray(args.steps) ? args.steps : [];
+                    const added = stepsInput.map((s) => db.addWorkflowStep(workflowId, {
+                        summary: String(s.summary),
+                        pendingTasks: s.pending_tasks ? String(s.pending_tasks) : undefined,
+                        historyIds: Array.isArray(s.history_ids) ? s.history_ids.map(String) : undefined
+                    }));
+                    return { content: [{ type: 'text', text: JSON.stringify({ status: 'synced', steps_added: added.length, steps: added }, null, 2) }] };
+                }
+                case 'workflow_import': {
+                    const devmindPath = resolveDevmindPath(args.devmind_path);
+                    const db = getDatabase(devmindPath);
+                    const result = (0, workflow_import_1.importWorkflowDocs)(db, args.folder_path ? String(args.folder_path) : undefined, args.file_path ? String(args.file_path) : undefined);
+                    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+                }
+                case 'workflow_search': {
+                    const devmindPath = resolveDevmindPath(args.devmind_path);
+                    const db = getDatabase(devmindPath);
+                    const status = args.status === 'active' || args.status === 'paused' || args.status === 'completed' ? args.status : undefined;
+                    const results = db.searchWorkflows(String(args.query), {
+                        include_artifact_content: args.include_artifact_content === true,
+                        status
+                    });
+                    return { content: [{ type: 'text', text: JSON.stringify({ results, total_workflows_matched: results.length }, null, 2) }] };
+                }
+                case 'workflow_read_artifact': {
+                    const devmindPath = resolveDevmindPath(args.devmind_path);
+                    const db = getDatabase(devmindPath);
+                    const result = db.readWorkflowArtifact(String(args.workflow_id), String(args.artifact_id));
+                    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+                }
+                case 'workflow_get_steps': {
+                    const devmindPath = resolveDevmindPath(args.devmind_path);
+                    const db = getDatabase(devmindPath);
+                    const steps = db.getWorkflowSteps(String(args.workflow_id), {
+                        last_n: args.last_n ? Number(args.last_n) : undefined,
+                        limit: args.limit ? Number(args.limit) : undefined,
+                        offset: args.offset ? Number(args.offset) : undefined
+                    });
+                    return { content: [{ type: 'text', text: JSON.stringify({ workflow_id: args.workflow_id, steps, count: steps.length }, null, 2) }] };
+                }
                 default:
                     throw new Error(`Tool not found: ${name}`);
             }