Repository navigation
Description
Summary
Publish libtmux-mcp as an OCI image on ghcr.io that runs its own tmux, and list it in the MCP Registry (repo, server.json reference) as io.github.libtmux/libtmux-mcp-java. The registry has no Maven package type, so the image is the only way in. Split out of #23.
Motivation
The registry accepts npm, pypi, nuget, cargo, oci and mcpb packages (package types), so the Maven Central jar alone cannot be listed. A container that drives the host's tmux is also fragile. A tmux client only talks to a server of a compatible protocol version, and the tmux client exits on a mismatch (client.c):
fprintf(stderr, "protocol version mismatch "Evidence
Client and server versions, and the server.json validator
Clients of each supported release against a tmux 3.7c server:
- 3.7c and 3.6 work.
- 3.5a, 3.4, 3.3a and 3.2a fail with
server exited unexpectedly. The server keeps running.
This server.json, written against the 2025-12-11 schema, passes mcp-publisher validate against the live registry. A copy with no $schema and a name containing a space was rejected with a 422 naming all three errors.
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"name": "io.github.libtmux/libtmux-mcp-java",
"title": "libtmux MCP (Java)",
"description": "Drive tmux sessions, windows and panes from an agent: read screens, run commands and wait for them.",
"version": "0.0.1-alpha.16",
"repository": { "url": "https://github.com/libtmux/libtmux-java", "source": "github", "subfolder": "libtmux-mcp" },
"packages": [
{
"registryType": "oci",
"identifier": "ghcr.io/libtmux/libtmux-mcp-java:0.0.1-alpha.16",
"transport": { "type": "stdio" },
"environmentVariables": [
{ "name": "LIBTMUX_TOOLSETS", "description": "Toolsets to expose: any of inspect,manage,execute,teardown", "isRequired": false, "isSecret": false }
]
}
]
}The image itself has not been built: no container engine was available while this was investigated.
Proposal
The invariants are the non-negotiable part; everything under intent is open.
Invariants
- The server's stdout stays protocol-only.
- The image's
io.modelcontextprotocol.server.namelabel equalsserver.json'sname. The registry verifies ownership through it. - The default mode does not depend on the host's tmux version.
- An image, or a registry entry, is published only from a release that passed its gates.
Intent (non-binding)
- The image runs its own pinned tmux, and users mount the directories their sessions need, as the filesystem MCP server's examples do. Its base is either a Java 25 JRE or the native binary from Ship GraalVM native binaries of
libtmux-mcpandtmux-workspace#28. - Build
linux/amd64andlinux/arm64on native runners, and pushghcr.io/libtmux/libtmux-mcp-java:<version>. - Keep
server.jsonat the root. Publish from the release job withmcp-publisher login github-oidc, which needsid-token: writeand no stored secret (GitHub Actions). Runmcp-publisher validatein the release rehearsal. - Document the host-socket mode as a recipe, with the version caveat above.
- Later, submit to the Docker MCP Catalog. Its
server.yamlmodels secrets and environment variables, not host socket mounts.
Not doing
- Host-socket mode as the default.
.mcpbbundles.
Activity
Docs(ci): Follow the rebased docs revision