lock_elements

Instructions

Implementation Reference

• src/mcp/index.ts:425-442 (handler)

  Main registration and handler for lock_elements tool. Validates input with IdsZ schema, iterates through elementIds, and calls client.updateElement(eid, { locked: true }) for each element. Returns JSON response with lockedCount.

  // --- Tool: lock_elements ---
  server.tool(
    'lock_elements',
    'Lock elements to prevent modification',
    { elementIds: IdsZ },
    async ({ elementIds }) => {
      try {
        let count = 0;
        for (const eid of elementIds) {
          await client.updateElement(eid, { locked: true });
          count++;
        }
        return { content: [{ type: 'text', text: JSON.stringify({ lockedCount: count }, null, 2) }] };
      } catch (err) {
        return { content: [{ type: 'text', text: `Error: ${(err as Error).message}` }], isError: true };
      }
    }
  );

• src/mcp/schemas/element.ts:108-115 (schema)

  Input validation schema ElementIdsSchema for lock_elements tool. Requires elementIds as an array of strings (max length LIMITS.MAX_ID_LENGTH), with minimum 1 and maximum LIMITS.MAX_ELEMENT_IDS elements.

  export const ElementIdsSchema = z
    .object({
      elementIds: z
        .array(z.string().max(LIMITS.MAX_ID_LENGTH))
        .min(1)
        .max(LIMITS.MAX_ELEMENT_IDS),
    })
    .strict();

• src/mcp/canvas-client.ts:67-87 (helper)

  CanvasClient.updateElement method that performs the actual API call to update an element with { locked: true }. Makes PUT request to /api/elements/{id} endpoint with API key authentication.

  async updateElement(
    id: string,
    data: Record<string, unknown>
  ): Promise<ServerElement> {
    const res = await fetch(
      `${this.baseUrl}/api/elements/${this.safePath(id)}`,
      {
        method: 'PUT',
        headers: this.headers(),
        body: JSON.stringify(data),
      }
    );
  
    if (!res.ok) {
      const body = await res.json().catch(() => ({})) as ApiResponse;
      throw new Error(body.error ?? `Canvas error: ${res.status}`);
    }
  
    const body = await res.json() as { element?: ServerElement };
    return body.element!;
  }

• src/mcp/apps/canvas-client-adapter.ts:59-78 (helper)

  CanvasClientAdapter.updateElement method for standalone mode. Updates element in the in-memory StandaloneStore by merging data with existing element, preserving id/createdAt, and updating timestamp/version.

  async updateElement(
    id: string,
    data: Record<string, unknown>
  ): Promise<ServerElement> {
    const existing = await this.store.get(id);
    if (!existing) throw new Error(`Element ${id} not found`);
  
    const updated: ServerElement = {
      ...existing,
      ...stripUndefined(data),
      id: existing.id,
      createdAt: existing.createdAt,
      updatedAt: new Date().toISOString(),
      version: existing.version + 1,
    };
  
    await this.store.set(id, updated);
    logger.debug({ id }, 'Element updated');
    return updated;
  }

• src/mcp/tools/lock-elements.ts:1-18 (handler)

  Alternative handler implementation lockElementsTool exported from tools directory but not used in main index.ts. Uses ElementIdsSchema for validation and calls client.updateElement(id, { locked: true }) in a loop, returning { success, lockedCount }.

  import type { CanvasClient } from '../canvas-client.js';
  import { ElementIdsSchema } from '../schemas/element.js';
  
  export async function lockElementsTool(
    args: unknown,
    client: CanvasClient
  ) {
    const { elementIds } = ElementIdsSchema.parse(args);
    let lockedCount = 0;
  
    for (const id of elementIds) {
      await client.updateElement(id, { locked: true });
      lockedCount++;
    }
  
    return { success: true, lockedCount };
  }