@longtable/mcp 0.1.31 → 0.1.33

package/README.md

@@ -1,6 +1,7 @@
 # @longtable/mcp
 
-MCP transport for LongTable workspace state and Researcher Checkpoints.
+MCP transport for LongTable workspace state, `$longtable-interview`, and
+Researcher Checkpoints.
 
 This package does not own LongTable state. It exposes structured tools over the
 existing `.longtable/` source of truth.
@@ -14,7 +15,7 @@ longtable-state
 Run:
 
 ```bash
-npx -y @longtable/mcp@0.1.31
+npx -y @longtable/mcp@0.1.33
 ```
 
 Self-test:
@@ -32,5 +33,14 @@ longtable mcp install --provider codex --checkpoint-ui strong --write
 If MCP elicitation is unavailable or not approved, the server returns the same
 pending `QuestionRecord` as a numbered fallback.
 
-Provider guidance should use `elicit_question` first when the MCP tool is
-available. `longtable question --print` is only the CLI fallback transport.
+Provider guidance should use interview tools for `$longtable-interview`:
+
+- `create_workspace`
+- `begin_interview`
+- `append_interview_turn`
+- `summarize_interview`
+- `confirm_first_research_shape`
+
+For later Researcher Checkpoints, provider guidance should use
+`elicit_question` first when the MCP tool is available. `longtable
+question --print` is only the CLI fallback transport.

package/dist/first-research-shape.d.ts

@@ -0,0 +1,25 @@
+import type { QuestionOption } from "@longtable/core";
+export interface FirstResearchShape {
+    handle: string;
+    currentGoal: string;
+    currentBlocker?: string;
+    researchObject?: string;
+    gapRisk?: string;
+    protectedDecision?: string;
+    openQuestions: string[];
+    nextAction: string;
+    confidence: "low" | "medium" | "high";
+    sourceHookId?: string;
+    confirmedAt?: string;
+}
+export interface FirstResearchShapeQuestionSpec {
+    prompt: string;
+    title: string;
+    question: string;
+    checkpointKey: string;
+    options: QuestionOption[];
+    displayReason: string;
+}
+export declare function buildFirstResearchShapeQuestion(shape: FirstResearchShape): FirstResearchShapeQuestionSpec;
+export declare function firstResearchShapeAnswerConfirms(answer: string): boolean;
+export declare function firstResearchShapeAnswerStatus(answer: string): "confirmed" | "active" | "deferred";

package/dist/first-research-shape.js

@@ -0,0 +1,111 @@
+function questionTitle(shape) {
+    if (shape.protectedDecision) {
+        return "Protected Research Decision";
+    }
+    if (shape.currentBlocker) {
+        return "Main Unresolved Issue";
+    }
+    return "Emerging Research Direction";
+}
+function questionText(shape) {
+    if (shape.protectedDecision) {
+        return `Before LongTable moves forward, what should stay explicitly open about ${shape.protectedDecision}?`;
+    }
+    if (shape.currentBlocker) {
+        return "What should LongTable do with the main unresolved issue in this emerging study?";
+    }
+    if (shape.openQuestions.length > 0) {
+        return "What should LongTable keep explicit as the next research move?";
+    }
+    return "How should LongTable carry this emerging study forward?";
+}
+function displayReason(shape) {
+    if (shape.protectedDecision) {
+        return `The interview surfaced a protected decision: ${shape.protectedDecision}. LongTable should not let it settle silently.`;
+    }
+    if (shape.currentBlocker) {
+        return `The main blocker is still open: ${shape.currentBlocker}. The next move should make that uncertainty explicit.`;
+    }
+    if (shape.openQuestions.length > 0) {
+        return `The interview surfaced open research questions. Choose the next move that keeps the most important one visible.`;
+    }
+    return "LongTable has enough context to propose a provisional research direction, but the next research move should still be explicit.";
+}
+function recommendedValue(shape) {
+    if (shape.protectedDecision) {
+        return "protect_decision";
+    }
+    if (shape.confidence === "high" && !shape.currentBlocker) {
+        return "stabilize_shape";
+    }
+    if (shape.currentBlocker || shape.confidence === "low") {
+        return "gather_context";
+    }
+    return "stabilize_shape";
+}
+function baseOptions(shape) {
+    const recommended = recommendedValue(shape);
+    const options = [];
+    if (shape.protectedDecision) {
+        options.push({
+            value: "protect_decision",
+            label: `Keep ${shape.protectedDecision} open`,
+            description: "Treat this as the guarded judgment while the broader direction stays provisional.",
+            recommended: recommended === "protect_decision"
+        });
+    }
+    options.push({
+        value: "stabilize_shape",
+        label: "Use this as the provisional direction",
+        description: "Carry this research shape forward as the current working direction.",
+        recommended: recommended === "stabilize_shape"
+    }, {
+        value: "gather_context",
+        label: "Gather one more concrete case",
+        description: "Ask for one more scene, source, dataset, or example before stabilizing it.",
+        recommended: recommended === "gather_context"
+    }, {
+        value: "revise_shape",
+        label: "Revise the emerging shape",
+        description: "Change the handle, blocker, or next action before LongTable treats it as usable."
+    });
+    if (!shape.protectedDecision) {
+        options.push({
+            value: "keep_open",
+            label: "Keep the study open longer",
+            description: "Do not stabilize this direction yet."
+        });
+    }
+    return options;
+}
+export function buildFirstResearchShapeQuestion(shape) {
+    const summaryLines = [
+        "LongTable has enough context to propose a provisional research direction.",
+        `Handle: ${shape.handle}`,
+        `Goal: ${shape.currentGoal}`,
+        shape.currentBlocker ? `Blocker: ${shape.currentBlocker}` : undefined,
+        shape.protectedDecision ? `Protected decision: ${shape.protectedDecision}` : undefined,
+        shape.openQuestions.length > 0 ? `Open question: ${shape.openQuestions[0]}` : undefined,
+        `Next action: ${shape.nextAction}`
+    ].filter(Boolean);
+    return {
+        prompt: summaryLines.join("\n"),
+        title: questionTitle(shape),
+        question: questionText(shape),
+        checkpointKey: "first_research_shape_confirmation",
+        options: baseOptions(shape),
+        displayReason: displayReason(shape)
+    };
+}
+export function firstResearchShapeAnswerConfirms(answer) {
+    return answer === "stabilize_shape" || answer === "protect_decision";
+}
+export function firstResearchShapeAnswerStatus(answer) {
+    if (firstResearchShapeAnswerConfirms(answer)) {
+        return "confirmed";
+    }
+    if (answer === "keep_open") {
+        return "deferred";
+    }
+    return "active";
+}

package/dist/index.d.ts

@@ -1 +1,2 @@
+export * from "./first-research-shape.js";
 export * from "./server.js";

package/dist/index.js

@@ -1 +1,2 @@
+export * from "./first-research-shape.js";
 export * from "./server.js";

package/dist/server.js

@@ -1,6 +1,6 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
-import { resolve } from "node:path";
+import { basename, resolve } from "node:path";
 import { cwd, exit } from "node:process";
 import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -9,13 +9,20 @@ import { z } from "zod";
 import { classifyCheckpointTrigger } from "@longtable/checkpoints";
 import { renderQuestionRecordInput } from "@longtable/provider-claude";
 import { renderQuestionRecordPrompt } from "@longtable/provider-codex";
-import { answerWorkspaceQuestion, createWorkspaceQuestion, inspectProjectWorkspace, loadProjectContextFromDirectory, loadWorkspaceState, syncCurrentWorkspaceView } from "@longtable/cli";
+import { loadSetupOutput } from "@longtable/setup";
+import { answerWorkspaceQuestion, createOrUpdateProjectWorkspace, createWorkspaceQuestion, inspectProjectWorkspace, loadProjectContextFromDirectory, loadWorkspaceState, syncCurrentWorkspaceView } from "@longtable/cli";
+import { buildFirstResearchShapeQuestion, firstResearchShapeAnswerConfirms, firstResearchShapeAnswerStatus } from "./first-research-shape.js";
 const SERVER_NAME = "longtable-state";
-const SERVER_VERSION = "0.1.31";
+const SERVER_VERSION = "0.1.33";
 const TOOL_NAMES = [
     "read_project",
     "read_session",
     "inspect_workspace",
+    "create_workspace",
+    "begin_interview",
+    "append_interview_turn",
+    "summarize_interview",
+    "confirm_first_research_shape",
     "pending_questions",
     "evaluate_checkpoint",
     "create_question",
@@ -33,6 +40,19 @@ const questionOptionSchema = z.object({
     description: z.string().optional(),
     recommended: z.boolean().optional()
 });
+const firstResearchShapeSchema = z.object({
+    handle: z.string().min(1),
+    currentGoal: z.string().min(1),
+    currentBlocker: z.string().optional(),
+    researchObject: z.string().optional(),
+    gapRisk: z.string().optional(),
+    protectedDecision: z.string().optional(),
+    openQuestions: z.array(z.string().min(1)).default([]),
+    nextAction: z.string().min(1),
+    confidence: z.enum(["low", "medium", "high"]).default("medium"),
+    sourceHookId: z.string().optional(),
+    confirmedAt: z.string().optional()
+});
 function textResult(structuredContent) {
     return {
         content: [
@@ -65,6 +85,260 @@ async function requireContext(startPath) {
     }
     return context;
 }
+function createId(prefix) {
+    return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function asInterviewState(state) {
+    return state;
+}
+function isInterviewHookRun(hook) {
+    return hook?.kind === "longtable_interview";
+}
+function activeInterviewHook(state, hookId) {
+    const hooks = state.hooks ?? [];
+    if (hookId) {
+        const hook = hooks.find((candidate) => candidate.id === hookId);
+        return isInterviewHookRun(hook) ? hook : undefined;
+    }
+    return [...hooks].reverse().find((hook) => hook.kind === "longtable_interview" &&
+        (hook.status === "pending" || hook.status === "active" || hook.status === "ready_to_confirm"));
+}
+function upsertInterviewHook(state, hook) {
+    const hooks = state.hooks ?? [];
+    const nextHooks = hooks.some((candidate) => candidate.id === hook.id)
+        ? hooks.map((candidate) => candidate.id === hook.id ? hook : candidate)
+        : [...hooks, hook];
+    return {
+        ...state,
+        hooks: nextHooks
+    };
+}
+function upsertQuestionObligation(state, obligation) {
+    const current = state.questionObligations ?? [];
+    const next = current.some((entry) => entry.id === obligation.id)
+        ? current.map((entry) => entry.id === obligation.id ? obligation : entry)
+        : [...current, obligation];
+    return {
+        ...state,
+        questionObligations: next
+    };
+}
+function ensureFirstResearchShapeObligation(state, shape, options) {
+    const existing = (state.questionObligations ?? []).find((obligation) => obligation.kind === "first_research_shape_confirmation" &&
+        obligation.status === "pending" &&
+        obligation.sourceHookId === shape.sourceHookId);
+    if (!existing) {
+        return upsertQuestionObligation(state, {
+            id: createId("question_obligation"),
+            kind: "first_research_shape_confirmation",
+            status: "pending",
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            prompt: options.prompt,
+            reason: options.reason,
+            ...(shape.sourceHookId ? { sourceHookId: shape.sourceHookId } : {}),
+            ...(options.questionId ? { questionId: options.questionId } : {})
+        });
+    }
+    return upsertQuestionObligation(state, {
+        ...existing,
+        updatedAt: new Date().toISOString(),
+        prompt: options.prompt,
+        reason: options.reason,
+        ...(options.questionId ? { questionId: options.questionId } : existing.questionId ? { questionId: existing.questionId } : {}),
+        ...(shape.sourceHookId ? { sourceHookId: shape.sourceHookId } : {})
+    });
+}
+function resolveFirstResearchShapeObligation(state, options) {
+    return {
+        ...state,
+        questionObligations: (state.questionObligations ?? []).map((obligation) => {
+            const matches = obligation.kind === "first_research_shape_confirmation" && ((options.sourceHookId && obligation.sourceHookId === options.sourceHookId) ||
+                (options.questionId && obligation.questionId === options.questionId));
+            if (!matches || obligation.status !== "pending") {
+                return obligation;
+            }
+            return {
+                ...obligation,
+                status: options.status ?? "satisfied",
+                updatedAt: new Date().toISOString(),
+                ...(options.questionId ? { questionId: options.questionId } : obligation.questionId ? { questionId: obligation.questionId } : {}),
+                ...(options.decisionId ? { decisionId: options.decisionId } : obligation.decisionId ? { decisionId: obligation.decisionId } : {})
+            };
+        })
+    };
+}
+function interviewDepth(turns) {
+    const usableTurns = turns.filter((turn) => turn.quality !== "thin").length;
+    if (usableTurns >= 3)
+        return "ready_to_summarize";
+    if (usableTurns >= 1)
+        return "forming_first_handle";
+    return "gathering_context";
+}
+function normalizeInterviewQuality(answer, quality) {
+    if (quality)
+        return quality;
+    const trimmed = answer.trim();
+    const wordCount = trimmed.split(/\s+/).filter(Boolean).length;
+    if (trimmed.length < 12 || wordCount < 3)
+        return "thin";
+    if (trimmed.length > 80 || wordCount >= 12)
+        return "rich";
+    return "usable";
+}
+function defaultFollowUpQuestion(answer) {
+    return answer.trim().length < 12
+        ? "Say one more sentence about where this problem appears or why it matters before LongTable tries to classify it."
+        : "What concrete scene, case, material, text, dataset, or decision would make that problem easier to inspect first?";
+}
+async function beginInterviewHook(context, options) {
+    const state = asInterviewState(await loadWorkspaceState(context));
+    const existing = activeInterviewHook(state);
+    if (existing) {
+        return { hook: existing, state };
+    }
+    const timestamp = new Date().toISOString();
+    const hook = {
+        id: createId("hook_interview"),
+        kind: "longtable_interview",
+        status: "active",
+        createdAt: timestamp,
+        updatedAt: timestamp,
+        targetOutcome: "first_research_handle",
+        depth: "gathering_context",
+        provider: options.provider,
+        turns: [],
+        qualityNotes: [],
+        rationale: [
+            "Official LongTable research start surface is provider-native `$longtable-interview`, not the CLI start questionnaire."
+        ]
+    };
+    const updated = upsertInterviewHook(state, hook);
+    updated.workingState = {
+        ...updated.workingState,
+        activeInterviewHookId: hook.id,
+        interviewSurface: "$longtable-interview",
+        ...(options.openingQuestion ? { interviewOpeningQuestion: options.openingQuestion } : {}),
+        ...(options.seedAnswer ? { interviewSeedAnswer: options.seedAnswer } : {})
+    };
+    await writeFile(context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
+    await syncCurrentWorkspaceView(context);
+    return { hook, state: updated };
+}
+async function appendInterviewTurn(context, options) {
+    const state = asInterviewState(await loadWorkspaceState(context));
+    const existing = activeInterviewHook(state, options.hookId);
+    if (!existing) {
+        throw new Error("No active LongTable interview hook was found. Run begin_interview first.");
+    }
+    const quality = normalizeInterviewQuality(options.answer, options.quality);
+    const needsFollowUp = options.needsFollowUp ?? quality === "thin";
+    const followUpQuestion = needsFollowUp
+        ? options.followUpQuestion ?? defaultFollowUpQuestion(options.answer)
+        : options.followUpQuestion;
+    const timestamp = new Date().toISOString();
+    const turn = {
+        id: createId("interview_turn"),
+        index: existing.turns.length + 1,
+        createdAt: timestamp,
+        question: options.question.trim(),
+        answer: options.answer.trim(),
+        ...(options.reflection?.trim() ? { reflection: options.reflection.trim() } : {}),
+        quality,
+        needsFollowUp,
+        ...(followUpQuestion?.trim() ? { followUpQuestion: followUpQuestion.trim() } : {}),
+        ...(options.rationale && options.rationale.length > 0 ? { rationale: options.rationale } : {})
+    };
+    const turns = [...existing.turns, turn];
+    const depth = interviewDepth(turns);
+    const hook = {
+        ...existing,
+        status: depth === "ready_to_summarize" ? "ready_to_confirm" : "active",
+        updatedAt: timestamp,
+        depth,
+        turns,
+        qualityNotes: [
+            ...existing.qualityNotes,
+            ...(needsFollowUp ? [`Turn ${turn.index} needs follow-up: ${followUpQuestion}`] : [])
+        ]
+    };
+    const updated = upsertInterviewHook(state, hook);
+    await writeFile(context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
+    await syncCurrentWorkspaceView(context);
+    return { hook, turn, state: updated };
+}
+async function summarizeInterviewHook(context, options) {
+    const state = asInterviewState(await loadWorkspaceState(context));
+    const existing = activeInterviewHook(state, options.hookId);
+    if (!existing) {
+        throw new Error("No active LongTable interview hook was found. Run begin_interview first.");
+    }
+    const timestamp = new Date().toISOString();
+    const shape = {
+        ...options.shape,
+        handle: options.shape.handle.trim(),
+        currentGoal: options.shape.currentGoal.trim(),
+        openQuestions: options.shape.openQuestions.map((question) => question.trim()).filter(Boolean),
+        nextAction: options.shape.nextAction.trim(),
+        sourceHookId: existing.id
+    };
+    const hook = {
+        ...existing,
+        status: "ready_to_confirm",
+        updatedAt: timestamp,
+        depth: "ready_to_summarize",
+        firstResearchShape: shape
+    };
+    const session = {
+        ...context.session,
+        lastUpdatedAt: timestamp,
+        currentGoal: shape.currentGoal,
+        ...(shape.currentBlocker ? { currentBlocker: shape.currentBlocker } : {}),
+        ...(shape.researchObject ? { researchObject: shape.researchObject } : {}),
+        ...(shape.gapRisk ? { gapRisk: shape.gapRisk } : {}),
+        ...(shape.protectedDecision ? { protectedDecision: shape.protectedDecision } : {}),
+        nextAction: shape.nextAction,
+        openQuestions: shape.openQuestions,
+        firstResearchShape: shape,
+        resumeHint: `I want to continue from the First Research Shape: ${shape.handle}.`
+    };
+    context.session = session;
+    const updated = upsertInterviewHook(state, hook);
+    updated.firstResearchShape = shape;
+    updated.workingState = {
+        ...updated.workingState,
+        currentGoal: shape.currentGoal,
+        ...(shape.currentBlocker ? { currentBlocker: shape.currentBlocker } : {}),
+        ...(shape.researchObject ? { researchObject: shape.researchObject } : {}),
+        ...(shape.gapRisk ? { gapRisk: shape.gapRisk } : {}),
+        ...(shape.protectedDecision ? { protectedDecision: shape.protectedDecision } : {}),
+        openQuestions: shape.openQuestions,
+        nextAction: shape.nextAction,
+        firstResearchShape: shape
+    };
+    if (shape.currentBlocker && !updated.openTensions.includes(shape.currentBlocker)) {
+        updated.openTensions.push(shape.currentBlocker);
+    }
+    updated.narrativeTraces.push({
+        id: createId("narrative_trace"),
+        timestamp,
+        source: "$longtable-interview",
+        traceType: "judgment",
+        summary: `First Research Shape: ${shape.handle}.`,
+        visibility: "explicit",
+        importance: shape.confidence
+    });
+    const questionSpec = buildFirstResearchShapeQuestion(shape);
+    const withObligation = ensureFirstResearchShapeObligation(updated, shape, {
+        prompt: questionSpec.question,
+        reason: questionSpec.displayReason
+    });
+    await writeFile(context.sessionFilePath, JSON.stringify(session, null, 2), "utf8");
+    await writeFile(context.stateFilePath, JSON.stringify(withObligation, null, 2), "utf8");
+    await syncCurrentWorkspaceView(context);
+    return { hook, shape, state: withObligation, session };
+}
 function findQuestion(records, questionId) {
     if (questionId) {
         return records.find((record) => record.id === questionId) ?? null;
@@ -77,7 +351,7 @@ function renderQuestionFallback(record, provider = "codex") {
         : renderQuestionRecordPrompt(record);
 }
 async function markQuestionTransport(context, questionId, status, message) {
-    const state = await loadWorkspaceState(context);
+    const state = asInterviewState(await loadWorkspaceState(context));
     let updatedQuestion = null;
     state.questionLog = (state.questionLog ?? []).map((record) => {
         if (record.id !== questionId) {
@@ -148,6 +422,51 @@ function acceptedAnswer(result) {
         answer
     };
 }
+async function markFirstResearchShapeConfirmation(context, shape, answer, questionId, decisionId) {
+    const state = asInterviewState(await loadWorkspaceState(context));
+    const timestamp = new Date().toISOString();
+    const confirmedShape = firstResearchShapeAnswerConfirms(answer)
+        ? { ...shape, confirmedAt: timestamp }
+        : shape;
+    state.firstResearchShape = confirmedShape;
+    state.workingState = {
+        ...state.workingState,
+        firstResearchShape: confirmedShape
+    };
+    state.hooks = (state.hooks ?? []).map((hook) => {
+        if (hook.id !== shape.sourceHookId || !isInterviewHookRun(hook)) {
+            return hook;
+        }
+        return {
+            ...hook,
+            status: firstResearchShapeAnswerStatus(answer),
+            updatedAt: timestamp,
+            firstResearchShape: confirmedShape,
+            linkedQuestionRecordIds: questionId
+                ? [...(hook.linkedQuestionRecordIds ?? []), questionId]
+                : hook.linkedQuestionRecordIds,
+            linkedDecisionRecordIds: decisionId
+                ? [...(hook.linkedDecisionRecordIds ?? []), decisionId]
+                : hook.linkedDecisionRecordIds
+        };
+    });
+    const nextState = resolveFirstResearchShapeObligation(state, {
+        sourceHookId: shape.sourceHookId,
+        questionId,
+        decisionId,
+        status: "satisfied"
+    });
+    const session = {
+        ...context.session,
+        firstResearchShape: confirmedShape,
+        lastUpdatedAt: timestamp
+    };
+    context.session = session;
+    await writeFile(context.sessionFilePath, JSON.stringify(session, null, 2), "utf8");
+    await writeFile(context.stateFilePath, JSON.stringify(nextState, null, 2), "utf8");
+    await syncCurrentWorkspaceView(context);
+    return { state: nextState, session, shape: confirmedShape };
+}
 function statusForElicitationError(error) {
     const message = error instanceof Error ? error.message : String(error);
     if (/timed?\s*out|timeout/i.test(message)) {
@@ -238,6 +557,221 @@ export function createLongTableMcpServer() {
             return errorResult(error instanceof Error ? error.message : String(error));
         }
     });
+    server.registerTool("create_workspace", {
+        title: "Create LongTable Workspace",
+        description: "Create a .longtable workspace in the current folder for provider-native $longtable-interview.",
+        inputSchema: cwdSchema.extend({
+            projectName: z.string().optional(),
+            projectPath: z.string().optional(),
+            seedGoal: z.string().optional(),
+            setupPath: z.string().optional(),
+            provider: z.enum(["codex", "claude"]).default("codex")
+        })
+    }, async ({ cwd: inputCwd, projectName, projectPath, seedGoal, setupPath, provider }) => {
+        try {
+            const targetPath = resolveStartPath(projectPath ?? inputCwd);
+            const setup = await loadSetupOutput(setupPath);
+            const context = await createOrUpdateProjectWorkspace({
+                projectName: projectName?.trim() || basename(targetPath) || "LongTable Research",
+                projectPath: targetPath,
+                currentGoal: seedGoal?.trim() || "First research handle pending",
+                requestedPerspectives: [],
+                disagreementPreference: setup.profileSeed.panelPreference ?? "show_on_conflict",
+                setup
+            });
+            const interview = await beginInterviewHook(context, {
+                provider: provider,
+                openingQuestion: "What do you want to research? If it is not clear yet, describe the problem in its rough form.",
+                seedAnswer: seedGoal
+            });
+            return textResult({
+                project: context.project,
+                session: context.session,
+                hook: interview.hook,
+                files: {
+                    project: context.projectFilePath,
+                    session: context.sessionFilePath,
+                    state: context.stateFilePath,
+                    current: context.currentFilePath
+                },
+                nextQuestion: "What do you want to research? If it is not clear yet, describe the problem in its rough form."
+            });
+        }
+        catch (error) {
+            return errorResult(error instanceof Error ? error.message : String(error));
+        }
+    });
+    server.registerTool("begin_interview", {
+        title: "Begin LongTable Interview",
+        description: "Create or resume the active $longtable-interview hook in an existing workspace.",
+        inputSchema: cwdSchema.extend({
+            openingQuestion: z.string().optional(),
+            seedAnswer: z.string().optional(),
+            provider: z.enum(["codex", "claude"]).default("codex")
+        })
+    }, async ({ cwd: inputCwd, openingQuestion, seedAnswer, provider }) => {
+        try {
+            const context = await requireContext(inputCwd);
+            const result = await beginInterviewHook(context, {
+                provider: provider,
+                openingQuestion,
+                seedAnswer
+            });
+            return textResult(result);
+        }
+        catch (error) {
+            return errorResult(error instanceof Error ? error.message : String(error));
+        }
+    });
+    server.registerTool("append_interview_turn", {
+        title: "Append LongTable Interview Turn",
+        description: "Record one natural-language interview question and answer, including quality/follow-up metadata.",
+        inputSchema: cwdSchema.extend({
+            hookId: z.string().optional(),
+            question: z.string().min(1),
+            answer: z.string().min(1),
+            reflection: z.string().optional(),
+            quality: z.enum(["thin", "usable", "rich"]).optional(),
+            needsFollowUp: z.boolean().optional(),
+            followUpQuestion: z.string().optional(),
+            rationale: z.array(z.string()).optional()
+        })
+    }, async ({ cwd: inputCwd, hookId, question, answer, reflection, quality, needsFollowUp, followUpQuestion, rationale }) => {
+        try {
+            const context = await requireContext(inputCwd);
+            const result = await appendInterviewTurn(context, {
+                hookId,
+                question,
+                answer,
+                reflection,
+                quality: quality,
+                needsFollowUp,
+                followUpQuestion,
+                rationale
+            });
+            return textResult(result);
+        }
+        catch (error) {
+            return errorResult(error instanceof Error ? error.message : String(error));
+        }
+    });
+    server.registerTool("summarize_interview", {
+        title: "Summarize LongTable Interview",
+        description: "Store the provisional First Research Shape after enough interview context has accumulated.",
+        inputSchema: cwdSchema.extend({
+            hookId: z.string().optional(),
+            shape: firstResearchShapeSchema
+        })
+    }, async ({ cwd: inputCwd, hookId, shape }) => {
+        try {
+            const context = await requireContext(inputCwd);
+            const result = await summarizeInterviewHook(context, {
+                hookId,
+                shape: shape
+            });
+            return textResult(result);
+        }
+        catch (error) {
+            return errorResult(error instanceof Error ? error.message : String(error));
+        }
+    });
+    server.registerTool("confirm_first_research_shape", {
+        title: "Confirm First Research Shape",
+        description: "Use MCP form elicitation to confirm, revise, defer, or request more context for the First Research Shape.",
+        inputSchema: cwdSchema.extend({
+            shape: firstResearchShapeSchema.optional(),
+            provider: z.enum(["codex", "claude"]).default("codex"),
+            fallbackOnly: z.boolean().default(false)
+        })
+    }, async ({ cwd: inputCwd, shape: inputShape, provider, fallbackOnly }) => {
+        try {
+            const context = await requireContext(inputCwd);
+            const state = asInterviewState(await loadWorkspaceState(context));
+            const shape = inputShape ?? state.firstResearchShape;
+            if (!shape) {
+                return errorResult("No First Research Shape was found to confirm. Run summarize_interview first.");
+            }
+            const spec = buildFirstResearchShapeQuestion(shape);
+            const created = await createWorkspaceQuestion({
+                context,
+                prompt: spec.prompt,
+                title: spec.title,
+                question: spec.question,
+                checkpointKey: spec.checkpointKey,
+                questionOptions: spec.options,
+                displayReason: spec.displayReason,
+                provider: provider,
+                required: true
+            });
+            const createdState = ensureFirstResearchShapeObligation(asInterviewState(await loadWorkspaceState(context)), shape, {
+                prompt: spec.question,
+                reason: spec.displayReason,
+                questionId: created.question.id
+            });
+            await writeFile(context.stateFilePath, JSON.stringify(createdState, null, 2), "utf8");
+            await syncCurrentWorkspaceView(context);
+            const fallback = renderQuestionFallback(created.question, provider);
+            if (fallbackOnly) {
+                const marked = await markQuestionTransport(context, created.question.id, "fallback_rendered", "MCP elicitation skipped by fallbackOnly.");
+                return textResult({
+                    question: marked ?? created.question,
+                    shape,
+                    elicitation: { attempted: false, reason: "fallbackOnly" },
+                    fallback
+                });
+            }
+            try {
+                await markQuestionTransport(context, created.question.id, "attempted");
+                const elicited = await server.server.elicitInput(buildElicitationParams(created.question));
+                const accepted = acceptedAnswer(elicited);
+                if (!accepted) {
+                    const status = elicited.action === "decline" || elicited.action === "cancel"
+                        ? "declined"
+                        : "fallback_rendered";
+                    const marked = await markQuestionTransport(context, created.question.id, status, `MCP elicitation returned action: ${elicited.action}.`);
+                    return textResult({
+                        question: marked ?? created.question,
+                        shape,
+                        elicitation: { attempted: true, action: elicited.action },
+                        fallback
+                    });
+                }
+                const decided = await answerWorkspaceQuestion({
+                    context,
+                    questionId: created.question.id,
+                    answer: accepted.answer,
+                    provider: provider,
+                    surface: "mcp_elicitation"
+                });
+                const marked = await markQuestionTransport(context, created.question.id, "accepted");
+                const confirmation = await markFirstResearchShapeConfirmation(context, shape, accepted.answer, created.question.id, decided.decision.id);
+                return textResult({
+                    shape: confirmation.shape,
+                    question: marked ? { ...decided.question, transportStatus: marked.transportStatus } : decided.question,
+                    decision: decided.decision,
+                    elicitation: { attempted: true, action: elicited.action }
+                });
+            }
+            catch (elicitationError) {
+                const status = statusForElicitationError(elicitationError);
+                const message = elicitationError instanceof Error ? elicitationError.message : String(elicitationError);
+                const marked = await markQuestionTransport(context, created.question.id, status, message);
+                return textResult({
+                    question: marked ?? created.question,
+                    shape,
+                    elicitation: {
+                        attempted: true,
+                        supported: status !== "unsupported" ? undefined : false,
+                        error: message
+                    },
+                    fallback
+                });
+            }
+        }
+        catch (error) {
+            return errorResult(error instanceof Error ? error.message : String(error));
+        }
+    });
     server.registerTool("pending_questions", {
         title: "List Pending Researcher Checkpoints",
         description: "List pending LongTable QuestionRecords.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longtable/mcp",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "private": false,
   "description": "LongTable MCP transport for workspace state and Researcher Checkpoints",
   "type": "module",
@@ -26,11 +26,12 @@
     "self-test": "node ./dist/server.js --self-test"
   },
   "dependencies": {
-    "@longtable/checkpoints": "0.1.31",
-    "@longtable/cli": "0.1.31",
-    "@longtable/core": "0.1.31",
-    "@longtable/provider-claude": "0.1.31",
-    "@longtable/provider-codex": "0.1.31",
+    "@longtable/checkpoints": "0.1.33",
+    "@longtable/cli": "0.1.33",
+    "@longtable/core": "0.1.33",
+    "@longtable/provider-claude": "0.1.33",
+    "@longtable/provider-codex": "0.1.33",
+    "@longtable/setup": "0.1.33",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.0.0"
   },