# ⌨️ HumanCode MCP

[![CI](https://github.com/Ryanabcraft/human-code-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Ryanabcraft/human-code-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![VS Code](https://img.shields.io/badge/VS%20Code-%5E1.85-blue)](https://code.visualstudio.com/)
[![Node](https://img.shields.io/badge/Node-%3E%3D18-green)](https://nodejs.org/)

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

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

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

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

```bash
# 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)

| Tool | O que faz |
|---|---|
| `vscode_get_status` | conexão, workspace, arquivo ativo, cursor, abas, terminal, fila |
| `vscode_list_instances` / `vscode_select_instance` | multi-window |
| `vscode_open_file` | abre (linha/coluna, preview) |
| `vscode_create_file` / `vscode_create_directory` | cria |
| `vscode_type_text` | **digitação visível** (preset, cps, delays, typoChance) |
| `vscode_replace_range` | substitui, com `animate` |
| `vscode_select_range` | seleciona visualmente |
| `vscode_delete` | backspace/delete/line/selection/range |
| `vscode_move_cursor` | move cursor |
| `vscode_save` / `vscode_save_all` | salva |
| `vscode_get_active_file` | path+conteúdo+cursor+seleção+dirty |
| `vscode_read_file` | inteiro ou por linhas, com cap |
| `vscode_list_files` | glob/ignore/maxDepth |
| `vscode_search` | texto + contexto |
| `vscode_terminal_create` / `vscode_terminal_run` / `vscode_terminal_read` / `vscode_terminal_interrupt` | terminal integrado real |
| `vscode_get_diagnostics` / `vscode_get_problems` / `vscode_reveal_problem` | erros TS/ESLint/etc |
| `vscode_format_document` / `vscode_rename_symbol` / `vscode_go_to_definition` / `vscode_find_references` / `vscode_execute_command` | linguagem |
| `vscode_pause` / `vscode_resume` / `vscode_stop` | controle da fila |

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

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

## Troubleshooting

| Sintoma | Causa provável |
|---|---|
| `EXTENSION_NOT_CONNECTED` | extensão não conectada; confira porta/token e o OutputChannel "HumanCode" |
| `PROTOCOL_MISMATCH` | versões diferentes de server/extensão; rebuild ambos |
| `UNAUTHORIZED` | `HUMANCODE_TOKEN` ≠ `humanCode.bridge.token` |
| Terminal `read` vazio | `onDidWriteTerminalData` indisponível no build; use `waitForCompletion: true` |
| Digitação duplicando `)` | auto-closing; a engine já faz skip-over, reporte o caso |

## 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.