# Green MCP Toolbox

A single deterministic MCP toolbox shared by multiple LLMs. Bun-first, Docker-isolated, observable, self-diagnosing.

## What it solves

Instead of every LLM installing its own jq, rg, fd, Git, Python, browser stack and MCP wrappers into the Windows PATH, clients connect to one MCP endpoint:

- MCP: `http://127.0.0.1:9400/mcp`
- Dashboard: `http://127.0.0.1:9400`
- VictoriaLogs: `http://127.0.0.1:9428`
- Playwright MCP upstream: `http://127.0.0.1:8931/mcp`
- Chrome CDP: first free loopback port at or after `9301`

## Included

- Bun 1.4.2 runtime
- jq, ripgrep, fd, Git, curl, Python 3
- MCP TypeScript SDK 2.0.0
- Official Sequential Thinking MCP 2026.8.31
- Official Microsoft Playwright MCP + headless Chromium/CDP
- VictoriaLogs 1.52.0
- Auto-Doctor for missing tools, ENOENT, version drift, duplicate PATH targets, dead services and MCP failures
- Mathematical router using capability match + observed success + latency + health + cost
- Mermaid architecture + live Kanban + recent evidence

## Router decision

A deterministic daemon is the default router. It is faster, measurable and cannot hallucinate tool names. A tiny ~1B local model through PAIR remains optional only for ambiguous natural-language classification. n8n is also optional, not required for core routing.

## Start

```bash
bun install --frozen-lockfile
bun run up
```

`bun run up` stops this stack, selects the first free CDP port >=9301, records it in ignored `.runtime.env`, then starts the stack.

## Validate

```bash
bun run ci
bun src/smoke.ts
bun src/browser-smoke.ts
```

The dashboard Auto-Doctor must report all checks GREEN before the stack is considered healthy.

## Shell policy

- Windows interactive: PowerShell 7
- Linux: `wsl.exe` -> Ubuntu 26
- Git Bash: Windows-specific `.sh` scripts only
- `cmd.exe`: only when an upstream Windows product explicitly requires it
- Toolbox: Linux container; it does not depend on the Windows developer PATH

See [Architecture](docs/ARCHITECTURE.md), [Kanban](docs/KANBAN.md), and [Security](SECURITY.md).