extract_revisions

Instructions

Implementation Reference

• packages/docx-mcp/src/tools/extract_revisions.ts:7-63 (handler)

  MCP tool handler for 'extract_revisions'. Resolves the session, validates limit/offset parameters, delegates to extractRevisions() from @usejunior/docx-core, caches results, applies pagination, and returns structured revision data with metadata.

  export async function extractRevisions_tool(
    manager: SessionManager,
    params: {
      file_path?: string;
      offset?: number;
      limit?: number;
    },
  ): Promise<ToolResponse> {
    const resolved = await resolveSessionForTool(manager, params, { toolName: 'extract_revisions' });
    if (!resolved.ok) return resolved.response;
    const { session, metadata } = resolved;
  
    // Validate limit
    const limit = params.limit ?? 50;
    if (typeof limit !== 'number' || limit < 1 || limit > 500) {
      return err('INVALID_LIMIT', `limit must be between 1 and 500, got ${limit}`, 'Provide a limit in the range 1–500.');
    }
  
    // Validate offset
    const offset = params.offset ?? 0;
    if (typeof offset !== 'number' || offset < 0) {
      return err('INVALID_OFFSET', `offset must be >= 0, got ${offset}`, 'Provide a non-negative offset.');
    }
  
    try {
      // Check extraction cache
      const cached = manager.getExtractionCache(session);
      let allChanges;
  
      if (cached) {
        allChanges = cached.changes;
      } else {
        // Compute extraction from DOM clones
        const docClone = session.doc.getDocumentXmlClone();
        const comments = await session.doc.getComments();
        const result = extractRevisions(docClone, comments);
        allChanges = result.changes;
        // Cache the full result for pagination
        manager.setExtractionCache(session, allChanges);
      }
  
      // Apply pagination
      const totalChanges = allChanges.length;
      const page = allChanges.slice(offset, offset + limit);
      const hasMore = offset + limit < totalChanges;
  
      return ok(mergeSessionResolutionMetadata({
        changes: page,
        total_changes: totalChanges,
        has_more: hasMore,
        edit_revision: session.editRevision,
        file_path: manager.normalizePath(session.originalPath),
      }, metadata));
    } catch (e: unknown) {
      return err('EXTRACTION_ERROR', errorMessage(e));
    }
  }

• packages/docx-core/src/primitives/extract_revisions.ts:287-382 (helper)

  Core implementation of extractRevisions(). Clones the DOM, applies acceptChanges/rejectChanges to get before/after text per paragraph, collects revision entries (INSERTION, DELETION, MOVE_FROM, MOVE_TO, FORMAT_CHANGE), associates comments, and applies pagination.

  export function extractRevisions(
    doc: Document,
    comments: Comment[],
    opts?: { offset?: number; limit?: number },
  ): ExtractRevisionsResult {
    const body = doc.getElementsByTagNameNS(W_NS, 'body').item(0);
    if (!body) {
      return { changes: [], total_changes: 0, has_more: false };
    }
  
    // Clone DOM twice and apply accept/reject
    const acceptedDoc = doc.cloneNode(true) as Document;
    const rejectedDoc = doc.cloneNode(true) as Document;
    acceptChanges(acceptedDoc);
    rejectChanges(rejectedDoc);
  
    // Build comment lookup by anchoredParagraphId
    const commentsByParaId = new Map<string, Comment[]>();
    for (const c of comments) {
      if (c.anchoredParagraphId) {
        const existing = commentsByParaId.get(c.anchoredParagraphId);
        if (existing) {
          existing.push(c);
        } else {
          commentsByParaId.set(c.anchoredParagraphId, [c]);
        }
      }
    }
  
    // Walk all paragraphs in the original tracked DOM
    const allParagraphs = Array.from(body.getElementsByTagNameNS(W_NS, 'p'));
    const changedParagraphs: ParagraphRevision[] = [];
  
    for (const p of allParagraphs) {
      if (!paragraphHasRevisions(p)) continue;
  
      const paraId = getParagraphBookmarkId(p);
      if (!paraId) continue; // All paragraphs should have bookmarks from session resolution
  
      // Detect entirely-inserted/deleted paragraphs to avoid stale bookmark lookups.
      // When rejectChanges() removes an inserted paragraph, it relocates bookmarks
      // to adjacent paragraphs, which would give the wrong before_text.
      const isFullyInserted = paragraphIsEntirelyInserted(p);
      const isFullyDeleted = paragraphIsEntirelyDeleted(p);
  
      // Look up before_text in rejected clone by bookmark
      let beforeText: string;
      if (isFullyInserted) {
        beforeText = ''; // Didn't exist before
      } else {
        const rejectedP = findParagraphByBookmarkId(rejectedDoc, paraId);
        beforeText = rejectedP ? getParagraphText(rejectedP) : '';
      }
  
      // Look up after_text in accepted clone by bookmark
      let afterText: string;
      if (isFullyDeleted) {
        afterText = ''; // Doesn't exist after
      } else {
        const acceptedP = findParagraphByBookmarkId(acceptedDoc, paraId);
        afterText = acceptedP ? getParagraphText(acceptedP) : '';
      }
  
      // Collect revision entries
      const revisions = collectRevisionEntries(p);
  
      // Skip structurally-empty paragraphs with only paragraph-level markers
      // (e.g. empty inserted paragraphs from comparison engines with pPr/rPr/ins only)
      if (revisions.length === 0 && beforeText === '' && afterText === '') continue;
  
      // Associate comments
      const paraComments = commentsByParaId.get(paraId) ?? [];
      const revisionComments = paraComments.map(commentToRevisionComment);
  
      changedParagraphs.push({
        para_id: paraId,
        before_text: beforeText,
        after_text: afterText,
        revisions,
        comments: revisionComments,
      });
    }
  
    // Apply pagination
    const totalChanges = changedParagraphs.length;
    const offset = opts?.offset ?? 0;
    const limit = opts?.limit ?? totalChanges;
    const page = changedParagraphs.slice(offset, offset + limit);
    const hasMore = offset + limit < totalChanges;
  
    return {
      changes: page,
      total_changes: totalChanges,
      has_more: hasMore,
    };
  }

• packages/docx-core/src/primitives/extract_revisions.ts:26-53 (schema)

  Type definitions for the extract_revisions tool: RevisionType, RevisionEntry, RevisionComment, ParagraphRevision, and ExtractRevisionsResult.

  export type RevisionType = 'INSERTION' | 'DELETION' | 'MOVE_FROM' | 'MOVE_TO' | 'FORMAT_CHANGE';
  
  export type RevisionEntry = {
    type: RevisionType;
    text: string;
    author: string;
  };
  
  export type RevisionComment = {
    author: string;
    text: string;
    date: string | null;
    replies?: RevisionComment[];
  };
  
  export type ParagraphRevision = {
    para_id: string;
    before_text: string;
    after_text: string;
    revisions: RevisionEntry[];
    comments: RevisionComment[];
  };
  
  export type ExtractRevisionsResult = {
    changes: ParagraphRevision[];
    total_changes: number;
    has_more: boolean;
  };

• packages/docx-mcp/src/tool_catalog.ts:344-354 (registration)

  Tool catalog registration for 'extract_revisions' with description, input schema (file_path, offset, limit), and annotations (readOnlyHint: true).

  {
    name: 'extract_revisions',
    description:
      'Extract tracked changes as structured JSON with before/after text per paragraph, revision details, and comments. Supports pagination via offset and limit. Read-only - does not modify the document.',
    input: z.object({
      ...FILE_FIELD,
      offset: z.number().optional().describe('0-based offset for pagination. Default: 0.'),
      limit: z.number().optional().describe('Max entries per page (1-500). Default: 50.'),
    }),
    annotations: { readOnlyHint: true, destructiveHint: false },
  },

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

  Import statement for extractRevisions_tool from the tool module.

  import { extractRevisions_tool } from './tools/extract_revisions.js';

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

  Case branch in the MCP server dispatcher that routes 'extract_revisions' calls to extractRevisions_tool.

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