toolkit-mcp-server

---

概述

日常开发实用工具：生成 ID、二维码和哈希，对值进行编码和解码，并查询公共 IP 或主机名的地理位置。除地理位置查询外，所有操作都在本地运行。

工具

工具	描述
toolkit_hash_value	将摘要（sha256/sha384/sha512/sha1/md5）生成为十六进制、base64 或 SRI 格式，或以恒定时间比较某个值与预期摘要
toolkit_generate_id	生成经密码学安全随机化的 UUIDv4、UUIDv7 或 ULID 标识符，每次调用最多生成 1000 个
toolkit_generate_qr	将文本或 URL 编码为 SVG、base64 PNG 或终端半区块格式的二维码
toolkit_encode_value	对 base64、base64url、十六进制或 URL 百分号编码进行编码或解码
toolkit_geolocate_ip	将公共 IP 或主机名解析为国家、城市、坐标、ASN 和时区
toolkit_check_network	受授权门控，默认关闭。 从服务主机执行 ping、traceroute、TCP 连通性检查或出口 IP 检查
toolkit_check_system	受授权门控，默认关闭。 检查服务主机的 OS、CPU、内存、平均负载或网络接口

能力参考

toolkit_hash_value _工具

• value 按 inputEncoding 读取（默认 utf8，也可为 hex、base64）；algorithm 为 sha256（默认）、sha384 或 sha512，也支持 sha1 和 md5，但仅用于校验和兼容；operation 为 generate 或 compare，省略时，如果提供了 expected，则执行比较
• generate 会返回按 digestEncoding 编码的 digest（默认 hex，也可为 base64；对于 SHA-2 算法，还可为 sri），以及 lengthInBytes；compare 会返回与 expected 比较后的 matches，expected 可为 hex、base64 或 SRI，也可包含多个条目的 npm integrity 值
• 无效的 expected 会导致 expected_malformed、expected_length_mismatch（提示会指出长度匹配的算法）或 expected_algorithm_mismatch

---

toolkit_generate_id _工具

• type 为 uuid_v4（默认）、uuid_v7 或 ulid；count 为 1–1000（默认值为 1）
• ids 始终恰好包含 count 个值；uuid_v7 和 ulid 批次即使在同一毫秒内也严格递增，并带有随机间隔，因此无法从一个 ID 推导出另一个

---

toolkit_generate_qr _工具

• data 在纠错级别 L 下最多为 2953 个 UTF-8 字节；在 M（默认）、Q 和 H 下容量更小；format 为 svg（默认）、png_base64 或 terminal；margin 为 0–20 个模块（默认值为 4），scale 为每个模块 1–32 px（默认值为 4）
• 返回 content、符号 version（1–40）、图像格式的 mimeType，以及 PNG 的 byteLength；png_base64 还会作为 MCP 图像块返回，terminal 则是针对深色背景绘制的纯 Unicode 半块字符
• 超出容量的输入会导致 data_too_large，并附带字节数；每边超过 2048 px 的 PNG 会导致 raster_too_large，并提供可用的缩放比例；svg 和 terminal 没有像素上限

---

toolkit_encode_value _工具

• 必须指定 operation（encode 或 decode）和 encoding（base64、base64url、hex、url）；输入中的 hex、base64 和 base64url 空白字符会被忽略，因此换行的 MIME 和 PEM 内容可直接解码
• 解码会返回 result，默认为 utf8 文本；若 outputEncoding 指定为 hex 或 base64，则会无损返回字节并在编码间转码；无效输入会导致 decode_failed，二进制字节则会导致 decode_not_utf8，而不会被替换字符取代

---

toolkit_geolocate_ip _工具

• target 为 IPv4/IPv6 地址或点分格式的主机名，并会先进行 DNS 解析；私有或保留地址会导致 private_target，无法解析的主机名会导致 unresolvable_host
• 也可以改为发送 targets（最多 1000 个），但不能同时发送两者：前 100 个会按顺序返回在 results 中，并附带每个目标的错误；failedCount 统计失败数量，unprocessedTargets 列出可重新提交的其余目标
• 返回 country、countryCode、region、city、latitude/longitude、asn、org 和 timezone，并附带 resolvedIp 和 source；proxy、hosting 或 mobile 中的 true 表示位置信息描述的是基础设施，而非个人
• 默认通过明文 HTTP 使用无需密钥的 ip-api 免费层（TOOLKIT_GEO_BASE_URL、TOOLKIT_GEO_API_KEY）；结果按解析后的 IP 缓存
• 单次查询和批量查询的速率限制各自独立（TOOLKIT_GEO_RATE_LIMIT_PER_MIN=45、TOOLKIT_GEO_BATCH_RATE_LIMIT_PER_MIN=15）；被拒绝的请求会返回 rate_limited 以及需等待的秒数，缓存命中不受限制

---

toolkit_check_network _工具

• mode 为 ping、traceroute、connectivity 或 public_ip；除 public_ip 外都必须指定 target，connectivity 还需要指定 port（1–65535）；count 为 1–10 次 ping（默认值为 3），timeoutMs 为 100–30000（默认值为 3000）
• 无响应的主机返回 reachable: false，而不是错误；ping 会添加 rttMs、sent、received 和 packetLossPercent，connectivity 会添加 outcome（open、refused、timeout、unreachable），traceroute 会返回 hops；无法解析的主机，或无法运行的 ping/traceroute 二进制文件，会以 unreachable 失败
• 仅当 TOOLKIT_ENABLE_NET_DIAGNOSTICS=true 时才会注册；除非 TOOLKIT_ALLOW_PRIVATE_NETWORK=true，否则私有和保留目标会以 private_target_blocked 失败

---

toolkit_check_system _工具

• what 为 os、cpu、memory、load 或 interfaces；恰好填充一个匹配的类别对象
• memory.availableBytes 是可分配的剩余内存；在容器内存限制下会显示 limitBytes；totalBytes、freeBytes 和 usedBytes 是原始操作系统数据，其中已使用的内存包含可回收缓存
• 仅当 TOOLKIT_ENABLE_SYSTEM_INFO=true 时才会注册，因为 os 和 interfaces 会披露主机拓扑和版本详情

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔的身份验证（none / jwt / oauth）、可切换的存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

本工具包特有功能：

• 哈希、ID 生成、QR 编码及编解码均在进程内通过 node:crypto 和 qrcode 库完成，不会调用上游服务
• 地理位置查询会调用服务提供方，而非目标地址；并检查 DNS 解析出的 IP 是否属于私有地址范围，确保主机名无法访问内部地址
• 默认拒绝的门控机制：除非启用，否则 toolkit_check_network 和 toolkit_check_system 不会出现在 tools/list 中。这两者报告的是服务端主机的信息，而非调用方的信息，因此适用于本地或可自托管部署
• 两级网络门控：启用诊断后，私有、回环、链路本地和保留目标（包括云元数据端点）仍会被屏蔽，直至设置 TOOLKIT_ALLOW_PRIVATE_NETWORK=true

便于 Agent 使用的输出：

• 来源信息：地理位置查询会返回 resolvedIp 和 source，对于服务提供方未报告的字段则予以省略，而不凭空编造
• 响应整形：服务提供方返回的字符串最长为 256 个字符，并会移除控制字符，避免由注册表控制的文本（如 org）塞满或破坏模型上下文
• 判别式输出：operation、format、mode 和 what 会回显实际执行的操作，且只会填充对应分支的字段
• 类型化失败：每种已声明的失败都包含 reason 和恢复提示；冲突输入（expected 与 generate 同时出现，或 outputEncoding 与 encode 同时出现）会按名称拒绝，而非忽略

开始使用

公共托管实例

公共实例位于 https://toolkit.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向此实例：

{
  "mcpServers": {
    "toolkit-mcp-server": {
      "type": "streamable-http",
      "url": "https://toolkit.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地

将以下内容添加到 MCP 客户端配置文件中。无需 API 密钥。

{
  "mcpServers": {
    "toolkit-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/toolkit-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "toolkit-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/toolkit-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "toolkit-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/toolkit-mcp-server:latest"]
    }
  }
}

若要启用受门控的主机探测工具，请将相应标志添加到 env 中（Docker 使用 -e）：

"env": {
  "MCP_TRANSPORT_TYPE": "stdio",
  "TOOLKIT_ENABLE_NET_DIAGNOSTICS": "true",
  "TOOLKIT_ENABLE_SYSTEM_INFO": "true"
}

若要使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥——地理位置查询默认使用无需密钥的 ip-api 免费层级。

安装

1. 克隆代码仓库：

git clone https://github.com/cyanheads/toolkit-mcp-server.git

2. 进入目录：

cd toolkit-mcp-server

3. 安装依赖项：

bun install

配置

所有变量均为可选项。

变量	说明	默认值
TOOLKIT_ENABLE_NET_DIAGNOSTICS	注册受开关控制的 toolkit_check_network 工具。在托管或共享部署中请保持关闭。	false
TOOLKIT_ENABLE_SYSTEM_INFO	注册受开关控制的 toolkit_check_system 工具。	false
TOOLKIT_ALLOW_PRIVATE_NETWORK	启用网络诊断后，允许访问私有、保留、环回和链路本地目标。	false
TOOLKIT_GEO_API_KEY	地理位置接口所需的 API 密钥（如有）。	无
TOOLKIT_GEO_BASE_URL	兼容 ip-api 的接口基础 URL。默认地址无需密钥，但使用明文 HTTP；ip-api 的 HTTPS 接口需要付费密钥。	http://ip-api.com
TOOLKIT_GEO_CACHE_TTL_SECONDS	地理位置内存缓存的存活时间（秒）。	3600
TOOLKIT_GEO_RATE_LIMIT_PER_MIN	每分钟最多地理位置请求数；缓存命中不计入。	45
TOOLKIT_GEO_BATCH_RATE_LIMIT_PER_MIN	每分钟最多批量地理位置请求数，单独计数。	15
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
OTEL_ENABLED	启用 OpenTelemetry。	false

完整的可选覆盖项列表请参见 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security, changelog sync
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t toolkit-mcp-server .
docker run --rm -p 3010:3010 toolkit-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/toolkit-mcp-server。默认会安装 OpenTelemetry 对等依赖项；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口——注册五个始终启用的工具，两个受开关控制的工具仅在相应开关开启时注册。
src/config	使用 Zod 解析并验证服务专属环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。共七个工具，其中五个始终启用，两个受开关控制。
src/services/geo	地理位置服务——DNS 解析、带重试的服务商调用、规范化、内存缓存。
src/services/network	网络诊断服务，以及共享的目标架构和私有地址范围分类器。
tests/	工具（tests/tools）和服务（tests/services）的 Vitest 测试套件。

开发指南

开发指南和架构规则请参见 CLAUDE.md / AGENTS.md。简而言之：

• 处理器抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 存储租户范围内的数据
• 在 src/index.ts 的 createApp() 数组中注册新工具；探测主机的工具仅在启用开关开启时注册
• 包装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；切勿编造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参见 LICENSE。