@longtable/mcp 0.1.52 → 0.1.54

package/README.md

@@ -16,7 +16,7 @@ longtable-state
 Run:
 
 ```bash
-npx -y @longtable/mcp@0.1.52
+npx -y @longtable/mcp@0.1.53
 ```
 
 Self-test:

package/dist/server.js

@@ -10,6 +10,7 @@ import { z } from "zod";
 import { classifyCheckpointTrigger } from "@longtable/checkpoints";
 import { renderQuestionRecordInput } from "@longtable/provider-claude";
 import { renderQuestionRecordPrompt } from "@longtable/provider-codex";
+import { evaluateResearchSpecificationReadiness } from "@longtable/core";
 import { loadSetupOutput } from "@longtable/setup";
 import { answerWorkspaceQuestion, applyResearchSpecificationAuditUpdate, applyResearchSpecificationPatch, clearWorkspaceQuestion, createOrUpdateProjectWorkspace, createWorkspaceQuestion, diffResearchSpecifications, findUnincorporatedResearchEvidence, inspectProjectWorkspace, loadProjectContextFromDirectory, loadWorkspaceState, proposeResearchSpecificationPatch, readResearchSpecificationHistory, syncCurrentWorkspaceView } from "@longtable/cli";
 import { buildFirstResearchShapeQuestion, firstResearchShapeAnswerConfirms, firstResearchShapeAnswerStatus } from "./first-research-shape.js";
@@ -196,6 +197,36 @@ function createId(prefix) {
 function asInterviewState(state) {
     return state;
 }
+function researchSpecificationReadinessFromState(state, session, specification) {
+    return evaluateResearchSpecificationReadiness({
+        firstResearchShape: state.firstResearchShape ?? session?.firstResearchShape,
+        researchSpecification: specification ?? state.researchSpecification ?? session?.researchSpecification,
+        questionLog: state.questionLog,
+        questionObligations: state.questionObligations
+    });
+}
+function nextStartQuestionForReadiness(readiness, openingQuestion) {
+    if (readiness.status === "shape_only") {
+        return "A First Research Shape is saved, but the Research Specification is still missing. Continue with the next Research Specification question: what research question, construct boundary, evidence boundary, or method commitment must be preserved before follow-up interview starts?";
+    }
+    if (readiness.status === "structurally_incomplete") {
+        return `The Research Specification draft is missing: ${readiness.blockingGaps.join(", ")}. Ask the next natural-language question that resolves the highest-risk missing section.`;
+    }
+    if (readiness.status === "draft_pending_confirmation") {
+        return "A Research Specification draft is saved. Show the Research Specification Preview and run confirm_research_specification before moving to option-first follow-up interview.";
+    }
+    if (readiness.status === "deferred") {
+        return "Research Specification confirmation is deferred. Resume the confirmation checkpoint before moving to option-first follow-up interview.";
+    }
+    if (readiness.status === "confirmed") {
+        return "The Research Specification is confirmed. Use $longtable-interview for structured follow-up decisions.";
+    }
+    return openingQuestion ?? "What do you want to research? If it is not clear yet, describe the problem in its rough form.";
+}
+async function currentResearchSpecificationReadiness(context, specification) {
+    const state = asInterviewState(await loadWorkspaceState(context));
+    return researchSpecificationReadinessFromState(state, context.session, specification);
+}
 function isInterviewHookRun(hook) {
     return hook?.kind === "longtable_interview";
 }
@@ -351,21 +382,14 @@ function defaultFollowUpQuestion(answer) {
 }
 async function beginInterviewHook(context, options) {
     const state = asInterviewState(await loadWorkspaceState(context));
+    const readiness = researchSpecificationReadinessFromState(state, context.session);
     const existing = activeInterviewHook(state);
     if (existing) {
-        return { hook: existing, state };
-    }
-    const confirmedShape = state.firstResearchShape?.confirmedAt ? state.firstResearchShape : undefined;
-    if (confirmedShape) {
-        const confirmedHook = [...(state.hooks ?? [])].reverse().find((hook) => isInterviewHookRun(hook) &&
-            hook.status === "confirmed" &&
-            hook.firstResearchShape?.handle === confirmedShape.handle);
         return {
-            hook: confirmedHook,
             state,
-            alreadyConfirmed: true,
-            shape: confirmedShape,
-            nextQuestion: options.openingQuestion ?? confirmedShape.openQuestions[0] ?? confirmedShape.nextAction
+            hook: existing,
+            readiness,
+            nextQuestion: nextStartQuestionForReadiness(readiness, options.openingQuestion)
         };
     }
     const timestamp = new Date().toISOString();
@@ -375,13 +399,16 @@ async function beginInterviewHook(context, options) {
         status: "active",
         createdAt: timestamp,
         updatedAt: timestamp,
-        targetOutcome: "first_research_handle",
+        targetOutcome: readiness.status === "no_spec" ? "first_research_handle" : "research_specification",
         depth: "gathering_context",
         provider: options.provider,
         turns: [],
         qualityNotes: [],
         rationale: [
-            "Official LongTable research start surface is provider-native `$longtable-start`, not the CLI start questionnaire."
+            "Official LongTable research start surface is provider-native `$longtable-start`, not the CLI start questionnaire.",
+            ...(readiness.status === "shape_only"
+                ? ["Confirmed First Research Shape is not enough; continue into Research Specification before follow-up interview."]
+                : [])
         ]
     };
     const updated = upsertInterviewHook(state, hook);
@@ -394,7 +421,12 @@ async function beginInterviewHook(context, options) {
     };
     await writeFile(context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
     await syncCurrentWorkspaceView(context);
-    return { hook, state: updated };
+    return {
+        hook,
+        state: updated,
+        readiness,
+        nextQuestion: nextStartQuestionForReadiness(readiness, options.openingQuestion)
+    };
 }
 async function appendInterviewTurn(context, options) {
     const state = asInterviewState(await loadWorkspaceState(context));
@@ -511,7 +543,13 @@ async function summarizeInterviewHook(context, options) {
     await writeFile(context.sessionFilePath, JSON.stringify(session, null, 2), "utf8");
     await writeFile(context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
     await syncCurrentWorkspaceView(context);
-    return { hook, shape, state: updated, session };
+    return {
+        hook,
+        shape,
+        state: updated,
+        session,
+        readiness: researchSpecificationReadinessFromState(updated, session)
+    };
 }
 function normalizeStringArray(values) {
     return (values ?? []).map((value) => value.trim()).filter(Boolean);
@@ -624,7 +662,13 @@ async function summarizeResearchSpecificationHook(context, options) {
     await writeFile(context.sessionFilePath, JSON.stringify(session, null, 2), "utf8");
     await writeFile(context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
     await syncCurrentWorkspaceView(context);
-    return { hook, specification, state: updated, session };
+    return {
+        hook,
+        specification,
+        state: updated,
+        session,
+        readiness: researchSpecificationReadinessFromState(updated, session, specification)
+    };
 }
 async function cancelInterviewHook(context, options) {
     const state = asInterviewState(await loadWorkspaceState(context));
@@ -855,7 +899,12 @@ async function markFirstResearchShapeConfirmation(context, shape, answer, questi
     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 };
+    return {
+        state: nextState,
+        session,
+        shape: confirmedShape,
+        readiness: researchSpecificationReadinessFromState(nextState, session)
+    };
 }
 async function markAlreadyConfirmedFirstResearchShape(context, shape) {
     const state = asInterviewState(await loadWorkspaceState(context));
@@ -895,7 +944,12 @@ async function markAlreadyConfirmedFirstResearchShape(context, shape) {
     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 };
+    return {
+        state: nextState,
+        session,
+        shape: confirmedShape,
+        readiness: researchSpecificationReadinessFromState(nextState, session)
+    };
 }
 async function markResearchSpecificationConfirmation(context, specification, answer, questionId, decisionId) {
     const state = asInterviewState(await loadWorkspaceState(context));
@@ -964,7 +1018,12 @@ async function markResearchSpecificationConfirmation(context, specification, ans
     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, specification: confirmedSpecification };
+    return {
+        state: nextState,
+        session,
+        specification: confirmedSpecification,
+        readiness: researchSpecificationReadinessFromState(nextState, session, confirmedSpecification)
+    };
 }
 async function markAlreadyConfirmedResearchSpecification(context, specification) {
     const state = asInterviewState(await loadWorkspaceState(context));
@@ -1005,7 +1064,12 @@ async function markAlreadyConfirmedResearchSpecification(context, specification)
     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, specification: confirmedSpecification };
+    return {
+        state: nextState,
+        session,
+        specification: confirmedSpecification,
+        readiness: researchSpecificationReadinessFromState(nextState, session, confirmedSpecification)
+    };
 }
 function statusForElicitationError(error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -1134,7 +1198,10 @@ export function createLongTableMcpServer() {
                     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."
+                readiness: "readiness" in interview ? interview.readiness : undefined,
+                nextQuestion: "nextQuestion" in interview
+                    ? interview.nextQuestion
+                    : "What do you want to research? If it is not clear yet, describe the problem in its rough form."
             });
         }
         catch (error) {
@@ -1161,6 +1228,7 @@ export function createLongTableMcpServer() {
                 hook: compactInterviewHook(result.hook),
                 alreadyConfirmed: "alreadyConfirmed" in result ? Boolean(result.alreadyConfirmed) : false,
                 shape: "shape" in result ? result.shape : result.hook?.firstResearchShape,
+                readiness: "readiness" in result ? result.readiness : undefined,
                 nextQuestion: "nextQuestion" in result ? result.nextQuestion : openingQuestion,
                 workspace: {
                     projectName: context.project.projectName,
@@ -1227,6 +1295,7 @@ export function createLongTableMcpServer() {
             return textResult({
                 hook: compactInterviewHook(result.hook),
                 shape: result.shape,
+                readiness: result.readiness,
                 session: {
                     currentGoal: result.session.currentGoal,
                     currentBlocker: result.session.currentBlocker,
@@ -1257,6 +1326,7 @@ export function createLongTableMcpServer() {
                 hook: compactInterviewHook(result.hook),
                 specification: result.specification,
                 preview: renderResearchSpecificationPreview(result.specification),
+                readiness: result.readiness,
                 session: {
                     currentGoal: result.session.currentGoal,
                     currentBlocker: result.session.currentBlocker,
@@ -1283,13 +1353,15 @@ export function createLongTableMcpServer() {
             if (!specification) {
                 return textResult({
                     found: false,
+                    readiness: researchSpecificationReadinessFromState(state, session),
                     message: "No Research Specification was found. Run summarize_research_specification first."
                 });
             }
             return textResult({
                 found: true,
                 specification,
-                preview: renderResearchSpecificationPreview(specification)
+                preview: renderResearchSpecificationPreview(specification),
+                readiness: researchSpecificationReadinessFromState(state, session, specification)
             });
         }
         catch (error) {
@@ -1456,6 +1528,7 @@ export function createLongTableMcpServer() {
                 const confirmation = await markAlreadyConfirmedFirstResearchShape(context, shape);
                 return textResult({
                     shape: confirmation.shape,
+                    readiness: confirmation.readiness,
                     elicitation: { attempted: false, reason: "already_confirmed" }
                 });
             }
@@ -1484,6 +1557,7 @@ export function createLongTableMcpServer() {
                 return textResult({
                     question: marked ?? created.question,
                     shape,
+                    readiness: await currentResearchSpecificationReadiness(context),
                     elicitation: { attempted: false, reason: "fallbackOnly" },
                     fallback
                 });
@@ -1507,6 +1581,7 @@ export function createLongTableMcpServer() {
                     return textResult({
                         question: cleared?.question ?? marked ?? created.question,
                         shape,
+                        readiness: await currentResearchSpecificationReadiness(context),
                         elicitation: { attempted: true, action: elicited.action },
                         fallback
                     });
@@ -1522,6 +1597,7 @@ export function createLongTableMcpServer() {
                 const confirmation = await markFirstResearchShapeConfirmation(context, shape, firstAcceptedAnswerValue(accepted.answer), created.question.id, decided.decision.id);
                 return textResult({
                     shape: confirmation.shape,
+                    readiness: confirmation.readiness,
                     question: marked ? { ...decided.question, transportStatus: marked.transportStatus } : decided.question,
                     decision: decided.decision,
                     elicitation: { attempted: true, action: elicited.action }
@@ -1534,6 +1610,7 @@ export function createLongTableMcpServer() {
                 return textResult({
                     question: marked ?? created.question,
                     shape,
+                    readiness: await currentResearchSpecificationReadiness(context),
                     elicitation: {
                         attempted: true,
                         supported: status !== "unsupported" ? undefined : false,
@@ -1571,6 +1648,7 @@ export function createLongTableMcpServer() {
                 return textResult({
                     specification: confirmation.specification,
                     preview: renderResearchSpecificationPreview(confirmation.specification),
+                    readiness: confirmation.readiness,
                     elicitation: { attempted: false, reason: "already_confirmed" }
                 });
             }
@@ -1593,6 +1671,7 @@ export function createLongTableMcpServer() {
                     question: marked ?? created.question,
                     specification,
                     preview: renderResearchSpecificationPreview(specification),
+                    readiness: await currentResearchSpecificationReadiness(context, specification),
                     elicitation: { attempted: false, reason: "fallbackOnly" },
                     fallback
                 });
@@ -1617,6 +1696,7 @@ export function createLongTableMcpServer() {
                         question: cleared?.question ?? marked ?? created.question,
                         specification,
                         preview: renderResearchSpecificationPreview(specification),
+                        readiness: await currentResearchSpecificationReadiness(context, specification),
                         elicitation: { attempted: true, action: elicited.action },
                         fallback
                     });
@@ -1633,6 +1713,7 @@ export function createLongTableMcpServer() {
                 return textResult({
                     specification: confirmation.specification,
                     preview: renderResearchSpecificationPreview(confirmation.specification),
+                    readiness: confirmation.readiness,
                     question: marked ? { ...decided.question, transportStatus: marked.transportStatus } : decided.question,
                     decision: decided.decision,
                     elicitation: { attempted: true, action: elicited.action }
@@ -1646,6 +1727,7 @@ export function createLongTableMcpServer() {
                     question: marked ?? created.question,
                     specification,
                     preview: renderResearchSpecificationPreview(specification),
+                    readiness: await currentResearchSpecificationReadiness(context, specification),
                     elicitation: {
                         attempted: true,
                         supported: status !== "unsupported" ? undefined : false,

package/package.json

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