clear_formatting

Instructions

Implementation Reference

• packages/docx-mcp/src/tools/clear_formatting.ts:1-106 (handler)

  The main handler function 'clearFormatting' that clears run-level formatting (bold, italic, underline, highlight, color, font) from paragraphs. It resolves the session, iterates over target paragraphs, removes the specified formatting elements from run properties (rPr), and marks the session as edited.

  import { SessionManager } from '../session/manager.js';
  import { ok, err, type ToolResponse } from './types.js';
  import { resolveSessionForTool, mergeSessionResolutionMetadata } from './session_resolution.js';
  import { OOXML, W } from '@usejunior/docx-core';
  
  export async function clearFormatting(
    manager: SessionManager,
    params: {
      file_path?: string;
      paragraph_ids?: string[];
      clear_highlight?: boolean;
      clear_bold?: boolean;
      clear_italic?: boolean;
      clear_underline?: boolean;
      clear_color?: boolean;
      clear_font?: boolean;
    },
  ): Promise<ToolResponse> {
    try {
      const resolved = await resolveSessionForTool(manager, params, { toolName: 'clear_formatting' });
      if (!resolved.ok) return resolved.response;
      const { session, metadata } = resolved;
  
      const { nodes } = session.doc.buildDocumentView({ includeSemanticTags: false });
      const pids = params.paragraph_ids ?? nodes.map((n) => n.id);
      let modifiedCount = 0;
  
      for (const pid of pids) {
        const pEl = session.doc.getParagraphElementById(pid);
        if (!pEl) continue;
  
        const rElems = Array.from(pEl.getElementsByTagNameNS(OOXML.W_NS, W.r));
        let pModified = false;
  
        for (const r of rElems) {
          const rPr = r.getElementsByTagNameNS(OOXML.W_NS, W.rPr).item(0);
          if (!rPr) continue;
  
          if (params.clear_highlight) {
            const highlights = Array.from(rPr.getElementsByTagNameNS(OOXML.W_NS, W.highlight));
            if (highlights.length > 0) {
              for (const h of highlights) h.parentNode?.removeChild(h);
              pModified = true;
            }
          }
  
          if (params.clear_bold) {
            const bolds = Array.from(rPr.getElementsByTagNameNS(OOXML.W_NS, W.b));
            if (bolds.length > 0) {
              for (const b of bolds) b.parentNode?.removeChild(b);
              pModified = true;
            }
          }
  
          if (params.clear_italic) {
            const italics = Array.from(rPr.getElementsByTagNameNS(OOXML.W_NS, W.i));
            if (italics.length > 0) {
              for (const i of italics) i.parentNode?.removeChild(i);
              pModified = true;
            }
          }
  
          if (params.clear_underline) {
            const underlines = Array.from(rPr.getElementsByTagNameNS(OOXML.W_NS, W.u));
            if (underlines.length > 0) {
              for (const u of underlines) u.parentNode?.removeChild(u);
              pModified = true;
            }
          }
  
          if (params.clear_color) {
            const colors = Array.from(rPr.getElementsByTagNameNS(OOXML.W_NS, W.color));
            if (colors.length > 0) {
              for (const c of colors) c.parentNode?.removeChild(c);
              pModified = true;
            }
          }
  
          if (params.clear_font) {
            const fonts = Array.from(rPr.getElementsByTagNameNS(OOXML.W_NS, W.rFonts));
            const sizes = Array.from(rPr.getElementsByTagNameNS(OOXML.W_NS, W.sz));
            const csSizes = Array.from(rPr.getElementsByTagNameNS(OOXML.W_NS, W.szCs));
            if (fonts.length > 0 || sizes.length > 0 || csSizes.length > 0) {
              for (const f of fonts) f.parentNode?.removeChild(f);
              for (const s of sizes) s.parentNode?.removeChild(s);
              for (const s of csSizes) s.parentNode?.removeChild(s);
              pModified = true;
            }
          }
        }
        if (pModified) modifiedCount++;
      }
  
      if (modifiedCount > 0) {
        manager.markEdited(session);
      }
  
      return ok(mergeSessionResolutionMetadata({
        success: true,
        file_path: manager.normalizePath(session.originalPath),
        paragraphs_modified: modifiedCount,
      }, metadata));
    } catch (e: any) {
      return err('CLEAR_FORMATTING_ERROR', `Failed to clear formatting: ${e.message}`);
    }
  }

• packages/docx-mcp/src/tool_catalog.ts:328-343 (schema)

  The tool registration definition in the catalog. Defines the 'clear_formatting' tool name, description, input schema (file_path, paragraph_ids, clear_highlight, clear_bold, clear_italic, clear_underline, clear_color, clear_font), and annotations (destructiveHint: true).

  {
    name: 'clear_formatting',
    description:
      'Clear specific run-level formatting (bold, italic, underline, highlight, color, font) from paragraphs.',
    input: z.object({
      ...FILE_FIELD,
      paragraph_ids: z.array(z.string()).optional().describe('Paragraph IDs to clear formatting from. If omitted, clears from all paragraphs.'),
      clear_highlight: z.boolean().optional().describe('Remove highlight formatting.'),
      clear_bold: z.boolean().optional().describe('Remove bold formatting.'),
      clear_italic: z.boolean().optional().describe('Remove italic formatting.'),
      clear_underline: z.boolean().optional().describe('Remove underline formatting.'),
      clear_color: z.boolean().optional().describe('Remove font color.'),
      clear_font: z.boolean().optional().describe('Remove font family and size.'),
    }),
    annotations: { readOnlyHint: false, destructiveHint: true },
  },

• packages/docx-mcp/src/server.ts:141-142 (registration)

  The case handler in the server's tool dispatch that routes 'clear_formatting' requests to the clearFormatting function.

  case 'clear_formatting':
    return await clearFormatting(sessions, args as Parameters<typeof clearFormatting>[1]);

• packages/docx-mcp/src/server.ts:29-29 (registration)

  Import of clearFormatting from the tools module in the server entry point.

  import { clearFormatting } from './tools/clear_formatting.js';

• packages/docx-mcp/src/tools/types.ts:1-11 (helper)

  The ToolResponse type and helper functions (ok/err) used by clearFormatting for returning results.

  export type ToolResponse =
    | { success: true; [key: string]: unknown }
    | { success: false; error: { code: string; message: string; hint?: string }; [key: string]: unknown };
  
  export function ok(extra: Record<string, unknown> = {}): ToolResponse {
    return { success: true, ...extra };
  }
  
  export function err(code: string, message: string, hint?: string): ToolResponse {
    return { success: false, error: { code, message, hint } };
  }