Codemod MCP

Codemod MCP (Model Context Protocol) provides AI assistants with tools for code analysis, AST manipulation, and codemod creation. The MCP server enables AI tools like Claude, Cursor, and others to understand code structure, create codemods, and perform automated code transformations.

Quick setup

1. Open IDE settings

   For Cursor IDE:

   • Open Cursor Settings
   • Navigate to MCP & Integrations
   • Click New MCP Server under MCP Tools
2. Add MCP server configuration

   Add the following configuration to your MCP settings:

   {
     "mcpServers": {
       "codemod": {
         "command": "npx",
         "args": ["codemod@latest", "mcp"]
       }
     }
   }
   
3. Restart your IDE

   Save the configuration file and restart your IDE to activate the Codemod MCP server.

Available tools

The Codemod MCP server provides these tools for AI assistants:

• dump_ast - Dump AST nodes in an AI-friendly format for given source code and language
• get_node_types - Get compressed tree-sitter node types for specific programming languages
• run_jssg_tests - Run tests for jssg (TypeScript transformation scripts) codemods with test cases
• get_jssg_instructions - Get jssg instructions for creating TypeScript transformation scripts
• get_ast_grep_instructions - Get ast-grep instructions for creating ast-grep rules
• get_codemod_cli_instructions - Get Codemod CLI instructions for creating codemods

Building Codemod packages with MCP

1. Ask the AI for a specific codemod

   Describe your transformation clearly:

   "Create a jssg codemod that converts all console.log statements to console.info in TypeScript files. 
   The codemod should:
   - Target .ts and .tsx files
   - Only transform console.log calls (not console.error, console.warn, etc.)
   - Preserve all arguments and formatting
   - Include test cases for the transformation"
   
2. Let MCP build the Codemod package

   The AI will use MCP tools to:

   • Analyze your codebase structure with dump_ast
   • Get TypeScript node types with get_node_types
   • Create the jssg codemod script
   • Generate test cases with run_jssg_tests
   • Set up the workflow.yaml and codemod.yaml files
3. Validate the workflow

   npx codemod@latest workflow validate -w workflow.yaml
   

   This ensures your workflow file is syntactically correct and follows the schema.

4. Understand and run the output package

   The MCP will create a complete Codemod package structure:

   my-codemod/
   ├── codemod.yaml        # Package metadata
   ├── workflow.yaml       # Workflow definition
   ├── scripts/
   │   └── codemod.ts      # Your jssg transformation
   └── tests/              # Test cases
   

   Run your codemod:

   npx codemod@latest workflow run -w ./my-codemod/
   

Why use Codemod MCP?

Codemod MCP democratizes code transformation by integrating robust deterministic engines into AI-powered development workflows:

• Individual Developers: Take care of repetitive refactors without manual effort
• Accessibility: Makes tackling tech debt more approachable for developers of all skill levels
• AI Integration: Seamlessly integrates deterministic code transformation engines into AI IDE workflows

Codemod MCP vs Codemod Studio

	Codemod MCP	Codemod Studio
Interface	Integrated into your IDE	Web-based interface
AI Model	Your choice of AI model	Built-in AI assistant
Control	Granular control over codemod creation	Quick prototyping and sharing
Iteration	Direct, instant control in your IDE	Web-based iteration
Sharing	Publishing to Codemod Registry and version control	Built-in sharing
Best For	Power users, framework maintainers, pro codemods	Quick codemod creation and collaboration

Best practices

When working with AI assistants through Codemod MCP, follow these guidelines for better results:

1. Be specific about output format

   Tell the AI exactly what type of codemod you want:

   • jssg: TypeScript-based transformation scripts (codemods) that operate on ASTs generated by ast-grep, allowing you to transform code in any supported language.
   • ast-grep YAML rule: general-purpose transformations
   • shell workflow: complex multi-step migrations
2. Provide clear requirements

   Describe your transformation in plain language with concrete examples:

   • Show before/after code snippets
   • Specify edge cases to handle or avoid
   • Include any constraints or special conditions
3. Break down complex changes

   Instead of one large transformation, create focused codemods for specific patterns:

   • One codemod per logical change
   • Simpler codemods are more maintainable
   • Easier to test and debug individual transformations

Troubleshooting

Server won't start

If the MCP server fails to start:

• Ensure you have Node.js 16.0.0 or higher installed
• Try running npx codemod@latest mcp manually to test

Tools not available

If MCP tools aren’t showing up:

• Restart your AI client after adding the MCP server
• Check the MCP server logs for error messages
• Verify the JSON configuration syntax is correct
• Ensure your AI client supports Model Context Protocol

Performance issues

For slow performance:

• More complex transformations may take longer to build
• Consider using specific file patterns to limit analysis scope
• Check system resources and network connectivity
• Use faster models if available