MCP Documentation Service

Instructions

Implementation Reference

• src/handlers/documents.ts:424-489 (handler)

  The primary handler method in DocumentHandler class that executes the move_document tool. Validates paths, copies file content, deletes source, optionally updates references in other docs, and returns ToolResponse.

  async moveDocument(
    sourcePath: string,
    destinationPath: string,
    updateReferences = true
  ): Promise<ToolResponse> {
    try {
      const validSourcePath = await this.validatePath(sourcePath);
      const validDestPath = await this.validatePath(destinationPath);
  
      // Check if source exists
      try {
        await fs.access(validSourcePath);
      } catch {
        throw new Error(`Source file does not exist: ${sourcePath}`);
      }
  
      // Create destination directory if it doesn't exist
      const destDir = path.dirname(validDestPath);
      await fs.mkdir(destDir, { recursive: true });
  
      // Read the source file
      const content = await fs.readFile(validSourcePath, "utf-8");
  
      // Write to destination
      await fs.writeFile(validDestPath, content, "utf-8");
  
      // Delete the source file
      await fs.unlink(validSourcePath);
  
      // Update references if requested
      let referencesUpdated = 0;
      if (updateReferences) {
        referencesUpdated = await this.updateReferences(
          sourcePath,
          destinationPath
        );
      }
  
      return {
        content: [
          {
            type: "text",
            text:
              `Successfully moved document from ${sourcePath} to ${destinationPath}` +
              (referencesUpdated > 0
                ? `. Updated ${referencesUpdated} references.`
                : ""),
          },
        ],
        metadata: {
          sourcePath,
          destinationPath,
          referencesUpdated,
        },
      };
    } catch (error) {
      const errorMessage =
        error instanceof Error ? error.message : String(error);
      return {
        content: [
          { type: "text", text: `Error moving document: ${errorMessage}` },
        ],
        isError: true,
      };
    }
  }

• src/schemas/tools.ts:69-73 (schema)

  Zod schema defining input for move_document tool: sourcePath, destinationPath, and optional updateReferences.

  export const MoveDocumentSchema = ToolInputSchema.extend({
    sourcePath: z.string(),
    destinationPath: z.string(),
    updateReferences: z.boolean().default(true),
  });

• src/index.ts:259-263 (registration)

  Tool registration in listTools handler: defines name 'move_document', description, and converts MoveDocumentSchema to JSON schema.

  name: "move_document",
  description:
    "Move a document from one location to another. Optionally updates references to the " +
    "document in other files.",
  inputSchema: zodToJsonSchema(MoveDocumentSchema) as any,

• src/index.ts:414-426 (registration)

  Tool call handler in CallToolRequestSchema switch: parses args with MoveDocumentSchema and calls documentHandler.moveDocument (note: case label is 'move_documentation_document' but error mentions 'move_document').

  case "move_documentation_document": {
    const parsed = MoveDocumentSchema.safeParse(args);
    if (!parsed.success) {
      throw new Error(
        `Invalid arguments for move_document: ${parsed.error}`
      );
    }
    return await documentHandler.moveDocument(
      parsed.data.sourcePath,
      parsed.data.destinationPath,
      parsed.data.updateReferences
    );
  }

• src/handlers/documents.ts:743-790 (helper)

  Private helper method called by moveDocument (and rename) to scan all .md files and update markdown links and direct path references from oldPath to newPath.

  private async updateReferences(
    oldPath: string,
    newPath: string
  ): Promise<number> {
    // Normalize paths for comparison
    const normalizedOldPath = oldPath.replace(/\\/g, "/");
    const normalizedNewPath = newPath.replace(/\\/g, "/");
  
    // Find all markdown files
    const files = await glob("**/*.md", { cwd: this.docsDir });
    let updatedCount = 0;
  
    for (const file of files) {
      const filePath = path.join(this.docsDir, file);
      const content = await fs.readFile(filePath, "utf-8");
  
      // Look for references to the old path
      // Match markdown links: [text](path)
      const linkRegex = new RegExp(
        `\\[([^\\]]+)\\]\\(${normalizedOldPath.replace(
          /[.*+?^${}()|[\]\\]/g,
          "\\$&"
        )}\\)`,
        "g"
      );
  
      // Match direct path references
      const pathRegex = new RegExp(
        normalizedOldPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
        "g"
      );
  
      // Replace references
      let updatedContent = content.replace(
        linkRegex,
        `[$1](${normalizedNewPath})`
      );
      updatedContent = updatedContent.replace(pathRegex, normalizedNewPath);
  
      // If content changed, write the updated file
      if (updatedContent !== content) {
        await fs.writeFile(filePath, updatedContent, "utf-8");
        updatedCount++;
      }
    }
  
    return updatedCount;
  }