MCP Documentation Service

Instructions

Implementation Reference

• src/handlers/documents.ts:177-281 (handler)

  The core handler function in DocumentHandler class that reads a document, applies sequential text replacements (with fuzzy line matching), generates a unified diff, and optionally writes changes back. Supports dry-run mode.

  async editDocument(
    docPath: string,
    edits: Array<{ oldText: string; newText: string }>,
    dryRun = false
  ): Promise<ToolResponse> {
    try {
      const validPath = await this.validatePath(docPath);
  
      // Read file content and normalize line endings
      const content = normalizeLineEndings(
        await fs.readFile(validPath, "utf-8")
      );
  
      // Apply edits sequentially
      let modifiedContent = content;
      for (const edit of edits) {
        const normalizedOld = normalizeLineEndings(edit.oldText);
        const normalizedNew = normalizeLineEndings(edit.newText);
  
        // If exact match exists, use it
        if (modifiedContent.includes(normalizedOld)) {
          modifiedContent = modifiedContent.replace(
            normalizedOld,
            normalizedNew
          );
          continue;
        }
  
        // Otherwise, try line-by-line matching with flexibility for whitespace
        const oldLines = normalizedOld.split("\n");
        const contentLines = modifiedContent.split("\n");
        let matchFound = false;
  
        for (let i = 0; i <= contentLines.length - oldLines.length; i++) {
          const potentialMatch = contentLines.slice(i, i + oldLines.length);
  
          // Compare lines with normalized whitespace
          const isMatch = oldLines.every((oldLine, j) => {
            const contentLine = potentialMatch[j];
            return oldLine.trim() === contentLine.trim();
          });
  
          if (isMatch) {
            // Preserve original indentation of first line
            const originalIndent = contentLines[i].match(/^\s*/)?.[0] || "";
            const newLines = normalizedNew.split("\n").map((line, j) => {
              if (j === 0) return originalIndent + line.trimStart();
              // For subsequent lines, try to preserve relative indentation
              const oldIndent = oldLines[j]?.match(/^\s*/)?.[0] || "";
              const newIndent = line.match(/^\s*/)?.[0] || "";
              if (oldIndent && newIndent) {
                const relativeIndent = newIndent.length - oldIndent.length;
                return (
                  originalIndent +
                  " ".repeat(Math.max(0, relativeIndent)) +
                  line.trimStart()
                );
              }
              return line;
            });
  
            contentLines.splice(i, oldLines.length, ...newLines);
            modifiedContent = contentLines.join("\n");
            matchFound = true;
            break;
          }
        }
  
        if (!matchFound) {
          throw new Error(
            `Could not find exact match for edit:\n${edit.oldText}`
          );
        }
      }
  
      // Create unified diff
      const diff = createUnifiedDiff(content, modifiedContent, docPath);
  
      // Format diff with appropriate number of backticks
      let numBackticks = 3;
      while (diff.includes("`".repeat(numBackticks))) {
        numBackticks++;
      }
      const formattedDiff = `${"`".repeat(
        numBackticks
      )}diff\n${diff}${"`".repeat(numBackticks)}\n\n`;
  
      if (!dryRun) {
        await fs.writeFile(validPath, modifiedContent, "utf-8");
      }
  
      return {
        content: [{ type: "text", text: formattedDiff }],
      };
    } catch (error) {
      const errorMessage =
        error instanceof Error ? error.message : String(error);
      return {
        content: [
          { type: "text", text: `Error editing document: ${errorMessage}` },
        ],
        isError: true,
      };
    }
  }

• src/schemas/tools.ts:38-47 (schema)

  Zod schema defining the input for edit_document tool: path to document, array of edits (oldText/newText pairs), optional dryRun flag.

  export const EditDocumentSchema = ToolInputSchema.extend({
    path: z.string(),
    edits: z.array(
      z.object({
        oldText: z.string(),
        newText: z.string(),
      })
    ),
    dryRun: z.boolean().default(false),
  });

• src/index.ts:216-222 (registration)

  Tool registration in the MCP server's listTools response, defining name, description, and input schema.

    description:
      "Make line-based edits to a markdown document. Each edit replaces exact line sequences " +
      "with new content. Returns a git-style diff showing the changes made.",
    inputSchema: zodToJsonSchema(EditDocumentSchema) as any,
  },
  {
    name: "list_documents",

• src/index.ts:335-347 (registration)

  Dispatch logic in the main CallToolRequest handler that parses input with EditDocumentSchema and delegates to documentHandler.editDocument.

  case "edit_document": {
    const parsed = EditDocumentSchema.safeParse(args);
    if (!parsed.success) {
      throw new Error(
        `Invalid arguments for edit_document: ${parsed.error}`
      );
    }
    return await documentHandler.editDocument(
      parsed.data.path,
      parsed.data.edits,
      parsed.data.dryRun
    );
  }

• src/handlers/documents.ts:20-37 (helper)

  Helper function to generate unified diff patch used in editDocument response.

  function createUnifiedDiff(
    originalContent: string,
    newContent: string,
    filepath: string = "file"
  ): string {
    // Ensure consistent line endings for diff
    const normalizedOriginal = normalizeLineEndings(originalContent);
    const normalizedNew = normalizeLineEndings(newContent);
  
    return createTwoFilesPatch(
      filepath,
      filepath,
      normalizedOriginal,
      normalizedNew,
      "original",
      "modified"
    );
  }