Dou Forge MCP — community core

Your AI. Your machines. One control plane.

Apache-2.0 community candidate 0.1.0a4. This directory is a release candidate, not yet a public release. The Apache-2.0 license is included at the repository root. Complete security review, independent installation and real ChatGPT OAuth onboarding remain release gates. Do not publish the parent private repository or its history; the license applies only to this independently reviewed community tree.

Dou Forge connects an MCP conversation to explicitly authorized user-owned machines through OpenSSH. This initial core implements bus_hosts, bus_plan, bus_exec, and bus_receipt. It is deliberately independent of private knowledge bases, source repositories, collaboration services and accelerator fleets. Those are not included or claimed to be implemented in this edition.

Install and validate

Controller: Linux/macOS, Python 3.11+, OpenSSH. Targets use administrator-managed SSH aliases.

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
douforge --config examples/config.json check
python -m pytest -q

The sample has no hosts, execution disabled, and free shell disabled. It never discovers your existing SSH hosts or private service configurations. Never paste a production token into source.

Related MCP server: termdesk

Offline first-run diagnostics

Run before configuring any real machine:

douforge --config examples/config.json --state "$HOME/.local/state/douforge-demo" doctor

Doctor makes no network requests, executes no commands, reads no credentials, and does not create a state database. It checks local prerequisites and reports missing SSH config, insecure state permissions and disabled actions. A status of offline_preflight_only DOES NOT prove an SSH connection, OAuth login or ChatGPT acceptance. Continue with oauth-check, an operator approved test action, and a real client only in an isolated environment.

Start with stdio

douforge --config examples/config.json --state "$HOME/.local/state/douforge-demo" serve

An MCP-capable local client may launch this command. Stdio uses the local principal and inherits the launcher's OS privileges. It is not authenticated HTTP and does not make ChatGPT able to reach a local pipe.

Add one machine deliberately

Copy examples/config.json to an ignored config.local.json. Add an existing SSH alias:

"hosts": {"demo": {"ssh_alias": "my-test-host", "tags": ["lab"]}},
"principals": {"local": {"hosts": ["demo"], "actions": ["hostname"]}}

Verify that alias and its host key as the operator. Set execution_enabled: true only after reviewing access. The default hostname action requires local operator approval:

1. The MCP client calls bus_plan(hosts=["demo"], action="hostname").

2. The operator reviews the exact command and hosts using the local command below.

3. The MCP client calls bus_exec(plan_id=..., request_id="a-stable-unique-id", confirm=true).

4. Repeating the same request returns its receipt rather than running the command twice.

douforge --config config.local.json --state "$HOME/.local/state/douforge-demo" approve PLAN_ID

Approval is not exposed as an MCP tool. confirm=true cannot replace it. An operator can mark a specific named action require_approval: false; that is a standing authorization, not a claim the command is intrinsically safe. Free shell is separately disabled and always requires approval.

HTTP and authentication

Loopback preview (no OAuth login service is provided in this mode):

export DOUFORGE_PREVIEW_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
douforge --config examples/config.json --state "$HOME/.local/state/douforge-preview" \
  serve --transport streamable-http --port 9384

The native server binds 127.0.0.1 by default, requires the bearer token, and refuses a public resource URL in preview mode. Never expose preview with a tunnel or reverse proxy. This mode tests HTTP middleware; it is not the ChatGPT signup experience.

For remote OAuth clients, configure http.auth_mode: "jwt", your HTTPS issuer_url, HTTPS jwks_url and intended resource_url. Tokens must be signed with RS256/ES256, match issuer and audience, include expiry, subject and forge:use scope. Configure that exact subject in principals. The official MCP SDK advertises protected-resource metadata. Bring an OAuth 2.1 authorization server with an appropriate client registration/consent flow and a TLS reverse proxy. This package does not create an identity provider, issue tokens, or silently trust Tailscale/private IPs.

ChatGPT OAuth end-to-end onboarding of this new edition remains unverified. The functioning private deployment is a separate implementation and must not be used as proof for this edition.

Safety and limitations

Read SECURITY.md. This is an automation control plane, not a sandbox. SSH executes with the selected remote account's privileges. Protect the controller and use least-privilege users. An arbitrary-shell action on the controller account can defeat same-account approval separation; do not grant it to untrusted clients. Admin configuration and OS isolation remain trust boundaries.

Plans are short-lived, bound to the configuration and caller, and single-use. SQLite receipts persist across restart. A crash after claim can leave an uncertain outcome; the server refuses to retry it. This is not exactly-once execution of distributed side effects. Inspect the remote host manually.

Output is bounded in memory, with an additional stop threshold. There is no unlimited full-output log. Timeouts terminate the local SSH process group; remote descendant termination is not guaranteed. A multi-host operation may partially complete; it is not an atomic distributed transaction.

Development and provenance

Use python -m pytest -q, ruff check src tests, and python -m build in this directory. Core behavior is new code informed by the private bus workflow; it is not a bulk export of private source. No private backend modules, deployment files, repository history, secrets, corpus or host list is included. Dependencies are installed from upstream, not vendored. See PROVENANCE.md.

Docker packaging

See Docker / Compose guide. Run python3 tools/init_docker_preview.py, then docker compose up --build --detach --wait in this community directory. The preview publishes only to host loopback, uses a generated file-backed token and a non-root, read-only container. The explicit --container-preview flag permits container-internal all-interface binding; it cannot enforce host-side isolation for you. Never expose preview through a public tunnel. For externally authenticated use, configure an HTTPS JWT issuer/resource and use the compose.jwt.yaml override; a complete OAuth login server is still operator-provided. No registry images are published by these files. Dockerfile architecture portability is not proof of acceptance on every architecture. See the recorded Docker smoke test results.

OAuth preflight

Run douforge --config CONFIG oauth-check --registration provided against administrator-reviewed configuration. This performs bounded, authenticated-TLS metadata reads only; it does not log in, register a client, or prove ChatGPT interoperability. See OAUTH.zh-CN.md for the separate onboarding checklist.