Skip to content

Commit 2a7810f

Browse files
authored
Merge pull request #49 from tarides/mcp-stop-status
Add stop_server + status MCP tools; TDQS-grade tool descriptions
2 parents e0fee55 + dc55d74 commit 2a7810f

20 files changed

Lines changed: 671 additions & 38 deletions

‎.github/workflows/publish.yml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,32 @@ jobs:
7373
echo "crate ${VERSION} did not appear on crates.io in time" >&2
7474
exit 1
7575
76+
# The MCPB package entry in server.json points at a GitHub release asset
77+
# (built + uploaded by release.yml on the same tag) and must carry that
78+
# file's sha256. release.yml runs in parallel, so wait for the asset, then
79+
# compute and inject the hash. The registry validates the URL with a HEAD
80+
# request at publish time, so the asset must be live before we publish.
81+
- name: Wait for MCPB asset and inject sha256 into server.json
82+
run: |
83+
URL=$(jq -r '.packages[] | select(.registryType=="mcpb") | .identifier' server.json)
84+
echo "MCPB asset: $URL"
85+
TMP=$(mktemp)
86+
for i in $(seq 1 60); do
87+
if curl -fsSL -A "$CRATES_UA" "$URL" -o "$TMP"; then
88+
echo "MCPB asset is live"
89+
break
90+
fi
91+
echo "waiting for MCPB asset (attempt ${i})..."
92+
sleep 10
93+
[ "$i" -eq 60 ] && { echo "MCPB asset did not appear in time" >&2; exit 1; }
94+
done
95+
SHA=$(sha256sum "$TMP" | awk '{print $1}')
96+
echo "sha256=$SHA"
97+
jq --arg h "$SHA" \
98+
'(.packages[] | select(.registryType=="mcpb") | .fileSha256) = $h' \
99+
server.json > server.json.tmp
100+
mv server.json.tmp server.json
101+
76102
- name: Install mcp-publisher
77103
run: |
78104
curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher

‎.github/workflows/release.yml‎

Lines changed: 20 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -41,27 +41,40 @@ jobs:
4141
tar czf "${DIR}.tar.gz" "$DIR"
4242
echo "TARBALL=${DIR}.tar.gz" >> "$GITHUB_ENV"
4343
44+
- name: Build MCPB bundle
45+
run: |
46+
VERSION="${GITHUB_REF#refs/tags/v}"
47+
MCPB="sudo-proxy-mcp-v${VERSION}-x86_64-linux.mcpb"
48+
packaging/mcpb/build-mcpb.sh \
49+
"$VERSION" \
50+
target/x86_64-unknown-linux-musl/release \
51+
.
52+
echo "MCPB=${MCPB}" >> "$GITHUB_ENV"
53+
4454
- name: Install rsign2 (minisign signer)
4555
run: cargo install rsign2 --locked
4656

47-
- name: Sign tarball (minisign)
57+
- name: Sign release assets (minisign)
4858
run: |
4959
umask 077
5060
printf '%s\n' "$MINISIGN_SECRET_KEY" > minisign.key
51-
rsign sign -W -s minisign.key -x "${TARBALL}.sig" \
52-
-t "sudo-proxy ${GITHUB_REF#refs/tags/} release" \
53-
"$TARBALL"
61+
for f in "$TARBALL" "$MCPB"; do
62+
rsign sign -W -s minisign.key -x "${f}.sig" \
63+
-t "sudo-proxy ${GITHUB_REF#refs/tags/} release" \
64+
"$f"
65+
rsign verify -P "$MINISIGN_PUBKEY" -x "${f}.sig" "$f"
66+
done
5467
rm -f minisign.key
55-
rsign verify -P "$MINISIGN_PUBKEY" -x "${TARBALL}.sig" "$TARBALL"
56-
echo "SIGNATURE=${TARBALL}.sig" >> "$GITHUB_ENV"
5768
env:
5869
MINISIGN_SECRET_KEY: ${{ secrets.MINISIGN_SECRET_KEY }}
5970
MINISIGN_PUBKEY: RWT7gwtBU0v4puI76u0oYwMAT9nmYwGimSOnqJJ+kHExsjTDQj1eZkMW
6071

6172
- name: Create GitHub Release
6273
run: |
6374
TAG="${GITHUB_REF#refs/tags/}"
64-
gh release create "$TAG" "$TARBALL" "$SIGNATURE" \
75+
gh release create "$TAG" \
76+
"$TARBALL" "${TARBALL}.sig" \
77+
"$MCPB" "${MCPB}.sig" \
6578
--title "$TAG" \
6679
--generate-notes
6780
env:

‎Cargo.lock‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[package]
22
name = "sudo-proxy"
3-
version = "1.0.0"
3+
version = "1.1.0"
44
edition = "2021"
55
license = "MIT"
66
description = "Privileged command execution proxy with human approval via pkexec or sudo"

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,7 @@ as `mcp-name: io.github.tarides/sudo-proxy`.
143143
## Documentation
144144

145145
- [docs/install.md](docs/install.md) — install variants, remote deploy, building from source
146-
- [docs/mcp.md](docs/mcp.md) — MCP tools (`start_server`, `execute`, `update_host`), config, known hosts
146+
- [docs/mcp.md](docs/mcp.md) — MCP tools (`start_server`, `execute`, `status`, `stop_server`, `update_host`), config, known hosts
147147
- [docs/usage.md](docs/usage.md) — CLI flags, non-privileged mode, SSH tunnels, agent forwarding
148148
- [docs/protocol.md](docs/protocol.md) — JSON-line wire protocol over the Unix socket
149149
- [docs/security.md](docs/security.md) — security model; [docs/security-audit.md](docs/security-audit.md) — point-in-time audit; [docs/threat-model.md](docs/threat-model.md) — STRIDE + attack tree; [docs/formalisation-roadmap.md](docs/formalisation-roadmap.md) — graduated-assurance plan; [docs/assurance-case.md](docs/assurance-case.md) — GSN argument

‎docs/mcp.md‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,24 @@ sudo-proxy as tools over stdio JSON-RPC. Any MCP-capable AI client
3030
- `host` (required): hostname to update.
3131
- `description`: human-readable description (e.g. "CI server").
3232
- `os`: operating system info (e.g. "Ubuntu 24.04").
33+
- Partial update: only the fields provided are changed; a host not yet in the
34+
registry is added automatically.
35+
36+
**`stop_server`** — stop a running sudo-proxy daemon.
37+
- `host`: which daemon to stop (omit for the local one).
38+
- Sends a `stop` control request over the socket. The daemon prints a
39+
shutdown notice on its terminal (no approval prompt), exits, and its
40+
terminal window — and SSH tunnel, for remote hosts — closes.
41+
- "Not running" is reported as a normal (non-error) result.
42+
- Daemons older than 1.1 don't understand `stop`; the tool reports their
43+
version and asks for a manual `q`/Ctrl+C in the daemon's terminal.
44+
45+
**`status`** — report daemon status without executing anything.
46+
- `host`: check one daemon; omit to check the local daemon plus every host in
47+
the registry.
48+
- Per host: socket presence, readiness, live daemon version (via a `ping`
49+
control request that needs no human approval), and registry metadata.
50+
- Read-only except for refreshing the registry's last-connected/version cache.
3351

3452
## Claude Code configuration
3553

@@ -106,7 +124,8 @@ correctly (no Docker needed):
106124
cargo test --test mcp_introspection
107125
```
108126

109-
It should enumerate `execute`, `start_server`, and `update_host`.
127+
It should enumerate `execute`, `start_server`, `status`, `stop_server`, and
128+
`update_host`.
110129

111130
## Glama terminology
112131

@@ -116,7 +135,7 @@ sudo-proxy:
116135
| Glama term | sudo-proxy |
117136
| ------------- | ---------- |
118137
| **Server** | the `sudo-proxy-mcp` binary — the stdio MCP server, listed as `tarides/sudo-proxy`. |
119-
| **Tools** | `execute`, `start_server`, `update_host`. |
138+
| **Tools** | `execute`, `start_server`, `status`, `stop_server`, `update_host`. |
120139
| **Connector** | *none* — a connector is a **remote/hosted** MCP server (a managed HTTP endpoint). sudo-proxy is local-only, so it is a server but never a connector. |
121140

122141
Two caveats:
@@ -130,5 +149,5 @@ Two caveats:
130149
process. sudo-proxy's own *server* — what the `start_server` tool spawns — is
131150
the `sudo-proxy` host daemon (Unix socket + TUI) that the MCP server proxies
132151
to. That daemon, `sudo-request`, `pkexec-cache`, and target *hosts* all sit
133-
below Glama's vocabulary; in MCP terms sudo-proxy is one server exposing three
152+
below Glama's vocabulary; in MCP terms sudo-proxy is one server exposing five
134153
tools.

‎docs/protocol.md‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,8 @@ The wire shape is always a list of stages: a single command is
2727
to `a | b | c`). The MCP `execute` tool accepts a convenience `argv`
2828
field and wraps it for you.
2929

30-
Field defaults (every field except `pipeline` is optional on the wire):
30+
Field defaults (every field is optional on the wire, but an `exec`
31+
request with an empty or missing `pipeline` is rejected at validation):
3132

3233
- `id` — defaults to a fresh UUIDv4.
3334
- `host`, `session`, `time`, `reason`, `env` — empty if omitted, but
@@ -37,6 +38,21 @@ Field defaults (every field except `pipeline` is optional on the wire):
3738
client that forgets the field still goes through approval + sudo).
3839
- `forward_agent` — defaults to `false`. Setting `true` is only valid
3940
when `privileged: false`.
41+
- `action` — defaults to `"exec"` (and is omitted from the wire for exec
42+
requests, keeping them byte-identical to the pre-1.1 format). See
43+
*Control actions* below.
44+
45+
**Control actions** (since 1.1): `"action": "stop"` asks the daemon to
46+
shut down cleanly — it prints a notice on its TTY (no approval prompt),
47+
replies `ok`, and exits; `"action": "ping"` replies `ok` with
48+
`"message": "pong"` without prompting. Both are sent with
49+
`"pipeline": []` and pass every gate an exec request does (same-UID
50+
check, field sanitization, freshness, replay protection), so a captured
51+
stop request cannot be replayed later. Compatibility: a pre-1.1 daemon
52+
ignores the unknown `action` key and rejects the empty pipeline at
53+
validation — before any prompt — with `"pipeline must not be empty"`;
54+
since every response carries the daemon's `version`, new clients use
55+
that reply to detect peers that predate control actions.
4056

4157
**Response:**
4258
```jsonc

‎packaging/mcpb/build-mcpb.sh‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
#!/usr/bin/env sh
2+
# Build an MCPB bundle (.mcpb) for the sudo-proxy-mcp MCP server.
3+
#
4+
# An .mcpb file is a zip of a manifest.json (which pins `sudo-proxy-mcp` as the
5+
# entry point) plus the binary itself. Unlike the crates.io package, this lets
6+
# MCP clients and directory probes launch the *MCP server* binary directly —
7+
# `cargo install sudo-proxy` installs four binaries and the registry has no way
8+
# to say "run sudo-proxy-mcp, not sudo-proxy". See docs/mcp.md.
9+
#
10+
# Usage: build-mcpb.sh <version> <bin_dir> <out_dir>
11+
# version release version, e.g. 1.1.0 (injected into the manifest)
12+
# bin_dir directory containing the built `sudo-proxy-mcp` binary
13+
# out_dir where to write the .mcpb (and its .sha256)
14+
#
15+
# Prints the sha256 to stdout and writes <out_dir>/<name>.mcpb.sha256.
16+
set -eu
17+
18+
VERSION="${1:?version required}"
19+
BIN_DIR="${2:?bin_dir required}"
20+
OUT_DIR="${3:?out_dir required}"
21+
22+
HERE=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
23+
MANIFEST_SRC="$HERE/manifest.json"
24+
BIN="$BIN_DIR/sudo-proxy-mcp"
25+
NAME="sudo-proxy-mcp-v${VERSION}-x86_64-linux.mcpb"
26+
OUT="$OUT_DIR/$NAME"
27+
28+
[ -f "$BIN" ] || { echo "error: $BIN not found" >&2; exit 1; }
29+
30+
mkdir -p "$OUT_DIR"
31+
STAGE=$(mktemp -d)
32+
trap 'rm -rf "$STAGE"' EXIT
33+
34+
# Canonical manifest content lives in manifest.json; only the version is injected
35+
# so it always tracks the release tag (single source of truth = Cargo.toml/tag).
36+
jq --arg v "$VERSION" '.version = $v' "$MANIFEST_SRC" > "$STAGE/manifest.json"
37+
cp "$BIN" "$STAGE/sudo-proxy-mcp"
38+
chmod +x "$STAGE/sudo-proxy-mcp"
39+
40+
rm -f "$OUT"
41+
# -X: no extra file attributes/timestamps -> reproducible-ish archive.
42+
( cd "$STAGE" && zip -qX "$OUT" manifest.json sudo-proxy-mcp )
43+
44+
SHA=$(sha256sum "$OUT" | awk '{print $1}')
45+
printf '%s' "$SHA" > "$OUT.sha256"
46+
echo "$SHA"

‎packaging/mcpb/manifest.json‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
{
2+
"manifest_version": "0.3",
3+
"name": "sudo-proxy",
4+
"version": "1.1.0",
5+
"description": "Privileged command execution proxy with human approval via pkexec or sudo",
6+
"author": {
7+
"name": "Tarides"
8+
},
9+
"homepage": "https://github.com/tarides/sudo-proxy",
10+
"documentation": "https://github.com/tarides/sudo-proxy/blob/main/docs/mcp.md",
11+
"server": {
12+
"type": "binary",
13+
"entry_point": "sudo-proxy-mcp",
14+
"mcp_config": {
15+
"command": "${__dirname}/sudo-proxy-mcp",
16+
"args": []
17+
}
18+
},
19+
"compatibility": {
20+
"platforms": ["linux"]
21+
}
22+
}

‎server.json‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
"name": "io.github.tarides/sudo-proxy",
44
"title": "sudo-proxy",
55
"description": "Privileged command execution proxy with human approval via pkexec or sudo",
6-
"version": "1.0.0",
6+
"version": "1.1.0",
77
"repository": {
88
"url": "https://github.com/tarides/sudo-proxy",
99
"source": "github"
@@ -13,7 +13,16 @@
1313
"registryType": "cargo",
1414
"registryBaseUrl": "https://crates.io",
1515
"identifier": "sudo-proxy",
16-
"version": "1.0.0",
16+
"version": "1.1.0",
17+
"transport": {
18+
"type": "stdio"
19+
}
20+
},
21+
{
22+
"registryType": "mcpb",
23+
"identifier": "https://github.com/tarides/sudo-proxy/releases/download/v1.1.0/sudo-proxy-mcp-v1.1.0-x86_64-linux.mcpb",
24+
"version": "1.1.0",
25+
"fileSha256": "SHA256-INJECTED-BY-PUBLISH-WORKFLOW",
1726
"transport": {
1827
"type": "stdio"
1928
}

0 commit comments

Comments
 (0)