@json-to-office/mcp-server 1.2.0

package/dist/index.d.ts

@@ -0,0 +1,718 @@
+import { McpServer, McpServerFactory, JsonSchemaType, StandardSchemaWithJSON } from '@modelcontextprotocol/server';
+import { FormatAdapter, FormatName } from '@json-to-office/jto-ops';
+export { FormatAdapter, FormatName } from '@json-to-office/jto-ops';
+import { ValidationError } from '@json-to-office/shared';
+
+/**
+ * Structured results, not protocol errors.
+ *
+ * A JSON-RPC error tells the agent "the call failed" and nothing it can act
+ * on. Every defect this server can describe — a bad document, an unknown
+ * handle, a missing host binary — is therefore a normal tool RESULT carrying
+ * path-addressed diagnostics, which the agent can read, repair and retry.
+ * Protocol errors stay reserved for transport and server failures (#202).
+ */
+
+type DiagnosticSeverity = 'error' | 'warning' | 'info';
+/**
+ * One machine-actionable defect.
+ *
+ * `path` is an RFC 6901 JSON Pointer into the document the tool was given, so
+ * an agent holding a workspace handle can turn a diagnostic straight into a
+ * JSON Patch target (#271).
+ */
+interface Diagnostic {
+    severity: DiagnosticSeverity;
+    /** Stable machine code — see `ERROR_CODES`. */
+    code: string;
+    message: string;
+    /** JSON Pointer into the offending document, when the defect has a location. */
+    path?: string;
+    /** What to do about it, in one sentence. */
+    suggestion?: string;
+    /** Free-form extras (offending value, component name, renderer id, …). */
+    context?: Record<string, unknown>;
+}
+/**
+ * The envelope every tool's `structuredContent` starts from.
+ *
+ * `ok` is the single field a caller must branch on; `diagnostics` is always
+ * present (possibly empty) so clients never special-case its absence.
+ */
+interface ToolEnvelope {
+    ok: boolean;
+    diagnostics: Diagnostic[];
+}
+/**
+ * Stable codes. Callers — including our own tests and downstream agents —
+ * branch on these, so treat them as API: add freely, rename never.
+ *
+ * `E_` for something that blocks, `W_` for something that does not. Every
+ * `code` this server puts on the wire is one of these: the validators speak
+ * three private dialects of their own (TypeBox ordinals, snake_case, the
+ * cores' own names) and `normalizeCode` maps all three in here at the
+ * boundary, so an agent has exactly one vocabulary to branch on.
+ */
+declare const ERROR_CODES: {
+    /** An exception escaped a tool handler. Always a bug here, never the caller's. */
+    readonly INTERNAL: "E_INTERNAL";
+    /** Neither `document` nor `handle` was supplied. */
+    readonly DOC_SOURCE_MISSING: "E_DOC_SOURCE_MISSING";
+    /** Both `document` and `handle` were supplied. */
+    readonly DOC_SOURCE_AMBIGUOUS: "E_DOC_SOURCE_AMBIGUOUS";
+    /** `handle` names no open workspace on this connection. */
+    readonly UNKNOWN_HANDLE: "E_UNKNOWN_HANDLE";
+    /** `revision` does not match the workspace's current revision. */
+    readonly STALE_REVISION: "E_STALE_REVISION";
+    /** A handle was used but no workspace store is installed (#271 not wired). */
+    readonly WORKSPACES_UNAVAILABLE: "E_WORKSPACES_UNAVAILABLE";
+    /** A requested output name resolved outside the output root. */
+    readonly OUTPUT_ROOT_ESCAPE: "E_OUTPUT_ROOT_ESCAPE";
+    /** Inline base64 was requested for an artifact over the size limit. */
+    readonly ARTIFACT_TOO_LARGE: "E_ARTIFACT_TOO_LARGE";
+    /** The document failed a rule that has no more specific code. */
+    readonly INVALID_DOCUMENT: "E_INVALID_DOCUMENT";
+    /** The document could not be parsed as JSON. */
+    readonly INVALID_JSON: "E_INVALID_JSON";
+    /** A property the schema requires is absent. */
+    readonly REQUIRED_PROPERTY: "E_REQUIRED_PROPERTY";
+    /** A property the component does not declare. */
+    readonly UNEXPECTED_PROPERTY: "E_UNEXPECTED_PROPERTY";
+    /** A value of the wrong JSON type. */
+    readonly TYPE_MISMATCH: "E_TYPE_MISMATCH";
+    /** No branch of a union accepted the value. */
+    readonly UNION_MISMATCH: "E_UNION_MISMATCH";
+    /** Right type, outside the schema's bounds, length, pattern or format. */
+    readonly VALUE_CONSTRAINT: "E_VALUE_CONSTRAINT";
+    /** Right type and shape, but not a value this position accepts. */
+    readonly INVALID_VALUE: "E_INVALID_VALUE";
+    /** `name` is not a component this format registers, or not one allowed here. */
+    readonly UNKNOWN_COMPONENT: "E_UNKNOWN_COMPONENT";
+    /** Two props that exclude each other were both set. */
+    readonly MUTUALLY_EXCLUSIVE: "E_MUTUALLY_EXCLUSIVE";
+    /** A theme the document names does not exist. */
+    readonly THEME_NOT_FOUND: "E_THEME_NOT_FOUND";
+    /** The document is empty. */
+    readonly EMPTY_DOCUMENT: "E_EMPTY_DOCUMENT";
+    /** The renderer could draw the document, but not this one feature of it. */
+    readonly UNSUPPORTED_RENDERER_FEATURE: "W_UNSUPPORTED_RENDERER_FEATURE";
+    /** A note the render host emitted mid-run (unknown theme, unreadable theme file). */
+    readonly HOST_NOTE: "W_HOST_NOTE";
+    /** A generation warning the core raised without a code of its own. */
+    readonly GENERATION: "W_GENERATION";
+    /** A required host binary (LibreOffice, poppler) is absent. */
+    readonly DEPENDENCY_MISSING: "E_DEPENDENCY_MISSING";
+    /** The client cancelled the request. */
+    readonly CANCELLED: "E_CANCELLED";
+};
+type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+/** Build one diagnostic; `severity` defaults to `error`. */
+declare function diagnostic(code: string, message: string, extra?: Omit<Diagnostic, 'code' | 'message' | 'severity'> & {
+    severity?: DiagnosticSeverity;
+}): Diagnostic;
+/**
+ * Adapt the repo's `ValidationError` to a diagnostic.
+ *
+ * The two shapes already agree on `path`/`message`/`suggestion`; the mapping
+ * exists to give every diagnostic a code from one published vocabulary, so
+ * clients can always switch on `code`.
+ */
+declare function fromValidationError(error: ValidationError, severity?: DiagnosticSeverity): Diagnostic;
+declare function fromValidationErrors(errors: readonly ValidationError[] | undefined, severity?: DiagnosticSeverity): Diagnostic[];
+/** A failed operation: `ok: false` plus at least one diagnostic. */
+interface Failure extends ToolEnvelope {
+    ok: false;
+}
+declare function failure(code: string, message: string, extra?: Omit<Diagnostic, 'code' | 'message' | 'severity'> & {
+    severity?: DiagnosticSeverity;
+}): Failure;
+declare function failureFrom(diagnostics: Diagnostic[]): Failure;
+/** A successful operation, with room for the non-fatal diagnostics it collected. */
+declare function success<T extends object>(payload: T, diagnostics?: Diagnostic[]): T & ToolEnvelope;
+/**
+ * The two-channel result every tool returns.
+ *
+ * `structuredContent` is what the schema-aware client reads; the text block is
+ * the same object stringified, which is what a client without structured
+ * output support (and every transcript) sees. They are never allowed to
+ * disagree, hence one argument.
+ */
+declare function toolResult<T extends object>(payload: T): {
+    content: [{
+        type: 'text';
+        text: string;
+    }];
+    structuredContent: T;
+};
+/**
+ * Run a tool body, converting anything that escapes into a diagnostic and
+ * collecting the warnings the run emitted along the way.
+ *
+ * Without the first half an exception becomes a JSON-RPC error, which is
+ * exactly the signal we reserve for transport failures — the agent would be
+ * told the server broke when in fact one document did.
+ *
+ * The second half is why the sink is installed here and not once per
+ * connection: `runWithDiagnosticSink` is `AsyncLocalStorage.run`, so a sink
+ * wrapped around server setup is long gone by the time a request arrives on a
+ * later turn of the loop, and every "Unknown theme …" `jto-ops` emitted was
+ * dropped. One request is the largest scope that actually holds, and it is
+ * also the one the agent can read — the notes come back in `diagnostics`
+ * beside the result they belong to instead of on a stderr no client parses.
+ */
+declare function guarded<T extends object>(body: () => Promise<T>): Promise<T | Failure>;
+/**
+ * Codes for defects in the REQUEST rather than in the document.
+ *
+ * `ERROR_CODES` covers the document and the transport; these cover the options
+ * an agent chose, which are a third thing — an agent that asked for a renderer
+ * that does not exist has nothing to repair in its JSON.
+ */
+declare const OPTION_ERROR_CODES: {
+    /** `renderer` names no renderer this format registers. */
+    readonly UNKNOWN_RENDERER: "E_UNKNOWN_RENDERER";
+    /** `date` is not parseable as a date. */
+    readonly INVALID_DATE: "E_INVALID_DATE";
+    /** `themePath` is not a data-only JSON theme path. */
+    readonly INVALID_THEME_PATH: "E_INVALID_THEME_PATH";
+    /** The tool does not support the requested format. */
+    readonly UNSUPPORTED_FORMAT: "E_UNSUPPORTED_FORMAT";
+};
+/**
+ * Normalize a validator path to an RFC 6901 JSON Pointer.
+ *
+ * The validators speak two dialects. The document validators emit
+ * pointer-shaped strings already (`/children/0/props/text`) but leave `~`
+ * unescaped and spell the root `root`; the older component validators emit
+ * JavaScript-ish paths (`children[0].props.text`, `name`). Both end up here so
+ * that every diagnostic this server hands back can be used verbatim as a JSON
+ * Patch target against a workspace document (#271).
+ */
+declare function toJsonPointer(path: string | undefined): string | undefined;
+/** Adapt validator errors to diagnostics, with pointers and gate-faithful severity. */
+declare function validationDiagnostics(errors: readonly ValidationError[] | undefined): Diagnostic[];
+/**
+ * Diagnostics out of an exception, when the exception is really a bad document.
+ *
+ * Both cores gate generation by throwing — `JsonValidationError` carrying
+ * `validationErrors`, `PresentationValidationError` carrying `errors`. Left
+ * alone those become `E_INTERNAL`, which tells an agent the server broke when
+ * in fact its JSON did. Duck-typed rather than `instanceof`, because the
+ * classes live inside the cores that `jto-ops` deliberately imports on demand.
+ */
+declare function diagnosticsFromThrown(error: unknown): Diagnostic[] | undefined;
+interface DiagnosticCounts {
+    error: number;
+    warning: number;
+    info: number;
+}
+/** Diagnostics by severity. `error > 0` is what every tool gates `ok` on. */
+declare function countDiagnostics(diagnostics: readonly Diagnostic[]): DiagnosticCounts;
+
+/**
+ * Access to the `@json-to-office/jto-ops` format adapters.
+ *
+ * The adapters themselves import their core on demand, so constructing one is
+ * cheap; memoizing is about identity rather than cost — the DOCX adapter keeps
+ * per-instance caches (theme resolution, visual pre-pass counters) that a
+ * fresh instance per tool call would throw away every request.
+ */
+
+/** The adapter for `format`, constructed on first use and reused after. */
+declare function getAdapter(format: FormatName): FormatAdapter;
+/** Drop the memoized adapters. Tests use this to isolate their caches. */
+declare function resetAdapters(): void;
+/**
+ * Reject an unknown renderer before any work happens.
+ *
+ * The ids come from the core's own registry, so this can never advertise a
+ * stale set — same check `jto generate` makes, for the same reason: a typo
+ * should cost a message, not a full render followed by one.
+ */
+declare function checkRenderer(adapter: FormatAdapter, renderer: string | undefined): Promise<Failure | undefined>;
+/**
+ * The document as the requested renderer profile sees it.
+ *
+ * Both formats discriminate their schema on the document's own top-level
+ * `renderer`, so asking "does this validate as office-open?" means validating
+ * a copy that says so. A copy, not a mutation: the caller's tree — which may
+ * be a workspace document — must come back unchanged.
+ */
+declare function withRenderer(document: unknown, renderer: string | undefined): unknown;
+
+/**
+ * The one directory this server is allowed to write to.
+ *
+ * #204's contract is "no writes outside the root", and the caller names the
+ * file. Anything a caller can name, a caller can point somewhere else — so the
+ * check has to survive `..`, absolute paths, Windows drive letters and, once
+ * the root is a real directory on disk, symlinks planted inside it. Every
+ * write therefore goes through `resolveOutputPath`, which answers a path only
+ * when it provably lands inside the root.
+ */
+
+/** Env var that names the output root, below the `--output-dir` flag. */
+declare const OUTPUT_DIR_ENV = "JTO_MCP_OUTPUT_DIR";
+interface OutputRoot {
+    /** Absolute path of the root. May not exist on disk until first use. */
+    readonly path: string;
+    /**
+     * True when this root is a temp directory this process invented, and so is
+     * safe to delete on shutdown. A configured root is never removed.
+     */
+    readonly ephemeral: boolean;
+    /** Create the root if absent; returns its real (symlink-resolved) path. */
+    ensure(): Promise<string>;
+    /**
+     * Absolute path for `name` inside the root, with parent directories created.
+     * Fails structurally rather than throwing — the result is a tool result.
+     */
+    resolveOutputPath(name: string): Promise<ResolvedOutputPath>;
+    /** Remove the root, but only when `ephemeral`. */
+    dispose(): Promise<void>;
+}
+type ResolvedOutputPath = {
+    ok: true;
+    path: string;
+    relative: string;
+} | Failure;
+interface OutputRootOptions {
+    /** `--output-dir` value, highest precedence. */
+    flagDir?: string;
+    /** Defaults to `process.env`; injectable so the precedence is testable. */
+    env?: NodeJS.ProcessEnv;
+    /** Defaults to `os.tmpdir()`; injectable for the same reason. */
+    tmpDir?: string;
+}
+/**
+ * Reject a name before it ever touches the filesystem.
+ *
+ * Cheap, synchronous and exhaustive about the shapes that cannot possibly be
+ * inside the root, so the expensive realpath check below only ever has to
+ * worry about symlinks.
+ */
+declare function checkOutputName(name: string): Failure | undefined;
+/**
+ * Resolve the root: `--output-dir`, then `JTO_MCP_OUTPUT_DIR`, then a temp
+ * directory of our own.
+ *
+ * Creation is deferred — a connection that never generates anything should not
+ * leave a directory behind — so the temp root's name is decided here but the
+ * `mkdir` happens on first use.
+ */
+declare function createOutputRoot(options?: OutputRootOptions): OutputRoot;
+
+/**
+ * The workspace contract.
+ *
+ * #271 adds connection-scoped documents an agent edits by JSON Patch instead
+ * of resending the whole tree. This module is the seam: the interface, the
+ * holder for a host's process-wide override, and a stand-in that answers every
+ * call with a structured "unavailable" so the inline path works untouched
+ * before #271 lands and on any connection where workspaces are switched off.
+ *
+ * The holder is deliberately NOT where a connection's own store lives. Handles
+ * are scoped to one connection, and a module-global default would hand the
+ * second `createServer` in a process the first one's documents; the connection
+ * store hangs off its `ToolDeps` instead (`../tools/workspace.ts`).
+ *
+ * The real store lives in `../workspace/store.ts`.
+ *
+ * Every method resolves rather than throws. A missing handle and a stale
+ * revision are ordinary answers a tool reports to the agent, not server
+ * failures (see `errors.ts`).
+ */
+
+type WorkspaceResult<T> = ({
+    ok: true;
+} & T) | Failure;
+/** RFC 6902 operation. Paths are RFC 6901 pointers — no private dialect (#271). */
+interface JsonPatchOperation {
+    op: 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test';
+    path: string;
+    from?: string;
+    value?: unknown;
+}
+/** What `jto_workspace_list` shows, and what every mutation returns. */
+interface WorkspaceRecord {
+    /** Opaque, server-generated, meaningless outside this connection. */
+    handle: string;
+    format: FormatName;
+    /** Starts at 1 on create; +1 per committed patch. Never reused, never decreases. */
+    revision: number;
+    /** Size of the serialized document, for the agent's own budgeting. */
+    bytes: number;
+    createdAt: string;
+    updatedAt: string;
+    /** Caller-supplied label, echoed back verbatim. */
+    title?: string;
+    /** Revisions pinned by `snapshot`, still retrievable through `get`. */
+    pinnedRevisions: number[];
+}
+interface WorkspaceStore {
+    /**
+     * False on the stand-in. Tools read it to describe the connection's
+     * capabilities (`jto_info`) without provoking an error.
+     */
+    readonly available: boolean;
+    /** Open a document. The returned revision is 1. */
+    create(input: {
+        format: FormatName;
+        document: unknown;
+        title?: string;
+    }): Promise<WorkspaceResult<{
+        record: WorkspaceRecord;
+    }>>;
+    /**
+     * Read a document.
+     *
+     * With `revision`, the read is checked: a revision that is neither current
+     * nor pinned fails `E_STALE_REVISION` rather than quietly returning newer
+     * JSON than the caller reasoned about. With `paths`, only those JSON
+     * Pointers are projected, keyed by pointer — that is `jto_workspace_inspect`
+     * on a large document.
+     */
+    get(handle: string, options?: {
+        revision?: number;
+        paths?: readonly string[];
+    }): Promise<WorkspaceResult<{
+        record: WorkspaceRecord;
+        document: unknown;
+        /** Present only when `paths` was given. */
+        projection?: Record<string, unknown>;
+    }>>;
+    /**
+     * Apply a patch atomically.
+     *
+     * Syntax and paths are checked, the patch is applied to a copy, and only a
+     * clean apply commits and bumps the revision — a half-applied document is
+     * never observable. `baseRevision` makes the write conditional; omitting it
+     * is a deliberate last-writer-wins.
+     */
+    patch(input: {
+        handle: string;
+        operations: readonly JsonPatchOperation[];
+        baseRevision?: number;
+    }): Promise<WorkspaceResult<{
+        record: WorkspaceRecord;
+    }>>;
+    /**
+     * Export the document and pin the revision it was taken at.
+     *
+     * The pin is what makes "snapshot before risky changes" real: after further
+     * patches, `get(handle, pinnedRevision)` still returns this exact tree, so
+     * an agent can compare or roll back without having kept the JSON in context.
+     */
+    snapshot(handle: string): Promise<WorkspaceResult<{
+        record: WorkspaceRecord;
+        document: unknown;
+    }>>;
+    /** Every open handle on this connection. Recovers references after context loss. */
+    list(): Promise<WorkspaceResult<{
+        records: WorkspaceRecord[];
+    }>>;
+    /** Release a handle and its memory. Idempotent: closing twice is not an error. */
+    close(handle: string): Promise<WorkspaceResult<{
+        handle: string;
+        closed: boolean;
+    }>>;
+    /**
+     * Release every handle at once.
+     *
+     * A connection's store is reachable only through its `ToolDeps`, so the
+     * documents go when the connection's deps do; this is for a host that wants
+     * the memory back at a moment of its own choosing.
+     */
+    closeAll(): Promise<void>;
+}
+/**
+ * The no-workspaces implementation.
+ *
+ * Note `list` succeeds with an empty array: "no open documents" is a true and
+ * useful answer, and failing it would make an agent think its own bookkeeping
+ * broke.
+ */
+declare const unavailableWorkspaceStore: WorkspaceStore;
+/** Install a process-wide store. Passing `undefined` removes the override. */
+declare function setWorkspaceStore(store: WorkspaceStore | undefined): void;
+declare function getWorkspaceStore(): WorkspaceStore;
+
+/**
+ * What every tool module is handed at registration.
+ *
+ * Tools reach for nothing else process-wide: the output root, the adapters and
+ * the workspace store all arrive here, so a test can stand a whole server up
+ * on a temp directory and a fake store without mutating global state.
+ */
+
+interface ToolDeps {
+    /** `@json-to-office/mcp-server`'s own version, as reported by `jto_info`. */
+    serverVersion: string;
+    /** The only directory the server writes to. */
+    outputRoot: OutputRoot;
+    /** Memoized format adapters from `@json-to-office/jto-ops`. */
+    getAdapter(format: FormatName): FormatAdapter;
+    /**
+     * The connection's workspace store.
+     *
+     * A function, not a value: #271 installs the real store after the tools are
+     * registered, and a snapshot taken at registration would pin the stand-in.
+     */
+    workspaces(): WorkspaceStore;
+    /** Ceiling for `outputMode: 'base64'`, in bytes. */
+    maxInlineArtifactBytes: number;
+}
+interface CreateToolDepsOptions {
+    /** `--output-dir`, or an already-built root (tests hand one in). */
+    outputDir?: string;
+    outputRoot?: OutputRoot;
+    env?: NodeJS.ProcessEnv;
+    serverVersion?: string;
+    workspaces?: () => WorkspaceStore;
+    getAdapter?: (format: FormatName) => FormatAdapter;
+    maxInlineArtifactBytes?: number;
+}
+declare function createToolDeps(options?: CreateToolDepsOptions): ToolDeps;
+
+/**
+ * The server, assembled once.
+ *
+ * Every tool module exposes the same `register(server, deps)` and is listed
+ * here in a fixed order, so the modules can be written independently and this
+ * file never has to change again as they land. Registration order is the order
+ * `tools/list` reports, which is also the order an agent reads them in — hence
+ * info, then discovery, then the authoring loop, then workspaces.
+ */
+
+/**
+ * The server's own prompt, surfaced to the client at initialize.
+ *
+ * These are the invariants an agent gets wrong without being told: that the
+ * JSON is the artifact and the file is a build product, that large rewrites
+ * lose more than they fix, and that looking at a rendered page is cheaper than
+ * reasoning about whether a layout worked (#271).
+ */
+declare const SERVER_INSTRUCTIONS = "Author Microsoft Word (.docx) and PowerPoint (.pptx) documents as JSON.\n\nThe JSON is authoritative. A generated file is a build product of the document JSON plus a renderer, a theme, fonts, assets and options \u2014 edit the JSON and regenerate; never treat the binary as the source.\n\nWorking rules:\n- Discover before authoring. Call jto_info first, then jto_discover and jto_describe_component (or read the jto:// resources) for the components and renderer ids a format actually supports.\n- Make small edits. With a workspace handle, patch precisely (RFC 6902 over RFC 6901 paths) instead of resending the whole document; without one, change one region at a time.\n- Validate often. Run jto_validate after each edit rather than once at the end; diagnostics are path-addressed, so they map straight back onto the JSON you just changed.\n- Preview when the answer is visual. jto_preview renders pages to PNG; use it whenever layout, overflow or fit is in question, not only before finishing.\n- Snapshot before risky changes. jto_workspace_snapshot pins the current revision so a restructuring you cannot cleanly undo is still recoverable.\n\nDocument defects come back as structured diagnostics with ok: false, not as errors \u2014 read them and repair. Generated files are written under the server's output root and returned as paths; ask for base64 only for small artifacts.";
+/** Build a server with every tool and resource registered. */
+declare function createServer(deps: ToolDeps): McpServer;
+/**
+ * The factory `serveStdio` wants.
+ *
+ * It is called once per connection and, on a 2025-era opening, once more for
+ * the pinned legacy instance — so it must build a fresh `McpServer` every
+ * time. `deps` are deliberately shared: the output root and the workspace
+ * store belong to the process, which for stdio is the connection.
+ */
+declare function createServerFactory(deps: ToolDeps): McpServerFactory;
+
+/**
+ * Tool schemas, authored as plain JSON Schema.
+ *
+ * `fromJsonSchema` wraps a JSON Schema in the Standard Schema shape the SDK
+ * validates against, and passes the schema itself through to `tools/list`
+ * verbatim. Authoring JSON Schema directly therefore keeps zod out of our own
+ * source and guarantees that what an agent discovers is exactly what the
+ * server enforces — no conversion step in between to drift.
+ */
+
+/**
+ * Wrap a JSON Schema for `registerTool`.
+ *
+ * The type parameter is the handler's view of the validated value — the SDK
+ * infers callback arguments from it and cannot derive it from a runtime schema
+ * object, so pass it explicitly: `S<{ format: FormatName }>({ … })`.
+ */
+declare function S<T = unknown>(schema: JsonSchemaType): StandardSchemaWithJSON<T, T>;
+/** Every format this server can author. */
+declare const FORMAT_NAMES: readonly FormatName[];
+declare const formatSchema: JsonSchemaType;
+/**
+ * The document a tool operates on: inline JSON, or a workspace reference.
+ *
+ * Both are spelled out on every document-taking tool rather than hidden behind
+ * a `oneOf`, because a discovering agent reads the flat property list and many
+ * clients render nothing else. `doc-source.ts` enforces the exclusivity that
+ * the schema deliberately does not.
+ */
+declare const documentSourceProperties: Record<string, JsonSchemaType>;
+/** Human-readable restatement of the rule the schema cannot express. */
+declare const DOCUMENT_SOURCE_RULE = "Supply exactly one of `document` (inline JSON) or `handle` (an open workspace).";
+/**
+ * Renderer, theme and determinism knobs, mirroring `GeneratorOptions` from
+ * `@json-to-office/jto-ops`. Shared verbatim by validate/generate/preview/diff
+ * so the same document renders the same way whichever tool an agent reaches
+ * for.
+ */
+declare const renderOptionProperties: Record<string, JsonSchemaType>;
+/** How a generated file comes back: written to disk, or inline. */
+declare const artifactOutputProperties: Record<string, JsonSchemaType>;
+declare const diagnosticSchema: JsonSchemaType;
+declare const diagnosticsSchema: JsonSchemaType;
+/** The `{ ok, diagnostics }` floor every tool output schema builds on. */
+declare const envelopeProperties: Record<string, JsonSchemaType>;
+/**
+ * A delivered file, exactly as `deliverArtifact` returns one.
+ *
+ * `relative` is not decoration: the SDK validates outgoing
+ * `structuredContent` against the declared schema, and this object closes
+ * `additionalProperties`, so omitting a field every path-mode artifact
+ * carries would turn each successful generation into an output-validation
+ * error. Generate, diff, preview and snapshot all report through this one
+ * definition.
+ */
+declare const artifactSchema: JsonSchemaType;
+/**
+ * `documentSourceProperties` as one nested object.
+ *
+ * A tool that takes two documents cannot spell them both flat — `jto_docx_diff`
+ * would need two `document` keys — so `before`/`after` each carry a bag of
+ * this shape. Single-document tools stay flat, which is what an agent reading
+ * a property list expects.
+ */
+declare const documentSourceSchema: JsonSchemaType;
+/** Where a tool actually read its document from, echoed back to the caller. */
+declare const sourceSummarySchema: JsonSchemaType;
+/** Compose an output schema from the standard envelope plus tool-specific fields. */
+declare function outputSchema(properties: Record<string, JsonSchemaType>, required?: readonly string[]): JsonSchemaType;
+/** The inline/handle pair, as the tool handlers see it after validation. */
+interface DocumentSourceInput {
+    document?: unknown;
+    handle?: string;
+    revision?: number;
+}
+/** `sourceSummarySchema`, as the tools report it. */
+interface SourceSummary {
+    origin: 'inline' | 'workspace';
+    handle?: string;
+    revision?: number;
+}
+/** `renderOptionProperties`, as the tool handlers see it after validation. */
+interface RenderOptionsInput {
+    renderer?: string;
+    theme?: string;
+    themePath?: string;
+    deterministic?: boolean;
+    generatedAt?: string;
+    baseDir?: string;
+}
+/** `artifactOutputProperties`, as the tool handlers see it after validation. */
+interface ArtifactOutputInput {
+    outputMode?: 'path' | 'base64';
+    filename?: string;
+}
+
+/**
+ * Delivery of generated bytes to the client.
+ *
+ * Default is a path under the output root: a .pptx inlined as base64 costs the
+ * agent its context window and the transport a multi-megabyte frame, for a
+ * payload it almost always just wants to hand to a viewer. Inlining is
+ * available, but only when asked for and only under a hard ceiling (#204).
+ */
+
+/**
+ * Ceiling for `outputMode: 'base64'`.
+ *
+ * 4 MiB of binary is ~5.5 MiB of base64 — already past what most clients will
+ * put in a model context, and the point beyond which a path is strictly better
+ * for everyone.
+ */
+declare const MAX_INLINE_ARTIFACT_BYTES: number;
+declare const MIME_TYPES: Record<string, string>;
+type ArtifactMode = 'path' | 'base64';
+type Artifact = {
+    mode: 'path';
+    /** Absolute path, always inside the output root. */
+    path: string;
+    /** Path relative to the output root, for display. */
+    relative: string;
+    bytes: number;
+    filename: string;
+    mimeType: string;
+} | {
+    mode: 'base64';
+    base64: string;
+    bytes: number;
+    filename: string;
+    mimeType: string;
+};
+interface DeliverArtifactOptions {
+    /** Name inside the output root; rejected if it escapes (see `output-root.ts`). */
+    filename: string;
+    mimeType: string;
+    /** Defaults to `path`. */
+    mode?: ArtifactMode;
+    outputRoot: OutputRoot;
+    /** Override the inline ceiling; tests and hosts with tighter budgets use it. */
+    maxInlineBytes?: number;
+}
+type DeliverArtifactResult = {
+    ok: true;
+    artifact: Artifact;
+} | Failure;
+/**
+ * Turn a generated buffer into the payload a tool reports.
+ *
+ * Over-limit inlining is a refusal, not a silent downgrade to a path: an agent
+ * that asked for bytes and got a path would go looking for a file it cannot
+ * read on a host with no shared filesystem, and never learn why.
+ */
+declare function deliverArtifact(buffer: Buffer, options: DeliverArtifactOptions): Promise<DeliverArtifactResult>;
+
+/**
+ * `{ document? | handle?, revision? }` → one concrete JSON document.
+ *
+ * Every document-taking tool starts here, so the inline and workspace paths
+ * cannot drift: whichever the agent used, the tool body sees the same tree and
+ * the same failure vocabulary.
+ */
+
+type ResolvedDocument = {
+    ok: true;
+    document: unknown;
+    origin: 'inline';
+} | {
+    ok: true;
+    document: unknown;
+    origin: 'workspace';
+    handle: string;
+    /** The revision actually read, which may be older than current when pinned. */
+    revision: number;
+} | Failure;
+/**
+ * Resolve a document source.
+ *
+ * The store is a parameter rather than a module lookup so a tool can be tested
+ * against a fake without touching the process-wide holder; it defaults to the
+ * installed store, which is what production wants.
+ */
+declare function resolveDocumentSource(source: DocumentSourceInput, store?: WorkspaceStore): Promise<ResolvedDocument>;
+/**
+ * Where the tool read the document from, for the caller's own bookkeeping.
+ *
+ * Every document-taking tool echoes this, so an agent can tell at a glance
+ * whether the answer describes the JSON it sent or the workspace revision the
+ * server holds — and, when pinned, which revision that actually was.
+ */
+declare function sourceSummary(resolved: Extract<ResolvedDocument, {
+    ok: true;
+}>): SourceSummary;
+/**
+ * Parse a document that arrived as a JSON string.
+ *
+ * Tools take `document` as an object, but a handful of callers (file contents,
+ * `jto_docx_diff`'s two sides) hold text; a parse failure is the agent's
+ * defect to fix, so it comes back structured like every other one.
+ */
+declare function parseDocumentJson(text: string, path?: string): {
+    ok: true;
+    document: unknown;
+} | Failure;
+
+declare const SERVER_VERSION: string;
+/** MCP `serverInfo.name`. Stable: clients key configuration off it. */
+declare const SERVER_NAME = "json-to-office";
+/** npm identity, reported by `jto_info` next to the workspace packages. */
+declare const PACKAGE_NAME = "@json-to-office/mcp-server";
+
+export { type Artifact, type ArtifactMode, type ArtifactOutputInput, type CreateToolDepsOptions, DOCUMENT_SOURCE_RULE, type DeliverArtifactOptions, type DeliverArtifactResult, type Diagnostic, type DiagnosticCounts, type DiagnosticSeverity, type DocumentSourceInput, ERROR_CODES, type ErrorCode, FORMAT_NAMES, type Failure, type JsonPatchOperation, MAX_INLINE_ARTIFACT_BYTES, MIME_TYPES, OPTION_ERROR_CODES, OUTPUT_DIR_ENV, type OutputRoot, type OutputRootOptions, PACKAGE_NAME, type RenderOptionsInput, type ResolvedDocument, type ResolvedOutputPath, S, SERVER_INSTRUCTIONS, SERVER_NAME, SERVER_VERSION, type SourceSummary, type ToolDeps, type ToolEnvelope, type WorkspaceRecord, type WorkspaceResult, type WorkspaceStore, artifactOutputProperties, artifactSchema, checkOutputName, checkRenderer, countDiagnostics, createOutputRoot, createServer, createServerFactory, createToolDeps, deliverArtifact, diagnostic, diagnosticSchema, diagnosticsFromThrown, diagnosticsSchema, documentSourceProperties, documentSourceSchema, envelopeProperties, failure, failureFrom, formatSchema, fromValidationError, fromValidationErrors, getAdapter, getWorkspaceStore, guarded, outputSchema, parseDocumentJson, renderOptionProperties, resetAdapters, resolveDocumentSource, setWorkspaceStore, sourceSummary, sourceSummarySchema, success, toJsonPointer, toolResult, unavailableWorkspaceStore, validationDiagnostics, withRenderer };