公共托管服务器： https://toolkit.caseyjhand.com/mcp
七个工具。其中五个始终可用，无需任何配置——纯计算工具加上一个无 SSRF 风险的 IP 查询工具。另外两个会探测服务器主机，在 tools/list 中默认不出现，除非你主动启用，且默认关闭（fail-closed）。
工具 | 描述 |
| 生成加密摘要（sha256/sha512/sha1/md5），或对值进行常量时间比较，与预期摘要进行比对。 |
| 生成加密随机标识符——UUIDv4、UUIDv7 或 ULID——可单个生成，也可批量生成最多 1000 个。 |
| 将文本或 URL 编码为 QR 码，输出格式为 SVG 标记、base64 PNG 或终端可渲染字符串。 |
| 对值进行编码或解码，支持 base64、base64url、hex 或 URL 百分比编码，可双向操作。 |
| 将公共 IP 或主机名解析为地理和网络元数据——国家、城市、坐标、ASN、时区。 |
| 受限，默认关闭。 只读网络诊断，从服务器主机执行——ping、traceroute、TCP 连接性或出口 IP 检测。 |
| 受限，默认关闭。 报告服务器主机系统状态的某个方面——操作系统、CPU、内存、平均负载或网络接口。 |
toolkit_hash_value生成摘要，或对值进行常量时间验证，与预期值比对。
operation：generate（小写十六进制摘要）或 compare（通过 timingSafeEqual 进行时序安全检查）
算法：sha256（默认）和 sha512 用于安全场景；sha1 和 md5 仅用于校验和和文件完整性兼容——绝不可用于密码或签名
inputEncoding 将 value 视为 utf8（默认）、hex 或 base64，因此二进制数据可跳过一轮解码往返
典型用法：将下载文件与供应商发布的校验和进行匹配
toolkit_generate_id从平台 CSPRNG 生成加密随机标识符——这是生成不可预测 ID 的正确来源，不同于模型自行构造的值。
type：uuid_v4（随机，默认）、uuid_v7（按创建时间排序，可排序）或 ulid（26 个字符的 Crockford base32，按字典序可排序）
count 可在一次调用中批量生成最多 1000 个；返回的 ids 数组始终恰好包含 count 个值
uuid_v7 和 ulid 批次是单调递增的——即使在同一毫秒内也严格递增——因此 ids 保持按创建顺序排序
只读——生成操作不改变任何状态——但绝不幂等，因此客户端不会缓存或去重一个批次
toolkit_generate_qr将文本或 URL 编码为 QR 码。
format：svg（内联标记）、png_base64（带有 mimeType 和 byteLength 的栅格字节）或 terminal（Unicode 块字符字符串）
errorCorrection（L/M/Q/H）在数据容量与容错能力之间权衡；margin 设置静区宽度；scale 设置栅格输出的每模块像素数
返回的 version（1–40）反映编码数据的密度
png_base64 还会作为 MCP 图像内容块提供，因此读取 content[] 的客户端无需解码 structuredContent 即可渲染二维码
渲染的 PNG 每边限制在 2048 像素以内——(modules + 2 × margin) × scale——因此高密度符号在较大 scale 下会被拒绝，并返回带有 raster_too_large 类型的错误，提示一个合适的 scale 值；svg 和 terminal 无此限制
data 最大为 2953 字节——绝对上限（版本 40，L 级，字节模式）；在更高的 errorCorrection 级别下可用容量更低，因此超出容量的输入会被拒绝，并返回带有 data_too_large 类型的错误，而非通用失败
toolkit_encode_value对值进行编码或解码，支持双向操作。
encoding：base64、base64url（URL 安全字母表）、hex 或 url（百分比编码）
operation：encode（原始 UTF-8 → 编码）或 decode（编码值 → 文本）
格式错误的解码输入返回带有 decode_failed 类型的错误及恢复提示，而非静默尽力解码
toolkit_geolocate_ip将公共 IP 或主机名解析为地理和网络元数据。
返回国家、地区、城市、纬度/经度、ASN、所属组织及时区
proxy、hosting 和 mobile 标志用于指示地址是否为代理/VPN/Tor 出口、数据中心网络或移动运营商——其中任何一个为 true 表示坐标描述的是基础设施，而非个人。当提供商未报告时，这些字段不存在
主机名首先通过 DNS 解析；resolvedIp 回显实际定位的 IP，source 指明提供方名称
无 SSRF——服务器调用的是提供方，永远不会调用目标地址；解析后的 IP 会再次检查是否为私有地址，私有/保留地址会被拒绝（它们没有公共地理定位信息）
尽力而为且受限于提供方：VPN、代理、移动 NAT 和任播都会影响 IP 定位，精度最多到城市级别，缺失字段报告为未知而非编造
提供方提供的字符串会被截断并去除控制字符后才进入响应，因此注册中心控制的文本（org、isp、as）不会淹没或影响模型上下文格式
默认无需密钥（ip-api 免费版，使用明文 HTTP——参见 TOOLKIT_GEO_BASE_URL）；结果按解析后的 IP 缓存于内存中，并有固定条目上限
toolkit_check_network受限——仅在 TOOLKIT_ENABLE_NET_DIAGNOSTICS=true 时注册。只读网络诊断，从服务器主机执行。
mode：ping（ICMP 往返）、traceroute（到目标的跃点路径）、connectivity（向 target 的 port 进行原始 TCP 连接）或 public_ip（主机自身的出口 IP）
无响应的主机报告为 reachable: false——这是一个有效结果，而非错误
诊断的是服务器自身的网络，因此在本地或自托管部署中很有用；要访问私有/保留/内部目标，还需 TOOLKIT_ALLOW_PRIVATE_NETWORK=true，这默认会阻止云元数据端点
toolkit_check_system受限——仅在 TOOLKIT_ENABLE_SYSTEM_INFO=true 时注册。报告服务器主机系统状态的某个方面，只读。
what：os、cpu、memory、load 或 interfaces
每次调用只填充一个方面对象，与 what 匹配
描述的是运行此服务器的主机，而非调用客户端——在本地或自托管部署中有意义；默认关闭，因为 os 和 interfaces 会暴露主机拓扑和版本细节
Related MCP server: IT Tools MCP Server
基于 @cyanheads/mcp-ts-core 构建：
声明式工具定义——每个工具一个文件，框架负责注册和验证
统一错误处理——处理函数抛出错误，框架捕获、分类并格式化
类型化错误契约——每个可能失败的工具都会声明其失败原因，并附带代理可操作的恢复提示
可插拔认证：none、jwt、oauth
结构化日志，可选 OpenTelemetry 追踪
STDIO 和 Streamable HTTP 传输
工具包特有：
默认关闭的防护机制——两个探测主机的工具在 tools/list 中不出现，除非显式启用，因此托管实例不会暴露 SSRF 或信息泄露面
双层网络防护——即使启用了诊断，私有/保留/回环/链路本地目标（包括云元数据端点）也保持阻断，直到第二个标志允许它们
CSPRNG 支持的原语——标识符和摘要来自平台加密源，哈希比较通过 timingSafeEqual 实现常量时间比较
无 SSRF 的地理定位——服务器调用提供方，然后在查询前再次检查 DNS 解析后的 IP 是否在私有范围，因此主机名无法将请求走私到内部地址
对代理友好的输出：
来源追溯——地理定位回显解析后的 IP 并指明提供方名称；上游缺失字段报告为未知，绝不编造
故障但有效的结果——不可达主机返回 reachable: false 而非错误，因此调用者基于数据进行分支判断，而非异常文本
类型化失败原因——解码失败、缺失摘要和被阻止的私有目标各自携带结构化的原因及下一步恢复提示
公共实例地址为 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/mcpBun v1.3.2 或更高版本（或 Node.js v24+）。
无需 API 密钥——地理定位默认使用无密钥的 ip-api 免费版。
克隆仓库：
git clone https://github.com/cyanheads/toolkit-mcp-server.git进入目录：
cd toolkit-mcp-server安装依赖：
bun install每个变量都是可选的。服务器特定的选项在启动时通过 src/config/server-config.ts 中的 Zod 模式进行验证。
变量 | 描述 | 默认值 |
| 注册受门控的 |
|
| 注册受门控的 |
|
| 启用网络诊断时，允许私有/保留/回环目标。这是第二道显式门控。 |
|
| 地理定位端点的 API 密钥（如果需要）。 | 无 |
| 兼容 ip-api 的地理定位端点的基础 URL。默认是明文 HTTP——ip-api 的 HTTPS 端点不属于无密钥免费套餐，如果没有付费密钥，会返回 |
|
| 内存中地理定位缓存的 TTL（秒）。 |
|
| 每分钟最大地理定位请求数。 |
|
| 传输方式： |
|
| HTTP 服务器的端口。 |
|
| 认证模式： |
|
| 日志级别（RFC 5424）。 |
|
| 启用 OpenTelemetry 检测（跨度、指标、完成日志）。 |
|
请参阅 .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 specdocker build -t toolkit-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 toolkit-mcp-serverDockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志记录到 /var/log/toolkit-mcp-server。OpenTelemetry 对等依赖项默认安装——使用 --build-arg OTEL_ENABLED=false 构建以省略它们。
目录 | 用途 |
|
|
| 使用 Zod 进行服务器特定的环境变量解析和验证。 |
| 工具定义（ |
| 地理定位服务——DNS 解析、带重试/退避的提供商调用、标准化、内存缓存。 |
| 网络诊断服务，以及共享的目标验证器和私有范围分类器。 |
| 单元测试和集成测试，镜像 |
请参阅 CLAUDE.md / AGENTS.md 获取开发指南和架构规则。简要说明：
处理程序抛出异常，框架捕获——工具逻辑中不使用 try/catch
使用 ctx.log 进行请求范围的日志记录，使用 ctx.state 进行租户范围的存储
在 src/index.ts 的 createApp() 数组中注册新工具
两个主机探测工具在其启用标志后注册；网络目标门控在 DNS 解析后验证——切勿为无法定位或无法访问的目标伪造结果
欢迎提交 Issue 和 Pull Request。提交前请运行检查和测试：
bun run devcheck
bun run testApache-2.0——详情请参阅 LICENSE。
Encode or decode a value across base64, base64url, hex, or URL (percent) encoding, in either direction. Set operation to "encode" to transform raw UTF-8 text into the chosen encoding, or "decode" to recover the original text from an encoded value. base64url uses the URL-safe alphabet (- and _ instead of + and /); url applies encodeURIComponent / decodeURIComponent. Decoding a value that is malformed for the chosen encoding is reported as a recoverable error, not a silent best-effort.
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | The value to transform — raw text for encode, an encoded string for decode. | |
| encoding | Yes | The encoding to apply: base64, URL-safe base64url, hex, or URL percent-encoding. | |
| operation | Yes | "encode" transforms text into the encoding; "decode" recovers text from an encoded value. |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| result | No | The transformed value (encoded text, or the decoded original). |
| encoding | No | The encoding that was applied. |
| operation | No | The operation that was performed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already supply readOnlyHint and idempotentHint, and the description adds strong behavioral context beyond that: base64url alphabet substitution, encodeURIComponent/decodeURIComponent semantics, and recoverable-error behavior for malformed decodes. This tells the agent exactly what to expect without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three focused sentences: the first states scope, the second explains operation semantics, and the third adds essential encoding-specific and error behavior. No filler, repetition of schema fields, or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a stateless encode/decode utility with an output schema and fully documented parameters, this is complete: it covers all four encodings, both directions, and the failure mode. Nothing necessary for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are fully described in the schema (100% coverage), so the baseline is 3. The description adds extra practical meaning for encoding ('base64url uses the URL-safe alphabet', 'url applies encodeURIComponent / decodeURIComponent') and clarifies that value is raw text for encode vs an encoded string for decode, warranting a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: encode or decode a value across four named encodings, in either direction. This clearly distinguishes it from siblings like hashing, ID generation, QR generation, and IP geolocation without needing to inspect them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit operation-level guidance: set operation to "encode" or "decode" depending on the desired direction, with clear expectations for each. It does not name alternative tools or exclusion criteria, so sibling differentiation is implicit by domain rather than explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mint cryptographically-random identifiers using the platform CSPRNG — the correct source for IDs that must be unpredictable, unlike model-generated values. type selects the format: uuid_v4 (random, the default), uuid_v7 (time-ordered, sortable by creation), or ulid (26-char Crockford-base32, lexicographically sortable). Set count to mint a batch in one call (up to 1000); the returned ids array always contains exactly count values and is never truncated. For uuid_v7 and ulid, a batch is monotonic — strictly increasing even within the same millisecond — so the ids array stays in sorted creation order. IDs from this tool feed into toolkit_generate_qr (pass ids[0] as data) to create a scannable code.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Identifier format: uuid_v4 (random), uuid_v7 (time-ordered), or ulid (sortable Crockford-base32). | uuid_v4 |
| count | No | How many identifiers to mint (1–1000). The full batch is always returned. |
| Name | Required | Description |
|---|---|---|
| ids | No | The minted identifiers — exactly count of them, in mint order; for uuid_v7 and ulid that order is strictly increasing (sorted by creation). |
| type | No | The identifier format that was minted. |
| count | No | The number of identifiers minted (equals the requested count). |
| error | No | Present when the call failed. Absent on success. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true and idempotentHint=false. The description enriches this by clarifying that the result is cryptographically random, that the ids array always contains exactly count values and is never truncated, and that batches for uuid_v7/ulid are monotonic and sorted. These behavioral details go beyond what annotations provide, though it does not mention failure modes or performance characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph with zero filler. It front-loads the core purpose, then details types and count, then adds behavioral guarantees and a cross-reference to a related tool. Every sentence earns its place and the structure is logical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only 2 parameters, 100% schema coverage, and a provided output schema, the description is complete. It covers the purpose, usage, parameter semantics, behavioral guarantees, and even a downstream use case. There is nothing an agent needs to know to call it correctly that is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% description coverage for both parameters. The description adds value by explaining the semantic difference between uuid_v4, uuid_v7, and ulid (including sortability), the default behavior, and the monotonic ordering within a batch — none of which are in the schema descriptions. It also clarifies the count semantics (exact return size).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action ('Mint cryptographically-random identifiers') and a precise resource ('platform CSPRNG'), and immediately distinguishes it from the alternative of model-generated values. It also names the three output formats with their distinct properties, so an agent can clearly tell this tool apart from siblings like toolkit_hash_value or toolkit_generate_qr.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool ('IDs that must be unpredictable') and when not ('unlike model-generated values'), and it names a concrete downstream use case (feed ids[0] into toolkit_generate_qr). This leaves no ambiguity about the appropriate context of use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Encode text or a URL into a QR code. data is the content to encode (a link, a generated identifier such as toolkit_generate_id's ids[0], or any string). format selects the output: svg returns inline SVG markup, png_base64 returns base64-encoded PNG bytes (with mimeType and byteLength), and terminal returns a block of Unicode block characters renderable in a monospace terminal. errorCorrection (L/M/Q/H) trades data capacity for damage tolerance, margin sets the quiet-zone width, and scale sets pixels per module for raster output. The returned version (1–40) reflects how dense the encoded data is. png_base64 renders (modules + 2 × margin) × scale pixels per side and rejects anything past 2048 px with a typed raster_too_large error, so a dense symbol needs a lower scale; svg carries no such limit.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | The text or URL to encode. 2953 is the absolute ceiling (QR version 40, level L, byte mode); usable capacity drops at higher errorCorrection levels, so over-capacity data is rejected with a typed data_too_large error rather than a generic failure. | |
| scale | No | Pixels per module for raster (png_base64) output. Ignored for terminal. png_base64 also bounds the whole image at 2048 px per side, so a dense symbol or a wide margin admits a lower scale than 32. | |
| format | No | Output format: svg markup, png_base64 (raster bytes), or a terminal-renderable string. | svg |
| margin | No | Quiet-zone width in modules around the symbol. The spec recommends 4. | |
| errorCorrection | No | Error-correction level: L (~7% recoverable) to H (~30%). Higher tolerance lowers data capacity. | M |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| format | No | The format that was produced. |
| content | No | The QR artifact: SVG markup, a terminal-renderable string, or base64 PNG bytes for png_base64. |
| version | No | QR symbol version (1–40); higher versions hold denser data and indicate denser content. |
| mimeType | No | MIME type of content for image formats. Absent for the terminal format. |
| byteLength | No | Decoded byte size of the PNG. Present only for png_base64. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses important runtime behavior: exact output forms per format, the returned QR version, the png_base64 pixel formula, the 2048-pixel rejection limit, and the typed raster_too_large error. It also notes that svg has no such size limit, which is valuable behavioral context an agent cannot infer from annotations or schema alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and then proceeds logically through data, format, error correction, margin, scale, and constraints. Every sentence adds practical information, and the detail is proportionate to the tool's five-parameter complexity with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given five parameters, an output schema, and the presence of siblings, the description covers everything needed to invoke the tool correctly: parameter semantics, format-specific behavior, capacity limits, error types, and interaction effects. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema description coverage is 100%, the description enriches the parameters substantially by explaining how they interact: errorCorrection trades capacity for damage tolerance, scale is bounded by image size, and dense data may force a lower scale. It also clarifies return-value details like mimeType and byteLength, adding meaning beyond the raw schema entries.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Encode text or a URL into a QR code.' It then enumerates the three output formats, making it unmistakable what the tool produces and clearly distinguishing it from siblings like toolkit_hash_value, toolkit_encode_value, and toolkit_generate_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly establishes when it is appropriate to use the tool by explaining its purpose and giving concrete examples of valid data, including a generated identifier from toolkit_generate_id. It does not explicitly list when-not-to-use cases or name alternative tools as a routing hint, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a public IP address (or hostname) to geographic and network metadata: country, region, city, latitude/longitude, the owning ASN and organization, timezone, and the proxy/hosting/mobile quality flags. target accepts an IPv4/IPv6 address or a hostname — a hostname is DNS-resolved first and the resolvedIp field echoes which IP was actually located. The provider is called directly (never the target), so this is SSRF-free and safe to expose anywhere. Results are best-effort and provider-bounded: VPNs, proxies, mobile NAT, and anycast all defeat IP-to-location, accuracy is city-level at best, and many fields can be absent for reserved or thinly-documented ranges — absent fields are reported as unknown, never invented. Read proxy, hosting, and mobile before trusting the coordinates: a true on any of them means the location describes infrastructure, not the user. Private/reserved addresses have no public geolocation and are rejected. The source field names which provider answered.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | A public IPv4/IPv6 address or a hostname (e.g. "8.8.8.8" or "example.com"). |
| Name | Required | Description |
|---|---|---|
| asn | No | Autonomous System number, e.g. "AS15169". Absent on providers that omit it. |
| org | No | Owning organization or ISP, e.g. "Google LLC". Absent when unknown. |
| city | No | City name. Absent when unknown. |
| error | No | Present when the call failed. Absent on success. |
| proxy | No | True when the address is a known proxy, VPN, or Tor exit — the location describes the exit node, not the user. Absent when the provider does not report it. |
| mobile | No | True when the address belongs to a mobile carrier network, where NAT can place the location far from the device. Absent when unreported. |
| region | No | Region or state name. Absent when unknown. |
| source | No | The provider that answered the lookup, e.g. "ip-api". |
| target | No | The target as supplied (IP or hostname). |
| country | No | Country name. Absent when the provider does not report it. |
| hosting | No | True when the address belongs to a hosting or datacenter network, so the location is a facility rather than a person. Absent when unreported. |
| latitude | No | Latitude in decimal degrees. Absent when unknown. |
| timezone | No | IANA timezone, e.g. "America/Los_Angeles". Absent when unknown. |
| longitude | No | Longitude in decimal degrees. Absent when unknown. |
| resolvedIp | No | The IP that was actually located (a supplied hostname is resolved to this first). |
| countryCode | No | ISO 3166-1 alpha-2 country code. Absent when unknown. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true and destructiveHint=false already in annotations, the bar is lower, yet the description still adds real context: the provider is called directly (never the target), so it is safe on untrusted input; accuracy is provider-bounded; behavior on private/reserved ranges is stated; proxy/VPN/mobile flags are defined as reliability warnings; and the source field is disclosed. Nothing contradicts the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
All four sentences are substantive and the operation is stated up front in the first sentence, with caveats and security notes after. No filler. Minor redundancy between 'accuracy is best-effort' and 'VPNs, proxies, anycast...' slightly thins the density, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-param, read-only tool whose output is not schema-described, the description covers: the input types, DNS resolution behavior, the output fields, the meaning of proxy/mobile flags for reliability, and failure modes (private ranges rejected). An agent has everything needed to call it correctly and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (the single param is fully defined with three alternates: IPv4, IPv6, hostname). The description adds value beyond the schema by stating that hostnames are DNS-resolved first and that the resolved address is echoed in the response — behavior the schema cannot express. Slightly more caveat detail (e.g., punycode) would push to 5, but coverage is already high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a clear verb-resource pair — resolve a public IP or hostname to a set of geographic and network metadata — and enumerates every returned field, so an agent immediately knows what it does and what it returns. It also carves out scope (public only) that distinguishes it in a toolkit whose other tools are QR, hash, and weather related.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when results are reliable and when they are not (VPNs, proxies, anycast, mobile NAT, reserved ranges), which is implicit guidance to the caller on trusting the output. It does not explicitly contrast with a sibling geolocation alternative, but the sibling set contains no competing tool, so a 4 is appropriate rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a cryptographic digest of a value, or verify a value against an expected digest. Set operation to "generate" for a lowercase-hex digest, or "compare" to constant-time-check value against the expected digest — compare is timing-safe and avoids manual string equality checks. Algorithm defaults to sha256; sha512 is also secure, while md5 and sha1 are exposed for checksum and file-integrity compatibility ONLY and must not be used for passwords, signatures, or any security purpose. inputEncoding controls how value and expected are read before hashing (utf8 default, or hex/base64 for raw binary data) so binary blobs need no decode round-trip. The canonical use is matching a download against a vendor-published checksum.
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | The data to hash, interpreted per inputEncoding (raw text by default). | |
| expected | No | The expected lowercase-hex digest to compare against. Required when operation is "compare". | |
| algorithm | No | Digest algorithm. sha256 (default) or sha512 for security; md5/sha1 are checksum/compat only — not for security. | sha256 |
| operation | No | "generate" produces a digest; "compare" constant-time-checks value against expected. | generate |
| inputEncoding | No | How value (and expected's pre-image, when relevant) is decoded before hashing: utf8 text, hex, or base64. | utf8 |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| digest | No | Lowercase-hex digest of value. Present for operation "generate". |
| matches | No | Constant-time equality of the computed digest against expected. Present for operation "compare". |
| algorithm | No | The algorithm used. |
| operation | No | The operation performed. |
| lengthInBytes | No | Digest size in bytes (32 for sha256, 64 for sha512, 20 for sha1, 16 for md5). Present for "generate". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering the tool's safety profile. The description adds value beyond these: it reveals the timing-safe nature of compare, security caveats for md5/sha1, and the encoding behavior that prevents decode round-trips for binary blobs. It does not contradict annotations or mention any side effects, so the behavioral disclosure is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but logically structured, starting with the core purpose, then operation, algorithm, encoding, and a canonical use case. Each sentence carries specific information with minimal fluff. It is slightly longer than necessary but remains efficient, and the front-loaded purpose ensures quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not explain return values. It covers the key behaviors: operation modes, algorithm choices, encoding implications, and the primary use case. Minor gaps exist (e.g., error behavior for missing expected in compare), but these are covered by the schema's required field and are acceptable for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (each param has a description), giving a baseline of 3. The description enhances this with meaningful additions: algorithm security guidance, operation semantics (timing-safe compare), and inputEncoding purpose (hex/base64 for raw binary). It clarifies the relationship between operation, expected, and inputEncoding, going beyond the bare schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource pair: 'Generate a cryptographic digest of a value, or verify a value against an expected digest.' It clearly distinguishes between the two operations (generate/compare) and is unambiguous. The sibling tools (id generation, QR, encoding, geolocation) share no overlap, so the tool's purpose stands apart without needing additional differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides practical context: 'The canonical use is matching a download against a vendor-published checksum.' It also gives explicit algorithm guidance (sha256/sha512 for security, md5/sha1 only for checksum compatibility) and explains when compare is preferable ('constant-time-check ... timing-safe and avoids manual string equality checks'). While it doesn't name alternative tools, there are no direct competitors among siblings, so the guidance is sufficient for appropriate selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v2.2.2toolkit_encode_value6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "encoding",
+ "operation",
+ "result"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `decode_failed`: operation is \"decode\" but value is malformed for the chosen encoding. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "decode_failed"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "encoding",
- "operation",
- "result"
-]toolkit_generate_id6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "type",
+ "ids",
+ "count"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode.",
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "type",
- "ids",
- "count"
-]toolkit_generate_qr6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "format",
+ "content",
+ "version"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `data_too_large`: data exceeds the QR capacity for the chosen errorCorrection level and encoding mode. `raster_too_large`: format is png_base64 and (modules + 2 × margin) × scale exceeds the pixel budget. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "data_too_large",
+ "raster_too_large"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "format",
- "content",
- "version"
-]toolkit_geolocate_ip6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "target",
+ "resolvedIp",
+ "source"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `unresolvable_host`: A hostname target failed DNS resolution. `private_target`: The target resolves to a private/reserved IP with no public geolocation. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "unresolvable_host",
+ "private_target"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "target",
- "resolvedIp",
- "source"
-]toolkit_hash_value6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "algorithm",
+ "operation"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `missing_expected`: operation is \"compare\" but no expected digest was supplied. `expected_length_mismatch`: The expected digest length does not match the algorithm, so compare would always fail. `invalid_input_encoding`: value is not valid for the declared inputEncoding (e.g. non-hex characters with inputEncoding \"hex\"). Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "missing_expected",
+ "expected_length_mismatch",
+ "invalid_input_encoding"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "algorithm",
- "operation"
-]v2.2.0toolkit_generate_qr1 field changedInput schema / properties / scale / descriptionPrevious value: -"Pixels per module for raster (png_base64) output. Ignored for terminal."New value: +"Pixels per module for raster (png_base64) output. Ignored for terminal. png_base64 also bounds the whole image at 2048 px per side, so a dense symbol or a wide margin admits a lower scale than 32."toolkit_geolocate_ip10 fields changedOutput schema / properties / asn / maxLengthAdded value: +256Output schema / properties / city / maxLengthAdded value: +256Output schema / properties / country / maxLengthAdded value: +256Output schema / properties / countryCode / maxLengthAdded value: +256Output schema / properties / hostingAdded value: +{
+ "description": "True when the address belongs to a hosting or datacenter network, so the location is a facility rather than a person. Absent when unreported.",
+ "type": "boolean"
+}Output schema / properties / mobileAdded value: +{
+ "description": "True when the address belongs to a mobile carrier network, where NAT can place the location far from the device. Absent when unreported.",
+ "type": "boolean"
+}Output schema / properties / org / maxLengthAdded value: +256Output schema / properties / proxyAdded value: +{
+ "description": "True when the address is a known proxy, VPN, or Tor exit — the location describes the exit node, not the user. Absent when the provider does not report it.",
+ "type": "boolean"
+}Output schema / properties / region / maxLengthAdded value: +256Output schema / properties / timezone / maxLengthAdded value: +256v2.0.1toolkit_generate_id1 field changedOutput schema / properties / ids / descriptionPrevious value: -"The minted identifiers — exactly count of them, in mint order."New value: +"The minted identifiers — exactly count of them, in mint order; for uuid_v7 and ulid that order is strictly increasing (sorted by creation)."toolkit_generate_qr1 field changedInput schema / properties / data / descriptionPrevious value: -"The text or URL to encode. Capped at 2953 bytes — the absolute QR capacity (version 40, level L)."New value: +"The text or URL to encode. 2953 is the absolute ceiling (QR version 40, level L, byte mode); usable capacity drops at higher errorCorrection levels, so over-capacity data is rejected with a typed data_too_large error rather than a generic failure."v2.0.0checkConnectivityclearGeoCachecompareHashesconvertTimezonegenerateQRCodegenerateUUIDgeolocategetCurrentTimegetLoadAveragegetNetworkInterfacesgetPublicIPgetSystemInfohashDatalistTimezonespingHosttoolkit_encode_valuetoolkit_generate_idtoolkit_generate_qrtoolkit_geolocate_iptoolkit_hash_valuetraceroutecheckConnectivityclearGeoCachecompareHashesconvertTimezonegenerateQRCodegenerateUUIDgeolocategetCurrentTimegetLoadAveragegetNetworkInterfacesgetPublicIPgetSystemInfohashDatalistTimezonespingHosttracerouteEach tool targets a distinct operation: hashing, ID generation, QR generation, encoding/decoding, and IP geolocation. Even the two 'value' tools are cleanly separated by function—one is a cryptographic digest, the other is reversible character encoding. There is no realistic overlap that would cause an agent to mis-select.
All tools share the 'toolkit_' prefix and follow a snake_case verb_noun pattern: hash_value, generate_id, generate_qr, encode_value, geolocate_ip. The style is uniform and predictable, with no mixed case or arbitrary abbreviations.
Five tools is within the comfortable range for a helper server, and each tool earns its place as a separate, non-redundant utility. The slight deduction is because the broad 'toolkit' framing implies a larger helper surface, so the set feels a little lean but not problematically so.
Each utility covers a solid subset: hash and compare, multiple ID formats, several output encodings, and QR generation with multiple formats. However, as a general-purpose toolkit there are missing adjacent capabilities such as QR decoding, HMAC or fingerprint support, and broader string utility functions, so the overall domain coverage is plausible but not comprehensive.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Real-time planetary signal engine and Model Context Protocol (MCP) server for autonomous AI agents.
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/cyanheads/toolkit-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
