cacheport

Name: cacheport
Author: CloudCorpRecords

本地服务

github.com/CloudCorpRecords数据库02 周前更新

代码仓库

关于 cacheport

cacheport 是面向 Redis 的键值缓存 CLI 与 MCP 服务，使用 RESP 协议通过 TCP 连接 Redis。它适合需要通过简单操作存取缓存的开发者，并在连接或服务器出错时返回错误，而不伪造结果。

主要功能

01按键写入和读取字符串
02设置写入过期时间
03删除一个或多个键
04按 glob 模式列出键
05通过 RESP 与 Redis 通信

适用场景

01保存带过期时间的缓存值
02读取或删除缓存键
03按模式检查 Redis 中的键

MCP 相关

stdio MCP 服务向客户端提供 set、get、delete 和 list 工具，用于操作 Redis 键值。操作会连接配置的 Redis 地址，连接失败和服务器错误会作为错误返回。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cloudcorprecords-cacheport": {
      "command": "npx",
      "args": [
        "-y",
        "@reneturcios/cacheport"
      ]
    }
  }
}

启动命令npx -y @reneturcios/cacheport

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@reneturcios/cacheport0.1.0stdio

ocighcr.io/cloudcorprecords/cacheport:0.1.0stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
key	string	是	要设置的 Redis 键
value	string	是	要存储在该键下的字符串值
expireSeconds	number	否	可选的过期时间（秒）；经过该时间后键将过期，且必须为正数

详细介绍

cacheport

cacheport 是一个小巧、简洁的 Redis 缓存前端。它会在键下存储一个值（可选设置过期时间）、读取该值、删除一个或多个键，并列出与 glob 模式匹配的键。它的全部职责就是这些，而且它通过普通 TCP 套接字使用 Redis 自己的线路协议 RESP 与 Redis 通信——不捆绑客户端库，也没有任何东西夹在你和服务器的实际回复之间。

Redis 不可用时，cacheport 会如实告知。MCP 服务即使没有后端服务器也会启动并列出其工具；只有实际执行操作时才会连接套接字，而连接被拒绝或服务器返回错误时，都会作为错误返回，绝不会捏造一个值。

安装

npx @reneturcios/cacheport get mykey

也可以运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/cacheport

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

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

退出码：成功时为 0；缓存或连接失败时为 1（错误信息会说明原因）；用法错误时为 2。

目标地址使用标准 Redis URL：redis:// 或 rediss://，包含主机、可选端口（默认 6379）、userinfo 中的可选密码，以及作为路径的可选数据库索引（/2 表示选择数据库 2）。命令和 mcp 都可以改为从环境变量读取目标地址：优先使用 REDIS_URL，然后是 CACHEPORT_REDIS_URL，再然后是拆分变量 REDIS_HOST / REDIS_PORT / REDIS_PASSWORD（或对应的 CACHEPORT_ 前缀变量）。如果这些变量都未设置， cacheport 会连接 localhost:6379。

与 Redis 的通信方式

每次操作都会建立一个连接，将命令写为 RESP bulk string 数组，然后解码回复——SET 返回简单字符串，GET 返回 bulk string（或 nil），DEL 返回整数，KEYS 返回数组。当目标地址包含密码或非零数据库索引时，会先在同一连接上执行 AUTH 和 SELECT。服务器错误回复会附带服务器自己的错误信息。

传给 set 的过期时间会以 EX <seconds> 的形式发送；小数秒会向下取整，非正数过期时间会在发送任何内容之前被拒绝。

MCP 服务

同一个二进制文件支持两种用法。mcp 子命令会启动一个 stdio MCP 服务：

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

MCP 客户端配置：

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

工具

工具	输入	返回内容
`set`	`key`（字符串，必填），`value`（字符串，必填），`expireSeconds`（数字，可选）	服务器状态回复，通常为 `OK`。
`get`	`key`（字符串，必填）	存储的字符串；键不存在时返回 `null`。
`delete`	`key`（字符串或字符串数组，必填）	实际删除的键数。
`list`	`pattern`（字符串，可选，默认 `*`）	与 glob 模式匹配的键名。

连接失败和服务器错误会作为工具错误返回，并附带底层错误信息——绝不会捏造值。

开发

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

核心逻辑位于可注入的执行器接口之后，测试套件会驱动该接口：RESP 编码器和解码器、URL 解析以及全部四种操作，都会使用虚假的内存中执行器进行测试。