MCP Tools Reference

The Renamify MCP Server provides 10 specialized tools for AI agents to perform intelligent renaming operations.

renamify_search

Search for identifiers across your codebase to understand their usage before renaming.

Parameters

Parameter	Type	Required	Default	Description
`search`	string	✅ Yes	-	The identifier to search for
`paths`	string[]	No	Current dir	Paths to search (files or directories)
`includes`	string[]	No	All files	Glob patterns to include
`excludes`	string[]	No	None	Glob patterns to exclude
`styles`	string[]	No	All styles	Case styles to detect
`preview`	string	No	`summary`	Output format
`dryRun`	boolean	No	`false`	Preview without saving
`renameFiles`	boolean	No	`true`	Include file renames in search
`renameDirs`	boolean	No	`true`	Include directory renames in search
`atomicSearch`	boolean	No	`false`	Treat search term as indivisible unit

Example

Tool: renamify_search
Arguments: {
  "search": "UserAccount",
  "includes": ["src/**/*.ts", "src/**/*.tsx"],
  "preview": "summary"
}

Result:
Found 45 occurrences across 12 files:
  UserAccount (15)
  userAccount (18)
  user_account (8)
  USER_ACCOUNT (4)
Files that would be renamed: 2
Directories that would be renamed: 0

Use this tool to explore the codebase before creating a renaming plan.

renamify_plan

Creates a comprehensive renaming plan that identifies all case variations of your identifiers.

Parameters

Parameter	Type	Required	Default	Description
`old`	string	✅ Yes	-	The identifier to replace
`new`	string	✅ Yes	-	The new identifier
`paths`	string[]	No	Current dir	Paths to search (files or directories)
`includes`	string[]	No	All files	Glob patterns to include
`excludes`	string[]	No	None	Glob patterns to exclude
`styles`	string[]	No	All styles	Case styles to detect
`preview`	string	No	`summary`	Output format
`dryRun`	boolean	No	`false`	Preview without saving
`renameFiles`	boolean	No	`true`	Rename matching files
`renameDirs`	boolean	No	`true`	Rename matching directories
`atomicSearch`	boolean	No	`false`	Treat search term as indivisible unit
`atomicReplace`	boolean	No	`false`	Treat replace term as indivisible unit

Case Styles

Available case style options:

snake - snake_case
camel - camelCase
pascal - PascalCase
kebab - kebab-case
screaming-snake - SCREAMING_SNAKE_CASE
title - Title Case
train - Train-Case
screaming-train - SCREAMING-TRAIN-CASE
dot - dot.case
lower-flat - lowerjoined (no separators)
upper-flat - UPPERJOINED (no separators)
sentence - Sentence case
lower-sentence - lower sentence
upper-sentence - UPPER SENTENCE
space-separated - Shorthand for all space-separated styles

Preview Formats

summary - AI-optimized concise format
table - Human-readable table
diff - Unified diff format
json - Full structured data

Example Usage

Tool: renamify_plan
Arguments: {
  "old": "UserAccount",
  "new": "CustomerAccount",
  "includes": ["src/**/*.ts", "tests/**/*.ts"],
  "excludes": ["node_modules/**", "dist/**"],
  "styles": ["camel", "pascal", "snake"],
  "preview": "summary",
  "dryRun": false
}

Atomic Mode Example

Tool: renamify_plan
Arguments: {
  "old": "DocSpring",
  "new": "FormAPI",
  "atomicSearch": true,
  "atomicReplace": true,
  "preview": "summary"
}

With atomic identifiers, compound words like “DocSpring” are treated as single units, preventing unwanted word boundary detection (e.g., doc_spring).

Response Example

Created plan: a3b7c9d4e8f2a6b1

Summary:
  Files to modify: 12
  Total replacements: 47
  Variants found:
    UserAccount (15)
    userAccount (18)
    user_account (8)
    USER_ACCOUNT (6)
  Files to rename: 3
    src/UserAccount.ts → src/CustomerAccount.ts
    tests/userAccount.test.ts → tests/customerAccount.test.ts
    docs/user-account.md → docs/customer-account.md

renamify_apply

Applies a renaming plan to make the actual changes to your codebase.

Parameters

Parameter	Type	Required	Default	Description
`planId`	string	No	Latest	Specific plan ID to apply
`planPath`	string	No	Auto	Path to plan file
`commit`	boolean	No	`false`	Create git commit after

Example Usage

Tool: renamify_apply
Arguments: {
  "commit": true
}

Response Example

Successfully applied plan a3b7c9d4e8f2a6b1
  ✓ Modified 12 files
  ✓ Applied 47 replacements
  ✓ Renamed 3 files
  ✓ Created git commit: "renamify: rename UserAccount to CustomerAccount"

All changes applied successfully.

Error Handling

If conflicts are detected:

Error: Conflicts detected in 2 files:
  - src/api/handlers.ts: Content changed since plan creation
  - lib/database.ts: File no longer exists

Run 'renamify_plan' again to create a fresh plan with current file state.

renamify_undo

Reverts a previously applied renaming operation.

Parameters

Parameter	Type	Required	Default	Description
`id`	string	No	`latest`	History ID to undo (use “latest” for most recent non-revert entry)

Example Usage

Tool: renamify_undo
Arguments: {
  "id": "a3b7c9d4e8f2a6b1"
}

Response Example

Successfully undone renaming a3b7c9d4e8f2a6b1
  ✓ Reverted 47 replacements in 12 files
  ✓ Restored 3 renamed files

All changes have been reverted.

renamify_redo

Re-applies a previously undone renaming.

Parameters

Parameter	Type	Required	Default	Description
`id`	string	No	`latest`	History ID to redo (use “latest” for most recent reverted entry)

Example Usage

Tool: renamify_redo
Arguments: {
  "id": "a3b7c9d4e8f2a6b1"
}

Response Example

Successfully redone renaming a3b7c9d4e8f2a6b1
  ✓ Re-applied 47 replacements in 12 files
  ✓ Re-renamed 3 files

All changes have been re-applied.

renamify_history

Shows the history of renaming operations.

Parameters

Parameter	Type	Required	Default	Description
`limit`	number	No	`10`	Number of entries to show

Example Usage

Tool: renamify_history
Arguments: {
  "limit": 5
}

Response Example

Renaming History (last 5 operations):

1. 4e8f2a6b1d3c7a9b [APPLIED]
   getUserData → fetchUserData
   12 files, 38 replacements
   Applied: 1734567890

2. a3b7c9d4e8f2a6b1 [UNDONE]
   UserAccount → CustomerAccount
   12 files, 47 replacements
   Applied: 1734567800
   Undone: 1734567900

3. 6b1d3a7c9e4f8a2b [APPLIED]
   snake_case → camelCase (config migration)
   8 files, 156 replacements
   Applied: 1734567600

renamify_status

Shows the current status of Renamify, including pending plans and system state.

Parameters

This tool takes no parameters.

Example Usage

Tool: renamify_status
Arguments: {}

Response Example

Renamify Status:

Current Directory: /home/user/project
Git Branch: feature/renaming
Git Status: Clean (no uncommitted changes)

Pending Plans:
  1d3a7c9e4f8b2a6c - oldFunction → newFunction
    Created: 5 minutes ago
    Status: Not applied
    Files: 8, Replacements: 23

Last Applied:
  4e8f2a6b1d3c7a9b - getUserData → fetchUserData
    Applied: 1 hour ago
    Status: Success

System:
  Renamify Version: 1.2.0
  Config: .renamify/config.toml found
  History Entries: 47

renamify_preview

Preview a plan in different formats without applying changes.

Parameters

Parameter	Type	Required	Default	Description
`planId`	string	No	Latest	Plan ID to preview
`planPath`	string	No	Auto	Path to plan file
`format`	string	No	`summary`	Preview format

Format Options

summary - Concise AI-friendly format
table - Detailed table view
diff - Unified diff format
json - Raw JSON data

Example Usage

Tool: renamify_preview
Arguments: {
  "format": "diff"
}

Response Example (diff format)

--- a/src/components/UserAccount.tsx
+++ b/src/components/CustomerAccount.tsx
@@ -1,8 +1,8 @@
-import { UserAccount } from '../types';
+import { CustomerAccount } from '../types';

-interface UserAccountProps {
-  account: UserAccount;
+interface CustomerAccountProps {
+  account: CustomerAccount;
 }

-export function UserAccountComponent({ account }: UserAccountProps) {
+export function CustomerAccountComponent({ account }: CustomerAccountProps) {

renamify_rename

Perform case-aware renaming in a single step (combines plan + apply).

Parameters

Parameter	Type	Required	Default	Description
`old`	string	✅ Yes	-	The identifier to replace
`new`	string	✅ Yes	-	The new identifier
`paths`	string[]	No	Current dir	Paths to search
`dryRun`	boolean	No	`false`	Preview without applying
`preview`	string	No	`summary`	Preview format
`excludeStyles`	string[]	No	None	Case styles to exclude
`includeStyles`	string[]	No	None	Additional case styles
`onlyStyles`	string[]	No	None	Use only these styles
`atomicSearch`	boolean	No	`false`	Treat search term as indivisible
`atomicReplace`	boolean	No	`false`	Treat replace term as indivisible

Example Usage

Tool: renamify_rename
Arguments: {
  "old": "getUserInfo",
  "new": "fetchUserProfile",
  "paths": ["src"],
  "dryRun": true
}

When to Use

Quick renames without saving a plan
Simple refactorings with immediate apply
When you don’t need to review changes beforehand

renamify_replace

Perform simple regex or literal string replacement without case transformations.

Parameters

Parameter	Type	Required	Default	Description
`pattern`	string	✅ Yes	-	Search pattern (regex or literal)
`replacement`	string	✅ Yes	-	Replacement string
`paths`	string[]	No	Current dir	Paths to search
`noRegex`	boolean	No	`false`	Treat pattern as literal
`preview`	string	No	`summary`	Preview format
`dryRun`	boolean	No	`false`	Preview without applying

Example Usage

Regex replacement:

Tool: renamify_replace
Arguments: {
  "pattern": "console\\.log\\((.*?)\\)",
  "replacement": "logger.debug($1)",
  "paths": ["src"]
}

Literal replacement:

Tool: renamify_replace
Arguments: {
  "pattern": "http://localhost:3000",
  "replacement": "https://api.example.com",
  "noRegex": true
}

When to Use

URL or endpoint replacements
Regex-based transformations
Literal string replacements without case variations
When you explicitly DON’T want case transformations

Tool Interaction Patterns

Safe Renaming Workflow

graph LR
    A[renamify_plan] --> B[renamify_preview]
    B --> C{Review OK?}
    C -->|Yes| D[renamify_apply]
    C -->|No| E[Adjust & re-plan]
    D --> F{Success?}
    F -->|No| G[renamify_undo]
    F -->|Yes| H[Complete]

Best Practices for AI Agents

Always plan before applying
- Use renamify_plan first
- Review with renamify_preview if needed
- Only then use renamify_apply
Use specific includes when possible
- Target specific directories: ["src/**/*.ts"]
- Exclude test files if not needed: ["!**/*.test.ts"]
Check status before operations
- Use renamify_status to verify clean state
- Ensure no pending uncommitted changes
Handle errors gracefully
- Check for “conflicts detected” messages
- Use renamify_undo if something goes wrong
- Re-plan if files have changed

Error Messages and Recovery

Common Error Patterns

Error	Cause	Solution
”Renamify CLI not available”	Binary not in PATH	Check installation
”No matches found”	Pattern too restrictive	Broaden search criteria
”Conflicts detected”	Files changed since plan	Create new plan
”Plan not found”	Invalid plan ID	Check with `renamify_history`
”Permission denied”	File permissions	Check file ownership

Recovery Strategies

When apply fails:

Note the error message
Use renamify_status to check state
If partially applied, use renamify_undo
Fix the issue and create a new plan

When patterns don’t match:

Start with broader patterns
Use dryRun: true to test
Adjust styles array if needed
Check file extensions in includes

Performance Considerations

Large Codebases

For repositories with >10,000 files:

Use specific includes patterns
Exclude build/dist directories
Consider breaking into multiple operations

Memory Usage

The MCP Server loads plans into memory:

Plans typically < 1MB for most renames
Very large plans (>10MB) may need chunking
Use format: "summary" for efficiency

Next Steps

Usage Examples

See real-world renaming scenarios

AI Agent Guide

Best practices for AI-assisted renaming