driftseal 0.2.0 → 0.3.0

package/README.md

@@ -12,7 +12,7 @@ Before an agent touches the code, DriftSeal records what this round will accompl
 seal intent → do the work → prove the result → close the round
 ```
 
-**One open intent. One declared proof. One durable trail.** No service, no database, no runtime dependencies—just a Node.js CLI and plain files that travel with the repo.
+**One open intent. One declared proof. One durable trail.** No service and no database—just local Node.js tools and plain files that travel with the repo.
 
 ## The problem is not speed. It is drift.
 
@@ -46,6 +46,44 @@ npm link
 
 The package includes `skills/use-driftseal`, an agent-agnostic companion skill that drives repository work through the complete DriftSeal loop while keeping decision records selective. Install or link it using your agent runtime’s skill discovery convention, then invoke `use-driftseal` by name.
 
+## Use DriftSeal through MCP
+
+The same package includes `driftseal-mcp`, a local stdio MCP server. It exposes
+structured tools for the complete intent and decision workflow while reusing the
+same locking, WAL, atomic-write, schema, and recovery implementation as the CLI.
+The server never shells out to `driftseal` and does not parse CLI output.
+
+Fix the server to one repository when starting it:
+
+```sh
+driftseal-mcp --root /absolute/path/to/repository
+```
+
+For Codex, add the installed command as a stdio MCP server:
+
+```sh
+codex mcp add driftseal -- driftseal-mcp --root /absolute/path/to/repository
+```
+
+The root is startup configuration, not a tool input. In MCP mode DriftSeal also
+ignores inherited `DRIFTSEAL_HOME` and `DRIFTSEAL_DECISION_HOME` overrides, so a
+tool call cannot redirect writes outside the selected repository.
+
+The v1 server provides:
+
+| MCP capability | Purpose |
+| --- | --- |
+| `driftseal_status`, `driftseal_log` | Read the current intent and intent history. |
+| `driftseal_begin`, `driftseal_end` | Open and honestly close a work round. |
+| `driftseal_decision_list`, `driftseal_decision_show` | Find and read MADR records. |
+| `driftseal_decision_add`, `driftseal_decision_update` | Add selective decisions and reconcile linked ones. |
+| `driftseal://intent/current` | Read the current intent as a JSON resource. |
+| `driftseal://intents/recent` | Read the ten most recent intents as a JSON resource. |
+| `driftseal://decisions` | Read the decision catalog as a JSON resource. |
+
+The companion skill remains important: MCP supplies controlled, structured
+operations; the skill teaches the agent when to use them and how to avoid drift.
+
 ## A work round
 
 Declare the round before changing files:

package/README.zh-CN.md

@@ -12,7 +12,7 @@ Agentic coding 可以很快。**DriftSeal 让这种快不以失控为代价。**
 封存 intent → 执行工作 → 证明结果 → 关闭本轮
 ```
 
-**一个 open intent，一份预先声明的验证标准，一条可靠留存的工作轨迹。** 不需要 service，不需要 database，也没有 runtime dependencies；只有一个 Node.js CLI，以及跟着 repo 一起走的普通文件。
+**一个 open intent，一份预先声明的验证标准，一条可靠留存的工作轨迹。** 不需要 service，也不需要 database；只有本地 Node.js tools，以及跟着 repo 一起走的普通文件。
 
 ## 真正麻烦的不是慢，而是偏航
 
@@ -46,6 +46,44 @@ npm link
 
 npm package 内含 `skills/use-driftseal`。这是一个不绑定特定 agent runtime 的配套 skill，会按完整 DriftSeal 闭环执行仓库任务，同时克制地使用 decision record。按照所用 agent runtime 的 skill discovery 约定安装或 link，之后通过名称 `use-driftseal` 调用即可。
 
+## 通过 MCP 使用 DriftSeal
+
+同一个 package 还提供本地 stdio MCP server：`driftseal-mcp`。它为完整的
+intent 与 decision 工作流提供结构化 tools，并与 CLI 复用同一套锁、WAL、
+atomic write、schema 和 recovery 实现。server 不会启动 `driftseal` 子进程，
+也不需要解析 CLI 输出。
+
+启动时把 server 固定到一个 repository：
+
+```sh
+driftseal-mcp --root /absolute/path/to/repository
+```
+
+在 Codex 中，可以把安装后的命令添加为 stdio MCP server：
+
+```sh
+codex mcp add driftseal -- driftseal-mcp --root /absolute/path/to/repository
+```
+
+root 只能在启动时配置，不是 tool input。MCP 模式也会忽略继承到进程中的
+`DRIFTSEAL_HOME` 和 `DRIFTSEAL_DECISION_HOME` override，因此 tool call 不能把
+写入重定向到所选 repository 之外。
+
+v1 server 提供：
+
+| MCP capability | 用途 |
+| --- | --- |
+| `driftseal_status`, `driftseal_log` | 读取当前 intent 和 intent 历史。 |
+| `driftseal_begin`, `driftseal_end` | 开启并诚实关闭一轮工作。 |
+| `driftseal_decision_list`, `driftseal_decision_show` | 查找并读取 MADR record。 |
+| `driftseal_decision_add`, `driftseal_decision_update` | 克制地增加 decision，并 reconcile 已关联的 decision。 |
+| `driftseal://intent/current` | 以 JSON resource 读取当前 intent。 |
+| `driftseal://intents/recent` | 以 JSON resource 读取最近十条 intent。 |
+| `driftseal://decisions` | 以 JSON resource 读取 decision catalog。 |
+
+配套 skill 仍然不可替代：MCP 提供受控、结构化的操作，skill 则告诉 agent
+何时使用这些操作，以及怎样避免 drift。
+
 ## 一轮标准工作流
 
 修改文件前，先声明这轮工作的目标：

package/bin/driftseal-mcp.js

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const { createApi, DECISION_STATUSES, END_STATUSES } = require('./driftseal.js');
+
+const SERVER_NAME = 'driftseal';
+const SERVER_VERSION = require('../package.json').version;
+
+function parseArguments(argv) {
+  let root = process.cwd();
+  for (let index = 0; index < argv.length; index++) {
+    const argument = argv[index];
+    if (argument === '--help' || argument === '-h') return { help: true, root };
+    if (argument === '--root') {
+      const value = argv[++index];
+      if (!value || value.startsWith('-')) throw new Error('--root requires a directory');
+      root = value;
+      continue;
+    }
+    if (argument.startsWith('--root=')) {
+      const value = argument.slice('--root='.length);
+      if (!value) throw new Error('--root requires a directory');
+      root = value;
+      continue;
+    }
+    throw new Error(`unknown argument: ${argument}`);
+  }
+  return { help: false, root };
+}
+
+function helpText() {
+  return `DriftSeal MCP server
+
+usage:
+  driftseal-mcp [--root <repository>]
+
+The server uses stdio transport and fixes all DriftSeal state to the selected
+repository. Tool calls cannot select another root.`;
+}
+
+function jsonText(value) {
+  return JSON.stringify(value, null, 2);
+}
+
+function success(structuredContent, summary) {
+  return {
+    structuredContent,
+    content: [{ type: 'text', text: summary || jsonText(structuredContent) }],
+  };
+}
+
+function failure(error) {
+  const message = error && error.message ? error.message : String(error);
+  return {
+    isError: true,
+    content: [{ type: 'text', text: `DriftSeal rejected the operation: ${message}` }],
+  };
+}
+
+function guarded(action) {
+  try {
+    return action();
+  } catch (error) {
+    return failure(error);
+  }
+}
+
+function registerTools(server, api, z) {
+  const intentRecord = z.object({
+    id: z.string(),
+    intent: z.string(),
+    verify: z.string().nullable(),
+    decisions: z.array(z.string()),
+    status: z.enum(END_STATUSES).or(z.literal('in_progress')),
+    note: z.string().nullable(),
+    verifyResult: z.string().nullable(),
+    beganAt: z.string(),
+    endedAt: z.string().nullable(),
+  });
+  const decisionRecord = z.object({
+    id: z.string(),
+    title: z.string(),
+    status: z.enum(DECISION_STATUSES),
+    file: z.string(),
+  });
+  const decisionWithContent = decisionRecord.extend({ content: z.string() });
+  const closedStatus = z.enum(END_STATUSES);
+  const decisionStatus = z.enum(DECISION_STATUSES);
+  const decisionId = z.string().regex(/^\d+$/, 'decision id must contain only digits');
+  const nonEmpty = z.string().trim().min(1);
+  const readOnly = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };
+  const localWrite = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
+
+  server.registerTool(
+    'driftseal_status',
+    {
+      title: 'Get current DriftSeal intent',
+      description:
+        'Inspect the one intent currently in progress before repository work or after context loss. Returns null when no intent is open.',
+      inputSchema: {},
+      outputSchema: { root: z.string(), intent: intentRecord.nullable() },
+      annotations: readOnly,
+    },
+    async () =>
+      guarded(() => {
+        const intent = api.status();
+        return success(
+          { root: api.root, intent },
+          intent ? `Intent ${intent.id} is ${intent.status}.` : 'No DriftSeal intent is in progress.'
+        );
+      })
+  );
+
+  server.registerTool(
+    'driftseal_begin',
+    {
+      title: 'Begin a DriftSeal intent',
+      description:
+        'Open one focused work-round intent before making repository changes. Fails if another intent is already open; close it explicitly first.',
+      inputSchema: {
+        intent: nonEmpty.describe('Outcome this work round will accomplish.'),
+        verify: nonEmpty.optional().describe('Exact command or outcome check that will prove completion.'),
+        decisions: z
+          .array(decisionId)
+          .default([])
+          .describe('Existing decision IDs this round may change or explicitly confirm.'),
+      },
+      outputSchema: { root: z.string(), intent: intentRecord },
+      annotations: localWrite,
+    },
+    async (input) =>
+      guarded(() => {
+        const intent = api.begin(input);
+        return success({ root: api.root, intent }, `Opened DriftSeal intent ${intent.id}.`);
+      })
+  );
+
+  server.registerTool(
+    'driftseal_end',
+    {
+      title: 'Close a DriftSeal intent',
+      description:
+        'Close the current work-round intent with an honest terminal status, note, and verification result. Linked decisions must be reconciled before completed or partial closure.',
+      inputSchema: {
+        id: z.string().optional().describe('Intent ID; omit to close the current open intent.'),
+        status: closedStatus.default('completed'),
+        note: nonEmpty.optional().describe('What actually happened in the round.'),
+        verifyResult: nonEmpty.optional().describe('Concise, honest result of the declared verification.'),
+      },
+      outputSchema: { root: z.string(), intent: intentRecord },
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    },
+    async (input) =>
+      guarded(() => {
+        const intent = api.end(input);
+        return success({ root: api.root, intent }, `Closed DriftSeal intent ${intent.id} as ${intent.status}.`);
+      })
+  );
+
+  server.registerTool(
+    'driftseal_log',
+    {
+      title: 'List DriftSeal intent history',
+      description:
+        'Review recent or complete DriftSeal intent history to re-anchor work and understand prior outcomes.',
+      inputSchema: { last: z.number().int().positive().max(100).optional() },
+      outputSchema: { root: z.string(), intents: z.array(intentRecord) },
+      annotations: readOnly,
+    },
+    async (input) =>
+      guarded(() => {
+        const intents = api.log(input);
+        return success({ root: api.root, intents }, `Found ${intents.length} DriftSeal intent records.`);
+      })
+  );
+
+  server.registerTool(
+    'driftseal_decision_list',
+    {
+      title: 'List DriftSeal decisions',
+      description:
+        'Find MADR decision records, optionally filtered by current status. Use this before showing or linking a decision.',
+      inputSchema: {
+        status: decisionStatus.optional(),
+        last: z.number().int().positive().max(100).optional(),
+      },
+      outputSchema: { root: z.string(), decisions: z.array(decisionRecord) },
+      annotations: readOnly,
+    },
+    async (input) =>
+      guarded(() => {
+        const decisions = api.decisionList(input);
+        return success({ root: api.root, decisions }, `Found ${decisions.length} DriftSeal decisions.`);
+      })
+  );
+
+  server.registerTool(
+    'driftseal_decision_show',
+    {
+      title: 'Show a DriftSeal decision',
+      description: 'Read one complete MADR decision record by stable numeric ID.',
+      inputSchema: { id: decisionId },
+      outputSchema: { root: z.string(), decision: decisionWithContent },
+      annotations: readOnly,
+    },
+    async ({ id }) =>
+      guarded(() => {
+        const decision = api.decisionShow({ id });
+        return success({ root: api.root, decision }, `Loaded DriftSeal decision ${decision.id}.`);
+      })
+  );
+
+  server.registerTool(
+    'driftseal_decision_add',
+    {
+      title: 'Add a DriftSeal decision',
+      description:
+        'Create a MADR record only for durable rationale, rejected paths, deferred choices, or costly-to-reverse decisions that Git and the intent log cannot recover.',
+      inputSchema: {
+        title: nonEmpty,
+        context: nonEmpty,
+        outcome: nonEmpty,
+        status: decisionStatus.default('accepted'),
+        drivers: z.array(nonEmpty).default([]),
+        options: z.array(nonEmpty).default([]),
+        consequences: z.array(nonEmpty).default([]),
+      },
+      outputSchema: { root: z.string(), decision: decisionWithContent },
+      annotations: localWrite,
+    },
+    async (input) =>
+      guarded(() => {
+        const decision = api.decisionAdd(input);
+        return success({ root: api.root, decision }, `Created DriftSeal decision ${decision.id}.`);
+      })
+  );
+
+  server.registerTool(
+    'driftseal_decision_update',
+    {
+      title: 'Reconcile a DriftSeal decision',
+      description:
+        'Reconcile one decision linked to the current open intent, updating or explicitly confirming its status with a history note.',
+      inputSchema: {
+        id: decisionId,
+        status: decisionStatus.optional(),
+        note: nonEmpty,
+      },
+      outputSchema: { root: z.string(), decision: decisionWithContent },
+      annotations: localWrite,
+    },
+    async (input) =>
+      guarded(() => {
+        const decision = api.decisionUpdate(input);
+        return success({ root: api.root, decision }, `Reconciled DriftSeal decision ${decision.id}.`);
+      })
+  );
+}
+
+function registerResources(server, api) {
+  const registerJson = (name, uri, title, description, read) => {
+    server.registerResource(
+      name,
+      uri,
+      { title, description, mimeType: 'application/json' },
+      async () => {
+        const value = read();
+        return { contents: [{ uri, mimeType: 'application/json', text: jsonText(value) }] };
+      }
+    );
+  };
+
+  registerJson(
+    'current-intent',
+    'driftseal://intent/current',
+    'Current DriftSeal intent',
+    'The work-round intent currently in progress for the fixed repository.',
+    () => ({ root: api.root, intent: api.status() })
+  );
+  registerJson(
+    'recent-intents',
+    'driftseal://intents/recent',
+    'Recent DriftSeal intents',
+    'The ten most recent work-round intent records for the fixed repository.',
+    () => ({ root: api.root, intents: api.log({ last: 10 }) })
+  );
+  registerJson(
+    'decision-catalog',
+    'driftseal://decisions',
+    'DriftSeal decision catalog',
+    'All MADR decision summaries for the fixed repository.',
+    () => ({ root: api.root, decisions: api.decisionList() })
+  );
+}
+
+async function createServer({ root }) {
+  const [{ McpServer }, { StdioServerTransport }, zod] = await Promise.all([
+    import('@modelcontextprotocol/sdk/server/mcp.js'),
+    import('@modelcontextprotocol/sdk/server/stdio.js'),
+    import('zod'),
+  ]);
+  const z = zod.z || zod.default || zod;
+  const api = createApi({ root: path.resolve(root), isolateStorage: true });
+  const server = new McpServer(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    {
+      instructions:
+        'Use driftseal_status before repository changes or after context loss. Open one focused intent with driftseal_begin before changes, then run the declared verification and close it honestly with driftseal_end. Reconcile every linked decision before completed or partial closure.',
+    }
+  );
+  registerTools(server, api, z);
+  registerResources(server, api);
+  return { server, transport: new StdioServerTransport(), root: api.root };
+}
+
+async function main() {
+  const options = parseArguments(process.argv.slice(2));
+  if (options.help) {
+    process.stdout.write(helpText() + '\n');
+    return;
+  }
+  const { server, transport } = await createServer(options);
+  await server.connect(transport);
+}
+
+module.exports = { createServer, helpText, parseArguments, registerResources, registerTools };
+
+if (require.main === module) {
+  main().catch((error) => {
+    const message = error && error.message ? error.message : String(error);
+    console.error(`driftseal-mcp: error: ${message}`);
+    process.exitCode = 1;
+  });
+}

package/bin/driftseal.js

@@ -40,6 +40,42 @@ const LOCK_STALE_MS = 30 * 60 * 1000;
 const LOCK_INIT_STALE_MS = 5 * 1000;
 const MAX_DECISION_SLUG_LENGTH = 180;
 
+class DriftSealError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'DriftSealError';
+  }
+}
+
+let activeOutput = null;
+
+function printLine(value = '') {
+  const text = String(value);
+  if (activeOutput) {
+    activeOutput.stdout += text + '\n';
+    return;
+  }
+  console.log(text);
+}
+
+function printError(value = '') {
+  const text = String(value);
+  if (activeOutput) {
+    activeOutput.stderr += text + '\n';
+    return;
+  }
+  console.error(text);
+}
+
+function writeOutput(value) {
+  const text = String(value);
+  if (activeOutput) {
+    activeOutput.stdout += text;
+    return;
+  }
+  process.stdout.write(text);
+}
+
 if (process.env._DRIFTSEAL_TEST_UMASK) {
   process.umask(Number.parseInt(process.env._DRIFTSEAL_TEST_UMASK, 8));
 }
@@ -176,7 +212,8 @@ function readEvents({ repairTail = false } = {}) {
     .map((line, i) => {
       try {
         return normalizeEvent(JSON.parse(line), i + 1);
-      } catch {
+      } catch (err) {
+        if (err instanceof DriftSealError) throw err;
         fail(`corrupt log line ${i + 1} in ${file}`);
       }
     });
@@ -928,8 +965,7 @@ function closeIntentAsEscape(events, record, requestedStatus, note, verifyResult
 }
 
 function fail(msg) {
-  console.error(`driftseal: error: ${msg}`);
-  process.exit(1);
+  throw new DriftSealError(msg);
 }
 
 function positiveInteger(value, flag) {
@@ -1005,6 +1041,32 @@ function render(rec) {
   return lines.join('\n');
 }
 
+function publicIntent(rec) {
+  if (!rec) return null;
+  return {
+    id: rec.id,
+    intent: rec.intent,
+    verify: rec.verify,
+    decisions: [...rec.decisions],
+    status: rec.status,
+    note: rec.note,
+    verifyResult: rec.verifyResult,
+    beganAt: rec.tsBegin,
+    endedAt: rec.tsEnd,
+  };
+}
+
+function publicDecision(decision, { includeContent = false } = {}) {
+  const record = {
+    id: decision.id,
+    title: decision.title,
+    status: decision.status,
+    file: decision.file,
+  };
+  if (includeContent) record.content = decision.content;
+  return record;
+}
+
 const INTENT_PROTOCOL_MARKER = '<!-- driftseal -->';
 const INTENT_PROTOCOL_END = '<!-- /driftseal -->';
 const DECISION_PROTOCOL_MARKER = '<!-- driftseal-decisions -->';
@@ -1232,19 +1294,21 @@ const commands = {
         'superseded by --force',
         null
       );
-      console.error(`driftseal: ${status} ${open.id}`);
+      printError(`driftseal: ${status} ${open.id}`);
     }
 
     const id = nextId(events);
-    appendEvent({
+    events.push(appendEvent({
       type: 'begin',
       id,
       ts: new Date().toISOString(),
       intent,
       verify: flags.verify || null,
       decisions,
-    });
-    console.log(id);
+    }));
+    const record = fold(events).find((candidate) => candidate.id === id);
+    printLine(id);
+    return publicIntent(record);
   },
 
   end(argv) {
@@ -1279,8 +1343,9 @@ const commands = {
         flags.note,
         flags['verify-result']
       );
-      console.log(`${target.id} ${terminalStatus}`);
-      return;
+      const record = fold(events).find((candidate) => candidate.id === target.id);
+      printLine(`${target.id} ${terminalStatus}`);
+      return publicIntent(record);
     }
 
     if (['completed', 'partial'].includes(status) && target.decisions.length > 0) {
@@ -1317,15 +1382,17 @@ const commands = {
       }
     }
 
-    appendEvent({
+    events.push(appendEvent({
       type: 'end',
       id: target.id,
       ts: new Date().toISOString(),
       status,
       note: flags.note || null,
       verifyResult: flags['verify-result'] || null,
-    });
-    console.log(`${target.id} ${status}`);
+    }));
+    const record = fold(events).find((candidate) => candidate.id === target.id);
+    printLine(`${target.id} ${status}`);
+    return publicIntent(record);
   },
 
   status(argv) {
@@ -1333,10 +1400,11 @@ const commands = {
     if (positionals.length > 0) fail('usage: driftseal status');
     const open = openIntent(fold(readEvents({ repairTail: true })));
     if (!open) {
-      console.log('no intent in progress');
-      return;
+      printLine('no intent in progress');
+      return null;
     }
-    console.log(render(open));
+    printLine(render(open));
+    return publicIntent(open);
   },
 
   log(argv) {
@@ -1348,10 +1416,11 @@ const commands = {
       records = records.slice(-n);
     }
     if (records.length === 0) {
-      console.log('log is empty');
-      return;
+      printLine('log is empty');
+      return [];
     }
-    console.log(records.map(render).join('\n\n'));
+    printLine(records.map(render).join('\n\n'));
+    return records.map(publicIntent);
   },
 
   decision(argv) {
@@ -1392,8 +1461,9 @@ const commands = {
       });
       ensureDirectoryDurable(decisionDir());
       atomicCreateFile(path.join(decisionDir(), file), content);
-      console.log(path.join(decisionDir(), file));
-      return;
+      const decision = findDecision(String(id));
+      printLine(path.join(decisionDir(), file));
+      return publicDecision(decision, { includeContent: true });
     }
 
     if (subcommand === 'update') {
@@ -1431,8 +1501,9 @@ const commands = {
         fail('simulated interruption after decision write');
       }
       appendEvent(reconciliationEvent('decision_reconcile_commit', update));
-      console.log(`${decision.id} ${update.fromStatus} -> ${update.toStatus} (${intent.id})`);
-      return;
+      const reconciled = findDecision(decision.id);
+      printLine(`${decision.id} ${update.fromStatus} -> ${update.toStatus} (${intent.id})`);
+      return publicDecision(reconciled, { includeContent: true });
     }
 
     if (subcommand === 'list') {
@@ -1448,8 +1519,8 @@ const commands = {
       }
       const index = decisionIndex();
       if (flags.count && !status) {
-        console.log(index.length);
-        return;
+        printLine(index.length);
+        return { count: index.length };
       }
       let records = decisionCatalog(!status && last ? index.slice(-last) : index);
       if (status) {
@@ -1457,19 +1528,19 @@ const commands = {
       }
       if (status && last) records = records.slice(-last);
       if (flags.count) {
-        console.log(records.length);
-        return;
+        printLine(records.length);
+        return { count: records.length };
       }
       if (records.length === 0) {
-        console.log(status ? `no decision records with status ${status}` : 'decision log is empty');
-        return;
+        printLine(status ? `no decision records with status ${status}` : 'decision log is empty');
+        return [];
       }
-      console.log(
+      printLine(
         records
           .map((record) => `[${record.id}] ${titleCase(record.status)} — ${record.title}\n  ${record.file}`)
           .join('\n')
       );
-      return;
+      return records.map(publicDecision);
     }
 
     if (subcommand === 'show') {
@@ -1478,8 +1549,8 @@ const commands = {
         fail('usage: driftseal decision show <id>');
       }
       const decision = findDecision(positionals[0]);
-      process.stdout.write(decision.content);
-      return;
+      writeOutput(decision.content);
+      return publicDecision(decision, { includeContent: true });
     }
 
     fail('usage: driftseal decision add|update|list|show (run: driftseal help)');
@@ -1539,15 +1610,16 @@ const commands = {
     }
 
     if (updated === current) {
-      console.log('AGENTS.md already contains the DriftSeal protocols; nothing to do');
-      return;
+      printLine('AGENTS.md already contains the DriftSeal protocols; nothing to do');
+      return { changed: false, target };
     }
     atomicWriteFile(target, updated);
-    console.log(`DriftSeal protocol ${existed ? 'updated in' : 'written to'} ${target}`);
+    printLine(`DriftSeal protocol ${existed ? 'updated in' : 'written to'} ${target}`);
+    return { changed: true, target };
   },
 
   help() {
-    console.log(`DriftSeal — Seal the intent. Stop the drift.
+    printLine(`DriftSeal — Seal the intent. Stop the drift.
 
 Intent-level write-ahead log for agent sessions.
 
@@ -1573,6 +1645,7 @@ decision add options:
 
 intent log: $DRIFTSEAL_HOME/events.jsonl, or .intent-log/events.jsonl
 decision log: $DRIFTSEAL_DECISION_HOME, or .decision-log/ in the current directory`);
+    return null;
   },
 };
 
@@ -1595,11 +1668,10 @@ function mutationResources(cmd, argv) {
   return [logDir(), decisionDir()];
 }
 
-function main() {
-  const [cmd, ...rest] = process.argv.slice(2);
+function dispatch(argv) {
+  const [cmd, ...rest] = argv;
   if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
-    commands.help();
-    process.exit(cmd ? 0 : 1);
+    return { data: commands.help(), exitCode: cmd ? 0 : 1 };
   }
   const fn = commands[cmd];
   if (!fn) fail(`unknown command: ${cmd} (run: driftseal help)`);
@@ -1609,10 +1681,144 @@ function main() {
   const readsIntentLog = ['status', 'log'].includes(cmd);
   if (mutates || readsIntentLog) {
     const resources = readsIntentLog ? [logDir()] : mutationResources(cmd, rest);
-    withMutationLocks(resources, () => fn(rest));
-  } else {
-    fn(rest);
+    return { data: withMutationLocks(resources, () => fn(rest)), exitCode: 0 };
   }
+  return { data: fn(rest), exitCode: 0 };
 }
 
-main();
+function repositoryRoot(root) {
+  if (typeof root !== 'string' || root.trim().length === 0) {
+    fail('repository root must be a non-empty path');
+  }
+  const resolved = path.resolve(root);
+  let stat;
+  try {
+    stat = fs.statSync(resolved);
+  } catch {
+    fail(`repository root does not exist: ${resolved}`);
+  }
+  if (!stat.isDirectory()) fail(`repository root is not a directory: ${resolved}`);
+  return fs.realpathSync(resolved);
+}
+
+function runCommand(argv, { root = process.cwd(), isolateStorage = false, capture = true } = {}) {
+  if (!Array.isArray(argv) || argv.some((arg) => typeof arg !== 'string')) {
+    fail('command arguments must be an array of strings');
+  }
+  if (capture && activeOutput) fail('nested captured DriftSeal commands are not supported');
+
+  const fixedRoot = repositoryRoot(root);
+  const previousCwd = process.cwd();
+  const previousIntentHome = process.env.DRIFTSEAL_HOME;
+  const previousDecisionHome = process.env.DRIFTSEAL_DECISION_HOME;
+  const output = { stdout: '', stderr: '', data: null, exitCode: 0 };
+  const previousOutput = activeOutput;
+
+  try {
+    process.chdir(fixedRoot);
+    if (isolateStorage) {
+      delete process.env.DRIFTSEAL_HOME;
+      delete process.env.DRIFTSEAL_DECISION_HOME;
+    }
+    if (capture) activeOutput = output;
+    const result = dispatch(argv);
+    output.data = result.data;
+    output.exitCode = result.exitCode;
+    return output;
+  } catch (err) {
+    if (capture) {
+      err.stdout = output.stdout;
+      err.stderr = output.stderr;
+    }
+    throw err;
+  } finally {
+    activeOutput = previousOutput;
+    process.chdir(previousCwd);
+    if (previousIntentHome === undefined) delete process.env.DRIFTSEAL_HOME;
+    else process.env.DRIFTSEAL_HOME = previousIntentHome;
+    if (previousDecisionHome === undefined) delete process.env.DRIFTSEAL_DECISION_HOME;
+    else process.env.DRIFTSEAL_DECISION_HOME = previousDecisionHome;
+  }
+}
+
+function appendFlag(argv, flag, value) {
+  if (value !== undefined && value !== null && value !== '') argv.push(flag, String(value));
+}
+
+function createApi({ root = process.cwd(), isolateStorage = false } = {}) {
+  const fixedRoot = repositoryRoot(root);
+  const call = (argv) => runCommand(argv, { root: fixedRoot, isolateStorage, capture: true }).data;
+  return Object.freeze({
+    root: fixedRoot,
+    status() {
+      return call(['status']);
+    },
+    begin({ intent, verify, decisions = [], force = false }) {
+      const argv = ['begin', intent];
+      appendFlag(argv, '--verify', verify);
+      for (const decision of decisions) appendFlag(argv, '--decision', decision);
+      if (force) argv.push('--force');
+      return call(argv);
+    },
+    end({ id, status, note, verifyResult } = {}) {
+      const argv = ['end'];
+      if (id) argv.push(String(id));
+      appendFlag(argv, '--status', status);
+      appendFlag(argv, '--note', note);
+      appendFlag(argv, '--verify-result', verifyResult);
+      return call(argv);
+    },
+    log({ last } = {}) {
+      const argv = ['log'];
+      appendFlag(argv, '--last', last);
+      return call(argv);
+    },
+    decisionAdd({ title, context, outcome, status, drivers = [], options = [], consequences = [] }) {
+      const argv = ['decision', 'add', title, '--context', context, '--outcome', outcome];
+      appendFlag(argv, '--status', status);
+      for (const driver of drivers) appendFlag(argv, '--driver', driver);
+      for (const option of options) appendFlag(argv, '--option', option);
+      for (const consequence of consequences) appendFlag(argv, '--consequence', consequence);
+      return call(argv);
+    },
+    decisionUpdate({ id, status, note }) {
+      const argv = ['decision', 'update', String(id), '--note', note];
+      appendFlag(argv, '--status', status);
+      return call(argv);
+    },
+    decisionList({ status, last, count = false } = {}) {
+      const argv = ['decision', 'list'];
+      appendFlag(argv, '--status', status);
+      appendFlag(argv, '--last', last);
+      if (count) argv.push('--count');
+      return call(argv);
+    },
+    decisionShow({ id }) {
+      return call(['decision', 'show', String(id)]);
+    },
+    init() {
+      return call(['init']);
+    },
+  });
+}
+
+function main() {
+  try {
+    const result = dispatch(process.argv.slice(2));
+    process.exitCode = result.exitCode;
+  } catch (err) {
+    const message = err && err.message ? err.message : String(err);
+    console.error(`driftseal: error: ${message}`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = {
+  DECISION_STATUSES,
+  END_STATUSES,
+  DriftSealError,
+  createApi,
+  runCommand,
+};
+
+if (require.main === module) main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftseal",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Seal intent, verification, and decisions into an auditable workflow for agentic coding",
   "keywords": [
     "driftseal",
@@ -25,7 +25,8 @@
   "type": "commonjs",
   "main": "index.js",
   "bin": {
-    "driftseal": "bin/driftseal.js"
+    "driftseal": "bin/driftseal.js",
+    "driftseal-mcp": "bin/driftseal-mcp.js"
   },
   "directories": {
     "test": "test"
@@ -42,5 +43,9 @@
   },
   "engines": {
     "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.4.3"
   }
 }

package/skills/use-driftseal/SKILL.md

@@ -11,15 +11,23 @@ activity streams.
 
 ## Locate DriftSeal
 
+- Prefer the `driftseal_*` MCP tools when the DriftSeal MCP server is available
+  for the target repository. Use `driftseal_status`, `driftseal_begin`,
+  `driftseal_end`, and the corresponding decision tools instead of invoking the
+  CLI through a shell.
 - Work from the repository root unless its instructions specify another scope.
-- Prefer `driftseal` from `PATH`. In a DriftSeal source checkout, fall back to
-  `node bin/driftseal.js` when the global command is unavailable.
-- Follow the repository's `AGENTS.md` and storage overrides such as `DRIFTSEAL_HOME`.
+- When MCP is unavailable, prefer `driftseal` from `PATH`. In a DriftSeal source
+  checkout, fall back to `node bin/driftseal.js` when the global command is
+  unavailable.
+- Follow the repository's `AGENTS.md`. Storage overrides such as
+  `DRIFTSEAL_HOME` apply to CLI use; the MCP server deliberately keeps state in
+  its fixed repository root.
 - If DriftSeal is unavailable, limit activity to read-only discovery and report the
   blocker. Do not mutate the repository without the required log.
 
-Use one command form consistently within a round. The examples below use
-`driftseal`; substitute the local source command when necessary.
+Use one interface consistently within a round. The examples below use
+`driftseal`; map them directly to the same-named MCP workflow when MCP is
+available, or substitute the local source command when necessary.
 
 ## Re-anchor Before Acting