@attentionform/astra-mcp-server 0.2.1 → 0.4.0

package/dist/lib/index.d.ts

@@ -4,7 +4,7 @@
  * Named re-exports ONLY (no `export *`): the public surface stays explicit
  * and reviewable — every name below is listed deliberately.
  */
-export { MCP_SESSION_MAX_DOCS, MCP_SESSION_MAX_BYTES, MCP_SESSION_IDLE_MS, SessionMutex, McpSessionStore, collectTrackedExtrasForGit, ensureGitRepo, getMcpAllowedRoots, canonicalizeForMcp, validateDocPath, validateSaveTarget, validateOpenBufferLabel, SESSION_REDO_MAX_DEPTH_CLAMP, SESSION_REDO_MAX_BYTES_CLAMP, createMcpSessionStore, } from './session-store';
+export { MCP_SESSION_MAX_DOCS, MCP_SESSION_MAX_BYTES, MCP_SESSION_IDLE_MS, SessionMutex, McpSessionStore, collectTrackedExtrasForGit, ensureGitRepo, getMcpAllowedRoots, describeAllowedFolders, canonicalizeForMcp, validateDocPath, validateSaveTarget, validateOpenBufferLabel, SESSION_REDO_MAX_DEPTH_CLAMP, SESSION_REDO_MAX_BYTES_CLAMP, createMcpSessionStore, } from './session-store';
 export type { McpSessionStoreOptions, DocHandle, McpSessionStats, } from './session-store';
 export { MCP_RESEARCH_FLAG, isResearchEnabled, LEAN6_TOOL_NAMES, getLean6ToolNames, GIT_HISTORY_TOOL_NAMES, getGitHistoryToolNames, mcpError, sanitizeCommitMessage, sanitizeCommitAuthor, COMMIT_MESSAGE_MAX, COMMIT_AUTHOR_MAX, COMMIT_AUTHOR_DEFAULT, MCP_ECMA_ESSENTIALS, MCP_WORKFLOW, LEAN6_DESCRIPTIONS, GIT_HISTORY_DESCRIPTIONS, OpenDocumentSchema, InspectDocumentSchema, SearchContentSchema, ExecuteBatchSchema, SaveDocumentSchema, CloseDocumentSchema, GetDocumentHistorySchema, RevertDocumentSchema, RedoDocumentSchema, extractStylePalette, handleOpenDocument, handleInspectDocument, handleSearchContent, handleExecuteBatch, executeSaveDocument, handleSaveDocument, handleCloseDocument, handleGetDocumentHistory, handleRevertDocument, handleRedoDocument, LEAN6_HANDLERS, GIT_HISTORY_HANDLERS, } from './mcp-tool-adapter';
 export type { Lean6ToolName, GitHistoryToolName, HistoryEntry, McpErrorCode, McpErrorShape, OpenDocumentInput, InspectDocumentInput, SearchContentInput, ExecuteBatchInput, SaveDocumentInput, CloseDocumentInput, GetDocumentHistoryInput, RevertDocumentInput, RedoDocumentInput, StylePalette, } from './mcp-tool-adapter';

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

@@ -27,6 +27,26 @@ export declare function resolveBaseline(handle: DocHandle): Promise<ValidationBa
 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[];
+/** Validation errors carried on an answer (bounded, first errors only). */
+export declare const AUDIT_VALIDATION_ERRORS_MAX = 10;
+export interface AuditValidation {
+    valid: boolean;
+    errorCount: number;
+    errors: Array<{
+        description: string;
+        xPath?: string;
+    }>;
+}
+/** The first `max` errors as {description, xPath?}, each cut to a readable length. */
+export declare function summarizeValidationErrors(errors: unknown, max?: number): Array<{
+    description: string;
+    xPath?: string;
+}>;
+/** The shape validate_document returns: valid, how many errors, and the first of them. */
+export declare function toAuditValidation(validation: {
+    ok: boolean;
+    errors?: unknown;
+}, max?: number): AuditValidation;
 /** The error a save or normalize raises when the edit adds validator errors. */
 export declare function introducedError(toolName: string, verdict: Extract<BaselineVerdict, {
     kind: 'introduced';
@@ -38,8 +58,12 @@ export declare function validationField(result: ValidationResult, verdict: Basel
     preExistingErrors: number;
     introducedErrors: 0;
     messages: string[];
+    valid: false;
+    errorCount: number;
 } | {
     ok: true;
+    valid: true;
+    errorCount: 0;
     tolerated?: undefined;
     preExistingErrors?: undefined;
     introducedErrors?: undefined;

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

@@ -87,6 +87,8 @@ export interface BatchOpCreatedIds {
     index: number;
     action: string;
     createdNodeIds: string[];
+    /** coverPage on a fresh template: the placeholder nodes it replaced, so the caller sees what went. */
+    removedSeedNodes?: string[];
 }
 /** Echo of unsaved edits discarded by a revert (counts + ids only, never text). */
 export interface DiscardedUnsavedSummary {
@@ -103,6 +105,8 @@ export declare function collectAstIdTexts(ast: {
     sections: Array<{
         nodes: Array<{
             id: string;
+            type?: string;
+            xml?: unknown;
             metadata: {
                 text?: unknown;
             };
@@ -160,6 +164,7 @@ export declare function hashDocumentXml(xml: string): string;
  * for the save path (which does not go through executeBatch).
  */
 export declare function countPendingRevisionsInParser(parser: {
+    countPackageRevisions?: () => number;
     getDocumentDom?: () => unknown;
     getDom?: () => unknown;
 }): number;

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

@@ -5,6 +5,12 @@ export interface McpErrorShape {
     code: McpErrorCode;
     message: string;
     remedy: string;
+    /** Present when the failure is a validation refusal: how many errors there are, and the first of them. */
+    errorCount?: number;
+    errors?: Array<{
+        description: string;
+        xPath?: string;
+    }>;
 }
 export declare function mcpError(code: McpErrorCode, message: string, remedy: string): McpErrorShape;
 /**

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

@@ -68,4 +68,6 @@ export declare function handleInspectDocument(store: McpSessionStore, input: unk
     remedy?: string;
     /** Compact summary of the session style guide (absent when none attached). */
     styleGuide?: StyleGuideSummary;
+    comments?: unknown;
+    revisions?: unknown;
 } | McpErrorShape>;

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

@@ -1,15 +1,8 @@
 import { PII_COVERAGE } from '@attentionform/astra-engine';
+import { type AuditValidation } from '../baseline-gate';
 import { type McpSessionStore } from '../../session-store';
 import { handleComposeDocument } from '../../../tools/compose-document';
 import type { McpErrorShape } from '../errors';
-export interface AuditValidation {
-    valid: boolean;
-    errorCount: number;
-    errors: Array<{
-        description: string;
-        xPath?: string;
-    }>;
-}
 /**
  * validate_document: strictly read-only preflight ISO audit. The verdict runs
  * on an isolated fork (see serializeSessionFork): revision, dirty flag,
@@ -41,6 +34,7 @@ export declare function handleGetStats(store: McpSessionStore, input: unknown):
     words: number;
     paragraphs: number;
     tables: number;
+    callouts: number;
     images: number;
     pages: number;
 } | McpErrorShape>;
@@ -57,6 +51,13 @@ export interface SanitizeDocumentOk {
     piiCoverage: typeof PII_COVERAGE;
     piiNote: string;
     acceptedRevisions: number;
+    unresolvedRevisions: {
+        kind: string;
+        count: number;
+        reason: string;
+        part: string;
+    }[];
+    revisionByKind: Record<string, number>;
     strippedComments: number;
     strippedMacros: string[];
     macroParts: string[];

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

@@ -24,13 +24,22 @@ export declare function executeSaveDocument(store: McpSessionStore, input: unkno
     /** Result of the validator gate: clean, or tolerated with the number of errors the file already had. */
     validation: {
         ok: true;
+        valid: true;
+        errorCount: 0;
     } | {
         ok: false;
+        valid: false;
+        errorCount: number;
         tolerated: true;
         preExistingErrors: number;
         introducedErrors: 0;
         messages: string[];
     };
+    /** The title written from the content because dc:title was a template placeholder, and where it came from. */
+    title?: string;
+    titleSetFrom?: string;
+    /** The configured author written as creator in place of the tool default. */
+    creatorSet?: 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. */
@@ -65,13 +74,22 @@ export declare function handleSaveDocument(store: McpSessionStore, input: unknow
     /** Result of the validator gate: clean, or tolerated with the number of errors the file already had. */
     validation: {
         ok: true;
+        valid: true;
+        errorCount: 0;
     } | {
         ok: false;
+        valid: false;
+        errorCount: number;
         tolerated: true;
         preExistingErrors: number;
         introducedErrors: 0;
         messages: string[];
     };
+    /** The title written from the content because dc:title was a template placeholder, and where it came from. */
+    title?: string;
+    titleSetFrom?: string;
+    /** The configured author written as creator in place of the tool default. */
+    creatorSet?: 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/handlers/search-batch.d.ts

@@ -24,6 +24,8 @@ export declare function handleSearchContent(store: McpSessionStore, input: unkno
         cells?: string[];
     }>;
     hint?: string;
+    /** True when more than 50 items matched and the list was cut at 50. */
+    truncated?: boolean;
 } | McpErrorShape>;
 export declare function handleExecuteBatch(store: McpSessionStore, input: unknown): Promise<{
     ok: true;
@@ -39,8 +41,30 @@ export declare function handleExecuteBatch(store: McpSessionStore, input: unknow
     results: BatchOpCreatedIds[];
     /** R-1: pending tracked revisions (w:ins + w:del) remaining after the batch. */
     revisionsPending: number;
-    /** R-1: accept remedy, present only when revisionsPending > 0. */
+    revisionResolution?: {
+        resolved: number;
+        resolvedIds: number[];
+        byKind: Record<string, number>;
+        unresolved: {
+            kind: string;
+            count: number;
+            reason: string;
+            part: string;
+        }[];
+        removedNodeIds?: string[];
+        idsMayHaveChanged?: boolean;
+        /** Bookmarks, comment ids and links affected when a deleted or moved paragraph was removed. */
+        removedBookmarks?: string[];
+        removedComments?: number[];
+        staleLinks?: {
+            bookmark: string;
+            count: number;
+        }[];
+    };
+    /** R-1: remedy, present only when revisionsPending > 0. Names acceptAll only when running it can still help. */
     revisionsRemedy?: string;
+    /** FX-07: how many of revisionsPending the resolution in this batch could not resolve. Absent when none. */
+    revisionsUnresolved?: number;
     /** R-14: advisory chart stale body refs (same shape [{nodeId, preview}]). Additive, never a failure. */
     possiblyStaleBodyRefs: {
         nodeId: string;

package/dist/lib/mcp/schema-dump.d.ts

@@ -7,6 +7,9 @@ export interface ToolDefinition {
 }
 export declare function getToolDefinitions(): ToolDefinition[];
 export declare function buildStamp(version: string): string;
+/** The SDK defaults to inlining repeated Zod nodes. Use shared definitions for
+ * the published catalog while keeping the same Zod schemas for call validation. */
+export declare function compactToolSchema(schema: unknown): Record<string, unknown>;
 export declare function generateSchemasToDir(targetDir: string, version?: string): {
     written: string[];
     count: number;

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

@@ -22,11 +22,24 @@ export declare const InspectDocumentSchema: z.ZodObject<{
     aroundNode: z.ZodOptional<z.ZodString>;
     window: z.ZodOptional<z.ZodNumber>;
     maxTokens: z.ZodOptional<z.ZodNumber>;
+    include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        comments: "comments";
+        revisions: "revisions";
+    }>>>;
+    reviewOffset: z.ZodOptional<z.ZodNumber>;
+    reviewLimit: z.ZodOptional<z.ZodNumber>;
+    commentId: z.ZodOptional<z.ZodNumber>;
+    revisionId: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 export declare const SearchContentSchema: z.ZodObject<{
     sessionId: z.ZodString;
     query: z.ZodString;
     regex: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        comments: "comments";
+        body: "body";
+        all: "all";
+    }>>;
 }, z.core.$strict>;
 export declare const ExecuteBatchSchema: z.ZodObject<{
     sessionId: z.ZodString;
@@ -77,8 +90,8 @@ export declare const ExecuteBatchSchema: z.ZodObject<{
         widthEmu: z.ZodOptional<z.ZodNumber>;
         heightEmu: z.ZodOptional<z.ZodNumber>;
         chartType: z.ZodOptional<z.ZodEnum<{
-            line: "line";
             area: "area";
+            line: "line";
             bar: "bar";
             column: "column";
             columnStacked: "columnStacked";
@@ -365,7 +378,6 @@ export declare const ExecuteBatchSchema: z.ZodObject<{
         border: z.ZodOptional<z.ZodString>;
         color: z.ZodOptional<z.ZodString>;
         sz: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
-        fontSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
         vAlign: z.ZodOptional<z.ZodString>;
         align: z.ZodOptional<z.ZodPreprocess<z.ZodEnum<{
             center: "center";
@@ -557,8 +569,8 @@ export declare const ExecuteBatchSchema: z.ZodObject<{
         }>>;
         target: z.ZodOptional<z.ZodString>;
         chartType: z.ZodOptional<z.ZodEnum<{
-            line: "line";
             area: "area";
+            line: "line";
             bar: "bar";
             column: "column";
             columnStacked: "columnStacked";
@@ -598,8 +610,8 @@ export declare const ExecuteBatchSchema: z.ZodObject<{
                     b: "b";
                     tr: "tr";
                     t: "t";
-                    none: "none";
                     r: "r";
+                    none: "none";
                     l: "l";
                 }>>;
                 overlay: z.ZodOptional<z.ZodBoolean>;
@@ -724,6 +736,7 @@ export declare const ExecuteBatchSchema: z.ZodObject<{
         action: z.ZodLiteral<"callout">;
         text: z.ZodString;
         anchor: z.ZodOptional<z.ZodString>;
+        id: z.ZodOptional<z.ZodString>;
         title: z.ZodOptional<z.ZodString>;
         theme: z.ZodOptional<z.ZodString>;
         position: z.ZodOptional<z.ZodEnum<{
@@ -820,24 +833,31 @@ export declare const ExecuteBatchSchema: z.ZodObject<{
     }, z.core.$strict>, z.ZodObject<{
         action: z.ZodLiteral<"comment">;
         operation: z.ZodEnum<{
+            delete: "delete";
             insert: "insert";
             reply: "reply";
+            resolve: "resolve";
+            unresolve: "unresolve";
         }>;
         target: z.ZodString;
-        text: z.ZodString;
+        text: z.ZodOptional<z.ZodString>;
         author: z.ZodOptional<z.ZodString>;
         date: z.ZodOptional<z.ZodString>;
         expectedVersion: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>, z.ZodObject<{
         action: z.ZodLiteral<"trackedChange">;
         operation: z.ZodEnum<{
+            accept: "accept";
+            reject: "reject";
             delete: "delete";
             insert: "insert";
             acceptAll: "acceptAll";
             rejectAll: "rejectAll";
         }>;
+        ids: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
         target: z.ZodOptional<z.ZodString>;
         text: z.ZodOptional<z.ZodString>;
+        occurrence: z.ZodOptional<z.ZodNumber>;
         author: z.ZodOptional<z.ZodString>;
         date: z.ZodOptional<z.ZodString>;
         expectedVersion: z.ZodOptional<z.ZodNumber>;

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

@@ -256,6 +256,12 @@ export interface McpSessionStats {
  * sandbox/paths), so MCP/engine verdicts can never disagree on semantics.
  */
 export declare function getMcpAllowedRoots(): string[];
+/**
+ * Plain-words description of where files may go right now, for error remedies. When the user
+ * named folders (--allowed-dir, ASTRA_EXTRA_DOC_ROOTS) those folders are the whole boundary, so
+ * the text names them; otherwise it names the defaults and how to widen them.
+ */
+export declare function describeAllowedFolders(): string;
 export { canonicalizeForMcp };
 /**
  * M3: jailed document-path validator.

package/dist/tools/compose-document.d.ts

@@ -41,6 +41,11 @@ export declare const ComposeDocumentSchema: z.ZodObject<{
     }>>;
     styleGuide: z.ZodOptional<z.ZodString>;
     dollarMath: z.ZodOptional<z.ZodBoolean>;
+    anchor: z.ZodOptional<z.ZodString>;
+    position: z.ZodOptional<z.ZodEnum<{
+        before: "before";
+        after: "after";
+    }>>;
 }, z.core.$strict>;
 export type ComposeDocumentInput = z.infer<typeof ComposeDocumentSchema>;
 export declare const COMPOSE_DOCUMENT_DESCRIPTION: string;
@@ -61,6 +66,8 @@ type ComposeDocumentOk = {
      * renumbered by position on reopen.
      */
     persistentIds?: Record<string, string>;
+    /** Set when dc:title was a template placeholder and is now written from the content: where it came from. */
+    titleSetFrom?: string;
     /** Per-op attribution (same rule as execute_batch: exact id claims, remainder best-effort). */
     results: BatchOpCreatedIds[];
     /** Read-only post-compose OOXML verdict (proof the composed package validates; save re-gates before writing). */

package/dist/tools/export.d.ts

@@ -5,8 +5,8 @@ export declare const ExportDocumentSchema: z.ZodObject<{
     sessionId: z.ZodString;
     format: z.ZodEnum<{
         markdown: "markdown";
-        html: "html";
         md: "md";
+        html: "html";
         pdf: "pdf";
     }>;
     outPath: z.ZodOptional<z.ZodString>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attentionform/astra-mcp-server",
-  "version": "0.2.1",
+  "version": "0.4.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.2.1",
-    "@attentionform/ooxml-validator": "^0.2.1",
+    "@attentionform/astra-engine": "^0.4.0",
+    "@attentionform/ooxml-validator": "^0.4.0",
     "@modelcontextprotocol/sdk": "^1.32.2",
     "@xmldom/xmldom": "0.8.15",
     "adm-zip": "0.6.1",