@attentionform/astra-mcp-server 0.1.0 → 0.2.0

package/dist/lib/mcp/baseline-gate.d.ts

@@ -0,0 +1,71 @@
+import { type BaselineVerdict, type ValidationBaseline, type ValidationResult } from '@attentionform/astra-engine';
+import type { DocHandle } from '../session-store';
+/** Set by the `--strict-validation` flag. */
+export declare function setStrictValidationDefault(value: boolean): void;
+/** True when a save refuses every validator error, whether or not the file had it before. */
+export declare function strictValidationDefault(): boolean;
+/** Set by the `--open-validation-timeout` flag. */
+export declare function setOpenValidationTimeoutMs(value: number): void;
+/** How long open_document waits for the validator, in milliseconds. 0 skips the check. */
+export declare function openValidationTimeoutMs(): number;
+export declare function sha256Hex(bytes: Buffer): string;
+/** Validates a package with the full error list, so the result can be compared. */
+export declare function validateForBaseline(bytes: Buffer): Promise<ValidationResult>;
+/** Stores the baseline of a package the session now holds as its saved state. */
+export declare function adoptBaseline(handle: DocHandle, result: ValidationResult): void;
+/**
+ * The baseline of a session. When the open did not produce one (timed out or skipped), the file on
+ * disk is validated, but only when it is still the file that was opened. Otherwise null, and the
+ * save is judged as not comparable.
+ */
+export declare function resolveBaseline(handle: DocHandle): Promise<ValidationBaseline | null>;
+/**
+ * Verdict for a package that revert_document or redo_document restores. Such a state was saved before,
+ * so it is allowed to carry the errors the file had when it was opened, as well as the errors of the
+ * saved state of the session. Anything beyond both is refused.
+ */
+export declare function judgeRestoredPackage(handle: DocHandle, result: ValidationResult): Promise<BaselineVerdict>;
+/** The first `limit` descriptions of a result, cut to a readable length. */
+export declare function firstMessages(result: ValidationResult, limit?: number): string[];
+/** The error a save or normalize raises when the edit adds validator errors. */
+export declare function introducedError(toolName: string, verdict: Extract<BaselineVerdict, {
+    kind: 'introduced';
+}>): Error;
+/** The `validation` field of an answer for a result that was judged. */
+export declare function validationField(result: ValidationResult, verdict: BaselineVerdict): {
+    ok: false;
+    tolerated: true;
+    preExistingErrors: number;
+    introducedErrors: 0;
+    messages: string[];
+} | {
+    ok: true;
+    tolerated?: undefined;
+    preExistingErrors?: undefined;
+    introducedErrors?: undefined;
+    messages?: undefined;
+};
+/** Adds the note about existing errors to a commit message; the message is cut, the note never. */
+export declare function withToleratedNote(message: string, preExisting: number): string;
+export type OpenValidationField = {
+    status: 'valid';
+} | {
+    status: 'invalid';
+    preExistingErrors: number;
+    baselineComparable: boolean;
+    messages: string[];
+    degraded: true;
+    note: string;
+} | {
+    status: 'timed-out';
+    degraded: 'unknown';
+    note: string;
+} | {
+    status: 'skipped';
+    note?: string;
+};
+/**
+ * Validates the file that was just opened and stores its baseline on the handle. The open itself is
+ * never refused for these reasons, and nothing is reported as valid unless the validator said so.
+ */
+export declare function validateAtOpen(handle: DocHandle, timeoutMs: number): Promise<OpenValidationField>;

package/dist/lib/mcp/handlers/open-inspect.d.ts

@@ -1,6 +1,7 @@
 import { DocxParser, type StyleGuideSummary } from '@attentionform/astra-engine';
 import type { McpSessionStore } from '../../session-store';
 import type { McpErrorShape } from '../errors';
+import { type OpenValidationField } from '../baseline-gate';
 export interface StylePalette {
     availableStyles: string[];
     brandColors: string[];
@@ -15,6 +16,7 @@ export declare function handleOpenDocument(store: McpSessionStore, input: unknow
     summary: unknown;
     evicted: string[];
     pendingNormalizations: string[];
+    validation: OpenValidationField;
 } | McpErrorShape>;
 /**
  * Phase C-2: docs rendering under ~2000 tokens return the full TOON

package/dist/lib/mcp/handlers/parity.d.ts

@@ -1,3 +1,4 @@
+import { PII_COVERAGE } from '@attentionform/astra-engine';
 import { type McpSessionStore } from '../../session-store';
 import { handleComposeDocument } from '../../../tools/compose-document';
 import type { McpErrorShape } from '../errors';
@@ -23,6 +24,8 @@ export declare function handleValidateDocument(store: McpSessionStore, input: un
     validation: AuditValidation;
     /** Repairs a save would make (e.g. children put in schema order); absent when none. */
     pendingNormalizations?: string[];
+    /** Advice when normalize_document can repair errors in the document. */
+    normalizeHint?: string;
 } | McpErrorShape>;
 /**
  * get_stats: token-cheap census over the live AST (pure read: no revision
@@ -51,6 +54,8 @@ export interface SanitizeDocumentOk {
     strippedExifBytes: number;
     purgedPII: number;
     bodyPII: number;
+    piiCoverage: typeof PII_COVERAGE;
+    piiNote: string;
     acceptedRevisions: number;
     strippedComments: number;
     strippedMacros: string[];
@@ -86,7 +91,17 @@ export declare function handleNormalizeDocument(store: McpSessionStore, input: u
     revision: number;
     dirty: boolean;
     normalized: string[];
-    validation: AuditValidation;
+    preStateCommit?: string;
+    remaining: number;
+    rolledBack: {
+        rule: string;
+        reason: string;
+    }[];
+    validation: AuditValidation & {
+        tolerated?: true;
+        preExistingErrors?: number;
+        introducedErrors?: 0;
+    };
     revisionsPending: number;
     revisionsRemedy?: string;
     redoCleared?: boolean;

package/dist/lib/mcp/handlers/save-close.d.ts

@@ -21,6 +21,16 @@ export declare function executeSaveDocument(store: McpSessionStore, input: unkno
     revision: number;
     commitOid: string;
     commitMessage: string;
+    /** Result of the validator gate: clean, or tolerated with the number of errors the file already had. */
+    validation: {
+        ok: true;
+    } | {
+        ok: false;
+        tolerated: true;
+        preExistingErrors: number;
+        introducedErrors: 0;
+        messages: string[];
+    };
     /** R-1: pending tracked revisions (w:ins + w:del) in the saved package. */
     revisionsPending: number;
     /** R-1: accept remedy, present only when revisionsPending > 0. */
@@ -52,6 +62,16 @@ export declare function handleSaveDocument(store: McpSessionStore, input: unknow
     revision: number;
     commitOid: string;
     commitMessage: string;
+    /** Result of the validator gate: clean, or tolerated with the number of errors the file already had. */
+    validation: {
+        ok: true;
+    } | {
+        ok: false;
+        tolerated: true;
+        preExistingErrors: number;
+        introducedErrors: 0;
+        messages: string[];
+    };
     /** R-1: pending tracked revisions (w:ins + w:del) in the saved package. */
     revisionsPending: number;
     /** R-1: accept remedy, present only when revisionsPending > 0. */

package/dist/lib/mcp/schemas.d.ts

@@ -6,6 +6,7 @@ export declare const OpenDocumentSchema: z.ZodObject<{
     allowMacros: z.ZodOptional<z.ZodBoolean>;
     stripMacros: z.ZodOptional<z.ZodBoolean>;
     author: z.ZodOptional<z.ZodString>;
+    validationTimeoutMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 export declare const InspectDocumentSchema: z.ZodObject<{
     sessionId: z.ZodString;
@@ -345,6 +346,7 @@ export declare const ExecuteBatchSchema: z.ZodObject<{
         col: z.ZodOptional<z.ZodNumber>;
         columnIndex: z.ZodOptional<z.ZodNumber>;
         text: z.ZodOptional<z.ZodString>;
+        cells: z.ZodOptional<z.ZodArray<z.ZodString>>;
         afterIndex: z.ZodOptional<z.ZodNumber>;
         index: z.ZodOptional<z.ZodNumber>;
         fill: z.ZodOptional<z.ZodString>;
@@ -738,6 +740,7 @@ export declare const ExecuteBatchSchema: z.ZodObject<{
         anchor: z.ZodString;
         text: z.ZodString;
         id: z.ZodOptional<z.ZodString>;
+        offset: z.ZodOptional<z.ZodNumber>;
         expectedVersion: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>, z.ZodObject<{
         action: z.ZodLiteral<"endnote">;
@@ -747,6 +750,7 @@ export declare const ExecuteBatchSchema: z.ZodObject<{
         anchor: z.ZodString;
         text: z.ZodString;
         id: z.ZodOptional<z.ZodString>;
+        offset: z.ZodOptional<z.ZodNumber>;
         expectedVersion: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>, z.ZodObject<{
         action: z.ZodLiteral<"watermark">;
@@ -862,6 +866,7 @@ export declare const SaveDocumentSchema: z.ZodObject<{
     author: z.ZodOptional<z.ZodString>;
     allowMacros: z.ZodOptional<z.ZodBoolean>;
     stripMacros: z.ZodOptional<z.ZodBoolean>;
+    strict: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export declare const CloseDocumentSchema: z.ZodObject<{
     sessionId: z.ZodString;

package/dist/lib/session-store.d.ts

@@ -1,4 +1,4 @@
-import { type DocumentAST, type DocxParserMacroOptions, DocxParser, OperationEngine, ToonGenerator, canonicalizeForAsset as canonicalizeForMcp, type StyleGuideConfig } from '@attentionform/astra-engine';
+import { type DocumentAST, type DocxParserMacroOptions, DocxParser, OperationEngine, ToonGenerator, canonicalizeForAsset as canonicalizeForMcp, type StyleGuideConfig, type ValidationBaseline } from '@attentionform/astra-engine';
 /**
  * Sprint-2 Muse session store (MCP Lean-6 backing).
  *
@@ -136,6 +136,16 @@ export interface DocHandle {
     styleGuide?: StyleGuideConfig;
     /** Raw guide ref the session guide was resolved from (name or file path). */
     styleGuideRef?: string;
+    /**
+     * Validator errors the saved state of the session already has, by signature. `undefined` means the
+     * open did not finish a check (timed out or skipped); `null` means a check ran but its result
+     * cannot be compared (cut short, or an exception).
+     */
+    validationBaseline?: ValidationBaseline | null;
+    /** The baseline at open, kept when a save replaces `validationBaseline`: a revert may return to a state with these errors. */
+    openBaseline?: ValidationBaseline | null;
+    /** sha256 of the file bytes read at open, to tell whether the file on disk is still the opened one. */
+    openSha256?: string;
 }
 /**
  * Per-commit audit metadata recorded alongside each history commit.

package/dist/tools/export.d.ts

@@ -10,6 +10,11 @@ export declare const ExportDocumentSchema: z.ZodObject<{
         pdf: "pdf";
     }>;
     outPath: z.ZodOptional<z.ZodString>;
+    imageMode: z.ZodOptional<z.ZodEnum<{
+        file: "file";
+        embed: "embed";
+    }>>;
+    assetPrefix: z.ZodOptional<z.ZodString>;
     tagged_pdf: z.ZodOptional<z.ZodBoolean>;
     tagged: z.ZodOptional<z.ZodBoolean>;
     strict: z.ZodOptional<z.ZodBoolean>;
@@ -27,6 +32,7 @@ export declare function mapExportError(err: unknown): {
     remedy: string;
 };
 export declare function validateExportTarget(rawPath: unknown, expectedFormat: 'html' | 'markdown' | 'md' | 'pdf'): string;
+export declare function validateAssetTarget(rawPath: unknown): string;
 export declare function handleExportDocument(store: McpSessionStore, rawArgs: unknown): Promise<{
     ok: boolean;
     format?: string;
@@ -35,6 +41,10 @@ export declare function handleExportDocument(store: McpSessionStore, rawArgs: un
     content?: string;
     dirty?: boolean;
     revision?: number;
+    imageMode?: 'file' | 'embed';
+    assetPrefix?: string;
+    assets?: string[];
+    assetCount?: number;
     warnings?: PreflightIssue[];
     blockers?: PreflightIssue[];
     message?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attentionform/astra-mcp-server",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Official Model Context Protocol (MCP) server for ASTra document IDE",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -41,8 +41,8 @@
     "adm-zip-gate": "node ../../scripts/check-adm-zip-imports.mjs"
   },
   "dependencies": {
-    "@attentionform/astra-engine": "^0.1.0",
-    "@attentionform/ooxml-validator": "^0.1.0",
+    "@attentionform/astra-engine": "^0.2.0",
+    "@attentionform/ooxml-validator": "^0.2.0",
     "@modelcontextprotocol/sdk": "^1.32.2",
     "@xmldom/xmldom": "0.8.15",
     "adm-zip": "0.6.1",