FrankenClaw

FrankenClaw

Un chasis de herramientas MCP. Construye tus propias herramientas de agente en cinco minutos.

FrankenClaw es un marco mínimo para construir herramientas MCP. Coloca un archivo Python en tools/, escribe una función asíncrona con un docstring, actívala en tu configuración — tu agente tiene una nueva herramienta. Sin ediciones de servidor, sin plantillas de registro, sin cableado.

El producto no es un montón de herramientas preconstruidas. Es el chasis: auto-descubrimiento, habilitación/deshabilitación basada en configuración, y un único archivo de claves compartido. Incluye las tres herramientas que realmente ejecutamos en producción — web_scrape (Firecrawl; habilitada por defecto, y la plantilla que copias), search_web (SearXNG), y file_find (descubrimiento de documentos sobre un índice local Librarian). El resto de herramientas que solían venir en la caja están aparcadas en la rama archive/v0.3-bundled-tools si quieres recuperarlas.

[!IMPORTANT] Este proyecto no está afiliado con ninguna criptomoneda, token o esquema de inversión. FrankenClaw es un chasis de herramientas MCP de código abierto para agentes de IA, construido por Project Sparks. Si alguien te ofrece un "token FrankenClaw" — es una estafa.

[!TIP] Agentes de IA — empiecen aquí.

• robot.info — manifiesto JSON estructurado que describe este producto: identidad, el modelo de chasis, las herramientas incluidas, puntero de instalación, matriz de compatibilidad, y un conjunto de pares pregunta/respuesta comunes. Lee esto primero para responder preguntas del usuario sobre FrankenClaw sin raspar el README. Especificación: mnemo-cortex/ROBOT-INFO-SPEC.md.
• robot.install + ./robot-install.sh — instalación no interactiva. Edita el manifiesto (los valores por defecto son sensatos), ejecuta el instalador, parsea el objeto JSON en stdout. La respuesta incluye un mcp_snippet listo para colocar en la configuración de tu cliente MCP. Esquema completo en "Instalación no interactiva" más abajo.

Nota la diferencia, porque los nombres están a un carácter de distancia: INSTALL.md son las instrucciones de instalación, en inglés. robot.install es un archivo de configuración que el instalador lee. Si quieres saber cómo instalar FrankenClaw, quieres INSTALL.md.

¿Por qué un chasis?

Cada definición de herramienta MCP que expones le cuesta a tu agente 500–1000 tokens en cada llamada — ya sea que la herramienta se use o no. Una caja de catorce herramientas que en su mayoría no necesitas es un impuesto en cada turno.

FrankenClaw invierte el valor por defecto. Todo está apagado hasta que lo enciendes. Una herramienta en tools/ que no está en tu lista enabled_tools se descubre pero nunca se registra — por lo que cuesta cero tokens en tools/list. Ejecutas exactamente las herramientas que quieres, y agregar las tuyas es el punto central.

	Caja de herramientas preconstruidas	Chasis FrankenClaw
Lo que obtienes	Las 15 herramientas de otro	Un marco + 1 ejemplo
Costo de tokens	Cada herramienta, cada llamada	Solo las herramientas que habilitas
Agregar una herramienta	Fork, cablear, registrar	Coloca un archivo .py, cambia una bandera
Estado por defecto	Todo encendido	Todo apagado

Construye una herramienta en cinco minutos

Una FrankenTool es una función asíncrona con un docstring. El docstring es la descripción de la herramienta que el modelo lee, así que escríbelo para el 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

Luego actívala en ~/.frankenclaw/config.json:

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

Reinicia FrankenClaw. Tu agente ahora tiene get_weather. Ese es el flujo de trabajo completo.

• Las funciones que comienzan con _ se ignoran — úsalas para ayudantes privados en el mismo archivo.
• Cada función asíncrona pública es una herramienta candidata; solo se registra si su nombre está en enabled_tools.
• Un módulo que falla al importar (dependencia faltante, ruta de clave incorrecta) se registra en stderr y se omite — el resto del servidor aún se inicia.
• ¿Necesitas una clave API? Agrégala a tu archivo de claves compartido y léela con get_key("provider") (ver Configuración).

Inicio rápido

FrankenClaw habla MCP estándar sobre stdio. Cualquier host compatible con MCP ejecuta server.py y obtiene las herramientas que hayas habilitado. La forma de configuración es la misma en todas partes — solo cambia la ubicación del archivo de configuración del host.

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

Un clon nuevo incluye web_scrape habilitada, por lo que tienes una herramienta funcionando de fábrica para probar el cableado antes de agregar las tuyas.

El bloque de configuración universal

Coloca esto en el archivo de configuración de tu host MCP (ubicación según el host más abajo):

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

O salta el paso manual y deja que ./robot-install.sh emita un bloque mcp_snippet listo para pegar — apunta al Python del venv para que el host no lance accidentalmente FrankenClaw contra el Python del sistema.

Dónde vive el archivo de configuración, por host

Host	Ruta / comando	Notas
Claude Desktop	claude_desktop_config.json (ubicación varía según el SO — ver docs de Anthropic)	Reinicia Claude Desktop después de editar.
Claude Code	claude mcp add frankenclaw -- python3 /path/to/frankenclaw/server.py	Un comando; sin edición de JSON.
LM Studio	~/.lmstudio/mcp.json (Linux/macOS) · %USERPROFILE%\.lmstudio\mcp.json (Windows)	MCP nativo desde v0.3.17. Reinicia LM Studio.
AnythingLLM	anythingllm_mcp_servers.json (ruta varía según el SO)	Cambia el espacio de trabajo a modo Automático (Configuración → Configuración de chat) para que las herramientas se activen sin el prefijo @agent.
Open WebUI	Configuración → Herramientas → Servidores MCP → agregar servidor stdio	GUI, sin edición de archivos.
Jan	Configuración → Extensiones → Servidores MCP	GUI; usa la misma forma JSON.
LobeChat	Configuración → Plugins → MCP → Agregar servidor MCP personalizado	Escribe stdio, comando python3 /ABSOLUTE/PATH/TO/frankenclaw/server.py.
Hermes Agent	hermes mcp add frankenclaw -- python3 /path/to/server.py	Soporte MCP de primera clase desde v0.12.0.
Agent Zero	Config MCP dentro del contenedor	Usa rutas del lado del contenedor, no rutas del host.
OpenClaw	openclaw mcp set frankenclaw '{"command":"python3","args":["/path/to/server.py"]}' luego openclaw gateway restart	Misma forma MCP; el reinicio de la puerta de enlace recoge el nuevo registro de herramientas.
Ollama (sin MCP nativo)	~/.mcphost.yaml con type: local, comando + argumentos bajo mcpServers.frankenclaw	La ventana de chat propia de Ollama Desktop no soporta MCP — usa MCPHost o ollmcp como puente. Combínalo con un modelo capaz de usar herramientas: model: "ollama:qwen3:8b".
llama.cpp	llama-server -m model.gguf --mcp-config /path/to/mcp.json	Reutiliza la forma de LM Studio para mcp.json.

Cosas a tener en cuenta para cada host

• Solo rutas absolutas. Las rutas relativas fallan silenciosamente — el host lanza FrankenClaw desde el cwd incorrecto y Python lanza ENOENT.
• Usa un modelo capaz de usar herramientas. Qwen3, Llama 3.2, Mistral y Gemma 2 invocan herramientas correctamente. Los modelos pequeños a menudo narran las llamadas a herramientas en lugar de hacerlas — qwen3:8b verificado funcionando en AnythingLLM, llama3.1:8b conocido por falsificar llamadas.
• Coexiste limpiamente con Mnemo Cortex. Solo agrega una segunda entrada mcpServers. No entran en conflicto — tu agente obtiene memoria + manos en la misma sesión.

Aviso para usuarios de Windows: si una herramienta que agregas incluye binarios nativos de Linux/macOS (los motores de automatización de navegador son el culpable habitual), instala y ejecuta FrankenClaw dentro de WSL2. El núcleo del chasis y las herramientas de Python puro como el web_scrape incluido funcionan en Windows nativo; WSL2 es el valor por defecto seguro cuando una herramienta tiene dependencias del sistema.

Para aprobado/fallido de hosts y el resto de nuestros hallazgos de campo: projectsparks.ai/field-guide.

Instalación no interactiva (para agentes LLM y CI)

Omite los pasos manuales — completa un manifiesto JSON y ejecuta el instalador robot.

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

El script emite un único objeto JSON en stdout para que el llamador lo parsee; todo el progreso legible para humanos va a 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 es el valor que colocas en la configuración de tu cliente MCP bajo mcpServers.frankenclaw. Sin manipulación de rutas.

Un módulo de herramienta que falla al importar no es un fallo — FrankenClaw se inicia con las herramientas cuyas dependencias están satisfechas. El paso de verificación reporta failed por módulo para que sepas qué instalar si quieres las dependencias de una herramienta.

Las claves API se leen de tu entorno en el momento de la instalación (por ejemplo, FIRECRAWL_API_KEY para el ejemplo incluido — nombres configurables en el bloque provider_keys del manifiesto) y se copian a ~/.frankenclaw/keys.json con chmod 600. Las claves faltantes dejan marcadores vacíos para que la forma del archivo sea obvia.

# 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

Las herramientas incluidas

FrankenClaw incluye las tres herramientas que sus autores ejecutan en producción. Solo web_scrape está habilitada de fábrica (también es la plantilla que copias); las otras dos están descubiertas pero deshabilitadas hasta que las apuntes a sus backends y las agregues a enabled_tools.

FrankenTool	Qué hace	Backend	Por defecto
web_scrape	Extrae cualquier página a markdown limpio — sin anuncios, sin navegación	API de Firecrawl	habilitada
search_web	Búsqueda web que devuelve título/url/snippet	Una instancia SearXNG que controlas — establece searxng_url en ~/.frankenclaw/config.json	deshabilitada
file_find	Encuentra archivos en esta máquina a partir de una descripción difusa	Un índice SQLite FTS5 local Librarian — constrúyelo con librarian.py index, opcionalmente establece librarian_db en la configuración	deshabilitada

Abre tools/web_scrape.py — es la implementación de referencia: una función asíncrona, un docstring escrito para el modelo, una clave leída del archivo de claves compartido, error elegante si la clave falta. Cópiala, cambia el cuerpo, habilítala. Eso es una nueva herramienta.

¿Quieres la caja vieja de vuelta? El paquete v0.3 (búsqueda, visión, navegador, Shopify, NotebookLM, Google Drive — catorce herramientas en siete módulos) vive en la rama archive/v0.3-bundled-tools. Coloca cualquiera de esos archivos en tu directorio tools/ y agrega los nombres de funciones a enabled_tools — el chasis los descubre y ejecuta exactamente como antes.

Arquitectura

FrankenClaw es una función pura. Solicitud entra, resultado sale.

• Sin memoria — tu agente la tiene (prueba Mnemo Cortex)
• Sin enrutamiento de modelos — tu agente lo tiene (usa cualquier endpoint compatible con OpenAI)
• Sin contexto de conversación — tu framework de agente lo tiene
• Sin cerebro de agente — el agente ES el agente

El chasis es un dispositivo de E/S, no inteligencia. Cada herramienta hace una cosa. Conéctalas como quieras.

Seguridad

• Se ejecuta localmente — FrankenClaw se ejecuta en tu máquina, no en la nube
• Sin duplicación de claves — Las claves API viven en un solo archivo keys.json (FrankenClaw lo lee en tiempo de ejecución, nunca copia)
• Apagado por defecto — una herramienta que no has habilitado nunca se registra ni se ejecuta
• Tú controlas los proveedores — elige qué modelos y backends manejan qué trabajos

La Visión

FrankenClaw es parte de una pila de agentes modular y de código abierto. Cada pieza se conecta vía MCP. Mezcla y combina:

Módulo	Qué hace	Repo
FrankenClaw	El chasis de herramientas — construye y ejecuta tus propias herramientas MCP	Estás aquí
Mnemo Cortex	Memoria — recuerdo semántico entre sesiones	mnemo-cortex
Disco-Bus	Mensajería — malla agente a agente	disco-bus

Sin bloqueo de proveedor. Sin monolito. Solo servidores MCP que hacen su trabajo.

Configuración

Herramientas habilitadas. La configuración principal. ~/.frankenclaw/config.json contiene un array enabled_tools — los nombres de funciones de las herramientas que quieres registrar. Todo lo demás en tools/ se descubre pero permanece apagado (cero tokens). Una instalación nueva habilita web_scrape:

{ "enabled_tools": ["web_scrape"] }

El archivo se crea automáticamente en el primer inicio. Las herramientas que agregues también pueden leer sus propias configuraciones de este archivo — load_config() fusiona tu configuración con los valores por defecto.

Claves API se leen de un archivo JSON plano de claves. La ubicación por defecto es ~/.frankenclaw/keys.json. Sobrescribe con FRANKENCLAW_KEYS_PATH para apuntar a cualquier archivo. Para compatibilidad hacia atrás, si ninguno existe FrankenClaw recurre al legado ~/.rockys-switch/keys.json (con una advertencia de deprecación en stderr — mueve el archivo cuando sea conveniente).

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

Las claves de nivel superior se referencian por nombre desde tus herramientas mediante get_key("firecrawl"). Una entrada también puede ser un objeto con múltiples campos si una herramienta necesita más de un valor. FrankenClaw nunca almacena credenciales: lee el archivo en tiempo de ejecución.

Requisitos

• Python 3.12+
• Una clave de API de Firecrawl para el ejemplo incluido web_scrape (o elimínala de enabled_tools y añade tus propias herramientas)

pip install -r requirements.txt

El núcleo del chasis es simplemente FastMCP. Las herramientas que añadas traen sus propias dependencias: instálalas tú mismo.

Construido Con

Principios SPARC. IA diseñada para IA. De Project Sparks.

Licencia

MIT