fluidcad 0.0.32 → 0.0.34

package/mcp/dist/tools/docs.js

@@ -0,0 +1,122 @@
+// Documentation tools — the agent-facing surface over `llm-docs/`.
+//
+// Each tool is a pure function over an injected `DocsIndex` so the server
+// wires it up via closure (no module-level singleton). Errors never throw
+// across the MCP boundary; everything is funneled into `ToolResult<T>`.
+import { err, ok } from "../types.js";
+export function listDocs(index, input = {}) {
+    try {
+        const docs = index.list(input.tag).map((d) => ({
+            id: d.id,
+            title: d.title,
+            summary: d.summary,
+            tags: d.tags,
+        }));
+        return ok({ docs });
+    }
+    catch (error) {
+        return err('internal', toMessage(error));
+    }
+}
+export function readDoc(index, input) {
+    if (!input || typeof input.id !== 'string' || input.id.length === 0) {
+        return err('invalid-input', '`id` is required and must be a non-empty string.');
+    }
+    const doc = index.get(input.id);
+    if (!doc) {
+        return err('invalid-input', `No doc with id "${input.id}".`);
+    }
+    try {
+        const body = index.body(doc.id) ?? '';
+        return ok({
+            id: doc.id,
+            title: doc.title,
+            body,
+            seeAlso: doc.seeAlso,
+        });
+    }
+    catch (error) {
+        return err('internal', toMessage(error));
+    }
+}
+export function searchDocs(index, input) {
+    if (!input || typeof input.query !== 'string' || input.query.length === 0) {
+        return err('invalid-input', '`query` is required and must be a non-empty string.');
+    }
+    if (input.limit !== undefined &&
+        (typeof input.limit !== 'number' || input.limit <= 0 || !Number.isFinite(input.limit))) {
+        return err('invalid-input', '`limit` must be a positive number when provided.');
+    }
+    try {
+        const limit = input.limit ?? 10;
+        const results = index.search(input.query, limit);
+        return ok({ results });
+    }
+    catch (error) {
+        return err('internal', toMessage(error));
+    }
+}
+export function getApiSignature(index, input) {
+    if (!input || typeof input.name !== 'string' || input.name.length === 0) {
+        return err('invalid-input', '`name` is required and must be a non-empty string.');
+    }
+    const docId = index.symbols[input.name];
+    if (!docId) {
+        return err('invalid-input', `No API symbol "${input.name}".`);
+    }
+    const doc = index.get(docId);
+    if (!doc) {
+        // The api index points at a docId that the main index does not know about
+        // — only possible if the manifests were generated separately, which should
+        // never happen because `build-llm-docs.ts` writes both atomically.
+        return err('internal', `API symbol "${input.name}" maps to missing doc "${docId}".`);
+    }
+    try {
+        const signature = index.firstCodeBlock(docId) ?? '';
+        return ok({
+            symbol: input.name,
+            docId: doc.id,
+            title: doc.title,
+            signature,
+            summary: doc.summary,
+        });
+    }
+    catch (error) {
+        return err('internal', toMessage(error));
+    }
+}
+export function getTypeDefinition(index, input) {
+    if (!input || typeof input.name !== 'string' || input.name.length === 0) {
+        return err('invalid-input', '`name` is required and must be a non-empty string.');
+    }
+    const docId = index.types[input.name];
+    if (!docId) {
+        return err('invalid-input', `No type "${input.name}". Call list_docs({tag:"type"}) to see every documented type.`);
+    }
+    const doc = index.get(docId);
+    if (!doc) {
+        return err('internal', `Type "${input.name}" maps to missing doc "${docId}".`);
+    }
+    try {
+        const definition = index.firstCodeBlock(docId) ?? '';
+        const body = index.body(docId) ?? '';
+        return ok({
+            name: doc.title,
+            docId: doc.id,
+            title: doc.title,
+            definition,
+            body,
+            summary: doc.summary,
+            seeAlso: doc.seeAlso,
+        });
+    }
+    catch (error) {
+        return err('internal', toMessage(error));
+    }
+}
+function toMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}

package/mcp/dist/tools/engine.d.ts

@@ -0,0 +1,56 @@
+import { type WorkspaceArg } from './inspection.ts';
+import { type ToolResult } from '../types.ts';
+export type RecomputeInput = WorkspaceArg;
+export type RecomputeOutput = {
+    success: boolean;
+};
+export declare function recompute(input: RecomputeInput): Promise<ToolResult<RecomputeOutput>>;
+export type RollbackToInput = WorkspaceArg & {
+    index: number;
+};
+export type RollbackToOutput = {
+    success: boolean;
+};
+export declare function rollbackTo(input: RollbackToInput): Promise<ToolResult<RollbackToOutput>>;
+export type AddBreakpointInput = WorkspaceArg & {
+    file: string;
+    line: number;
+};
+export type AddBreakpointOutput = {
+    success: boolean;
+};
+export declare function addBreakpoint(input: AddBreakpointInput): Promise<ToolResult<AddBreakpointOutput>>;
+export type ClearBreakpointsInput = WorkspaceArg;
+export type ClearBreakpointsOutput = {
+    success: boolean;
+};
+export declare function clearBreakpoints(input: ClearBreakpointsInput): Promise<ToolResult<ClearBreakpointsOutput>>;
+export type ImportStepInput = WorkspaceArg & {
+    path: string;
+};
+export type ImportStepOutput = {
+    success: boolean;
+    fileName: string;
+};
+export declare function importStep(input: ImportStepInput): Promise<ToolResult<ImportStepOutput>>;
+export type ExportFormat = 'step' | 'stl';
+export type ExportResolution = 'coarse' | 'medium' | 'fine';
+export type ExportInput = WorkspaceArg & {
+    format: ExportFormat;
+    shapeIds: string[];
+    saveAsPath?: string;
+    resolution?: ExportResolution;
+    includeColors?: boolean;
+};
+export type ExportSavedOutput = {
+    savedTo: string;
+    bytesWritten: number;
+};
+export type ExportBase64Output = {
+    format: ExportFormat;
+    mimeType: string;
+    base64: string;
+    bytes: number;
+};
+export type ExportOutput = ExportSavedOutput | ExportBase64Output;
+export declare function exportShapes(input: ExportInput): Promise<ToolResult<ExportOutput>>;

package/mcp/dist/tools/engine.js

@@ -0,0 +1,145 @@
+// Engine-control tools — wrappers around existing FluidCAD REST routes that
+// let the agent recompute, rollback, set breakpoints, and import/export
+// geometry. All workspace resolution and HTTP-error mapping is shared with
+// the inspection tools.
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { resolveClient } from "./inspection.js";
+import { HttpError } from "../client.js";
+import { err, ok } from "../types.js";
+async function callWithClient(input, fn) {
+    const resolved = resolveClient(input);
+    if (resolved.ok === false) {
+        return resolved;
+    }
+    const { client } = resolved.data;
+    try {
+        const data = await fn(client);
+        return ok(data);
+    }
+    catch (e) {
+        if (e instanceof HttpError) {
+            return err('http-error', `HTTP ${e.statusCode}: ${e.body.slice(0, 200)}`, {
+                statusCode: e.statusCode,
+            });
+        }
+        return err('internal', e?.message ?? String(e));
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}
+export async function recompute(input) {
+    return callWithClient(input, (client) => client.postJson('/api/recompute', {}));
+}
+export async function rollbackTo(input) {
+    if (typeof input?.index !== 'number' || !Number.isInteger(input.index) || input.index < 0) {
+        return err('invalid-input', '`index` is required and must be a non-negative integer.');
+    }
+    const { index } = input;
+    return callWithClient(input, (client) => client.postJson('/api/rollback', { index }));
+}
+export async function addBreakpoint(input) {
+    if (!input?.file || typeof input.file !== 'string') {
+        return err('invalid-input', '`file` is required and must be a non-empty string.');
+    }
+    if (typeof input?.line !== 'number' || !Number.isInteger(input.line) || input.line < 0) {
+        return err('invalid-input', '`line` is required and must be a non-negative integer.');
+    }
+    const sourceLocation = { filePath: input.file, line: input.line };
+    return callWithClient(input, (client) => client.postJson('/api/add-breakpoint', { sourceLocation }));
+}
+export async function clearBreakpoints(input) {
+    return callWithClient(input, (client) => client.postJson('/api/clear-breakpoints', {}));
+}
+export async function importStep(input) {
+    if (!input?.path || typeof input.path !== 'string') {
+        return err('invalid-input', '`path` is required and must be a non-empty string.');
+    }
+    const absPath = path.resolve(input.path);
+    let bytes;
+    try {
+        bytes = await fsp.readFile(absPath);
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT') {
+            return err('invalid-input', `File not found: ${input.path}`);
+        }
+        return err('internal', e?.message ?? String(e));
+    }
+    const fileName = path.basename(absPath);
+    const data = bytes.toString('base64');
+    return callWithClient(input, (client) => client.postJson('/api/import-file', { fileName, data }));
+}
+export async function exportShapes(input) {
+    if (input?.format !== 'step' && input?.format !== 'stl') {
+        return err('invalid-input', '`format` is required and must be "step" or "stl".');
+    }
+    if (!Array.isArray(input?.shapeIds) || input.shapeIds.length === 0) {
+        return err('invalid-input', '`shapeIds` is required and must be a non-empty array.');
+    }
+    if (input.shapeIds.some((id) => typeof id !== 'string' || id.length === 0)) {
+        return err('invalid-input', '`shapeIds` entries must be non-empty strings.');
+    }
+    if (input.resolution !== undefined &&
+        input.resolution !== 'coarse' &&
+        input.resolution !== 'medium' &&
+        input.resolution !== 'fine') {
+        return err('invalid-input', '`resolution` must be "coarse", "medium", or "fine".');
+    }
+    if (input.saveAsPath !== undefined && typeof input.saveAsPath !== 'string') {
+        return err('invalid-input', '`saveAsPath` must be a string when provided.');
+    }
+    const body = {
+        format: input.format,
+        shapeIds: input.shapeIds,
+        resolution: input.resolution ?? 'medium',
+    };
+    if (input.includeColors !== undefined) {
+        body.includeColors = input.includeColors;
+    }
+    if (input.saveAsPath !== undefined) {
+        body.saveAsPath = input.saveAsPath;
+    }
+    const resolved = resolveClient(input);
+    if (resolved.ok === false) {
+        return resolved;
+    }
+    const { client } = resolved.data;
+    try {
+        const raw = await client.postRaw('/api/export', body);
+        if (raw.statusCode >= 400) {
+            const text = raw.data.toString('utf8');
+            return err('http-error', `HTTP ${raw.statusCode}: ${text.slice(0, 200)}`, {
+                statusCode: raw.statusCode,
+            });
+        }
+        if (raw.contentType.includes('application/json')) {
+            const parsed = JSON.parse(raw.data.toString('utf8'));
+            // Mirror the server's `savedTo` so the agent always returns absolute
+            // paths to the user; double-check the file exists for friendlier errors.
+            if (parsed?.savedTo && !fs.existsSync(parsed.savedTo)) {
+                return err('internal', `Server reported savedTo=${parsed.savedTo} but the file is missing.`);
+            }
+            return ok(parsed);
+        }
+        return ok({
+            format: input.format,
+            mimeType: raw.contentType,
+            base64: raw.data.toString('base64'),
+            bytes: raw.data.length,
+        });
+    }
+    catch (e) {
+        if (e instanceof HttpError) {
+            return err('http-error', `HTTP ${e.statusCode}: ${e.body.slice(0, 200)}`, {
+                statusCode: e.statusCode,
+            });
+        }
+        return err('internal', e?.message ?? String(e));
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}

package/mcp/dist/tools/inspection.d.ts

@@ -0,0 +1,75 @@
+import { FluidCadClient } from '../client.ts';
+import { type ToolResult } from '../types.ts';
+import type { RegistryEntry } from '../types.ts';
+export type WorkspaceArg = {
+    workspace?: string;
+};
+export type ResolvedClient = {
+    client: FluidCadClient;
+    entry: RegistryEntry;
+};
+/**
+ * Resolve a workspace argument to a `FluidCadClient`. Returns an error
+ * variant when the argument is ambiguous or cannot be matched. Callers own
+ * `client.close()` (typically inside a finally).
+ */
+export declare function resolveClient(input: WorkspaceArg): ToolResult<ResolvedClient>;
+export type GetSceneSummaryInput = WorkspaceArg;
+export declare function getSceneSummary(input: GetSceneSummaryInput): Promise<ToolResult<unknown>>;
+export type ListShapesInput = WorkspaceArg;
+export declare function listShapes(input: ListShapesInput): Promise<ToolResult<unknown>>;
+export type GetCompileErrorInput = WorkspaceArg;
+export declare function getCompileError(input: GetCompileErrorInput): Promise<ToolResult<unknown>>;
+export type GetShapePropertiesInput = WorkspaceArg & {
+    shapeId: string;
+};
+export declare function getShapeProperties(input: GetShapePropertiesInput): Promise<{
+    ok: false;
+    code: import("../types.ts").ToolErrorCode;
+    message: string;
+    details?: unknown;
+} | {
+    ok: true;
+    data: unknown;
+}>;
+export type GetFacePropertiesInput = WorkspaceArg & {
+    shapeId: string;
+    faceIndex: number;
+};
+export declare function getFaceProperties(input: GetFacePropertiesInput): Promise<{
+    ok: false;
+    code: import("../types.ts").ToolErrorCode;
+    message: string;
+    details?: unknown;
+} | {
+    ok: true;
+    data: unknown;
+}>;
+export type GetEdgePropertiesInput = WorkspaceArg & {
+    shapeId: string;
+    edgeIndex: number;
+};
+export declare function getEdgeProperties(input: GetEdgePropertiesInput): Promise<{
+    ok: false;
+    code: import("../types.ts").ToolErrorCode;
+    message: string;
+    details?: unknown;
+} | {
+    ok: true;
+    data: unknown;
+}>;
+export type HitTestInput = WorkspaceArg & {
+    shapeId: string;
+    rayOrigin: [number, number, number];
+    rayDir: [number, number, number];
+    edgeThreshold?: number;
+};
+export declare function hitTest(input: HitTestInput): Promise<{
+    ok: false;
+    code: import("../types.ts").ToolErrorCode;
+    message: string;
+    details?: unknown;
+} | {
+    ok: true;
+    data: unknown;
+}>;

package/mcp/dist/tools/inspection.js

@@ -0,0 +1,121 @@
+// Inspection tools — read-only views of a running FluidCAD workspace.
+//
+// Each tool maps to a single HTTP call against the FluidCAD server. The
+// workspace resolution rule is consistent across all of them: an explicit
+// `workspace` wins; with one running instance the singleton is used; with
+// multiple, the agent must disambiguate.
+import { findByWorkspace, listLiveInstances } from "../discovery.js";
+import { FluidCadClient, HttpError } from "../client.js";
+import { err, ok } from "../types.js";
+/**
+ * Resolve a workspace argument to a `FluidCadClient`. Returns an error
+ * variant when the argument is ambiguous or cannot be matched. Callers own
+ * `client.close()` (typically inside a finally).
+ */
+export function resolveClient(input) {
+    if (input?.workspace) {
+        const entry = findByWorkspace(input.workspace);
+        if (!entry) {
+            return err('workspace-not-found', `No running FluidCAD workspace at "${input.workspace}". Call list_workspaces to see what's available.`);
+        }
+        return ok({ client: new FluidCadClient(entry), entry });
+    }
+    const instances = listLiveInstances();
+    if (instances.length === 0) {
+        return err('no-server', 'No running FluidCAD workspaces. Start one with `fluidcad serve`.');
+    }
+    if (instances.length > 1) {
+        return err('no-workspace', `Multiple FluidCAD workspaces are running (${instances.length}). Pass \`workspace\` to disambiguate.`, { workspaces: instances.map((e) => e.workspacePath) });
+    }
+    return ok({ client: new FluidCadClient(instances[0]), entry: instances[0] });
+}
+async function callWithClient(input, fn) {
+    const resolved = resolveClient(input);
+    if (resolved.ok === false) {
+        return resolved;
+    }
+    const { client } = resolved.data;
+    try {
+        const data = await fn(client);
+        return ok(data);
+    }
+    catch (e) {
+        if (e instanceof HttpError) {
+            return err('http-error', `HTTP ${e.statusCode}: ${e.body.slice(0, 200)}`, {
+                statusCode: e.statusCode,
+            });
+        }
+        return err('internal', e?.message ?? String(e));
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}
+export async function getSceneSummary(input) {
+    return callWithClient(input, (client) => client.getJson('/api/scene/summary'));
+}
+export async function listShapes(input) {
+    return callWithClient(input, (client) => client.getJson('/api/scene/shapes'));
+}
+export async function getCompileError(input) {
+    return callWithClient(input, (client) => client.getJson('/api/scene/compile-error'));
+}
+export async function getShapeProperties(input) {
+    if (!input?.shapeId || typeof input.shapeId !== 'string') {
+        return err('invalid-input', '`shapeId` is required and must be a non-empty string.');
+    }
+    const shapeId = input.shapeId;
+    return callWithClient(input, (client) => client.getJson(`/api/shape-properties?shapeId=${encodeURIComponent(shapeId)}`));
+}
+export async function getFaceProperties(input) {
+    if (!input?.shapeId || typeof input.shapeId !== 'string') {
+        return err('invalid-input', '`shapeId` is required and must be a non-empty string.');
+    }
+    if (typeof input.faceIndex !== 'number' ||
+        !Number.isInteger(input.faceIndex) ||
+        input.faceIndex < 0) {
+        return err('invalid-input', '`faceIndex` is required and must be a non-negative integer.');
+    }
+    const { shapeId, faceIndex } = input;
+    return callWithClient(input, (client) => client.getJson(`/api/face-properties?shapeId=${encodeURIComponent(shapeId)}&faceIndex=${faceIndex}`));
+}
+export async function getEdgeProperties(input) {
+    if (!input?.shapeId || typeof input.shapeId !== 'string') {
+        return err('invalid-input', '`shapeId` is required and must be a non-empty string.');
+    }
+    if (typeof input.edgeIndex !== 'number' ||
+        !Number.isInteger(input.edgeIndex) ||
+        input.edgeIndex < 0) {
+        return err('invalid-input', '`edgeIndex` is required and must be a non-negative integer.');
+    }
+    const { shapeId, edgeIndex } = input;
+    return callWithClient(input, (client) => client.getJson(`/api/edge-properties?shapeId=${encodeURIComponent(shapeId)}&edgeIndex=${edgeIndex}`));
+}
+export async function hitTest(input) {
+    if (!input?.shapeId || typeof input.shapeId !== 'string') {
+        return err('invalid-input', '`shapeId` is required and must be a non-empty string.');
+    }
+    if (!isVec3(input?.rayOrigin)) {
+        return err('invalid-input', '`rayOrigin` must be a 3-element array of finite numbers.');
+    }
+    if (!isVec3(input?.rayDir)) {
+        return err('invalid-input', '`rayDir` must be a 3-element array of finite numbers.');
+    }
+    const edgeThreshold = input.edgeThreshold;
+    if (edgeThreshold !== undefined &&
+        (typeof edgeThreshold !== 'number' || !Number.isFinite(edgeThreshold) || edgeThreshold < 0)) {
+        return err('invalid-input', '`edgeThreshold` must be a non-negative finite number when provided.');
+    }
+    const body = {
+        shapeId: input.shapeId,
+        rayOrigin: input.rayOrigin,
+        rayDir: input.rayDir,
+        edgeThreshold: edgeThreshold ?? 0,
+    };
+    return callWithClient(input, (client) => client.postJson('/api/hit-test', body));
+}
+function isVec3(value) {
+    return (Array.isArray(value) &&
+        value.length === 3 &&
+        value.every((n) => typeof n === 'number' && Number.isFinite(n)));
+}

package/mcp/dist/tools/screenshot.d.ts

@@ -0,0 +1,63 @@
+import { type WorkspaceArg } from './inspection.ts';
+import { type ToolResult } from '../types.ts';
+declare const NAMED_VIEWS: readonly ["front", "back", "left", "right", "top", "bottom", "iso-ftr", "iso-fbr", "iso-ftl", "iso-fbl", "iso-btr", "iso-bbr", "iso-btl", "iso-bbl"];
+export type NamedView = (typeof NAMED_VIEWS)[number];
+export type ScreenshotView = {
+    kind: 'current';
+} | {
+    kind: 'named';
+    name: NamedView;
+} | {
+    kind: 'orbit-from-current';
+    azimuthDeg: number;
+    elevationDeg: number;
+} | {
+    kind: 'look-from';
+    eye: [number, number, number];
+    target?: [number, number, number];
+};
+export type ImageResult = {
+    image: {
+        mimeType: string;
+        base64: string;
+    };
+};
+export type ScreenshotInput = WorkspaceArg & {
+    view?: ScreenshotView;
+    width?: number;
+    height?: number;
+    showGrid?: boolean;
+    showAxes?: boolean;
+    transparent?: boolean;
+    autoCrop?: boolean;
+    fitToModel?: boolean;
+    margin?: number;
+};
+export declare function screenshot(input: ScreenshotInput): Promise<ToolResult<ImageResult>>;
+export type ScreenshotMultiInput = WorkspaceArg & {
+    width?: number;
+    height?: number;
+    showGrid?: boolean;
+    showAxes?: boolean;
+    transparent?: boolean;
+    margin?: number;
+};
+export declare function screenshotMulti(input: ScreenshotMultiInput): Promise<ToolResult<ImageResult>>;
+export type ScreenshotShapeInput = WorkspaceArg & {
+    shapeId: string;
+    margin?: number;
+    width?: number;
+    height?: number;
+    showGrid?: boolean;
+    showAxes?: boolean;
+    transparent?: boolean;
+};
+export declare function screenshotShape(input: ScreenshotShapeInput): Promise<ToolResult<ImageResult>>;
+export type CameraState = {
+    position: [number, number, number];
+    target: [number, number, number];
+    up: [number, number, number];
+    projection: 'orthographic' | 'perspective';
+};
+export declare function getCameraState(input: WorkspaceArg): Promise<ToolResult<CameraState>>;
+export {};