@loicngr/kobo 1.5.2 → 1.5.4

package/README.md

@@ -15,6 +15,7 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 - **Live agent output** — stream `stdout`/`stderr` from Claude Code to the browser via WebSocket, with persisted event replay on reconnect
 - **Task & acceptance criteria tracking** — the agent reports progress through a dedicated MCP server (`kobo-tasks`) that reads and updates tasks directly from the SQLite database
 - **Notion integration** — pull workspace missions straight from Notion pages, extract markdown, and use it as the source of truth for acceptance criteria
+- **Sentry integration** — paste a Sentry issue URL to spin up a dedicated "fix workspace" with the stacktrace, tags, and offending spans written to `.ai/thoughts/SENTRY-<id>.md`; the agent is primed with a TDD fix workflow and has access to the Sentry MCP tools for deeper digging
 - **Per-workspace dev servers** — start/stop Docker or Node dev servers scoped to each branch, with log streaming
 - **Conventional-commit enforcement** — project-level git conventions are written to `.ai/.git-conventions.md` inside every workspace so Claude follows them during commits
 - **Pull request automation** — one-click `push`, `pull`, and `open-pr` endpoints integrate with the GitHub CLI, using a configurable prompt template
@@ -41,6 +42,7 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 - Optional: Docker (if you configure per-workspace dev servers)
 - Optional: `gh` CLI (if you use the PR automation)
 - Optional: a Notion integration token (only if you want to import workspace missions from Notion pages — see [Notion integration](#notion-integration))
+- Optional: a Sentry auth token (only if you want to create fix workspaces from Sentry issue URLs — see [Sentry integration](#sentry-integration))
 
 ### Run via `npx` (recommended)
 
@@ -137,6 +139,51 @@ If you need to pin a specific version of the Notion MCP server, use a fork, or a
 
 Without a valid token configured, the Notion import field in the workspace creation form will return an error when you click **Refresh** or submit a Notion URL — the rest of Kōbō (workspaces, agents, tasks, Git integration) keeps working independently.
 
+## Sentry integration
+
+Kōbō can turn a Sentry issue into a dedicated "fix workspace" — you paste the issue URL at workspace creation and Kōbō extracts the stacktrace, culprit, tags, offending spans and extra context, writes them as a local markdown file inside the worktree (`.ai/thoughts/SENTRY-<id>.md`), and primes the Claude agent with a TDD fix workflow that points at that file. The agent also keeps access to the Sentry MCP tools (`search_issue_events`, `get_issue_tag_values`, `get_sentry_resource`) so it can dig deeper on its own. **This feature is opt-in and reuses the Sentry MCP configuration you already have for Claude Code** — Kōbō does not manage a Sentry token separately.
+
+Under the hood, Kōbō spawns the official [`@sentry/mcp-server`](https://www.npmjs.com/package/@sentry/mcp-server) as a child process using the exact `command`, `args`, and `env` from your `~/.claude.json`, then calls `get_sentry_resource` over stdio. No token handling inside Kōbō — if you change the token or the host in your Claude Code config, Kōbō follows automatically.
+
+### Getting a Sentry auth token
+
+1. In Sentry, go to **Settings → Developer Settings → Custom Integrations** (or **User Auth Tokens** for personal use)
+2. Create a token with at least these scopes: `project:read`, `event:read`, `org:read`
+3. Copy the token (format `sntryu_...` for user tokens)
+
+### Configuring the Sentry MCP in Claude Code
+
+The recommended setup is to register the Sentry MCP once in Claude Code — Kōbō picks it up automatically:
+
+```bash
+claude mcp add sentry -s user \
+  -e SENTRY_ACCESS_TOKEN=sntryu_your_token_here \
+  -e SENTRY_HOST=your-org.sentry.io \
+  -- npx -y @sentry/mcp-server@latest
+```
+
+For self-hosted Sentry, set `SENTRY_HOST` to your Sentry hostname (e.g. `sentry.mycompany.com`).
+
+### How Kōbō picks the entry
+
+Kōbō reads `~/.claude.json` and uses the first entry under `mcpServers` whose key contains `sentry` (case-insensitive) **and is not disabled**. This means:
+
+- A single `sentry` entry → used as-is
+- Multiple entries whose key contains `sentry` → the first matching non-disabled key wins
+- Toggle `"disabled": true` on an entry to make Kōbō skip it
+
+### Usage
+
+1. In the workspace creation form, click **Import Sentry**
+2. Paste the issue URL (e.g. `https://your-org.sentry.io/issues/112081699`)
+3. Submit — Kōbō extracts the issue, writes `.ai/thoughts/SENTRY-<numericId>.md`, creates a `Fix: <title>` task, and boots the agent with the fix workflow
+
+The Sentry issue Short-ID (e.g. `ACME-API-3` — the canonical identifier Sentry assigns to each issue) is used as the ticket prefix for the working branch (e.g. `fix/ACME-API-3--slow-db-query` or `bugfix/ACME-API-3--slow-db-query`, depending on the branch prefix you chose at creation). The Short-ID is also what Sentry recognises in commit messages like `Fixes ACME-API-3` to auto-close the issue on merge. The local copy of the issue is written to `.ai/thoughts/SENTRY-<shortId>.md` (e.g. `SENTRY-ACME-API-3.md`). When Sentry is active, the description field becomes optional — the extracted context is enough to start work.
+
+If the MCP server is slow to initialize (e.g. cold `npx` fetch, self-hosted host validation), bump the handshake timeout with `KOBO_MCP_INIT_TIMEOUT_MS` (default: `30000`).
+
+Without a valid Sentry MCP configured in `~/.claude.json`, the Sentry import field returns a clear error when you submit — the rest of Kōbō keeps working.
+
 ## Recommended: Superpowers plugin for Claude Code
 
 For the best experience, we recommend installing the [**superpowers**](https://github.com/obra/superpowers) plugin in Claude Code. Kōbō is designed to work well with it out of the box:

package/dist/server/index.js

@@ -12,6 +12,7 @@ import gitRouter from './routes/git.js';
 import imagesRouter from './routes/images.js';
 import notionRouter from './routes/notion.js';
 import plansRouter from './routes/plans.js';
+import sentryRouter from './routes/sentry.js';
 import settingsRouter from './routes/settings.js';
 import templatesRouter from './routes/templates.js';
 import workspacesRouter from './routes/workspaces.js';
@@ -47,6 +48,7 @@ app.get('/api/health', (c) => c.json({ status: 'ok', version: getPackageVersion(
 app.route('/api/workspaces', workspacesRouter);
 app.route('/api/workspaces', imagesRouter);
 app.route('/api/notion', notionRouter);
+app.route('/api/sentry', sentryRouter);
 app.route('/api/git', gitRouter);
 app.route('/api/settings', settingsRouter);
 app.route('/api/dev-server', devServerRouter);

package/dist/server/routes/sentry.js

@@ -0,0 +1,20 @@
+import { Hono } from 'hono';
+import { extractSentryIssue } from '../services/sentry-service.js';
+/** Hono sub-router for Sentry issue extraction (preflight). */
+const app = new Hono();
+// POST /api/sentry/extract — extract a Sentry issue by URL
+app.post('/extract', async (c) => {
+    try {
+        const body = await c.req.json();
+        if (!body.url) {
+            return c.json({ error: 'Missing required field: url' }, 400);
+        }
+        const content = await extractSentryIssue(body.url);
+        return c.json(content);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+export default app;

package/dist/server/routes/settings.js

@@ -24,6 +24,17 @@ app.get('/global', (c) => {
         return c.json({ error: message }, 500);
     }
 });
+// GET /api/settings/mcp-servers — list active MCP servers from Claude config
+app.get('/mcp-servers', (c) => {
+    try {
+        const servers = settingsService.listActiveClaudeMcpServers();
+        return c.json(servers);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
 // PUT /api/settings/global — update global settings
 app.put('/global', async (c) => {
     try {

package/dist/server/routes/workspaces.js

@@ -9,6 +9,7 @@ import * as agentManager from '../services/agent-manager.js';
 import * as devServerService from '../services/dev-server-service.js';
 import * as notionService from '../services/notion-service.js';
 import { renderPrTemplate } from '../services/pr-template-service.js';
+import * as sentryService from '../services/sentry-service.js';
 import * as settingsService from '../services/settings-service.js';
 import { runSetupScript } from '../services/setup-script-service.js';
 import * as terminalService from '../services/terminal-service.js';
@@ -52,6 +53,7 @@ app.post('/', async (c) => {
             permissionMode: body.permissionMode || globalSettings.defaultPermissionMode || 'plan',
         });
         let notionContent = null;
+        let sentryContent = null;
         // Extract Notion page content if a URL was provided
         if (body.notionUrl) {
             workspaceService.updateWorkspaceStatus(workspace.id, 'extracting');
@@ -63,6 +65,23 @@ app.post('/', async (c) => {
                 console.error(`[workspaces] Failed to extract Notion page: ${message}`);
             }
         }
+        // Extract Sentry issue content if a URL was provided. Done early (before
+        // worktree creation) so the issue ID can be injected into the branch name.
+        if (body.sentryUrl) {
+            workspaceService.updateWorkspaceStatus(workspace.id, 'extracting');
+            try {
+                sentryContent = await sentryService.extractSentryIssue(body.sentryUrl);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                console.error(`[workspaces] Failed to extract Sentry issue: ${message}`);
+            }
+        }
+        // Update workspace name with Sentry issue title if the user did not provide
+        // a custom name and Notion hasn't already filled it.
+        if (sentryContent?.title && !notionContent?.title && workspace.name === 'workspace') {
+            workspace = workspaceService.updateWorkspaceName(workspace.id, sentryContent.title);
+        }
         // Create tasks from extracted Notion data
         if (notionContent) {
             let sortOrder = 0;
@@ -116,14 +135,16 @@ app.post('/', async (c) => {
         // then falls back to a TK-XXXX pattern anywhere in the workspace name.
         // The worktree has not been created yet, so a DB update is sufficient.
         {
-            const detectedTicketId = notionContent?.ticketId || workspace.name.match(/[A-Z]+-\d+/i)?.[0];
+            // Sentry's canonical identifier is the issue short-ID (e.g. "ACME-API-3"),
+            // which is what Sentry auto-close recognises in commit messages.
+            const detectedTicketId = notionContent?.ticketId || sentryContent?.issueId || workspace.name.match(/[A-Z]+-\d+/i)?.[0];
             if (detectedTicketId && !workingBranch.toLowerCase().includes(detectedTicketId.toLowerCase())) {
                 const ticketPrefix = detectedTicketId.toUpperCase();
                 const slashIdx = workingBranch.indexOf('/');
                 const typePrefix = slashIdx >= 0 ? workingBranch.slice(0, slashIdx + 1) : 'feature/';
-                // Use Notion title or workspace name for the slug — both have proper accented
+                // Use Notion/Sentry title or workspace name for the slug — all have proper accented
                 // characters that NFD normalization can transliterate (é→e, ç→c, etc.)
-                const titleSource = notionContent?.title || workspace.name;
+                const titleSource = notionContent?.title || sentryContent?.title || workspace.name;
                 const titleSlug = titleSource
                     .normalize('NFD')
                     .replace(/[\u0300-\u036f]/g, '')
@@ -262,6 +283,57 @@ app.post('/', async (c) => {
                 console.error('[workspaces] Failed to save Notion content:', err);
             }
         }
+        // --- Sentry file + task (extraction already done before worktree creation) --
+        let sentryFilePath = null;
+        if (sentryContent) {
+            try {
+                const thoughtsDir = path.join(worktreePath, '.ai', 'thoughts');
+                fs.mkdirSync(thoughtsDir, { recursive: true });
+                // File is named SENTRY-<shortId>.md (e.g. SENTRY-ACME-API-3.md) — the
+                // Short-ID is the canonical Sentry identifier. Falls back to the numeric
+                // ID if the Short-ID could not be parsed from the MCP response.
+                const idForFile = sentryContent.issueId || sentryContent.issueNumericId;
+                sentryFilePath = path.join(thoughtsDir, `SENTRY-${idForFile}.md`);
+                const today = new Date().toISOString().split('T')[0];
+                const tags = sentryContent.tags;
+                const env = tags.environment ?? 'unknown';
+                const tagsBlock = Object.entries(tags)
+                    .map(([k, v]) => `- ${k}: ${v}`)
+                    .join('\n') || '- (none)';
+                const spansBlock = sentryContent.offendingSpans.length > 0 ? sentryContent.offendingSpans.map((s) => `- ${s}`).join('\n') : 'N/A';
+                const extra = sentryContent.extraContext || 'N/A';
+                const md = `# Fix: ${sentryContent.title || sentryContent.issueId || sentryContent.issueNumericId}\n\n` +
+                    `## Source\n` +
+                    `- Sentry: ${body.sentryUrl}\n` +
+                    `- Issue Short-ID: ${sentryContent.issueId} (use in commit messages for auto-close)\n` +
+                    `- Issue numeric ID: ${sentryContent.issueNumericId}\n` +
+                    `- Retrieved: ${today}\n\n` +
+                    `## Summary\n` +
+                    `- **Culprit**: ${sentryContent.culprit}\n` +
+                    `- **Platform**: ${sentryContent.platform}\n` +
+                    `- **Environment**: ${env}\n` +
+                    `- **Occurrences**: ${sentryContent.occurrences} (first: ${sentryContent.firstSeen}, last: ${sentryContent.lastSeen})\n\n` +
+                    `## Tags\n${tagsBlock}\n\n` +
+                    `## Error Detail / Offending Spans\n${spansBlock}\n\n` +
+                    `## Additional Context\n${extra}\n\n` +
+                    `## MCP Tools for deeper analysis\n` +
+                    `If you need more context, the following Sentry MCP tools are available:\n` +
+                    `- \`mcp__sentry__get_sentry_resource(url, resourceType)\` — fetch the issue, breadcrumbs, replay, or trace\n` +
+                    `- \`mcp__sentry__search_issue_events(organizationSlug, issueId='${sentryContent.issueId}')\` — recent events for this issue\n` +
+                    `- \`mcp__sentry__get_issue_tag_values(organizationSlug, issueId='${sentryContent.issueId}', key)\` — filter by tag (environment, user, browser, …)\n`;
+                fs.writeFileSync(sentryFilePath, md, 'utf-8');
+                workspaceService.createTask(workspace.id, {
+                    title: `Fix: ${sentryContent.title || sentryContent.issueId || `Sentry #${sentryContent.issueNumericId}`}`,
+                    isAcceptanceCriterion: false,
+                    sortOrder: 9999,
+                });
+            }
+            catch (err) {
+                console.error('[workspaces] Failed to save Sentry content:', err);
+                sentryFilePath = null;
+            }
+        }
+        // ------------------------------------------------------------------------
         // Update Notion status if both property name and value are configured
         const notionStatusProp = effectiveSettings.notionStatusProperty;
         const notionTargetStatus = effectiveSettings.notionInProgressStatus;
@@ -299,6 +371,24 @@ app.post('/', async (c) => {
                 brainstormPrompt += `\nNotion ticket: ${body.notionUrl}`;
                 brainstormPrompt += `\nLocal copy: ${notionFilePath}\n`;
             }
+            if (sentryFilePath && sentryContent) {
+                brainstormPrompt += `\nSentry issue: ${body.sentryUrl}`;
+                brainstormPrompt += `\nIssue Short-ID: ${sentryContent.issueId} (canonical, use in commit messages for auto-close)`;
+                brainstormPrompt += `\nIssue numeric ID: ${sentryContent.issueNumericId}`;
+                brainstormPrompt += `\nLocal copy: ${sentryFilePath}\n`;
+                brainstormPrompt +=
+                    `\nFix workflow:\n` +
+                        `1. Read the local Sentry file above for full context\n` +
+                        `2. Locate the bug from the stacktrace / culprit\n` +
+                        `3. Write a failing test that reproduces the bug (TDD)\n` +
+                        `4. Implement the minimal fix\n` +
+                        `5. Confirm the test passes, run related tests\n` +
+                        `6. Commit referencing the Sentry Short-ID (e.g. "fix(scope): description (${sentryContent.issueId})") — Sentry auto-closes the issue when the commit is merged\n` +
+                        `\nIf you need more context, Sentry MCP tools are available:\n` +
+                        `- mcp__sentry__get_sentry_resource(url, resourceType) — fetch the issue, breadcrumbs, replay or trace\n` +
+                        `- mcp__sentry__search_issue_events(organizationSlug, issueId='${sentryContent.issueId}') — recent events\n` +
+                        `- mcp__sentry__get_issue_tag_values(organizationSlug, issueId='${sentryContent.issueId}', key) — filter by tag\n`;
+            }
             if (todos.length > 0) {
                 brainstormPrompt += `\nTasks:\n${todos.map((t) => `- [${t.status === 'done' ? 'x' : ' '}] ${t.title}`).join('\n')}\n`;
             }

package/dist/server/services/notion-service.js

@@ -1,16 +1,11 @@
-import { spawn } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { getPackageVersion } from '../utils/paths.js';
+import { callMcpTool, initializeMcp, readClaudeMcpEntry, spawnMcpProcess, unwrapMcpResult, } from '../utils/mcp-client.js';
+import { getGlobalSettings } from './settings-service.js';
 // Gherkin keywords (French and English)
 const GHERKIN_PATTERN = /^(Scénario|Étant donné|Quand|Alors|Scenario|Given|When|Then|Feature|Fonctionnalité|And|Et|But|Mais)/i;
 // Keywords that start a NEW scenario and must flush the current block.
 // NOTE: `Feature`/`Fonctionnalité` are top-level containers, not a new scenario,
 // so they stay attached to the first scenario rather than triggering a split.
 const SCENARIO_START_PATTERN = /^(Scénario|Scenario)/i;
-const nextRpcId = (() => {
-    let counter = 1;
-    return () => counter++;
-})();
 /**
  * Parse a Notion URL and extract the page_id in UUID format (with dashes).
  * Handles:
@@ -35,192 +30,51 @@ export function parseNotionUrl(url) {
     // Convert 32 hex chars to UUID format: 8-4-4-4-12
     return `${raw.slice(0, 8)}-${raw.slice(8, 12)}-${raw.slice(12, 16)}-${raw.slice(16, 20)}-${raw.slice(20)}`;
 }
-/** Send a JSON-RPC request to the MCP process and read the response (30s timeout). */
-export async function callMcpTool(mcpProcess, toolName, args) {
-    const id = nextRpcId();
-    const request = JSON.stringify({
-        jsonrpc: '2.0',
-        id,
-        method: 'tools/call',
-        params: {
-            name: toolName,
-            arguments: args,
-        },
-    });
-    return new Promise((resolve, reject) => {
-        if (!mcpProcess.stdin || !mcpProcess.stdout) {
-            reject(new Error('MCP process stdin/stdout not available'));
-            return;
-        }
-        let buffer = '';
-        const timeout = setTimeout(() => {
-            mcpProcess.stdout?.removeListener('data', onData);
-            mcpProcess.stdout?.removeListener('error', onError);
-            mcpProcess.kill();
-            reject(new Error(`callMcpTool('${toolName}') timed out after 30s`));
-        }, 30_000);
-        const onData = (chunk) => {
-            buffer += chunk.toString();
-            // Try to parse complete JSON lines
-            const lines = buffer.split('\n');
-            // Keep the last (potentially incomplete) line in the buffer
-            buffer = lines.pop() ?? '';
-            for (const line of lines) {
-                const trimmed = line.trim();
-                if (!trimmed)
-                    continue;
-                try {
-                    const parsed = JSON.parse(trimmed);
-                    if (parsed.id === id) {
-                        clearTimeout(timeout);
-                        mcpProcess.stdout?.removeListener('data', onData);
-                        mcpProcess.stdout?.removeListener('error', onError);
-                        if (parsed.error) {
-                            reject(new Error(`MCP tool '${toolName}' error: ${parsed.error.message} (code: ${parsed.error.code})`));
-                        }
-                        else {
-                            resolve(parsed.result);
-                        }
-                    }
-                }
-                catch {
-                    // Ignore JSON parse errors for partial lines
-                }
-            }
-        };
-        const onError = (err) => {
-            clearTimeout(timeout);
-            mcpProcess.stdout?.removeListener('data', onData);
-            reject(err);
-        };
-        mcpProcess.stdout.on('data', onData);
-        mcpProcess.stdout.once('error', onError);
-        mcpProcess.stdin.write(`${request}\n`);
-    });
-}
 /**
- * Read the Notion token from Claude Code's config file as a fallback.
+ * Read the Notion token from the user's Claude Code config as a fallback.
+ * Picks the first enabled `mcpServers` entry named `notion` (disabled entries
+ * are skipped). Returns an empty string when none is found.
  */
-function readNotionTokenFromClaudeConfig() {
-    try {
-        const homedir = process.env.HOME ?? process.env.USERPROFILE ?? '';
-        const configPath = `${homedir}/.claude.json`;
-        const raw = readFileSync(configPath, 'utf-8');
-        const config = JSON.parse(raw);
-        const mcpServers = config.mcpServers;
-        const notionServer = mcpServers?.notion;
-        return notionServer?.env?.NOTION_TOKEN ?? notionServer?.env?.NOTION_API_TOKEN ?? '';
-    }
-    catch {
-        return '';
+function readNotionMcpEntryFromClaudeConfig(preferredKey) {
+    const normalizedPreferred = preferredKey?.trim();
+    const match = normalizedPreferred
+        ? readClaudeMcpEntry((k) => k === normalizedPreferred)
+        : readClaudeMcpEntry((k) => k === 'notion');
+    if (!match) {
+        if (normalizedPreferred) {
+            throw new Error(`Notion MCP key '${normalizedPreferred}' not found or disabled in ~/.claude.json (mcpServers section)`);
+        }
+        return null;
     }
+    return match;
 }
-function spawnMcpProcess() {
-    const notionToken = process.env.NOTION_API_TOKEN ?? process.env.NOTION_TOKEN ?? readNotionTokenFromClaudeConfig();
-    const mcpCommand = process.env.NOTION_MCP_COMMAND ?? 'npx';
-    const mcpArgs = process.env.NOTION_MCP_ARGS
+export function buildNotionMcpConfig(preferredKey) {
+    const configEntry = readNotionMcpEntryFromClaudeConfig(preferredKey);
+    const configEnv = configEntry?.entry.env ?? {};
+    const notionToken = process.env.NOTION_API_TOKEN ??
+        process.env.NOTION_TOKEN ??
+        configEnv.NOTION_TOKEN ??
+        configEnv.NOTION_API_TOKEN ??
+        '';
+    const command = process.env.NOTION_MCP_COMMAND ?? configEntry?.entry.command ?? 'npx';
+    const args = process.env.NOTION_MCP_ARGS
         ? process.env.NOTION_MCP_ARGS.split(' ')
-        : ['-y', '@notionhq/notion-mcp-server'];
-    const mcpProcess = spawn(mcpCommand, mcpArgs, {
-        stdio: ['pipe', 'pipe', 'pipe'],
-        env: {
-            ...process.env,
-            OPENAPI_MCP_HEADERS: JSON.stringify({
-                Authorization: `Bearer ${notionToken}`,
-                'Notion-Version': '2022-06-28',
-            }),
-        },
-    });
-    mcpProcess.stderr?.on('data', (data) => {
-        // Silently consume stderr to avoid cluttering logs
-        const text = data.toString();
-        if (process.env.DEBUG_NOTION_MCP) {
-            console.error('[notion-mcp stderr]', text);
-        }
-    });
-    return mcpProcess;
-}
-/** Initialize the MCP server by sending an initialize handshake (10s timeout). */
-async function initializeMcp(mcpProcess) {
-    const id = nextRpcId();
-    const request = JSON.stringify({
-        jsonrpc: '2.0',
-        id,
-        method: 'initialize',
-        params: {
-            protocolVersion: '2024-11-05',
-            capabilities: {},
-            clientInfo: { name: 'kobo', version: getPackageVersion() },
-        },
-    });
-    await new Promise((resolve, reject) => {
-        if (!mcpProcess.stdin || !mcpProcess.stdout) {
-            reject(new Error('MCP process not ready'));
-            return;
-        }
-        let buffer = '';
-        const timeout = setTimeout(() => {
-            mcpProcess.stdout?.removeListener('data', onData);
-            mcpProcess.kill();
-            reject(new Error('initializeMcp timed out after 10s'));
-        }, 10_000);
-        const onData = (chunk) => {
-            buffer += chunk.toString();
-            const lines = buffer.split('\n');
-            buffer = lines.pop() ?? '';
-            for (const line of lines) {
-                const trimmed = line.trim();
-                if (!trimmed)
-                    continue;
-                try {
-                    const parsed = JSON.parse(trimmed);
-                    if (parsed.id === id) {
-                        clearTimeout(timeout);
-                        mcpProcess.stdout?.removeListener('data', onData);
-                        const initialized = JSON.stringify({
-                            jsonrpc: '2.0',
-                            method: 'notifications/initialized',
-                        });
-                        mcpProcess.stdin?.write(`${initialized}\n`);
-                        resolve();
-                    }
-                }
-                catch {
-                    // ignore
-                }
-            }
-        };
-        const onError = (err) => {
-            clearTimeout(timeout);
-            mcpProcess.stdout?.removeListener('data', onData);
-            reject(err);
-        };
-        mcpProcess.stdout.on('data', onData);
-        mcpProcess.stdout.once('error', onError);
-        mcpProcess.stdin.write(`${request}\n`);
-    });
-}
-/**
- * Unwrap MCP tool response.
- * MCP returns { content: [{ type: "text", text: "..." }] }
- * where text is a JSON-stringified API response.
- */
-function unwrapMcpResult(result) {
-    if (result && typeof result === 'object') {
-        const obj = result;
-        if (Array.isArray(obj.content)) {
-            const first = obj.content[0];
-            if (first?.type === 'text' && first.text) {
-                try {
-                    return JSON.parse(first.text);
-                }
-                catch {
-                    return first.text;
-                }
-            }
-        }
+        : (configEntry?.entry.args ?? ['-y', '@notionhq/notion-mcp-server']);
+    const env = {
+        ...process.env,
+        ...configEnv,
+    };
+    if (!env.OPENAPI_MCP_HEADERS && notionToken) {
+        env.OPENAPI_MCP_HEADERS = JSON.stringify({
+            Authorization: `Bearer ${notionToken}`,
+            'Notion-Version': '2022-06-28',
+        });
     }
-    return result;
+    return { command, args, env };
+}
+function spawnNotionMcp(preferredKey) {
+    const { command, args, env } = buildNotionMcpConfig(preferredKey);
+    return spawnMcpProcess(command, args, env);
 }
 function extractTextFromRichText(richText) {
     if (!Array.isArray(richText))
@@ -340,7 +194,8 @@ export function parseBlocks(blocks) {
  */
 export async function extractNotionPage(notionUrl) {
     const pageId = parseNotionUrl(notionUrl);
-    const mcpProcess = spawnMcpProcess();
+    const global = getGlobalSettings();
+    const mcpProcess = spawnNotionMcp(global.notionMcpKey);
     // Give the process a moment to start
     await new Promise((resolve, reject) => {
         const timeout = setTimeout(() => resolve(), 1000);
@@ -405,7 +260,8 @@ export async function extractNotionPage(notionUrl) {
 /** Update a status property on a Notion page. Best-effort, does not throw. */
 export async function updateNotionStatus(notionUrl, propertyName, statusValue) {
     const pageId = parseNotionUrl(notionUrl);
-    const mcpProcess = spawnMcpProcess();
+    const global = getGlobalSettings();
+    const mcpProcess = spawnNotionMcp(global.notionMcpKey);
     try {
         await new Promise((resolve, reject) => {
             const timeout = setTimeout(() => resolve(), 1000);