MCP Documentation Service

Instructions

Implementation Reference

• src/handlers/documents.ts:494-606 (handler)

  The DocumentHandler.renameDocument method implements the core logic for the rename_document tool. It validates paths, preserves file extension, updates frontmatter title, optionally updates references in other documents, and handles errors.

  async renameDocument(
    docPath: string,
    newName: string,
    updateReferences = true
  ): Promise<ToolResponse> {
    try {
      const validPath = await this.validatePath(docPath);
  
      // Get directory and extension
      const dir = path.dirname(validPath);
      const ext = path.extname(validPath);
  
      // Create new path
      const newPath = path.join(dir, newName + ext);
      const validNewPath = await this.validatePath(newPath);
  
      // Check if source exists
      try {
        await fs.access(validPath);
      } catch {
        throw new Error(`Source file does not exist: ${docPath}`);
      }
  
      // Check if destination already exists
      try {
        await fs.access(validNewPath);
        throw new Error(`Destination file already exists: ${newPath}`);
      } catch (error) {
        // If error is "file doesn't exist", that's good
        if (
          !(
            error instanceof Error &&
            error.message.includes("Destination file already exists")
          )
        ) {
          // Continue with rename
        } else {
          throw error;
        }
      }
  
      // Read the source file
      const content = await fs.readFile(validPath, "utf-8");
  
      // Parse frontmatter
      const { frontmatter, content: docContent } = parseFrontmatter(content);
  
      // Update title in frontmatter if it exists
      if (frontmatter.title) {
        frontmatter.title = newName;
      }
  
      // Reconstruct content with updated frontmatter
      let frontmatterStr = "---\n";
      for (const [key, value] of Object.entries(frontmatter)) {
        if (Array.isArray(value)) {
          frontmatterStr += `${key}:\n`;
          for (const item of value) {
            frontmatterStr += `  - ${item}\n`;
          }
        } else {
          frontmatterStr += `${key}: ${value}\n`;
        }
      }
      frontmatterStr += "---\n\n";
  
      const updatedContent = frontmatterStr + docContent;
  
      // Write to new path
      await fs.writeFile(validNewPath, updatedContent, "utf-8");
  
      // Delete the source file
      await fs.unlink(validPath);
  
      // Update references if requested
      let referencesUpdated = 0;
      if (updateReferences) {
        const relativeSrcPath = path.relative(this.docsDir, validPath);
        const relativeDestPath = path.relative(this.docsDir, validNewPath);
        referencesUpdated = await this.updateReferences(
          relativeSrcPath,
          relativeDestPath
        );
      }
  
      return {
        content: [
          {
            type: "text",
            text:
              `Successfully renamed document from ${docPath} to ${newName}${ext}` +
              (referencesUpdated > 0
                ? `. Updated ${referencesUpdated} references.`
                : ""),
          },
        ],
        metadata: {
          originalPath: docPath,
          newPath: path.relative(this.docsDir, validNewPath),
          referencesUpdated,
        },
      };
    } catch (error) {
      const errorMessage =
        error instanceof Error ? error.message : String(error);
      return {
        content: [
          { type: "text", text: `Error renaming document: ${errorMessage}` },
        ],
        isError: true,
      };
    }
  }

• src/schemas/tools.ts:75-79 (schema)

  Zod schema defining the input parameters for the rename_document tool: path (current document path), newName (new filename without extension), updateReferences (whether to update links in other files).

  export const RenameDocumentSchema = ToolInputSchema.extend({
    path: z.string(),
    newName: z.string(),
    updateReferences: z.boolean().default(true),
  });

• src/index.ts:265-271 (registration)

  Tool registration in the listTools handler, defining the tool name, description, and input schema.

  {
    name: "rename_document",
    description:
      "Rename a document while preserving its location and content. Optionally updates " +
      "references to the document in other files.",
    inputSchema: zodToJsonSchema(RenameDocumentSchema) as any,
  },

• src/index.ts:428-440 (registration)

  Dispatch handler in the CallToolRequestSchema that parses input using RenameDocumentSchema and calls documentHandler.renameDocument. Note: case label is 'rename_documentation_document' while tool name is 'rename_document'.

  case "rename_documentation_document": {
    const parsed = RenameDocumentSchema.safeParse(args);
    if (!parsed.success) {
      throw new Error(
        `Invalid arguments for rename_document: ${parsed.error}`
      );
    }
    return await documentHandler.renameDocument(
      parsed.data.path,
      parsed.data.newName,
      parsed.data.updateReferences
    );
  }