TalkPipe MCP

An intentionally narrow local MCP tool adapter for mcc0nnell/talkpipe. Built to make approved TalkPipe pipelines invocable by MCP clients, including future ChatGPT connections.

Status (October 2026): The stdio adapter has been exercised by the official MCP Python SDK client. This is not yet connected to ChatGPT as a custom plugin. It is not a network service.

Setup

Python 3.11+:

git clone https://github.com/mcc0nnell/talkpipe-mcp.git
cd talkpipe-mcp
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
python -m unittest discover -s tests -v
python -u talkpipe_mcp.py

Installation pins the user's TalkPipe fork to commit 1b40f4c73a27a6ffb72f4715f5768c7cb12f3ffd and MCP SDK version 1.30.0. No other model or network provider is required for the three included workflows.

Related MCP server: io.github.readyagentsdev/readyagents

Tools

Approved talkpipe_run workflows:

• normalize: collapse whitespace within each item.

• keyword_filter: normalize then filter items containing needle (literal, case-insensitive).

• text_statistics: normalize then yield character/word counts and a 160-character preview.

Example MCP tool arguments:

{"workflow":"keyword_filter","items":["  SignPipe  ", "TalkPipe on Butcher", "Lightpanda MCP"],"needle":"pipe"}

MCP clients that support local stdio servers can configure the command as the absolute path to the venv's Python executable and the arguments as -u and the absolute path to talkpipe_mcp.py. See examples/stdio-config.json and replace paths before use.

Safety boundaries

Only approved deterministic workflows may run. No arbitrary ChatterLang, Python evaluation, shell subprocesses, web requests, data persistence, or model-provider calls are exposed. Input is bounded to 100 strings, 4096 characters each, 65536 total characters; result output is capped at 50 items. Results are returned to the MCP caller and never intentionally written to storage by this adapter.

Do not expose this stdio server to the public Internet. The absence of a network listener does not imply it is safe to wrap in an unauthenticated HTTP gateway. Deploying via Cloudflare requires identity-based access, an authenticated Streamable HTTP MCP endpoint, request authorization, destination/pipeline policy, resource isolation, and operational audit controls. The ChatGPT connection requires user-controlled installation/authorization.

Scope and next steps

This is a real TalkPipe pipeline adapter, not an LLM or a generalized code runner. Future versions can add reviewed named workflows for accessibility testing, browser receipt normalization, or WindAnvil evidence. A ChatGPT-installable remote MCP connector is not claimed or implemented.

License: Apache-2.0. See LICENSE.

Connect privately to ChatGPT

Desktop-only compatibility and web/mobile research: See the verified surface matrix and migration runbook. Bundled mcp.json / .mcp.json makes the current imported plugin Desktop only. A Connection → Tunnel custom MCP connection is a web option only on eligible workspaces; OpenAI does not currently document custom MCP connections as mobile-ready. Plus-compatible ChatGPT Sites is another candidate, but requires its own authenticated connection to Blade and a real invocation test. Preserve the working plugin until a replacement passes.

The preferred deployment for the private Blade-gated Commander MCP is OpenAI's Secure MCP Tunnel: no public Cloudflare URL, firewall opening, or inbound HTTP listener is required. The tunnel client calls the signed-Blade-gated Commander MCP server over local stdio and polls the OpenAI control plane via outbound HTTPS.

On Butcher

The supported tunnel-client release is installed at ~/.local/bin/tunnel-client and the TalkPipe runtime is at ~/lab/talkpipe-runtime/.venv/bin/python. Run the adapter tests first:

cd ~/lab/talkpipe-mcp
~/lab/talkpipe-runtime/.venv/bin/python -m unittest discover -s tests -v

In OpenAI Platform tunnel settings, create a tunnel and associate it with the ChatGPT workspace you will use. It must be usable by a runtime API key with the Tunnels Read + Use permission. Do not use an admin key as the long-lived runtime key.

In a shell on Butcher, obtain the exact tunnel identifier and configure:

export CONTROL_PLANE_TUNNEL_ID='tunnel_REPLACE_WITH_YOUR_ID'
./scripts/private-tunnel.sh configure

The private profile is saved in ~/.config/tunnel-client/, mode 0600, and contains a key reference, not a credential. The script refuses missing or invalid identifiers. For security, do not put secrets in a command line or in Git. Provision a Restricted Tunnels Read + Use key interactively on Butcher (not through ChatGPT):

./scripts/install-tunnel-runtime-key.sh

The prompt hides your input and writes a private 0600 key file at ~/.config/tunnel-client/windanvil-runtime-key. The tunnel profile references that file without embedding the key.

./scripts/private-tunnel.sh doctor
./scripts/private-tunnel.sh run

Keep the run process alive while using Commander in ChatGPT. Its health admin UI is loopback-only and the tunnel is outbound-only.

In ChatGPT (web)

Open Plugins, select + → Add custom MCP server, enter the name WindAnvil Commander, select Tunnel, choose the associated tunnel or enter its ID, and review authentication and the risk warning. Select Create as a plugin only after inspecting the discovered eight commander_* tools. Review write/execute permissions for commander_talkpipe_run and commander_file_create.

This user-initiated connection requires the relevant ChatGPT workspace permissions and Platform tunnel permissions. A functioning local adapter or stored tunnel profile does not mean ChatGPT is connected. Test by invoking commander_health and commander_status from ChatGPT; only that confirms the end-to-end path.

Current operational boundary: Until those account-side tunnel and ChatGPT steps are completed and a real tool call succeeds, this repository is ready for private connection, not connected. The Commander adapter does not expose arbitrary ChatterLang or Python.

Cloudflare Workers/Tunnel can provide a public alternative, but that would require a separate authenticated MCP transport and identity configuration. Do not publish the existing unprotected stdio tool behind an anonymous HTTP proxy.

WindAnvil Commander gateway (Blade-gated)

windanvil_commander_mcp.py is the safer replacement entrypoint for the private tunnel. It exposes three tools over local MCP stdio:

• commander_health: query the Blade Unix socket health

• commander_status: inspect admitted capabilities and grants

• commander_talkpipe_run: send a pinned TalkPipe pipeline envelope via EXEC + tab + talkpipe.run, never directly invoke Python or ChatterLang

All three require WINDANVIL_LOCAL_SOCKET (default ~/runtime/blade/blade.sock) to exist, be Unix-domain, have permissions 0600, and be owned by the current UID. The client also checks the peer UID and same socket inode after connect. There is no alternate execution path if Blade refuses a request. commander_talkpipe_run accepts only a constrained pipeline name and lowercase 64-character SHA-256; the native Blade runtime retains signature verification, admission, revocation, pipeline digest enforcement, and evidence receipt authority. The MCP facade cannot issue or renew grants.

The protocol is the repository's tools/blade-local.py wire format from mcc0nnell/windanvil-blade.

Observed limitation on Butcher: the native blade.sock is missing; Commander tool calls therefore return BLOCKED. The unit and MCP integration tests use a synthetic local socket to check the wire/protocol boundary, not to claim a live signed-grant execution. This does not yet replace the existing Desktop Commander connection, and commander.windanvil.com/mcp currently returns HTTP 503 (control_plane_not_configured). No remote endpoint was activated by this work.

Run tests with python -m unittest discover -s tests -v. The private tunnel launcher now points to this Blade-gated entrypoint instead of direct TalkPipe. The original talkpipe_mcp.py remains a local-only development interface for the existing bounded text workflows and must not be the production remote execution target.

Native host-inspection parity slice

WindAnvil Blade now has a separate signed host.inspect capability in mcc0nnell/windanvil-blade. commander_host_inspect exposes its three read-only operations:

• system.info: OS release, architecture, numeric UID (empty path)

• dir.list: capped directory listing relative to an administrator-pinned root

• file.read: capped 16 KiB regular text-file reads, under the same root

• file.find: bounded recursive filename search under that root

• content.search: bounded literal content search returning path and line numbers only

Example tool arguments:

{"operation":"file.read","path":"inside.txt"}

The client only sends EXEC host.inspect to the local Blade socket; both client-side path validation and native openat + O_NOFOLLOW checks apply. Hidden paths, traversal and symlinks are denied. The native Celix bundle must already be admitted by a valid Ed25519-signed manifest for the exact bundle SHA-256. There is no file-read fallback to shell or direct Python.

Proof scope: a local development Blade authority on Butcher admitted the bundle, repeated directory listings returned identical results, file reads worked, and symlink/traversal attempts were blocked. Native receipts record the decisions. The cloud endpoint at commander.windanvil.com/mcp remains unconnected to Blade until the secure control plane is configured; this proof does not establish ChatGPT plugin connectivity or device parity.

Desktop Commander should remain active until host/file/process/shell/session and remote-device operations are all implemented behind signed capabilities, authenticated end to end, and verified from ChatGPT.

Independently admitted process inspection

commander_process_list invokes precisely EXEC process.inspect with operation process.list on the same protected Blade Unix socket. It is a separate signed native Celix capability, not an expansion of host.inspect permissions. There are no PID, command line or signal arguments. The native capability returns at most 100 PIDs and 64-character sanitized process names for processes owned by Blade's UID. Other users' processes, environment variables, shell access and process termination are not exposed.

The MCP tool declares read-only, non-destructive annotations. When the process inspection grant is unavailable or the Blade socket fails, the result is BLOCKED with no direct-process Python fallback. Verified with the official MCP Python SDK and native signed Blade runtime on Butcher; 22 automated adapter tests passed. This is local proof only and does not imply that ChatGPT has connected to the public Commander endpoint.

Signed read-only Git inspection

commander_git_inspect invokes the separate dynamically admitted git.inspect Blade capability. It accepts only git.status or git.history; the MCP caller cannot provide a repository path, Git arguments, arbitrary commands, Git config or executable hooks.

The native libgit2 capability pins a same-UID worktree and returns sanitized branch/HEAD and status counts or the five most recent commit hashes/timestamps. The implementation intentionally excludes raw diffs, Git commit messages, secrets, checkout, fetch, push, and commit commands. Only the signed bundle can authorize it. When the signed grant is absent, the tool returns BLOCKED, never a fallback Git shell.

Verified with an official MCP SDK client and a real signed Blade bundle: status/history PASS and git.push BLOCKED; 23 adapter tests passed. The host's malicious test hook and configured external diff did not execute. See the separate WindAnvil Blade repository's docs/git-inspect-capability.md. This is a local development proof, not registration as a native ChatGPT plugin or Desktop Commander parity.

Signed atomic create-only file writes

commander_file_create accepts only a safe relative path and up to 2048 UTF-8 bytes. It invokes the separately signed file.create Blade capability through the default private socket. The native bundle uses a dedicated operator-pinned private directory and publishes data through an exclusive temporary file and atomic hard link. It never overwrites.

The tool has write-capability MCP annotations and requires appropriate caller approval. No shell, Python, or unchecked remote-HTTP fallback is available. An unavailable or refused Blade grant returns BLOCKED.

Verified on Butcher with an official MCP client: new create PASS, duplicate BLOCKED, traversal BLOCKED; mode 0600 and contents verified. The adapter suite passed 24 tests. This is a development grant, not an active public ChatGPT connection or permission to edit arbitrary system files.

Blade-gated fixed process probes

commander_process_probe accepts only kernel, uptime or disk, and invokes a separate signed native process.probe Celix capability. The Blade runtime runs fixed, root-owned absolute executables through posix_spawn with a minimal environment, three-second deadline, no shell, and a 4096-byte output cap. There are no user-supplied executables, arguments, working directories or process IDs.

A missing or denied grant returns BLOCKED. On Butcher an official MCP SDK client verified all three fixed probes and rejection of an attempted sh probe. The adapter suite passed 25 tests. This is not a general-purpose command runner, interactive shell or ChatGPT cloud plugin; service persistence and production identity remain separate.

Verified local-to-ChatGPT connection boundary (October 2026)

The preferred private connection is OpenAI Secure MCP Tunnel, not a public Cloudflare proxy to Blade. The host has a supported tunnel-client binary, but requires an actual Platform tunnel_id, a restricted runtime key with Tunnels Read + Use permissions, and the user-controlled ChatGPT plugin connection. A publicly reachable commander.windanvil.com/mcp Worker currently responds with 503 control_plane_not_configured; do not bypass this guard.

To check the eight actual Commander tools and six development-signed capabilities before requesting tunnel access:

cd ~/lab/talkpipe-mcp
./scripts/private-tunnel.sh preflight

The preflight makes five real nonmutating MCP calls using official SDK stdio transport and checks each admitted capability. No remote connection, token, tunnel, cloud availability or ChatGPT installation is claimed. The same command must fail closed if Blade is unavailable.

After creating a tunnel in Platform settings and associating it with the intended ChatGPT workspace, set CONTROL_PLANE_TUNNEL_ID (do not guess an ID) and invoke ./scripts/private-tunnel.sh configure. The generated mode-0600 profile references a local file: secret and contains no key. Run ./scripts/install-tunnel-runtime-key.sh interactively on Butcher to store the restricted runtime key with mode 0600. Never provide it in a repo, chat, CLI argument or recorded log. Only then run ./scripts/private-tunnel.sh doctor and ./scripts/private-tunnel.sh run. In ChatGPT Plugins choose Add custom MCP server → Tunnel, select that same tunnel, review permissions for all eight tools, connect, and verify at least one benign tool call from the chat. These account-side actions are not accomplished by configuring a profile.

Cloudflare Wrangler authentication is separate from the OpenAI tunnel. An expired Wrangler OAuth access token can usually be refreshed with wrangler whoami; a valid Cloudflare account session does not provision the missing Cloudflare Worker control plane or any OpenAI tunnel.

Deployment-as-code (Butcher)

ops/DEPLOYMENT.md is the canonical deployment map: tracked tunnel profile example, real-profile drift audit, signed Blade MCP preflight, restricted runtime-key installation and pointers to the Blade cron/boot recovery scripts. The real tunnel ID and credentials remain in private host configuration rather than source control.

Run python3 scripts/audit-tunnel-deployment.py before tunnel doctor. A successful deployment audit does not imply a connected ChatGPT plugin.

Persistent outbound tunnel (Butcher)

The version-controlled watchdog in ops/TUNNEL_SUPERVISOR.md manages the exact WindAnvil Commander tunnel profile, validates the reviewed tunnel-client binary and private key-file permissions, checks Blade integrity, and starts a detached tunnel with private health/log files. A tracked cron installer preserves Desktop Commander and other existing jobs while adding @reboot and five-minute recovery:

./scripts/manage-tunnel-cron.py install
./scripts/supervise-commander-tunnel.py check

A controlled stop/restart recovery has been exercised on Butcher. Host reboot recovery and native ChatGPT plugin connectivity are not yet proven.

Private ChatGPT plugin package

See ops/PLUGIN.md for the version-controlled private plugin manifest, Secure MCP Tunnel connection declaration and signed-use skill. The package generator substitutes the approved tunnel ID into a locally built ZIP without copying any runtime credential or signed private key. Private plugin creation is distinct from verified availability of its tools in the current ChatGPT conversation.