⌨️ HumanCode MCP

Watch AI program like a human. OpenCode / Claude Code / Codex → MCP Server → VS Code Extension → real Editor API. Open, type, run, fix — all visible on screen.

User: "Create a login page."

HumanCode:
  Opening src/pages/Login.tsx ...
  Typing ................... 184 chars
  Running npm test ...
  2 errors detected.
  Opening src/components/Input.tsx ...
  Fixing ............
  Tests passed ✓

No mouse-coordinate hacks. No fake animations. Every keystroke is a real progressive edit through the VS Code API. The goal is not to fool anyone — it's observability: supervision, demos, education, recordings, debugging agents.

Architecture

flowchart LR
    Client["MCP Client<br/>(OpenCode / Claude / Codex)"] -- "stdio :: vscode_* tools" --> Server["@humancode/mcp-server<br/>(MCP SDK + WS bridge)"]
    Server -- "ws://127.0.0.1:38475<br/>hello / request / event / ping" --> Ext["humancode-vscode<br/>(VS Code Extension)"]
    Ext -- "Editor API<br/>(window, workspace, Terminal)" --> IDE["Your open project<br/>(what you see on screen)"]

MCP Client (OpenCode / Claude / Codex)
   │  stdio :: MCP tools (vscode_*)
   ▼
@humancode/mcp-server  (Node, MCP SDK oficial)
   │  WebSocket ws://127.0.0.1:38475 :: hello/welcome, request/response, events, ping/pong
   ▼
humancode-vscode  (VS Code Extension)
   │  VS Code Editor API (window, workspace, languages, Terminal)
   ▼
Projeto aberto no VS Code (o que você vê na tela)

• Transport: WebSocket localhost. Server escuta, extensões discam. Token de sessão (HUMANCODE_TOKEN), binding padrão 127.0.0.1, handshake com protocolVersion antes de qualquer tool.

• Protocolo compartilhado: packages/shared (@humancode/shared) — BridgeRequest/Response/Event, zod schemas, ErrorCode, TypingConfig. Server e extensão importam do mesmo lugar; nada duplicado.

• Fila: ActionQueue (idle/running/paused/cancelled/failed) serializa edições — mutex do editor + Pause/Resume/Stop.

• Typing: HumanTypingEngine com presets instant/fast/natural/human/presentation/custom, jitter de delay, pausas contextuais (; , ) } newline), typo simulation opcional (default 0), chunk 1–4 chars por edit (barato mas visível), guard contra auto-closing duplicado.

• Terminal: sempre o integrado real. Leitura via onDidWriteTerminalData + shell-integration fallback (documentado no código — a API padrão não expõe buffer PTY).

• Multi-window: cada extensão tem instanceId; vscode_list_instances / vscode_select_instance.

Related MCP server: vscode-helper

Monorepo

human-code-mcp/
├── packages/shared/          # protocolo, tipos, schemas zod
├── apps/mcp-server/          # MCP stdio + bridge WS + 25+ tools + security
├── apps/vscode-extension/    # editor/typing/terminal/diagnostics/queue/ui
├── tests/                    # typing, queue, protocolo (node:test, determinísticos)
├── examples/opencode|claude-code|codex/

Install & build

npm install
npm run build:shared
npm run build:server
npm run build:extension   # requer VS Code types; saída em apps/vscode-extension/out
npm test                  # ver "Testing" abaixo

Pré-requisitos: Node >= 18, VS Code >= 1.85.

Run

# 1. MCP server (stdio; o bridge WS sobe junto)
HUMANCODE_PORT=38475 HUMANCODE_HOST=127.0.0.1 HUMANCODE_TOKEN=sua-senha \
  node apps/mcp-server/dist/index.js

# 2. Extensão: abra apps/vscode-extension no VS Code, F5 (Extension Development Host),
#    ou `npx vsce package` + instalar o .vsix. Configure:
#    humanCode.bridge.port = 38475, humanCode.bridge.token = sua-senha

MCP client config

OpenCode (opencode.json): ver examples/opencode/ — formato real mcp + type: local.

Claude Code (.mcp.json ou claude mcp add): ver examples/claude-code/.

Codex (~/.codex/config.toml [mcp_servers.humancode]): ver examples/codex/.

Tools (28)

Resources: workspace://status, workspace://diagnostics, workspace://active-file. Prompt: human-code-development (workflow observar→editar→salvar→diagnosticar→testar→corrigir).

Modes & settings

• humanCode.mode: fast (direto) · human (tudo animado) · hybrid (anima ≤ hybrid.maxAnimatedCharacters, default 300).

• humanCode.typing.preset: instant/fast/natural/human/presentation/custom + delays, typoChance (default 0).

• humanCode.followEditor (default true), humanCode.focusLock (true), humanCode.confirmTerminalCommands (never/dangerous/always), humanCode.previewChanges.

• Status bar: Connected/Typing/Paused/Disconnected → abre o Control Panel (webview com Pause/Resume/Stop).

• Command Palette: HumanCode: Connect/Disconnect/Pause/Resume/Stop/Open Control Panel/Change Mode/Change Typing Speed.

Suggested agent system prompt

You are controlling VS Code through HumanCode MCP.

When editing code:
1. Inspect the current workspace (vscode_get_status, vscode_list_files).
2. Read relevant files (vscode_read_file / vscode_get_active_file).
3. Open the file being changed (vscode_open_file) so the user can watch.
4. Apply changes through HumanCode tools: vscode_type_text for small visible
   edits; vscode_replace_range (animate=true) for surgical fixes; create_file
   for new files. Prefer targeted modifications over whole-file rewrites.
5. Keep edits observable in Human/Hybrid mode — one logical change at a time.
6. Save after meaningful changes (vscode_save).
7. Inspect diagnostics (vscode_get_diagnostics / vscode_get_problems).
8. Run relevant tests in the integrated terminal (vscode_terminal_run with
   waitForCompletion) and read output (vscode_terminal_read).
9. On failure, vscode_reveal_problem, fix visibly, re-run. Fix issues before finishing.

Never run destructive shell commands without explicit user confirmation.

Testing

# unit/deterministic (typing com Clock+Random injetados, queue, protocolo):
npx tsx --test tests/*.test.ts

Troubleshooting

Security

Loopback-only por padrão (warning se bind não-local), token de sessão, allowlist de execute_command, política de confirmação de comandos destrutivos (rm -rf, del /s, format, shutdown, git reset --hard...), sem any indiscriminado, schemas zod em toda borda.

Limitations (honest)

• Leitura de buffer PTY não existe na API estável → stream capture + shell-integration fallback.

• vscode.executeCommand allowlist é conservadora; amplie em editorController.executeCommand se precisar.

• Typing muito rápido (< 4ms/char) agrupa em chunks — ainda são edits reais.