# AgentDock MCP Harness

> **无限流 / Infinite Coding Flow**
>
> **把 ChatGPT / Claude 网页版的大额度、近似无限配额，变成你的远程 Coding Token 池。**
>
> **Use your ChatGPT / Claude Web quota as a remote coding agent — no second API token meter.**

如果你的 ChatGPT / Claude 网页套餐本身提供大额度或近似无限的使用量，AgentDock 就能让这部分现有配额直接驱动你自己 Linux 服务器上的真实开发流程，而不是再额外购买一套 Coding Agent API Token。

If your chat plan gives you high or near-unlimited usage, AgentDock lets that same chat-model quota drive real remote software engineering on your own Linux server.

**No second coding model. No extra server-side AI API key. No separate per-token reasoning bill.**

AgentDock keeps ChatGPT / Claude / another MCP-capable chat client as the **only reasoning agent** and adds the missing execution layer: Git worktrees, file editing, shell/process execution, tests, durable tasks, approvals, commits, host access, and audit.

### Why the token model matters

Long coding tasks are token-hungry. A real debugging loop may repeatedly:

```text
read code
→ search more files
→ reason
→ edit
→ run tests
→ inspect failure
→ reason again
→ edit again
→ run the full suite
→ review diff
```

With an API-based coding agent, every reasoning loop consumes separately billed API tokens.

With AgentDock, the reasoning stays inside the chat product you already use. If your ChatGPT / Claude plan provides a large or near-unlimited chat allowance, **that existing allowance becomes the reasoning budget for remote coding**, while the server only executes deterministic MCP tools.

> AgentDock does not claim that every chat subscription is literally unlimited. Plans can have usage, rate, or context limits. The value proposition is that AgentDock adds **no second model/API token meter on the server**.

**Status:** v0.1 Core is complete and has passed both automated MCP black-box acceptance and a live ChatGPT Web acceptance on a real Linux server.

> Naming note: this project is not affiliated with other projects named AgentDock. The public repository uses **AgentDock MCP Harness** to distinguish this execution harness from unrelated agent frameworks and desktop tools.

## What problem does it solve?

### 1. ChatGPT Web is smart, but it cannot normally work on your server

Chat models can reason about code extremely well, but without an execution harness they cannot reliably:

- inspect a real repository;
- edit files safely;
- run tests and builds;
- manage long-running processes;
- create isolated Git changes;
- survive a dropped MCP connection;
- commit the finished result.

AgentDock turns MCP from a collection of remote commands into a durable software-engineering workflow.

### 2. You should not need a second AI just to execute code

Many "coding agent" architectures look like this:

```text
ChatGPT
   |
   v
remote server
   |
   v
another LLM / coding agent API
   |
   v
shell / files / Git
```

That creates duplicated reasoning, duplicated context, another API key, and another token bill.

AgentDock uses:

```text
ChatGPT / Claude / MCP client
          |
          | reasoning + decisions
          v
       AgentDock
          |
          | deterministic execution
          v
 Git / files / processes / Linux
```

**One reasoning agent. No server-side LLM required.**

### 3. A raw SSH MCP is not a professional coding harness

Giving a model `ssh` or `run_command` is useful, but it leaves the model responsible for inventing its own engineering workflow every time.

AgentDock provides first-class primitives for:

- Task lifecycle;
- isolated Git worktrees;
- file read/search/patch/write;
- asynchronous processes;
- incremental output;
- test failure inspection;
- Git diff and commit;
- approval requests;
- structured audit.

The model reasons about the software problem instead of repeatedly rebuilding shell orchestration.

### 4. Long coding tasks should survive disconnects

Browser sessions, MCP connections, OAuth proxies, and remote services can restart.

AgentDock persists Task and process metadata so the same `task_id` can resume after a reconnect or AgentDock restart. A process that was running before a restart is explicitly restored as `INTERRUPTED`, never falsely reported as still running.

### 5. AI coding should not pollute your source checkout

Every write-capable coding Task gets its own Git worktree based on the source repository's current `HEAD`.

Your source checkout can even be dirty; AgentDock keeps those existing uncommitted changes out of the Task.

The AI can test, edit, diff, and commit in isolation while the source working tree remains untouched.

### 6. Powerful remote access needs approval and evidence

AgentDock can intentionally access host files and run commands using the permissions of its OS user.

Instead of pretending this is risk-free, AgentDock makes the boundary explicit:

- deterministic `allow / ask / deny` policy;
- structured ApprovalRequest;
- `ALLOW_ONCE / ALLOW_TASK / DENY / ASK_USER`;
- workspace-vs-host audit;
- process exit codes and timestamps;
- Git commit evidence;
- best-effort secret redaction in persisted audit.

## What do you get?

With AgentDock connected, a chat model can carry out a workflow like:

```text
"Fix this bug on my server"
        |
        v
inspect repo
        |
create isolated Task/worktree
        |
search + read code
        |
edit
        |
run real test -> FAIL
        |
read failure
        |
edit again
        |
test -> PASS
        |
full suite -> PASS
        |
review git diff
        |
create real commit
        |
finish Task
        |
return commit SHA + audit
```

All of that can happen while **the chat model remains the brain and AgentDock remains the execution harness**.

## Who is this for?

AgentDock is especially useful if you:

- already use ChatGPT Web / Claude / another strong MCP-capable chat model;
- want that chat model to work directly on a remote Linux development machine;
- do not want to run or pay for a second server-side coding model;
- want more structure than a generic SSH MCP;
- care about Git isolation, resumability, approvals, and auditability;
- want a coding-harness experience from the browser rather than another local coding-agent application.

## Architecture

```text
ChatGPT / MCP client
        |
        | MCP
        v
+-------------------------+
| AgentDock MCP Harness   |
|-------------------------|
| Task lifecycle          |
| Git / worktrees         |
| File primitives         |
| Process lifecycle       |
| Deterministic policy    |
| Smart approval protocol |
| Durable state           |
| Structured audit        |
+-------------------------+
        |
        v
 Linux filesystem / Git / processes / OS
```

For remote deployments, TLS, public ingress, and OAuth can remain outside Core:

```text
ChatGPT Web
   |
 HTTPS + OAuth
   |
auth / reverse proxy
   |
stdio or HTTP adapter
   |
AgentDock Core
```

## v0.1 capabilities

### Task lifecycle

- `task.create`
- `task.resume`
- `task.finish`
- `task.cancel`
- `task.cleanup`

Write-capable tasks are Git-native and get an isolated worktree based on the source repository's current `HEAD`. Dirty source repositories are allowed; their uncommitted changes are not copied into the Task.

### Files

- `file.read`
- `file.search`
- `file.patch`
- `file.write`

Relative paths resolve against the Task worktree. Explicit absolute paths access the host according to native OS permissions.

`file.patch` uses optimistic concurrency through a SHA-256 returned by `file.read`; stale edits fail with `PATCH_CONFLICT`.

### Processes

- `process.start`
- `process.status`
- `process.output`
- `process.cancel`

Processes are asynchronous, Task-scoped, and support explicit argv or shell mode. Output is pulled incrementally with cursor semantics.

Persisted diagnostic output is bounded; live output preserves fidelity.

### Git

- `repo.inspect`
- `git.diff`
- `git.commit`

v0.1 creates real local commits but does not implement push, merge, deploy, PR, or rebase orchestration as first-class AgentDock tools.

### Approval

Deterministic policy produces one of:

- `allow`
- `ask`
- `deny`

When policy returns `ask`, AgentDock emits a structured ApprovalRequest. The connected reasoning agent can answer:

- `ALLOW_ONCE`
- `ALLOW_TASK`
- `DENY`
- `ASK_USER`

AgentDock performs no LLM risk classification.

### Audit

`audit.get` exposes structured Task history including:

- Task lifecycle;
- workspace versus host file access;
- process IDs, cwd, status, exit code and timestamps;
- approvals;
- Git commit SHA;
- completion state.

Persisted audit uses best-effort secret redaction. Live file/process responses remain faithful to the OS-authorized content.

## Proven acceptance path

The v0.1 acceptance suite exercises the public MCP surface against a disposable real Git repository:

```text
task.create
  -> isolated worktree
  -> file.search / file.read / first patch
  -> real targeted test FAIL
  -> inspect failure
  -> second failure-driven patch
  -> disconnect / reconnect
  -> AgentDock restart / task.resume
  -> Smart Approval
  -> targeted test PASS
  -> full suite PASS
  -> git.diff
  -> real git.commit
  -> task.finish
  -> audit.get
  -> source repository zero-pollution
```

Run it with:

```bash
npm run acceptance:v0.1
```

## Requirements

AgentDock currently targets:

- Linux
- Node.js 24+
- Git
- an MCP client capable of invoking the exposed tools

The v0.1 release provides stdio. The v0.2 development line now supports both stdio and native stateless Streamable HTTP on loopback by default.

macOS and Windows execution backends are not implemented yet.

## Install from source

Clone and install:

```bash
git clone https://github.com/gabyic/agentdock-mcp-harness.git
cd agentdock-mcp-harness
./scripts/install.sh
```

The installer performs a user-local installation by default and does not require root for Core.

See [docs/deployment.md](docs/deployment.md) for local MCP configuration and remote deployment guidance.

## Development

```bash
npm ci
npm test
npm run acceptance:v0.1
```

The primary test seam is MCP black-box integration. Tests intentionally use real Git repositories, real worktrees, real filesystem operations and real child processes rather than bypassing MCP to call service classes directly.

## Security model

AgentDock is an execution harness. An authenticated client can intentionally run commands and access host paths permitted to the AgentDock OS user.

Important properties:

- no hidden sandbox is implied;
- host permissions come from the operating system;
- approval policy is deterministic;
- Task write operations are isolated in Git worktrees;
- arbitrary host side effects are audited but are not promised universal rollback;
- persisted audit redacts common secret patterns on a best-effort basis.

Do not expose AgentDock directly to the public internet without an authentication layer.

See [SECURITY.md](SECURITY.md).

## Roadmap

v0.2 focuses on production distribution and protocol modernization rather than feature sprawl:

- ✅ MCP 2026-07-28 / TypeScript SDK v2 migration;
- ✅ native stateless Streamable HTTP while retaining stdio;
- stable configuration schema and `doctor` diagnostics;
- installation / upgrade / uninstall lifecycle;
- service health and restart hardening;
- release CI, versioning and reproducible packages;
- documentation for remote ChatGPT deployment.

See [docs/roadmap-v0.2.md](docs/roadmap-v0.2.md).

## Non-goals for v0.2

These remain deliberately deferred:

- server-side LLM inference;
- autonomous Pi/OpenCode/Codex workers;
- macOS / Windows execution backends;
- browser / GUI automation;
- Kubernetes orchestration;
- SaaS, billing, teams or RBAC;
- universal rollback for arbitrary host side effects.

## License

MIT. See [LICENSE](LICENSE).