VoidLang

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

Documentação

VoidLang MCP

Uma linguagem em estilo bytecode projetada para LLMs. O modelo escreve opcodes numéricos como JSON, o servidor retorna um binário funcional, um app React, um scaffold iOS / Android, ou um docker-compose.yml. Sem sintaxe. Sem parsing. Sem desperdício de tokens com pontuação.

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

9 alvos de compilação: linux, macos, windows, ios, android, web, pwa, wasm, docker.
~160 opcodes cobrindo HTTP, SQL, Redis, JWT, bcrypt, UI web, UI mobile, E/S de arquivos e topologia Docker.
Endpoint ISA de uma chamada retorna o conjunto completo de instruções em uma única chamada — sem descoberta de esquema por chamada.
Dois transportes: HTTP (qualquer LLM, qualquer IDE, qualquer agente) e MCP stdio JSON-RPC (Claude Desktop / Claude Code).
Nível de produção: servidor apenas com stdlib, Dockerfile multi-estágio, healthcheck, pronto para Railway.

Por que isso existe

LLMs são péssimos em escrever sintaxe válida em uma linguagem nova, mas são excelentes em gerar arrays JSON. VoidLang inverte o contrato: a linguagem é um array JSON de pares [opcode, args…]. O compilador faz todo o trabalho — formatação, imports, tratamento de erros, topologia de deploy — então o modelo só precisa expressar intenção, não código repetitivo.

Uma API web que fala com Postgres, autentica com JWT, tem CRUD em duas tabelas e faz deploy para Docker compose cabe em ~80 instruções. Uma versão equivalente em Go escrita à mão tem ~1500 linhas.

Início rápido

Execute o servidor localmente

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

ou sem instalar:

make dev

Abra http://localhost:7070 para a página inicial, ou acesse qualquer endpoint:

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

Compile seu primeiro arquivo 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 .

A resposta contém o código-fonte Go gerado, um go.mod e (se go estiver no PATH do servidor) uma URL para baixar o binário compilado.

Ou execute como um servidor MCP do Claude Desktop / Claude Code

Adicione ao ~/.config/claude/claude_desktop_config.json (ou equivalente):

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

O Claude verá quatro ferramentas: isa, isa_quick, targets, compile.

Endpoints

Método	Caminho	O que faz
GET	`/`	Página inicial (útil para verificar um deploy).
GET	`/isa`	ISA completo — forneça isso uma vez a qualquer LLM.
GET	`/isa/quick`	ISA condensado de ~2k tokens.
GET	`/targets`	Alvos de compilação disponíveis.
POST	`/compile`	`{void, target?, name?}` → artefatos.
POST	`/run`	Compilar + executar localmente (opt-in, veja abaixo).
GET	`/artifacts/{id}`	Baixar um blob binário previamente compilado.
GET	`/health`	Relatório de liveness + capacidade da toolchain.
GET	`/mcp`	Manifesto leve de ferramentas.

`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`

Desabilitado por padrão. Defina VOIDMCP_ALLOW_RUN=1 no servidor para habilitar. O servidor compilará e executará o binário gerado, retornando stdout/stderr/código de saída. Não habilite isso em um deploy público no Railway — use apenas em um sandbox onde executar código arbitrário seja seguro.

Deploy no Railway

O repositório inclui um Dockerfile, um railway.json e um nixpacks.toml como fallback. Para fazer deploy:

# 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

O caminho do healthcheck (/health) está conectado via railway.json, então o Railway falhará rapidamente se o servidor não conseguir iniciar.

Após o deploy:

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

Variáveis de ambiente

Variável	Padrão	Significado
`PORT`	`7070`	Porta HTTP (o Railway define isso automaticamente).
`VOIDMCP_ALLOW_RUN`	não definido	Defina como `1` para habilitar `POST /run`. Não habilite em produção.
`VOIDMCP_PUBLIC_BASE`	autodetectado	Substitui a URL base incorporada em `download_url`.

Ganchos de monetização

O repositório é licenciado sob MIT, então você é livre para implantá-lo como SaaS pago. Um padrão comum:

Coloque um gateway de API (ex.: Kong, Cloudflare Workers ou um serviço de proxy pequeno) na frente de voidmcp. Autentique por chave de API. Meça chamadas de /compile por chave.
Cobre por compilação ou por mês por agente LLM. A base de custo é os ~50–500 ms de CPU que cada chamada usa; precifique o valor da saída (um binário funcional), não o tempo de CPU.
Opcional: limite de taxa para /compile com uma janela deslizante baseada em Redis (a ISA expõe os opcodes que você precisaria para construir isso no próprio VoidLang, recursivamente).
Ideia para nível gratuito: /isa, /isa/quick, /targets são somente leitura e baratos — deixe-os sem autenticação para maximizar a adoção pelo modelo.

Como um LLM usa isso

O fluxo esperado é:

Uma vez por sessão: GET /isa — carregue o conjunto completo de instruções no contexto do modelo. ~30k tokens. (Ou GET /isa/quick para ~2k.)
Para cada solicitação do usuário: emita um arquivo void como objeto JSON, envie para POST /compile. Transmita a resposta de volta ao usuário com um link de download.
Refinamento opcional: se o LLM cometer um erro, o servidor retorna build_log com o diagnóstico do compilador Go. Alimente isso de volta ao LLM e peça um array de instruções corrigido.

Um modelo completo de prompt de sistema está em docs/LLM_PROMPT.md.

Exemplos

examples/hello.void — Hello World mínimo.
examples/todo_api.void — API CRUD completa com Postgres + autenticação JWT + docker-compose.

Arquitetura

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)

O servidor tem zero dependências Go externas. Os programas gerados dependem de gin, pgx, go-redis, golang-jwt e x/crypto — eles são baixados na primeira compilação e armazenados em cache.

Desenvolvimento

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

O servidor em si não tem estado, exceto por um cache em memória de 30 minutos dos artefatos compilados (para que os links /artifacts/{id} não expirem rápido demais). Reinicie e pronto.

Documentação

docs/ISA.md — referência opcode por opcode.
docs/LLM_PROMPT.md — prompt de sistema pronto para qualquer LLM.
docs/DEPLOY.md — notas de deploy no Railway / Fly / VM bare-metal.

Licença

MIT — um produto da voidback. Use, faça fork, faça deploy, cobre por isso, reescreva em uma linguagem que nunca ouvimos falar. A voidback existe para avançar a era da IA agêntica de forma aberta. Por favor, contribua, brinque e continue avançando. Não há limites. Nem mesmo AGI.