convez.ai
SkillIntegração & APIsAvançado
davideFerigato

MigraAPI

davideFerigato/MigraAPI

Automatiza migração de código entre APIs com agentes paralelos

Ver no GitHub
InicialPluginScore · de 0 a 100

Agente 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/MigraAPI

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 4 meses
Versão
v2.0.0
Issues abertas
0
Contribuidores
1

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

┌─────────────────────────────────────────────────────────────────┐
│                    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

ComponentDescriptionTools
api-migration SkillMigration rules, regex patterns, scanner scriptRead, Grep, Glob, Bash
scanner SubagentScans a file and returns structured JSON with occurrencesRead, Grep, Glob
rewriter SubagentApplies transformations using mapping rulesRead, Write, Edit
validator SubagentVerifies syntactic correctness with obstacle reportingRead, Bash, Grep
MCP ServerExposes tools, resources, prompts via MCP protocol(server-side)
OrchestratorMain agent that loads the skill and coordinates subagentsTask tool

Progressive Disclosure

The skill uses a 3-level progressive disclosure mechanism to minimize context consumption:

LevelDescription
1. DiscoveryClaude preloads only name and description in the system prompt
2. ActivationWhen the task matches the description, Claude reads the full SKILL.md
3. ExecutionIf 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

FeaturePurposeWhen to useExample
SkillsDynamic, reusable instructions for specialized tasksRepeated workflows needing specific knowledgeapi-migration skill with migration rules
CLAUDE.mdProject-wide always-active configurationProject settings, style preferencesIgnoring files, env vars
HooksEvent-based automations (pre/post)Triggers like “before every edit, backup”pre-edit hook that backs up files
SubagentsTask delegation to isolated context windowsTasks that would blow the main context, parallel executionScanner, rewriter, validator

MCP Server (Model Context Protocol)

MigraAPI includes a complete MCP Server that exposes all migration capabilities to any MCP-compatible client.

Tools

ToolDescription
scan_file_toolScan a single file for deprecated API calls
scan_directory_toolRecursively scan a directory
rewrite_file_toolApply migration changes to a file (with dry-run)
validate_file_toolValidate a migrated file for syntax correctness
migrate_codebase_toolFull pipeline: scan → rewrite → validate

Resources

ResourceDescription
migration-rules://currentComplete migration rules as JSON
migration-rules://language/{language}Rules filtered by language

Prompts

PromptDescription
migrate_codebase_promptTemplate for migrating an entire codebase
resolve_ambiguity_promptAsk Claude to resolve ambiguous migration patterns

Advanced Features (MCP Advanced Topics)

FeatureDescriptionFile
SamplingServer asks client (Claude) for completions to resolve ambiguitiesmcp_server/sampling.py
Progress NotificationsReal-time progress updates during long operationsmcp_server/progress.py
RootsPermission model for filesystem accessmcp_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)

  1. Start the MCP server:
python -m mcp_server.server --transport stdio
  1. Connect from Claude Desktop (configured as above)
  2. 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:

  1. Structure is already ready:
    .claude/skills/api-migration/
    .claude/agents/
    
  2. Add to a marketplace:
    /plugin marketplace add anthropics/skills
    
  3. 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-migration skill 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 validator subagent 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 name and description in SKILL.md frontmatter.
  • 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.md and the PATTERNS dict in scanner.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-tools includes Write and Edit.
  • 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

Acknowledgements


Ver o original no GitHub

Bom para

Relacionados