vtimestamp

vtimestamp-mcp

用于验证和查询 Verus 区块链上 vtimestamp 证明的 MCP 服务。

让 AI Agent（Claude Desktop、VS Code 等）能够直接从区块链验证文档时间戳，并列出 VerusID 上的所有时间戳。

在寻找写入服务？ 请参阅 vtimestamp-mcp-write — 需要本地守护进程，以及持有该身份私钥的钱包。

安装

Claude Code

claude mcp add --transport stdio --scope user vtimestamp-read -- npx vtimestamp-mcp@latest

Claude Desktop

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "vtimestamp": {
      "command": "npx",
      "args": ["-y", "vtimestamp-mcp@latest"]
    }
  }
}

使用 yarn：

{
  "mcpServers": {
    "vtimestamp": {
      "command": "yarn",
      "args": ["dlx", "vtimestamp-mcp"]
    }
  }
}

使用 pnpm：

{
  "mcpServers": {
    "vtimestamp": {
      "command": "pnpm",
      "args": ["dlx", "vtimestamp-mcp"]
    }
  }
}

VS Code

添加到 VS Code MCP 设置：

{
  "mcp": {
    "servers": {
      "vtimestamp": {
        "command": "npx",
        "args": ["-y", "vtimestamp-mcp@latest"]
      }
    }
  }
}

工具

vtimestamp_verify

验证文件或文本是否已在某个 VerusID 上添加时间戳。提供文件路径或文本即可 — 服务会计算 SHA-256 哈希，并将其与链上记录进行比对。

参数	类型	必填	描述
identity	string	是	VerusID 名称（例如，alice@）
file_path	string	二选一	要验证的文件路径
text	string	二选一	要验证的文本字符串

必须提供 file_path 或 text（两者不可同时提供）。

提示词示例：

• “检查 /path/to/report.pdf 中的文件是否已在 alice@ 上添加时间戳”
• “验证以下文本是否已在 bob@ 上添加时间戳：我确认发票 #4521 已获批准”

vtimestamp_list

列出 VerusID 上记录的所有时间戳。

参数	类型	必填	描述
identity	string	是	VerusID 名称（例如，alice@）

示例：“alice@ 添加过时间戳的文档有哪些？”

vtimestamp_info

获取有关 vtimestamp 服务的信息。

无需参数。

示例：“vtimestamp 是什么？”

工作原理

默认情况下，服务会查询公共 Verus 主网 RPC 端点。无需钱包、API 密钥或身份验证。

AI Agent (Claude Desktop, VS Code, etc.)
    │ stdio (JSON-RPC)
    ▼
vtimestamp-mcp (local)
    │ HTTPS (JSON-RPC 1.0)
    ▼
Public Verus Mainnet RPC (rpc.vrsc.syncproof.net, fallback api.verus.services)

你也可以让此服务连接到自己的守护进程 — 适用于测试网（没有公共 RPC 支持解密）、高调用量 Agent、自定义链，或是不希望检查请求经过公共 RPC 的用户。请参阅下方的配置。

链上存储结构

vtimestamp 存储在 VerusID 的 contentmultimap 下，并通过 getidentityhistory 读取（每次 updateidentity 对应一条历史记录）。此服务会透明地处理两种链上结构：

• 公开加密（flags: 13，由 [email protected]+ 写入） — 守护进程的 {data:{}} 封装会生成一个带有链上公开的 epk 和 ivk 的单一密文 DataDescriptor。读取这类数据需要 decryptdata、来源交易的 txid，以及 retrieve: true。由于 IVK 位于链上（公开加密模式），任何人都可以解密 — 无需共享密钥。
• 旧版明文（flags: 0，由 [email protected] 及更早版本写入） — 在带标签的键下使用按字段划分的 DataDescriptor（sha256、title、description、filename、filesize）。无需 decryptdata，可直接读取。

读取器会根据每条记录的 flags 选择处理方式。混合身份（较早写入的旧版记录与新的加密记录并存）也能正确处理 — 两种记录都会显示在 vtimestamp_list 输出中。

背景信息请参阅：如何在身份上发布加密数据。

公共 RPC 要求

decryptdata 是一个守护进程 RPC 方法，并非所有公共 Verus RPC 都将其列入允许列表。截至本文撰写时：

端点	链	decryptdata	说明
https://rpc.vrsc.syncproof.net	VRSC 主网	✅ 已启用	此服务的主端点。
https://api.verus.services	VRSC 主网	❌ 已禁用	仅作备用。加密条目在此处无法解密，但仍可读取旧版明文数据。
https://api.verustest.net	VRSCTEST	❌ 已禁用	没有公共测试网 RPC 支持 decryptdata。测试网加密数据读取需要本地守护进程。

如果 syncproof 无法访问，调用会回退到 api.verus.services，加密条目会正常显示为无法解密，而不会导致崩溃。

配置

使用默认公共 RPC 时，无需配置。如需将服务指向你自己的守护进程（测试网必需，高用量场景推荐），请设置环境变量。

环境变量

所有变量均为可选。设置其中任意一个，都会使服务从公共 RPC 模式切换到本地守护进程模式。

变量	说明
VERUS_RPC_URL	守护进程 RPC URL（例如，主网使用 http://127.0.0.1:27486，测试网使用 http://127.0.0.1:18843）
VERUS_CONF_PATH	VRSC.conf / vrsctest.conf 文件的路径。自动推导 URL（http://127.0.0.1:<rpcport>）和凭据。
VERUS_RPC_USER	覆盖项：RPC 用户名
VERUS_RPC_PASSWORD	覆盖项：RPC 密码

行为：

• （未设置环境变量） → 使用公共 RPC 组合（rpc.vrsc.syncproof.net 为主端点，api.verus.services 为备用端点）。仅限主网。
• 设置 VERUS_RPC_URL → 使用该 URL 的单一本地端点。身份验证信息取自 VERUS_RPC_USER + VERUS_RPC_PASSWORD；若未设置，则从 VERUS_CONF_PATH 自动推导。
• 设置 VERUS_CONF_PATH（未设置 VERUS_RPC_URL）→ URL 为配置文件中的 http://127.0.0.1:<rpcport>，凭据取自配置文件。

本地守护进程示例（测试网）

{
  "mcpServers": {
    "vtimestamp": {
      "command": "npx",
      "args": ["-y", "vtimestamp-mcp@latest"],
      "env": {
        "VERUS_CONF_PATH": "/Users/you/Library/Application Support/Komodo/vrsctest/vrsctest.conf"
      }
    }
  }
}

或者显式指定所有设置：

{
  "mcpServers": {
    "vtimestamp": {
      "command": "npx",
      "args": ["-y", "vtimestamp-mcp@latest"],
      "env": {
        "VERUS_RPC_URL": "http://127.0.0.1:18843",
        "VERUS_RPC_USER": "rpc-user-from-conf",
        "VERUS_RPC_PASSWORD": "rpc-password-from-conf"
      }
    }
  }
}

要求

• Node.js 18+
• 默认运行：无需其他条件，使用公共主网 RPC。
• 测试网或本地守护进程模式：目标主机上需运行 verusd（或 verusd -chain=vrsctest）。

许可证

MIT