MigraAPI
davideFerigato/MigraAPI
Automatiza migração de código entre APIs com agentes paralelos
Ver no GitHubAgente Claude que automatiza migração de código entre APIs deprecadas e novas usando Skills, Subagentes e MCP Server. Processa migrações em Python e JavaScript com execução paralela de subagentes, divulgação progressiva e saídas estruturadas.
Instalação
npx convez-ai davideFerigato/MigraAPI1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Migrar código Python/JavaScript de APIs descontinuadas
- Processar grandes volumes de migração com subagentes paralelos
- Gerar relatórios estruturados de incompatibilidade e conversão
Veredito

Solução robusta para automação de migrações de API em escala, com arquitetura bem pensada usando agentes paralelos e notificações de progresso. Ideal para times que precisam refatorar grandes bases de código legado.
README
A tradução para o português deste README ainda está na fila.
AI agent based on Claude Skills, Subagents, and MCP Server (Anthropic) that automatically migrates code from a deprecated API to a new API.
Table of Contents
- Architecture
- Progressive Disclosure
- Skills vs CLAUDE.md vs Hooks vs Subagents
- MCP Server (Model Context Protocol)
- Prerequisites
- Installation
- Usage
- Plugin Distribution
- Enterprise Managed Settings
- Security Best Practices
- Examples
- Troubleshooting
- Roadmap
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ MCP Client (any) │
│ Claude Desktop / Claude Code / Cursor / VS Code │
└─────────────────────────────────────────────────────────────────┘
│
▼ MCP Protocol (STDIO / HTTP)
┌─────────────────────────────────────────────────────────────────┐
│ MigraAPI MCP Server │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Tools: scan_file, scan_directory, rewrite_file, │ │
│ │ validate_file, migrate_codebase │ │
│ │ Resources: migration-rules://current, │ │
│ │ migration-rules://language/{language} │ │
│ │ Prompts: migrate-codebase, resolve-ambiguity │ │
│ │ Advanced: Sampling, Progress, Roots │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Orchestrator (Claude Code) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Scanner │ │ Rewriter │ │ Validator │ │
│ │ Subagent │ │ Subagent │ │ Subagent │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ↑ ↑ ↑ │
│ (parallel on files) (parallel) (parallel) │
└─────────────────────────────────────────────────────────────────┘
│
▼
File System (read/write)
Components
| Component | Description | Tools |
|---|---|---|
api-migration Skill | Migration rules, regex patterns, scanner script | Read, Grep, Glob, Bash |
scanner Subagent | Scans a file and returns structured JSON with occurrences | Read, Grep, Glob |
rewriter Subagent | Applies transformations using mapping rules | Read, Write, Edit |
validator Subagent | Verifies syntactic correctness with obstacle reporting | Read, Bash, Grep |
| MCP Server | Exposes tools, resources, prompts via MCP protocol | (server-side) |
| Orchestrator | Main agent that loads the skill and coordinates subagents | Task tool |
Progressive Disclosure
The skill uses a 3-level progressive disclosure mechanism to minimize context consumption:
| Level | Description |
|---|---|
| 1. Discovery | Claude preloads only name and description in the system prompt |
| 2. Activation | When the task matches the description, Claude reads the full SKILL.md |
| 3. Execution | If needed, Claude loads additional files (migration-rules.json, regex-patterns.md) and runs external scripts (scanner.py) that do not consume context |
Skills vs CLAUDE.md vs Hooks vs Subagents
| Feature | Purpose | When to use | Example |
|---|---|---|---|
| Skills | Dynamic, reusable instructions for specialized tasks | Repeated workflows needing specific knowledge | api-migration skill with migration rules |
| CLAUDE.md | Project-wide always-active configuration | Project settings, style preferences | Ignoring files, env vars |
| Hooks | Event-based automations (pre/post) | Triggers like “before every edit, backup” | pre-edit hook that backs up files |
| Subagents | Task delegation to isolated context windows | Tasks that would blow the main context, parallel execution | Scanner, rewriter, validator |
MCP Server (Model Context Protocol)
MigraAPI includes a complete MCP Server that exposes all migration capabilities to any MCP-compatible client.
Tools
| Tool | Description |
|---|---|
scan_file_tool | Scan a single file for deprecated API calls |
scan_directory_tool | Recursively scan a directory |
rewrite_file_tool | Apply migration changes to a file (with dry-run) |
validate_file_tool | Validate a migrated file for syntax correctness |
migrate_codebase_tool | Full pipeline: scan → rewrite → validate |
Resources
| Resource | Description |
|---|---|
migration-rules://current | Complete migration rules as JSON |
migration-rules://language/{language} | Rules filtered by language |
Prompts
| Prompt | Description |
|---|---|
migrate_codebase_prompt | Template for migrating an entire codebase |
resolve_ambiguity_prompt | Ask Claude to resolve ambiguous migration patterns |
Advanced Features (MCP Advanced Topics)
| Feature | Description | File |
|---|---|---|
| Sampling | Server asks client (Claude) for completions to resolve ambiguities | mcp_server/sampling.py |
| Progress Notifications | Real-time progress updates during long operations | mcp_server/progress.py |
| Roots | Permission model for filesystem access | mcp_server/roots.py |
Running the MCP Server
Locally (STDIO):
python -m mcp_server.server --transport stdio
Remotely (Streamable HTTP):
python -m mcp_server.server --transport streamable-http --port 8000
Claude Desktop Integration
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"migrapi": {
"command": "python3",
"args": ["-m", "mcp_server.server", "--transport", "stdio"],
"cwd": "/path/to/MigraAPI"
}
}
}
For detailed MCP documentation, see docs/mcp.md.
Prerequisites
- Claude Code (agentic mode enabled) – installation guide
- Python 3.9+ (for scanner script and MCP server)
- Node.js (for JavaScript examples, optional)
- Unix terminal (macOS/Linux)
Installation
git clone https://github.com/davideferigato/MigraAPI
cd MigraAPI
# No external dependencies – all standard
MCP Server Dependencies (optional)
pip install -r requirements-mcp.txt
Usage
Automated demo script
./demo-script.sh
Runs simulated scanning and produces migration_report.json.
Real usage with Claude Code
claude
Then ask:
Migrate the code in examples/before from the old API to the new API using the api-migration skill.
Claude will activate the skill, invoke subagents in parallel, and return the result.
Via MCP Server (Claude Desktop / any MCP client)
- Start the MCP server:
python -m mcp_server.server --transport stdio
- Connect from Claude Desktop (configured as above)
- Use the tools directly:
scan_file_tool("examples/before/sample.py")rewrite_file_tool("examples/before/sample.py")validate_file_tool("examples/before/sample.py")
Plugin Distribution
To package MigraAPI as a Claude Code plugin:
- Structure is already ready:
.claude/skills/api-migration/ .claude/agents/ - Add to a marketplace:
/plugin marketplace add anthropics/skills - Install the plugin:
/plugin install migrapi@your-org/skills
See plugin.json for metadata.
Enterprise Managed Settings
In enterprise environments, skills can be centrally deployed:
- Managed settings preinstall skills on all team workstations.
- An admin can enforce the
api-migrationskill on specific repositories. - Skills auto-update when the central repository changes.
Security Best Practices
- Always verify skills from external sources – inspect content, especially scripts.
- Use
allowed-tools– restrict sensitive tools (e.g.,Write,Bash). In this skill, the scanner only has read tools. - Never include secrets or API keys in skill files.
- Run scripts in sandboxes (containers or isolated environments) when possible.
- Audit changes – use the
validatorsubagent to check every modification.
For detailed security policy, see SECURITY.md.
Examples
Before migration (examples/before/sample.py):
from old_api import Client
client = Client(api_key="test")
user = client.get_user(user_id=123)
After migration (examples/after/sample.py):
from new_api import Client
client = Client(api_key="test")
user = client.fetch_user_by_id(user_id=123)
Run the test suite:
python tests/test_migration.py
Troubleshooting
Skill does not activate
- Check
nameanddescriptioninSKILL.mdfrontmatter. - Verify the skill is in
.claude/skills/api-migration/. - Explicitly ask: “Use the api-migration skill to...”
Scanner finds no occurrences
- Update patterns in
regex-patterns.mdand thePATTERNSdict inscanner.py. - Ensure file extensions are
.py,.js,.mjs,.cjs. - Test manually:
python .claude/skills/api-migration/scripts/scanner.py <file>
Rewriter errors
- Check file write permissions.
- Ensure
allowed-toolsincludesWriteandEdit. - Refine mappings in
migration-rules.json(use more specific strings).
Validation fails
- Inspect the JSON error output for line numbers.
- Manually correct the file or adjust migration rules.
- Add an intermediate validation step in the orchestration.
MCP Server not starting
- Check Python version:
python --version(requires 3.9+) - Install dependencies:
pip install -r requirements-mcp.txt - Verify port is available:
netstat -an | grep 8000
Roadmap
- Claude Skills implementation (progressive disclosure, hooks, plugin.json)
- Subagents with structured JSON and obstacle reporting
- MCP Server with tools, resources, prompts
- MCP Advanced Topics (Sampling, Progress, Roots)
- Streamable HTTP transport for remote deployment
- Full documentation and CI/CD
- Publish as a plugin on Anthropic marketplace