VoidLang

VoidLang - Código Máquina Nativo para LLM MCP

Documentación

VoidLang MCP

Un lenguaje de estilo bytecode diseñado para LLMs. El modelo escribe opcodes numéricos como JSON, el servidor devuelve un binario funcional, una app React, un scaffold de iOS / Android, o un docker-compose.yml. Sin sintaxis. Sin parsing. Sin desperdicio de tokens en puntuación.

┌──────────────────────────────────────────────────────────────────────┐
│  LLM  ──[opcode JSON]──▶  voidmcp  ──▶  Go / React / Swift / Kotlin  │
│                                  │                                   │
│                                  └──▶  go build / npm build          │
│                                                                      │
│                                  ──▶  artifact URL (binary / zip)    │
└──────────────────────────────────────────────────────────────────────┘

9 objetivos de compilación: linux, macos, windows, ios, android, web, pwa, wasm, docker.
~160 opcodes que cubren HTTP, SQL, Redis, JWT, bcrypt, interfaz web, interfaz móvil, E/S de archivos y topología Docker.
El endpoint ISA de una sola llamada devuelve el conjunto completo de instrucciones en una sola llamada — sin descubrimiento de esquema por llamada.
Dos transportes: HTTP (cualquier LLM, cualquier IDE, cualquier agente) y MCP stdio JSON-RPC (Claude Desktop / Claude Code).
Nivel de producción: servidor solo con stdlib, Dockerfile multi-etapa, healthcheck, listo para Railway.

Por qué existe esto

Los LLMs son terribles escribiendo sintaxis válida en un lenguaje nuevo, pero son excelentes generando arrays JSON. VoidLang invierte el contrato: el lenguaje es un array JSON de pares [opcode, args…]. El compilador hace todo el trabajo — formato, imports, manejo de errores, topología de despliegue — así que el modelo solo tiene que expresar intención, no código repetitivo.

Una API web que habla con Postgres, autentica con JWT, tiene CRUD en dos tablas y se despliega con Docker compose, cabe en ~80 instrucciones. Una versión escrita a mano en Go de la misma app es ~1500 líneas.

Inicio rápido

Ejecuta el servidor localmente

make build && ./build/voidmcp --addr :7070

o sin instalar:

make dev

Abre http://localhost:7070 para la página de inicio, o golpea cualquier endpoint:

curl -s http://localhost:7070/isa | jq '.opcodes | length'
# → ~95

Compila tu primer archivo void

curl -sX POST http://localhost:7070/compile \
  -H 'Content-Type: application/json' \
  -d '{"void": {
    "v": 1,
    "name": "hello",
    "tgt": ["linux"],
    "ins": [
      [1, "hello"],
      [3, "linux"],
      [242, "Hello from VoidLang!"]
    ]
  }}' | jq .

La respuesta contiene el código fuente Go generado, un go.mod, y (si go está en el PATH del servidor) una URL para descargar el binario compilado.

O ejecútalo como servidor MCP de Claude Desktop / Claude Code

Añade a ~/.config/claude/claude_desktop_config.json (o equivalente):

{
  "mcpServers": {
    "voidlang": {
      "command": "/absolute/path/to/build/voidmcp",
      "args": ["stdio"]
    }
  }
}

Claude verá cuatro herramientas: isa, isa_quick, targets, compile.

Endpoints

Método	Ruta	Qué hace
GET	`/`	Página de inicio (útil para verificar un despliegue).
GET	`/isa`	ISA completo — dale esto una vez a cualquier LLM.
GET	`/isa/quick`	ISA condensado de ~2k tokens.
GET	`/targets`	Objetivos de compilación disponibles.
POST	`/compile`	`{void, target?, name?}` → artefactos.
POST	`/run`	Compilar + ejecutar localmente (opt-in, ver abajo).
GET	`/artifacts/{id}`	Descargar un blob binario previamente compilado.
GET	`/health`	Informe de liveness + capacidades de toolchain.
GET	`/mcp`	Manifiesto ligero de herramientas.

`POST /compile`

// request
{
  "void":   { "v": 1, "name": "todo_api", "tgt": ["linux", "docker"], "ins": [/*…*/] },
  "target": "linux",     // optional override
  "name":   "todo_api"   // optional override
}

// response
{
  "ok": true,
  "app": "todo_api",
  "targets": [
    {
      "target": "linux",
      "kind":   "binary",
      "binary_size": 9482240,
      "download_url": "http://localhost:7070/artifacts/3f6a2b1c8e9d4f70",
      "files": { "main.go": "…", "go.mod": "…" }
    },
    {
      "target": "docker-compose",
      "kind":   "text",
      "files": { "docker-compose.yml": "…", ".env.example": "…", "Dockerfile": "…" }
    }
  ]
}

`POST /run`

Deshabilitado por defecto. Establece VOIDMCP_ALLOW_RUN=1 en el servidor para habilitarlo. El servidor compilará y ejecutará el binario generado, devolviendo stdout/stderr/código de salida. No habilites esto en un despliegue público de Railway — úsalo solo en un sandbox donde ejecutar código arbitrario sea seguro.

Despliegue en Railway

El repositorio incluye un Dockerfile, un railway.json y un nixpacks.toml como respaldo. Para desplegar:

# install the Railway CLI once
npm i -g @railway/cli
railway login

# inside this repo
railway init                      # pick "Empty Project"
railway up                        # builds + deploys the Dockerfile
railway domain                    # mint a public URL

La ruta de healthcheck (/health) está conectada a través de railway.json, así que Railway fallará rápido si el servidor no puede arrancar.

Después del despliegue:

curl https://your-app.up.railway.app/isa | jq '.opcodes | length'

Variables de entorno

Var	Default	Significado
`PORT`	`7070`	Puerto HTTP (Railway lo establece automáticamente).
`VOIDMCP_ALLOW_RUN`	sin establecer	Establece a `1` para habilitar `POST /run`. No habilitar en producción.
`VOIDMCP_PUBLIC_BASE`	autodetectado	Sobrescribe la URL base incrustada en `download_url`.

Ganchos de monetización

El repositorio tiene licencia MIT, así que eres libre de desplegarlo como SaaS de pago. Un patrón común:

Pon una puerta de enlace API (por ejemplo, Kong, Cloudflare Workers, o un pequeño servicio proxy) delante de voidmcp. Autentica por clave API. Mide las llamadas /compile por clave.
Cobra por compilación o por mes por agente LLM. La base de coste es el ~50–500 ms de CPU que usa cada llamada; valora el valor de salida (un binario funcional), no el tiempo de CPU.
Opcional: limita la tasa de /compile con una ventana deslizante respaldada por Redis (el ISA expone los opcodes que necesitarías para construir esto en VoidLang mismo, recursivamente).
Idea para el nivel gratuito: /isa, /isa/quick, /targets son de solo lectura y baratos — déjalos sin autenticar para maximizar la adopción por parte de los modelos.

Cómo lo usa un LLM

El bucle esperado es:

Una vez por sesión: GET /isa — carga el conjunto completo de instrucciones en el contexto del modelo. ~30k tokens. (O GET /isa/quick para ~2k.)
Por cada solicitud del usuario: emite un archivo void como objeto JSON, envíalo a POST /compile. Transmite la respuesta de vuelta al usuario con un enlace de descarga.
Refinamiento opcional: si el LLM cometió un error, el servidor devuelve build_log con el diagnóstico del compilador de Go. Aliméntalo de vuelta al LLM y pídele un array de instrucciones corregido.

Una plantilla completa de prompt de sistema está en docs/LLM_PROMPT.md.

Ejemplos

examples/hello.void — Hello World mínimo.
examples/todo_api.void — API CRUD completa con Postgres + autenticación JWT + docker-compose.

Arquitectura

voidLang/
├── cmd/voidmcp/            main entrypoint (HTTP + stdio mode)
├── internal/
│   ├── isa/                opcode definitions + metadata
│   ├── void/               .void file decoder
│   ├── codegen/
│   │   ├── golang/         Go backend (linux/macos/windows/docker/wasm seed)
│   │   ├── web/            React + Vite project generator
│   │   ├── mobile/         iOS (SwiftUI) + Android (Compose) scaffolds
│   │   ├── wasm/           WebAssembly build helper
│   │   └── docker/         docker-compose.yml generator
│   └── mcp/                HTTP server + stdio JSON-RPC transport
├── examples/               sample .void files
├── docs/                   ISA reference, deployment, LLM prompt template
├── Dockerfile              multi-stage build for production
├── railway.json            Railway deploy config
├── nixpacks.toml           Railway nixpacks fallback
├── Makefile                build / run / docker helpers
└── go.mod                  stdlib-only (no external deps)

El servidor tiene cero dependencias externas de Go. Los programas generados sí dependen de gin, pgx, go-redis, golang-jwt y x/crypto — esos se descargan en la primera compilación y se cachean.

Desarrollo

make dev        # run via `go run` (no install)
make stdio      # run MCP stdio mode
make test       # run unit tests
make fmt        # gofmt
make docker-run # full Dockerised cycle

El servidor en sí no tiene estado aparte de una caché en memoria de 30 minutos de artefactos compilados (para que los enlaces /artifacts/{id} no expiren demasiado rápido). Reinicia y listo.

Documentación

docs/ISA.md — referencia opcode por opcode.
docs/LLM_PROMPT.md — prompt de sistema listo para usar en cualquier LLM.
docs/DEPLOY.md — notas de despliegue en Railway / Fly / VM desnuda.

Licencia

MIT — un producto de voidback. Úsalo, hazle fork, despliégalo, cobra por él, reescríbelo en un lenguaje que nunca hayamos oído. voidback existe para avanzar la era de la IA agéntica de forma abierta. Por favor, contribuye, juega con ello y sigue avanzando. No hay límite. Ni siquiera AGI.