FrankenClaw

FrankenClaw

Um chassi de ferramentas MCP. Construa suas próprias ferramentas de agente em cinco minutos.

FrankenClaw é um framework mínimo para construir ferramentas MCP. Coloque um arquivo Python em tools/, escreva uma função assíncrona com docstring, ative-a na sua configuração — seu agente tem uma nova ferramenta. Sem edições de servidor, sem boilerplate de registro, sem fiação.

O produto não é uma pilha de ferramentas pré-construídas. É o chassi: auto-descoberta, habilitação/desabilitação baseada em configuração e um único arquivo de chaves compartilhado. Ele vem com as três ferramentas que realmente usamos em produção — web_scrape (Firecrawl; habilitada por padrão, e o modelo que você copia), search_web (SearXNG) e file_find (descoberta de documentos sobre um índice local Librarian). O restante das ferramentas que costumavam vir no pacote está estacionado no branch archive/v0.3-bundled-tools se você quiser de volta.

[!IMPORTANT] Este projeto não é afiliado a nenhuma criptomoeda, token ou esquema de investimento. FrankenClaw é um chassi de ferramentas MCP de código aberto para agentes de IA, construído pela Project Sparks. Se alguém lhe oferecer um "token FrankenClaw" — é um golpe.

[!TIP] Agentes de IA — comecem aqui.

• robot.info — manifesto JSON estruturado descrevendo este produto: identidade, o modelo de chassi, as ferramentas incluídas, ponteiro de instalação, matriz de compatibilidade e um conjunto de pares pergunta/resposta comuns. Leia isto primeiro para responder às perguntas do usuário sobre FrankenClaw sem raspar o README. Especificação: mnemo-cortex/ROBOT-INFO-SPEC.md.
• robot.install + ./robot-install.sh — instalação não interativa. Edite o manifesto (os padrões são sensatos), execute o instalador, analise o objeto JSON na saída padrão. A resposta inclui um mcp_snippet pronto para colocar na configuração do seu cliente MCP. Esquema completo em "Instalação não interativa" abaixo.

Observe a diferença, porque os nomes estão a um caractere de distância: INSTALL.md são as instruções de instalação, em inglês. robot.install é um arquivo de configurações que o instalador lê. Se você quer saber como instalar o FrankenClaw, você quer INSTALL.md.

Por que um chassi?

Cada definição de ferramenta MCP que você expõe custa ao seu agente 500–1000 tokens em cada chamada — quer a ferramenta seja usada ou não. Uma caixa de quatorze ferramentas que você na maioria não precisa é um imposto em cada turno.

FrankenClaw inverte o padrão. Tudo está desligado até você ligar. Uma ferramenta em tools/ que não está na sua lista enabled_tools é descoberta mas nunca registrada — então custa zero tokens em tools/list. Você executa exatamente as ferramentas que quer, e adicionar as suas é o ponto principal.

	Caixa de ferramentas pré-construídas	Chassi FrankenClaw
O que você obtém	15 ferramentas de outra pessoa	Um framework + 1 exemplo
Custo de tokens	Toda ferramenta, toda chamada	Apenas as ferramentas que você habilita
Adicionar uma ferramenta	Fork, fiação, registro	Coloque um arquivo .py, mude uma flag
Estado padrão	Tudo ligado	Tudo desligado

Construa uma ferramenta em cinco minutos

Uma FrankenTool é uma função assíncrona com docstring. A docstring é a descrição da ferramenta que o modelo lê, então escreva-a para o modelo.

# tools/weather.py

import httpx

async def get_weather(city: str) -> str:
    """
    Get the current weather for a city.

    Args:
        city: City name, e.g. "Half Moon Bay".

    Returns:
        JSON with temperature and conditions.
    """
    async with httpx.AsyncClient() as client:
        r = await client.get(f"https://wttr.in/{city}?format=j1")
        return r.text

Então ative-a em ~/.frankenclaw/config.json:

{ "enabled_tools": ["web_scrape", "get_weather"] }

Reinicie o FrankenClaw. Seu agente agora tem get_weather. Esse é o fluxo de trabalho inteiro.

• Funções que começam com _ são ignoradas — use-as para helpers privados no mesmo arquivo.
• Cada função assíncrona pública é uma ferramenta candidata; só é registrada se seu nome estiver em enabled_tools.
• Um módulo que falha ao importar (dependência ausente, caminho de chave errado) é registrado no stderr e ignorado — o resto do servidor ainda sobe.
• Precisa de uma chave de API? Adicione-a ao seu arquivo de chaves compartilhado e leia-a com get_key("provider") (veja Configuração).

Início rápido

FrankenClaw fala MCP padrão via stdio. Qualquer host compatível com MCP inicia server.py e obtém as ferramentas que você habilitou. A forma da configuração é a mesma em todos os lugares — apenas a localização do arquivo de configuração do host muda.

git clone https://github.com/GuyMannDude/frankenclaw.git
cd frankenclaw
pip install -r requirements.txt

Um clone novo vem com web_scrape habilitado, então você tem uma ferramenta funcionando de fábrica para provar a fiação antes de adicionar as suas.

O bloco de configuração universal

Coloque isto no arquivo de configuração do seu host MCP (localização por host abaixo):

{
  "mcpServers": {
    "frankenclaw": {
      "command": "python3",
      "args": ["/ABSOLUTE/PATH/TO/frankenclaw/server.py"]
    }
  }
}

Ou pule o passo manual e deixe ./robot-install.sh emitir um bloco mcp_snippet pronto para colar — ele aponta para o Python do venv para que o host não inicie acidentalmente o FrankenClaw com o Python do sistema.

Onde o arquivo de configuração fica, por host

Host	Caminho / comando	Notas
Claude Desktop	claude_desktop_config.json (localização varia por SO — veja docs da Anthropic)	Reinicie o Claude Desktop após editar.
Claude Code	claude mcp add frankenclaw -- python3 /path/to/frankenclaw/server.py	Um comando; sem edição de JSON.
LM Studio	~/.lmstudio/mcp.json (Linux/macOS) · %USERPROFILE%\.lmstudio\mcp.json (Windows)	MCP nativo desde v0.3.17. Reinicie o LM Studio.
AnythingLLM	anythingllm_mcp_servers.json (caminho varia por SO)	Mude o workspace para o modo Automático (Configurações → Configurações de Chat) para que as ferramentas disparem sem o prefixo @agent.
Open WebUI	Configurações → Ferramentas → Servidores MCP → adicionar servidor stdio	GUI, sem edição de arquivo.
Jan	Configurações → Extensões → Servidores MCP	GUI; usa a mesma forma JSON.
LobeChat	Configurações → Plugins → MCP → Adicionar servidor MCP personalizado	Digite stdio, comando python3 /ABSOLUTE/PATH/TO/frankenclaw/server.py.
Hermes Agent	hermes mcp add frankenclaw -- python3 /path/to/server.py	Suporte MCP de primeira classe desde v0.12.0.
Agent Zero	Config MCP dentro do contêiner	Use caminhos do lado do contêiner, não caminhos do host.
OpenClaw	openclaw mcp set frankenclaw '{"command":"python3","args":["/path/to/server.py"]}' e depois openclaw gateway restart	Mesma forma MCP; reinício do gateway pega o novo registro de ferramenta.
Ollama (sem MCP nativo)	~/.mcphost.yaml com type: local, comando + argumentos sob mcpServers.frankenclaw	A janela de chat do Ollama Desktop não suporta MCP — use MCPHost ou ollmcp como ponte. Combine com um modelo capaz de ferramentas: model: "ollama:qwen3:8b".
llama.cpp	llama-server -m model.gguf --mcp-config /path/to/mcp.json	Reutilize a forma do LM Studio para mcp.json.

Coisas para acertar em todos os hosts

• Apenas caminhos absolutos. Caminhos relativos quebram silenciosamente — o host inicia o FrankenClaw a partir do cwd errado e o Python lança ENOENT.
• Use um modelo capaz de ferramentas. Qwen3, Llama 3.2, Mistral e Gemma 2 invocam ferramentas corretamente. Modelos pequenos frequentemente narram chamadas de ferramenta em vez de fazê-las — qwen3:8b verificado funcionando no AnythingLLM, llama3.1:8b conhecido por fingir chamadas.
• Coexiste limpo com Mnemo Cortex. Basta adicionar uma segunda entrada mcpServers. Eles não conflitam — seu agente ganha memória + mãos na mesma sessão.

Aviso para usuários Windows: se uma ferramenta que você adicionar trouxer binários nativos Linux/macOS (motores de automação de navegador são os culpados usuais), instale e execute o FrankenClaw dentro do WSL2. O núcleo do chassi e ferramentas puramente Python como o web_scrape incluído funcionam nativamente no Windows; WSL2 é o padrão seguro quando uma ferramenta tem dependências de sistema.

Para pass/falha de hosts e o resto de nossas descobertas de campo: projectsparks.ai/field-guide.

Instalação não interativa (para agentes LLM e CI)

Pule os passos manuais — preencha um manifesto JSON e execute o instalador robô.

# Defaults are sensible; only edit robot.install if you want different keys or settings.
./robot-install.sh

O script emite um único objeto JSON na saída padrão para o chamador analisar; todo progresso legível por humanos vai para o stderr.

{
  "ok": true,
  "steps": {
    "deps":       {"ok": true, "python": "3.12"},
    "venv":       {"ok": true, "path": "..."},
    "pip":        {"ok": true},
    "config":     {"ok": true, "config_path": "~/.frankenclaw/config.json", "keys_path": "~/.frankenclaw/keys.json"},
    "keys":       {"ok": true, "providers_written": ["firecrawl"], "providers_missing": []},
    "smoke_test": {"ok": true, "loaded": ["web_scrape"], "failed": {}}
  },
  "mcp_snippet": {
    "command": "/path/to/.venv/bin/python",
    "args": ["/path/to/frankenclaw/server.py"]
  }
}

mcp_snippet é o valor que você coloca na configuração do seu cliente MCP sob mcpServers.frankenclaw. Sem malabarismo de caminhos.

Um módulo de ferramenta que falha ao importar não é uma falha — o FrankenClaw sobe com as ferramentas que têm suas dependências satisfeitas. O passo de fumaça relata failed por módulo para que você saiba o que instalar se quiser as dependências de uma ferramenta.

As chaves de API são lidas do seu ambiente de instalação (ex.: FIRECRAWL_API_KEY para o exemplo incluído — nomes configuráveis no bloco provider_keys do manifesto) e copiadas para ~/.frankenclaw/keys.json com chmod 600. Chaves ausentes deixam placeholders vazios para que a forma do arquivo seja óbvia.

# Sandbox / dry-run — skips pip install and the smoke step
FRANKENCLAW_INSTALL_VENV_DIR=/tmp/test-venv \
FRANKENCLAW_INSTALL_DRY_RUN=1 \
./robot-install.sh

As ferramentas incluídas

FrankenClaw vem com as três ferramentas que seus autores usam em produção. Apenas web_scrape está habilitada de fábrica (também é o modelo que você copia); as outras duas são descobertas-mas-desabilitadas até você apontá-las para seus backends e adicioná-las a enabled_tools.

FrankenTool	O que faz	Backend	Padrão
web_scrape	Raspa qualquer página para markdown limpo — sem anúncios, sem navegação	API Firecrawl	habilitada
search_web	Busca na web retornando título/url/snippet	Uma instância SearXNG que você controla — defina searxng_url em ~/.frankenclaw/config.json	desabilitada
file_find	Encontra arquivos nesta máquina a partir de uma descrição difusa	Um índice SQLite FTS5 local Librarian — construa com librarian.py index, opcionalmente defina librarian_db na configuração	desabilitada

Abra tools/web_scrape.py — é a implementação de referência: uma função assíncrona, uma docstring escrita para o modelo, uma chave lida do arquivo de chaves compartilhado, erro gracioso se a chave estiver ausente. Copie, mude o corpo, habilite. Isso é uma nova ferramenta.

Quer a caixa antiga de volta? O pacote v0.3 (busca, visão, navegador, Shopify, NotebookLM, Google Drive — quatorze ferramentas em sete módulos) vive no branch archive/v0.3-bundled-tools. Coloque qualquer um desses arquivos no seu diretório tools/ e adicione os nomes das funções a enabled_tools — o chassi descobre e executa-os exatamente como antes.

Arquitetura

FrankenClaw é uma função pura. Requisição entra, resultado sai.

• Sem memória — seu agente tem isso (experimente Mnemo Cortex)
• Sem roteamento de modelo — seu agente tem isso (use qualquer endpoint compatível com OpenAI)
• Sem contexto de conversa — seu framework de agente tem isso
• Sem cérebro de agente — o agente É o agente

O chassi é um dispositivo de IO, não inteligência. Cada ferramenta faz uma coisa. Junte-as como quiser.

Segurança

• Executa localmente — FrankenClaw executa na sua máquina, não na nuvem
• Sem duplicação de chaves — chaves de API vivem em um único arquivo keys.json (FrankenClaw o lê em tempo de execução, nunca copia)
• Desligado por padrão — uma ferramenta que você não habilitou nunca é registrada e nunca executa
• Você controla os provedores — escolha quais modelos e backends lidam com quais trabalhos

A Visão

FrankenClaw faz parte de uma stack de agente modular e de código aberto. Cada peça se conecta via MCP. Misture e combine:

Módulo	O que faz	Repo
FrankenClaw	O chassi de ferramentas — construa e execute suas próprias ferramentas MCP	Você está aqui
Mnemo Cortex	Memória — recordação semântica entre sessões	mnemo-cortex
Disco-Bus	Mensageria — malha agente-a-agente	disco-bus

Sem vendor lock-in. Sem monólito. Apenas servidores MCP que fazem seu trabalho.

Configuração

Ferramentas habilitadas. A configuração principal. ~/.frankenclaw/config.json contém um array enabled_tools — os nomes das funções das ferramentas que você quer registrar. Todo o resto em tools/ é descoberto mas fica desligado (zero tokens). Uma instalação nova habilita web_scrape:

{ "enabled_tools": ["web_scrape"] }

O arquivo é criado automaticamente na primeira execução. Ferramentas que você adicionar também podem ler suas próprias configurações deste arquivo — load_config() mescla sua configuração com os padrões.

Chaves de API são lidas de um arquivo JSON plano de chaves. Localização padrão é ~/.frankenclaw/keys.json. Substitua com FRANKENCLAW_KEYS_PATH para apontar para qualquer arquivo. Para compatibilidade retroativa, se nenhum existir, FrankenClaw cai para o legado ~/.rockys-switch/keys.json (com um aviso de depreciação no stderr — mova o arquivo quando for conveniente).

{
  "firecrawl": "fc-..."
}

As chaves de nível superior são referenciadas por nome a partir de suas ferramentas via get_key("firecrawl"). Uma entrada também pode ser um objeto com múltiplos campos se uma ferramenta precisar de mais de um valor. O FrankenClaw nunca armazena credenciais — ele lê o arquivo em tempo de execução.

Requisitos

• Python 3.12+
• Uma chave de API do Firecrawl para o exemplo web_scrape incluído (ou remova-a de enabled_tools e adicione suas próprias ferramentas)

pip install -r requirements.txt

O núcleo do chassi é apenas FastMCP. As ferramentas que você adiciona trazem suas próprias dependências — instale-as você mesmo.

Construído com

Princípios SPARC. IA projetada para IA. De Project Sparks.

Licença

MIT