cmdop-care

cmdop-care

A small, read-only Model Context Protocol(MCP) stdio server exposing 4 read-only tools over an already-enrolledcmdop machine fleet: roster visibility, machine health,one bounded live diagnostic, and cmdop-owned storage usage.

Published: io.github.commandoperator/cmdop-care· Current version: v0.1.2 · License: Apache-2.0

If you already use cmdop on a machine, this is the conservative MCP entrypoint: connect an MCP-aware assistant to read fleet health without exposing ashell, arbitrary file reads, or open-ended machine delegation. The host mustalready be enrolled; credentials stay in the host operating system keyring.For broader machine operations, use the main cmdop MCP server instead.

This is not the full cmdop MCP surface. It intentionally omitsask_machine, run_command, read_file, and list_dir — every tool thatexecutes a command, reads an arbitrary file, or delegates an open-ended taskto another machine. If you need those, use the main cmdop CLI's own MCPserver (cmdop mcp stdio), which is a separate, broader, product-integrationsurface with its own review requirements. cmdop-care exists specifically tooffer a narrower, safer, publishable subset for the official MCP Registry.

Requirement: an already-enrolled cmdop CLI on the host

cmdop-care requires the host machine to already be enrolled via the maincmdop CLI. It does not implement enrollment itself, and it does not accept arelay token via an environment variable or a mounted secret as a primarycredential path. On startup it reads:

• the relay OAuth/enrollment Bearer token the cmdop CLI already stored inthe OS keyring (macOS Keychain / Linux Secret Service / Windows CredentialManager) when you ran cmdop enroll <enrollment-password>;
• any per-machine connection PIN the cmdop CLI has already cached in thesame keyring (e.g. from a prior cmdop connect), for care_diagnose only.

If no token is found, every tool responds with a clear "not enrolled" messageinstead of failing silently or hanging.

This "host-keyring passthrough" model was a deliberate design decision (seesecurity-architecture-2026-07-18.md in this artifact's source repository)to avoid introducing a second, weaker credential-handling path for theproduct — this binary is not a fully standalone identity; it rides the sameenrollment as the CLI already installed on the host.

The 4 tools

list_machines

Lists the machines in the enrolled fleet.

• Input: none.
• Output: an array of {host, online, os}. No machine ID/UUID is everreturned — this is a deliberate redaction decision (the internal relayidentifier is dropped before serialization, not merely omitted fromrendering).

care_status

Reads the durable Machine Care projection (facts, findings, coverage,freshness) for one enrolled machine.

• Input: machine (string, required) — exact display name fromlist_machines.
• Output: aggregate facts/findings with closed-vocabulary codes, coverageflags, and reason codes. No raw paths, commands, environment variables, ormachine identity.
• Read-only; works even while the target machine is offline (it reads arelay-stored projection, not a live round-trip).

care_diagnose

Runs one bounded, typed process/startup diagnostic on a live enrolledmachine — useful for "why is this machine slow?"

• Input: machine (string, required).
• Output: a bounded snapshot of process and startup-item facts.

Two disclosures, read before using this tool:

1. PIN forwarding. If the target machine requires a connection PIN, it isforwarded automatically from this host's local OS-keyring PIN cache.You cannot and do not need to pass a PIN as a tool argument. If themachine requires a PIN and none is cached on this host, the call failsclosed with a permission error — it never proceeds without one.
2. Process data reaches your LLM provider. The response includes rawOS process IDs (PIDs) and process names from the target machine. Thatmeans whatever MCP client and LLM you are using — Claude Code, Codex, orany other MCP-speaking assistant — will see the names of processesrunning on that machine. This is a deliberate, reviewed part of thediagnostic contract (it is bounded: at most 20 process entries, nocommand lines, no arguments, no environment variables, no file paths),but you should know it before enabling this tool on a machine whoseprocess list you don't want an external LLM provider to see.

It never executes a shell command, accepts no PID or command argument, andperforms no mutation.

care_storage_inventory

Reads the latest validated cmdop-owned storage inventory for one enrolledmachine.

• Input: machine (string, required).
• Output: aggregate byte totals per closed-vocabulary storage source(e.g. cmdop_logs, devcache_go_build). Accepts no path argument anddeletes nothing.

What every tool call does not do

• No tool accepts a shell command, a file path, or a raw PID as an argument.
• The only free-form input across all 4 tools is the machine string, usedpurely as an opaque lookup key resolved server-side against your ownfleet — never interpolated into a path, command, or query.
• Every call is wrapped in a 15-second timeout independent of the relay's owntransport defaults, and a small per-tool rate limit, so a stuck or abusedbackend cannot hang the process or become a high-volume exfiltrationchannel.

Build and run

go build -o cmdop-care .
./cmdop-care

Or via Docker (after resolving and pinning the base image digest — see the<PIN-BEFORE-BUILD> comment in Dockerfile):

docker build -t cmdop-care:0.1.2 .
docker run --rm -i cmdop-care:0.1.2

The server speaks MCP over stdio only — there is no listening port. Pointyour MCP client (Claude Code, Codex, or any other MCP-speaking assistant) atthe built binary or image the way you would any other stdio MCP server.

For AI-client setup notes, including a minimal MCP JSON configuration and firstprompt, see llms-install.md.

For marketplace submissions that require a square logo image, use the canonical400×400 PNG in assets/cmdop-care-400.png.

Releasing a new version

Maintainers: see RELEASE.md — the short version is make publish, always run manually, never triggered by any CI or by cmdop_go'sown release.

Relay address

By default cmdop-care dials the local embedded cmdop relay on loopback(127.0.0.1:63142). Set CMDOP_CARE_RELAY_ADDR to override the dial targetfor advanced self-hosted setups. This is a transport address only — never acredential.

Compatibility

Contributing to this repository

This repository enables a tracked pre-commit hook that rejects stagedenvironment files, private keys, and probable API tokens. After cloning, run:

git config core.hooksPath .githooks

Security

This artifact went through an explicit threat-model and code-audit reviewbefore implementation (see the Cmdop organization's internalsecurity-architecture-2026-07-18.md and code-audit-2026-07-18.md, referencedfrom this repository's delivery track). Report a security issue to[email protected] (confirm this mailbox is live and monitored beforerelying on it — this repository's maintainers must verify that beforepublication).

License

Apache-2.0 — see LICENSE.