@attentionform/astra-mcp-server 0.0.0-stage → 0.1.0

package/dist/tools/visual.d.ts

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * @attentionform/astra-mcp-server visual tool.
+ *
+ * Dual-mode visual review for MCP:
+ * - Level 1 (default, always-on, <500 tokens): deterministic spatial
+ *   telemetry (ASCII wireframe + large-defect warnings) in every inspect.
+ * - Level 2 (opt-in `withVisual:true` tool param only, no launch flag): headless
+ *   LO -> PDF -> pdftoppm render (PNG default, JPEG opt-in) returning
+ *   server-side FILE PATHS + metadata (never base64 — token bloat).
+ *
+ * Missing binaries degrade gracefully with `{ok:false, code:'E_DEPENDENCY',
+ * remedy}` (install LibreOffice + poppler-utils). Prompt law applies:
+ * image is approximate, XML is truth, large defects only.
+ *
+ * Engine wiring: session store via ../lib/session-store, visual review via
+ * @attentionform/astra-engine (single source of truth, no drift).
+ * Standalone module: registered in `src/index.ts` tool table.
+ */
+import { z } from 'zod';
+import { type McpSessionStore } from '../lib/session-store';
+import { buildVisualTelemetry, hasVisualPdfBackend as hasPdfBackend, type EngineErrorCode, type VisualImageFormat, type VisualPageMap, type VisualTelemetry } from '@attentionform/astra-engine';
+/** Legacy argv helper; opt-in renders use the withVisual tool param (startup rejects unknown flags). */
+export declare const MCP_VISUAL_FLAG = "--with-visual";
+/** True when argv carries `--with-visual`; startup rejects unknown flags so this enables nothing. */
+export declare function isVisualEnabled(argv?: readonly string[]): boolean;
+export type McpVisualErrorCode = EngineErrorCode;
+export interface McpVisualError {
+    ok: false;
+    code: McpVisualErrorCode;
+    message: string;
+    remedy: string;
+}
+export interface VisualImageRef {
+    page: number;
+    path: string;
+    format: VisualImageFormat;
+    bytes: number;
+}
+export interface VisualInspectOk {
+    ok: true;
+    sessionId: string;
+    revision: number;
+    /**
+     * Phase C-1b: true when the in-memory session holds unsaved execute_batch
+     * edits — visual renders in-memory session state, not the last saved file.
+     */
+    dirty: boolean;
+    /** Always-on spatial telemetry (<500 tokens). */
+    telemetry: VisualTelemetry;
+    /** Prompt law + verify rule (vision-model instruction). */
+    promptLaw: string;
+    verifyRule: string;
+    /** Opt-in renders (only when withVisual:true). File paths, not base64. */
+    images?: VisualImageRef[];
+    totalPages: number;
+    outDir?: string;
+    /**
+     * Advisory stale-seed hint (additive, present only when untouched template
+     * seed tables are detected; absent when clean). Lists table node ids whose
+     * text still matches known financial-template seed values.
+     */
+    staleTableIds?: string[];
+    /** One-line advisory naming staleTableIds + heuristic limits. */
+    staleContentHint?: string;
+    /** True when the stale list hit STALE_SEED_TABLE_MAX (ids truncated). */
+    staleTruncated?: boolean;
+}
+/**
+ * Q0b: pure mapper for render-stage failures (exported for the E-code
+ * contract test). Previously every non-DEPENDENCY failure collapsed to E_IO;
+ * now the engine code survives verbatim, E_IO stays the uncoded fallback.
+ */
+export declare function mapVisualRenderError(err: unknown): McpVisualError;
+/**
+ * Q0b: pure mapper for outer (session-resolution) failures. Previously every
+ * failure collapsed to E_SESSION; now the engine code survives verbatim,
+ * E_SESSION stays the fallback for unknown/expired sessions.
+ */
+export declare function mapVisualOuterError(err: unknown): McpVisualError;
+export declare const VisualInspectSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    pages: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    withVisual: z.ZodOptional<z.ZodBoolean>;
+    format: z.ZodOptional<z.ZodEnum<{
+        png: "png";
+        jpeg: "jpeg";
+    }>>;
+    jpegQuality: z.ZodOptional<z.ZodNumber>;
+    dpi: z.ZodOptional<z.ZodNumber>;
+    outputDir: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type VisualInspectInput = z.infer<typeof VisualInspectSchema>;
+export declare const VISUAL_INSPECT_DESCRIPTION: string;
+/**
+ * Stale seed-table hint (advisory, additive, bounded).
+ *
+ * Detects tables that still carry untouched `financial`-template seed values
+ * (Metric/Previous Q/Current Q/Net Revenue seed figures). A table counts as
+ * stale when its concatenated text matches >=2 markers — a single generic
+ * word (e.g. "Metric") never fires alone. Present only when stale tables
+ * exist; clean docs stay silent (no fields emitted).
+ *
+ * Limits (honest): matches known financial-template seed strings only;
+ * custom templates and paraphrased stale content are NOT covered; an edited
+ * table still matches until ALL seed strings are replaced. Capped at
+ * STALE_SEED_TABLE_MAX ids (staleTruncated:true when capped).
+ */
+export declare const STALE_SEED_TABLE_MARKERS: readonly ["Net Revenue", "Operating Profit", "$1,250,000", "$1,520,000", "$340,000", "$415,000", "Previous Q", "Current Q", "Growth (%)"];
+/** Cap on stale table ids listed in one visual_inspect response. */
+export declare const STALE_SEED_TABLE_MAX = 10;
+type StaleAst = {
+    sections?: Array<{
+        nodes?: Array<{
+            id?: unknown;
+            type?: unknown;
+            metadata?: Record<string, unknown>;
+        }>;
+    }>;
+};
+/** Table node ids whose text still matches known template seed values (bounded). */
+export declare function findStaleSeedTables(ast: StaleAst): {
+    ids: string[];
+    truncated: boolean;
+};
+/** One-line advisory hint naming stale table ids (call only when ids non-empty). */
+export declare function buildStaleContentHint(ids: readonly string[], truncated: boolean): string;
+/**
+ * Pure telemetry enrichment for `inspect_document` (no MCP store needed).
+ * Returns the wireframe + warnings + token count, budget-enforced <500.
+ */
+export declare function buildInspectVisualTelemetry(ast: Parameters<typeof buildVisualTelemetry>[0], opts?: {
+    page?: number;
+    pageMap?: VisualPageMap | null;
+    renderTotalPages?: number;
+}): {
+    telemetry: VisualTelemetry;
+    promptLaw: string;
+    verifyRule: string;
+};
+/** Capability probe passthrough (respects PATH at call time). */
+export declare function visualBackendStatus(): ReturnType<typeof hasPdfBackend>;
+/** Artifacts dir passthrough (session workspace folder). */
+export declare function visualArtifactsDir(subDir?: string): string;
+export declare function visualTelemetryBudget(): number;
+export declare function estimateVisualTokens(text: string): number;
+/**
+ * Moves rendered images into the caller's folder as `<document>-page-<n>.<ext>`.
+ * The folder was already checked against the allowed roots. The write refuses a
+ * symlink anywhere on the path and opens the name with O_NOFOLLOW, so a link
+ * planted before or during the write cannot redirect it. A file already under
+ * that name is replaced: it is the previous render of the same page.
+ */
+export declare function placeImages(images: VisualImageRef[], dir: string, docPath: string): VisualImageRef[];
+/**
+ * Store-aware handler: telemetry always, file-path images only when
+ * `withVisual:true`. Never throws — maps every failure to the
+ * `{ok:false, code, remedy}` contract (E_DEPENDENCY for missing binaries).
+ */
+export declare function handleVisualInspect(store: McpSessionStore, input: unknown): Promise<VisualInspectOk | McpVisualError>;
+export {};

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@attentionform/astra-mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Official Model Context Protocol (MCP) server for ASTra document IDE",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "astra-mcp-server": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "!dist/**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "BUSL-1.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Attentionform/astra.git",
+    "directory": "packages/mcp-server"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "astra",
+    "ooxml",
+    "docx",
+    "word",
+    "ai-agent"
+  ],
+  "type": "commonjs",
+  "scripts": {
+    "build": "node ../../scripts/check-adm-zip-imports.mjs && tsc --noEmit -p tsconfig.json && esbuild src/index.ts --bundle --packages=external --platform=node --target=node20 --format=cjs --outfile=dist/index.js --log-level=warning && tsc -p tsconfig.dts.json && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "start": "node dist/index.js",
+    "adm-zip-gate": "node ../../scripts/check-adm-zip-imports.mjs"
+  },
+  "dependencies": {
+    "@attentionform/astra-engine": "^0.1.0",
+    "@attentionform/ooxml-validator": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "@xmldom/xmldom": "0.8.15",
+    "adm-zip": "0.6.1",
+    "isomorphic-git": "^1.25.0",
+    "marked": "18.0.5",
+    "p-limit": "^3.1.0",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "esbuild": "^0.25.12",
+    "typescript": "^5.2.2",
+    "vitest": "^4.1.7"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "homepage": "https://attentionform.com",
+  "bugs": {
+    "url": "https://github.com/Attentionform/astra/issues"
+  },
+  "author": {
+    "name": "Attentionform",
+    "url": "https://attentionform.com"
+  }
+}