@rotifer/mcp-server

Framework de Agente de IA auto-evolutivo — pesquise, compare e instale Genes classificados por aptidão na Arena via MCP

Documentação

@rotifer/mcp-server

Construa, componha e execute agentes de IA — diretamente da sua IDE.

Pesquise genes, crie agentes com genomas componíveis, execute pipelines em um sandbox WASM e compita na Arena. Zero configuração. Funciona com Cursor, Claude Desktop, Windsurf e qualquer cliente compatível com MCP.

Início Rápido

Cursor

Adicione em .cursor/mcp.json:

{
  "mcpServers": {
    "rotifer": {
      "command": "npx",
      "args": ["@rotifer/mcp-server"]
    }
  }
}

Claude Desktop

Adicione em claude_desktop_config.json:

{
  "mcpServers": {
    "rotifer": {
      "command": "npx",
      "args": ["@rotifer/mcp-server"]
    }
  }
}

Windsurf / Outros Clientes MCP

Use o mesmo comando npx — qualquer cliente que suporte transporte MCP stdio funcionará.

O Que Ele Pode Fazer?

Criar e executar um agente em uma única conversa

You: "Build me an agent for code security scanning"
AI:  → create_agent({ agent_name: "sec-bot", gene_ids: ["security-scanner", "genesis-code-format"],
                       composition: "Seq" })
     Agent 'sec-bot' created with 2-gene Seq genome.

You: "Run it on my project"
AI:  → agent_run({ agent_name: "sec-bot", input: "{\"path\":\"./src\"}" })
     Pipeline complete — 3 findings, 0 critical.

Pesquisar, comparar e compor genes

You: "Find the best gene for web search"
AI:  → search_genes({ query: "web search" })
     Found 8 genes. Top match: genesis-web-search (F(g) = 0.87, Native)

You: "Compare it against the lite version"
AI:  → compare_genes({ gene_ids: ["...", "..."] })
     Side-by-side: success rate, latency, fitness breakdown

Ciclo de vida completo do gene a partir da sua IDE

You: "Wrap my function as a gene"
AI:  → wrap_gene({ gene_name: "my-search", domain: "search.web", fidelity: "Wrapped" })
     → compile_gene({ gene_name: "my-search" })
     → test_gene({ gene_name: "my-search", compliance: true })
     → publish_gene({ gene_name: "my-search", changelog: "Initial release" })

Ferramentas (31)

Descoberta e Análise

Ferramenta	Descrição	Parâmetros Principais
`search_genes`	Pesquise o ecossistema Gene por nome, domínio ou descrição	`query`, `domain`, `fidelity`, `sort` (`relevance`/`newest`/`popular`/`fitness`), `page`, `per_page`
`get_gene_detail`	Obtenha informações detalhadas sobre um Gene (fenótipo, aptidão, metadados)	`gene_id`, `content_hash` (qualquer um identifica o gene)
`get_arena_rankings`	Rankings da Arena para um domínio, ordenados pela aptidão F(g)	`domain`, `page`, `per_page`
`compare_genes`	Comparação lado a lado da aptidão de 2–5 Genes	`gene_ids` (array)
`get_gene_stats`	Estatísticas de download (total, 7d, 30d, 90d)	`gene_id`
`get_leaderboard`	Ranking de reputação dos criadores	`limit`
`get_developer_profile`	Perfil público e reputação do criador	`username`
`get_gene_reputation`	Detalhamento da reputação (Arena, Uso, Estabilidade)	`gene_id`
`list_gene_versions`	Cadeia de histórico de versões com changelogs	`owner`, `gene_name`
`suggest_domain`	Sugira domínios correspondentes do registro	`description`

Workspace Local

Ferramenta	Descrição	Parâmetros Principais
`list_local_genes`	Escaneie o workspace local em busca de Genes instalados	`project_root`, `domain`, `fidelity`
`list_local_agents`	Liste os Agentes no workspace local	`project_root`, `state`

Ciclo de Vida do Gene

Ferramenta	Descrição	Parâmetros Principais
`init_gene`	Inicialize um novo projeto Gene com arquivos iniciais	`gene_name`, `fidelity`, `domain`, `no_genesis`
`scan_genes`	Escaneie funções candidatas ou arquivos SKILL.md	`path`, `skills`, `skills_path`
`wrap_gene`	Encapsule uma função/habilidade como um Gene	`gene_name`, `domain`, `fidelity`, `from_skill`, `from_clawhub`
`test_gene`	Teste um Gene (validação de esquema + sandbox)	`gene_name`, `verbose`, `compliance`
`compile_gene`	Compile um Gene para WASM IR	`gene_name`, `check`, `wasm_path`, `lang`
`doctor`	Verifique o toolchain local TypeScript→WASM (esbuild / javy) e relate o que está faltando — somente leitura; use quando `compile_gene` falhar	`project_root`
`run_gene`	Execute um Gene local	`gene_name`, `input`, `verbose`, `no_sandbox`, `trust_unsigned`
`publish_gene`	Publique no Rotifer Cloud	`gene_name`, `all`, `description`, `changelog`, `skip_arena`, `skip_security`
`install_gene`	Instale um Gene do Cloud Registry. `force` cria um snapshot da cópia que ele substitui	`gene_id`, `project_root`, `force`
`rollback_gene`	Desfaça a última sobrescrita de um Gene local; chame sem nome para listar o que pode ser desfeito	`gene_name`, `project_root`
`vg_scan`	Verificação de segurança V(g) — análise estática para segurança de código Gene/Skill	`path`, `gene_id`, `all`, `project_root`
`arena_submit`	Meça um Gene local no sandbox e envie a medição para a Arena. As pontuações são produzidas executando o Gene, nunca fornecidas pelo chamador	`gene_name`, `project_root`

Composição de Agentes

Ferramenta	Descrição	Parâmetros Principais
`create_agent`	Crie um Agente compondo múltiplos Genes	`agent_name`, `gene_ids`, `composition` (`Seq`/`Par`/`Cond`/`Try`/`TryPool`), `domain`, `top`, `strategy`, `par_merge`
`agent_run`	Execute um Agente local pelo nome	`agent_name`, `input`, `verbose`, `no_sandbox`

Autenticação e Análise

Ferramenta	Descrição	Parâmetros Principais
`auth_status`	Verifique o status de login	—
`login`	Login OAuth (GitHub/GitLab)	`provider`, `endpoint`
`logout`	Limpe as credenciais	—
`get_mcp_stats`	Análise de chamadas MCP	`days`
`get_my_reputation`	Reputação do usuário atual	—

Recursos (7)

Os Recursos MCP permitem que clientes de IA referenciem dados do Rotifer como contexto:

Template de URI	Descrição
`rotifer://genes/{gene_id}/stats`	Estatísticas de download do Gene
`rotifer://genes/{gene_id}`	Detalhes do Gene + fenótipo
`rotifer://developers/{username}`	Perfil do criador + reputação
`rotifer://leaderboard`	Principais criadores por pontuação de reputação
`rotifer://local/genes`	Inventário local de Genes
`rotifer://local/agents`	Registro local de Agentes
`rotifer://version`	Versão do MCP Server e disponibilidade de atualização

Cada recurso retorna o que a ferramenta do mesmo trabalho retorna, então um conjunto declarado cobre ambos: com --tools=evolve, rotifer://genes/{gene_id}/stats, rotifer://developers/{username} e rotifer://leaderboard desaparecem da listagem e são recusados se lidos diretamente, porque get_gene_stats, get_developer_profile e get_leaderboard não foram solicitados. rotifer://version sempre responde — é o servidor descrevendo a si mesmo, não uma capacidade. Antes da 0.16.0, estes eram acessíveis independentemente do que o conjunto de ferramentas dizia.

Prompts (4)

Os Prompts MCP dão aos clientes de IA fluxos de trabalho guiados para tarefas comuns:

Prompt	Descrição	Argumentos Principais
`rotifer-hello`	Criação interativa de agente — escolha um template e execute imediatamente	`template`, `input`
`rotifer-guide`	Entenda o Protocolo Rotifer — genes, agentes, Arena, modelo de fidelidade	—
`rotifer-architect`	Projete um Agente — busca de genes orientada por tarefa + planejamento de composição	`task`
`rotifer-challenge`	Avaliação na Arena — envie um gene, compare com concorrentes	`gene`

Tente perguntar à sua IA: "Use o prompt rotifer-hello para me criar um agente" ou "Use rotifer-architect para projetar um agente para Q&A de documentos".

Arquitetura

┌─────────────────────────────────────────────────┐
│  AI IDE (Cursor / Claude / Windsurf)            │
│                                                 │
│  "Find genes for code formatting"               │
│       │                                         │
│       ▼                                         │
│  ┌─────────────────────┐                        │
│  │  MCP Client         │                        │
│  │  (stdio transport)  │                        │
│  └────────┬────────────┘                        │
└───────────┼─────────────────────────────────────┘
            │ MCP Protocol
            ▼
┌─────────────────────────────────────────────────┐
│  @rotifer/mcp-server                            │
│                                                 │
│  30 Tools  7 Resources  4 Prompts  Local Scanner│
│  ┌──────────┐  ┌───────────┐   ┌────────────┐  │
│  │ discover │  │rotifer:// │   │ ./genes/    │  │
│  │ lifecycle│  │genes/stats│   │ phenotype   │  │
│  │ agents   │  │developers │   │ agents      │  │
│  │ auth     │  │leaderboard│   └────────────┘  │
│  └────┬─────┘  └─────┬─────┘         │         │
└───────┼──────────────┼────────────────┼─────────┘
        │              │                │
        ▼              ▼                ▼
┌─────────────────────────────────────────────────┐
│  Rotifer Cloud API          Local File System   │
│  (Supabase)                 (genes/, .rotifer/) │
└─────────────────────────────────────────────────┘

Configuração

Zero configuração por padrão — conecta-se à API pública do Rotifer Cloud.

Para usar um endpoint personalizado, crie ~/.rotifer/cloud.json:

{
  "endpoint": "https://your-supabase-instance.supabase.co",
  "anonKey": "your-anon-key"
}

Ou defina variáveis de ambiente:

ROTIFER_CLOUD_ENDPOINT=https://your-instance.supabase.co
ROTIFER_CLOUD_ANON_KEY=your-anon-key

Escolhendo quais ferramentas expor

Todas as trinta e uma ferramentas estão disponíveis por padrão. ROTIFER_MCP_TOOLS restringe isso ao que uma integração específica realmente precisa — útil quando o servidor está anexado a um assistente que não deve poder publicar ou fazer login em seu nome:

npx @rotifer/mcp-server --tools=evolve          # the rank-and-swap preset (10 tools)
npx @rotifer/mcp-server --tools=readonly        # nothing that writes (14 tools)
ROTIFER_MCP_TOOLS=search_genes,get_gene_detail  # an exact list
ROTIFER_MCP_TOOLS=evolve,vg_scan                # a preset plus one

A flag e a variável fazem a mesma coisa, e a flag vence se ambas forem definidas. Ambas existem porque os chamadores diferem no que podem alcançar: um usuário de shell define a variável, enquanto algo que inicia este servidor a partir de um manifesto controla apenas a linha de comando.

Um conjunto declarado cobre toda a superfície, não apenas tools/list. Ferramentas fora dele são recusadas quando chamadas pelo nome; recursos que duplicam uma ferramenta excluída são removidos da listagem e recusados quando lidos; e as saídas de escape do sandbox abaixo permanecem desativadas a menos que sejam declaradas separadamente. Uma restrição com uma forma não listada de contorná-la não é uma restrição.

Ferramentas fora do conjunto desaparecem de listTools e são recusadas se chamadas mesmo assim. A recusa diz como adicionar a ferramenta de volta e, onde existir, o comando CLI rotifer que faz o mesmo trabalho — então um conjunto restrito é um limite que você pode ver e cruzar deliberadamente, não um beco sem saída.

Deixe sem definir e nada muda.

Desativando o sandbox

agent_run e run_gene aceitam no_sandbox, e run_gene também aceita trust_unsigned — opções que executam código Gene como Node.js simples em vez de dentro do sandbox WASM. Restringir o conjunto de ferramentas significaria pouco se uma ferramenta dentro do conjunto restrito ainda pudesse fazer isso, então estas são recusadas a menos que declaradas na inicialização:

npx @rotifer/mcp-server --allow=no-sandbox
npx @rotifer/mcp-server --allow=no-sandbox,trust-unsigned
ROTIFER_MCP_ALLOW=no-sandbox                    # same thing

Nada é removido. A opção passa de "qualquer chamador pode defini-la" para "alguém a declarou na inicialização", e você sempre pode fazer isso você mesmo:

rotifer agent run <name> --no-sandbox
rotifer run <gene> --trust-unsigned

O que muda é que um assistente não pode mais decidir remover o sandbox por conta própria. Passar no_sandbox: false é pedir o comportamento seguro e nunca é recusado.

Desfazendo uma instalação

install_gene com force costumava sobrescrever um Gene sem volta. Agora move a cópia antiga para <genes>/.snapshots/ primeiro, e rollback_gene a coloca de volta:

rollback_gene {}                          → what can be rolled back
rollback_gene { gene_name: "formatter" }  → restore the copy that was replaced

Um snapshot por Gene: a próxima sobrescrita desse Gene o substitui, e um rollback o consome. Isso desfaz a última atualização em vez de manter um histórico — list_gene_versions já responde quais versões existem upstream.

Mantendo o servidor atualizado

O servidor sempre informou quando estava desatualizado — uma linha no stderr na inicialização, uma vez por dia. self-update é a outra metade:

rotifer-mcp-server self-update              # check, verify, install
rotifer-mcp-server self-update --rollback   # back to the version it replaced

Ele recusa qualquer versão para a qual o npm não tenha atestação de proveniência — este pacote publica a partir do CI com --provenance, então uma build não atestada não é uma que este projeto lançou.

Duas coisas que vale a pena saber:

Um servidor em execução continua servindo o código antigo. Instalar substitui arquivos no disco; não substitui o processo com o qual seu editor já está falando. Reinicie seu host MCP depois.
Se você iniciar via npx, não há nada para atualizar. Um npx @rotifer/mcp-server sem pinagem re-resolve a versão publicada mais recente a cada execução, então self-update diz isso e para em vez de instalar uma cópia global que a obscureceria.

Este é um comando que você executa, não uma ferramenta que o modelo pode chamar. Atualizar significa uma instalação global, e uma ferramenta nem poderia relatar o resultado honestamente — o modelo diria "atualizado" enquanto ainda estaria sendo servido pelo processo antigo.

Relatório de uso

Quando você está conectado, cada chamada de ferramenta reporta um registro de uso ao Rotifer Cloud: o nome da ferramenta, o id do Gene sobre o qual atuou, se teve sucesso, quanto tempo levou e seu id de usuário. É isso que get_mcp_stats lê de volta. Executar um Gene também registra a invocação, da qual as métricas anti-manipulação do protocolo dependem.

Ele não envia os argumentos que você passa, o conteúdo de qualquer arquivo, suas variáveis de ambiente ou sua configuração local.

Desconectado, nenhum registro de uso é enviado. Uma solicitação sai de qualquer forma: instalar um Gene incrementa o contador público de instalações desse Gene. Ela carrega o id do Gene e nada mais — sem id de usuário, sem sessão, sem argumentos — e é assim que a Arena conta instalações. Até 0.15.1 nada a impedia, e esta seção dizia "desconectado, nada é reportado", o que não era verdade para uma instalação.

ROTIFER_TELEMETRY=0 agora interrompe todos os três:

ROTIFER_TELEMETRY=0    # also accepts false / off

Os três são logMcpCall, logGeneInvocation e a chamada track_download dentro de installGene, todos em src/cloud.ts — curtos o suficiente para ler por completo. Nada mais aqui relata algo por conta própria: todas as outras chamadas de saída neste servidor são uma ferramenta que você invocou fazendo seu trabalho — uma consulta, uma publicação, um login — além do download do artefato WASM e uma verificação de versão npm por dia.

Requisitos

Node.js >= 20

Combine com a CLI

Este servidor MCP funciona melhor junto com a CLI do Rotifer. A CLI fornece o runtime local (sandbox WASM, mecanismo Arena, compilador IR) enquanto o servidor MCP expõe tudo isso ao seu assistente de IA:

npm install -g @rotifer/playground
rotifer init my-agent && cd my-agent
rotifer hello --template quality-advisor   # your first Agent workspace in seconds

Licença

Apache-2.0

@rotifer/mcp-server

Documentação