vtimestamp-write

vtimestamp-mcp-write

用于在 Verus 区块链上创建 vtimestamp 证明的 MCP 服务。

使 AI Agent（Claude Desktop、VS Code 等）能够在 VerusID 上创建文档时间戳——通过本地或远程守护进程直接写入 Verus 区块链。

在寻找只读服务？ 请参阅 vtimestamp-mcp——无需守护进程或钱包。

前提条件

• Node.js 18+
• Verus 守护进程（verusd） 正在运行，并且：
  • 已将该身份的私钥导入钱包
  • 已启用 RPC 访问（默认在 localhost 上启用）

安装

Claude Code

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

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

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

完成后，服务会自动从 VRSC.conf 检测 RPC 凭据（见下方的配置）。

VS Code

将以下内容添加到 VS Code MCP 设置：

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

配置

服务会自动从本地 VRSC.conf 文件读取 RPC 凭据。大多数用户无需手动配置。

自动检测的 VRSC.conf 路径：

• macOS： ~/Library/Application Support/Komodo/VRSC/VRSC.conf
• Linux： ~/.komodo/VRSC/VRSC.conf
• Windows： %AppData%\Roaming\Komodo\VRSC\VRSC.conf

环境变量

均为可选项——仅在非标准设置或使用远程守护进程时需要。

变量	说明
VERUS_CONF_PATH	VRSC.conf 的自定义路径
VERUS_RPC_URL	覆盖项：守护进程 RPC URL（用于远程守护进程）
VERUS_RPC_USER	覆盖项：RPC 用户名（用于远程守护进程）
VERUS_RPC_PASSWORD	覆盖项：RPC 密码（用于远程守护进程）

工具

vtimestamp_create

在 VerusID 上创建新的时间戳。提供文件路径或文本，服务会自动计算 SHA-256 哈希值。

参数	类型	必填	说明
identity	string	是	VerusID 名称（例如，alice@）
file_path	string	二选一	要计算哈希并添加时间戳的文件路径
text	string	二选一	要计算哈希并添加时间戳的文本（例如，证明或报告）
title	string	是	时间戳标题
description	string	否	内容说明
filename	string	否	原始文件名（使用 file_path 时自动检测）
filesize	number	否	文件大小，单位为字节（使用 file_path 时自动检测）
sourceoffunds	string	否	资金来源地址（R 地址、z 地址或 ID@）
feeoffer	number	否	VRSC 手续费报价（默认值：0.0001）

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

示例提示词：

• “在 alice@ 上为路径为 /path/to/report.pdf 的文件添加时间戳”
• “在 alice@ 上为这段文本添加时间戳：我证明发票 #4521 已获批准”

成功响应：

{
  "success": true,
  "identity": "alice@",
  "hash": "a7f3b2c1...",
  "title": "Q4 Report",
  "transaction_id": "abc123...",
  "message": "Timestamp created successfully"
}

错误情况：

• 找不到身份 → 返回包含身份名称的错误
• 哈希重复 → 返回包含现有区块高度和 txid 的错误
• 找不到文件 → 返回 InvalidParams 错误
• RPC 调用失败 → 返回包含守护进程消息的错误

工作原理

服务会连接到 Verus 守护进程（本地或远程）以创建链上时间戳。守护进程的钱包中必须有该身份的私钥，才能对 updateidentity 交易签名。

AI Agent (Claude Desktop, VS Code, etc.)
    │ stdio (JSON-RPC)
    ▼
vtimestamp-mcp-write (local)
    │ HTTP (JSON-RPC 1.0, with auth)
    ▼
Your Verus Daemon (verusd)
    ├── Has identity's private key in wallet
    ├── Signs and broadcasts updateidentity tx
    └── Local (127.0.0.1) or remote (VPS)

链上存储结构

自 v1.2.0 起，此服务会在 VerusID 的 contentmultimap 下将时间戳写为公开加密条目。每个时间戳都会在 proof.basic 外层键（iJvkQ3uTKmRoFiE3rtP8YJxryLBKu8enmX）下生成一个条目，并使用守护进程的 {data: {...}} 信封简写形式。守护进程会将其展开为链上的 DataDescriptor，包含 flags: 13（HAS_OBJECTDATA | ENCRYPTED | HAS_IVK）——密文位于 objectdata 中，epk 和 ivk 字段则会公开发布。

元数据（sha256、标题、描述、文件名、文件大小）会先以 JSON 字符串形式合并为一条消息，再进行加密，因此一次解密调用即可恢复所有字段。由于 IVK 在链上公开发布（公开加密模式），任何人都可以解密这些条目——读者无需共享密钥或访问钱包。读取端请参阅 vtimestamp-mcp。

这对检查意味着：

• 通过任何读取 RPC（getidentity、getidentityhistory、getidentitycontent）检查 cmm，返回的都是密文描述符，而非可读字符串。
• 要恢复原始字段，必须调用 decryptdata，并传入描述符、来源交易的 txid 以及 retrieve: true。守护进程会将密文存储为指向写入交易的间接引用——txid 是解密输入的一部分。
• 验证某个哈希是否与某个身份关联无需钱包——只需访问具有 decryptdata 白名单权限的节点上的守护进程 RPC。

旧版条目仍可使用。 由 1.1.x 及更早版本写入的时间戳（使用 flags: 0 的明文逐字段 DataDescriptor）会永久保留在链上（cmm 仅追加），而 [email protected]+ 可透明读取这两种结构。

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

守护进程设置

本地守护进程

最简单的设置方式——verusd 与 MCP 服务运行在同一台机器上。无需配置——凭据会从 VRSC.conf 中自动检测。

远程守护进程（VPS）

你可以将 MCP 服务指向运行在另一台机器（例如 VPS）上的 verusd 实例。需要在守护进程的 VRSC.conf 中修改两项配置：

1. 允许你的 IP： 添加 rpcallowip=<your-ip>（守护进程默认仅接受 localhost）
2. 开放端口： 确保 RPC 端口（27486）可通过所有防火墙访问

然后在 MCP 配置中设置环境变量覆盖项（VERUS_RPC_URL、VERUS_RPC_USER、VERUS_RPC_PASSWORD）。

重要： RPC 凭据通过纯 HTTP 发送。如果通过开放互联网（而非本地网络）连接，请使用 SSH 隧道保护连接：

ssh -L 27486:127.0.0.1:27486 user@your-vps

然后使用 VERUS_RPC_URL=http://127.0.0.1:27486，就像连接本地服务一样——其余工作由隧道处理。

安全说明

• 此服务会读取你的 VRSC.conf，以自动检测 RPC 凭据——不会复制或在其他位置存储任何机密信息
• 此服务会执行链上写入，并产生少量交易手续费（默认 0.0001 VRSC）
• 此服务仅连接到你的本地守护进程（或你配置的 URL）——不会向其他位置发送数据
• 如果连接远程守护进程，请使用 SSH 隧道，而不是直接暴露 RPC 端口
• 可使用 sourceoffunds 参数控制由哪个地址支付手续费

许可证

MIT