cacheport

cacheport

cacheport is a small, honest front end for a Redis cache. It stores a value under a key (optionally with an expiry), reads it back, deletes one key or several at once, and lists the keys that match a glob pattern. That is the whole job, and it does it by speaking Redis's own wire protocol, RESP, over a plain TCP socket — there is no client library bundled and nothing between you and the server's actual replies.

When Redis is not there, cacheport says so. The MCP server starts and lists its tools with no server behind it at all; only an actual operation touches the socket, and a refused connection or a server error comes back as an error, never as a made-up value.

Install

npx @reneturcios/cacheport get mykey

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/cacheport

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

CLI

# Store a value, with and without an expiry
cacheport set greeting "hello world"
cacheport set session abc123 --expire-seconds 3600

# Read it back (prints (nil) when the key is gone)
cacheport get greeting

# Delete one key, or several in one call; prints how many were removed
cacheport delete greeting
cacheport delete session old-session temp-key

# List keys; the pattern is a Redis glob and defaults to *
cacheport list
cacheport list "user:*"

# Start the MCP server (Redis URL optional, see below)
cacheport mcp redis://localhost:6379

cacheport --version

Exit codes: 0 on success, 1 when the cache or the connection fails (the error says which), 2 for usage errors.

The target is a normal Redis URL: redis:// or rediss://, with a host, an optional port (default 6379), an optional password in the userinfo, and an optional database index as the path (/2 selects db 2). Commands and mcp alike can take the target from the environment instead: REDIS_URL first, then CACHEPORT_REDIS_URL, then the split variables REDIS_HOST / REDIS_PORT / REDIS_PASSWORD (or their CACHEPORT_ spellings). With none of those set, cacheport talks to localhost:6379.

How it talks to Redis

Each operation opens a connection, writes the command as a RESP array of bulk strings, and decodes the reply — a simple string for SET, a bulk string (or nil) for GET, an integer for DEL, an array for KEYS. When the target carries a password or a non-zero database index, AUTH and SELECT run first on the same connection. Server error replies surface with the server's own message attached.

An expiry passed to set is sent as EX <seconds>; fractional seconds are floored, and a non-positive expiry is refused before anything is sent.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/cacheport mcp redis://localhost:6379

MCP client configuration:

{
  "mcpServers": {
    "cacheport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/cacheport", "mcp"],
      "env": { "REDIS_URL": "redis://localhost:6379" }
    }
  }
}

Tools

Tool	Input	What it returns
set	key (string, required), value (string, required), expireSeconds (number, optional)	The server status reply, normally OK.
get	key (string, required)	The stored string, or null when the key does not exist.
delete	key (string or array of strings, required)	How many keys were actually removed.
list	pattern (string, optional, default *)	The key names matching the glob pattern.

Connection failures and server errors come back as tool errors with the underlying message — never as invented values.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network, no live Redis
npm run dev     # run the CLI from source via tsx

The core logic sits behind an injectable executor interface, which is what the test suite drives: the RESP encoder and decoder, URL parsing, and all four operations are covered against a fake in-memory executor.

License

MIT — see LICENSE.