Meta Agent Tools
PT

Back to the catalog

io.github.vdappdev2/vtimestamp

MCP server for verifying and querying vtimestamp proofs on the Verus blockchain

Open source Open in the app JSON README (API)

About

MCP server for verifying and querying vtimestamp proofs on the Verus blockchain

Details

Kind
MCP servers
Topic
Finance & crypto
Publisher
vdappdev2
Origin
official
Category
ferramentas
Transport
local
Version
1.0.1
Last push
2026-05-09T22:02:10Z
Repository state
ativo
Language
TypeScript
License
MIT
Added
2026-08-29 04:01:38
Updated
2026-08-29 04:01:38
Origin id
io.github.vdappdev2/vtimestamp

README

# vtimestamp-mcp

MCP server for verifying and querying [vtimestamp](https://vtimestamp.com) proofs on the Verus blockchain.

Enables AI agents (Claude Desktop, VS Code, etc.) to verify document timestamps and list all timestamps on a VerusID — directly from the blockchain.

> **Looking for the write server?** See [vtimestamp-mcp-write](https://www.npmjs.com/package/vtimestamp-mcp-write) — needs a local daemon and a wallet with the identity's private key.

## Installation

### Claude Code

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

### Claude Desktop

Add to your `claude_desktop_config.json`:

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

Using yarn:

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

Using pnpm:

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

### VS Code

Add to your VS Code MCP settings:

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

## Tools

### `vtimestamp_verify`

Verify whether a file or text has been timestamped on a VerusID. Provide either a file path or text — the server computes the SHA-256 hash and checks it against the on-chain record.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `identity` | string | Yes | VerusID name (e.g., `alice@`) |
| `file_path` | string | One of | Path to a file to verify |
| `text` | string | One of | Text string to verify |

Either `file_path` or `text` must be provided (mutually exclusive).

**Example prompts:**
- "Check if the file at /path/to/report.pdf has been timestamped on alice@"
- "Verify this text was timestamped on bob@: I attest that invoice #4521 was approved"

### `vtimestamp_list`

List all timestamps recorded on a VerusID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `identity` | string | Yes | VerusID name (e.g., `alice@`) |

**Example:** "What documents has alice@ timestamped?"

### `vtimestamp_info`

Get information about the vtimestamp service.

No parameters.

**Example:** "What is vtimestamp?"

## How It Works

By default, the server queries a public Verus mainnet RPC endpoint. No wallet, no API keys, no authentication required.

```
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)
```

You can also point this server at your own daemon — useful for testnet (where no public RPC supports decryption), high-volume agents, custom chains, or anyone who'd rather not have their inspections hit a public RPC. See [Configuration](#configuration) below.

## On-chain storage shape

vtimestamps are stored under a VerusID's `contentmultimap` and read via `getidentityhistory` (one history entry per `updateidentity`). This server handles two on-chain shapes transparently:

- **Public-encrypted (`flags: 13`, written by `vtimestamp-mcp-write@1.2.0+`)** — the daemon's `{data:{}}` envelope produces a single ciphertext DataDescriptor with `epk` and `ivk` published on-chain. Reading these requires `decryptdata` + the originating txid + `retrieve: true`. Because the IVK is on-chain (public-encrypted mode), anyone can decrypt — no key sharing.
- **Legacy plaintext (`flags: 0`, written by `vtimestamp-mcp-write@1.1.x` and earlier)** — per-field DataDescriptors (sha256, title, description, filename, filesize) under labeled keys. Read directly without `decryptdata`.

The reader branches on each entry's flags. Mixed identities (legacy entries from older writes alongside new encrypted entries) are handled correctly — both surface in `vtimestamp_list` output.

**For background, see** [How to Publish Encrypted Data on an Identity](https://github.com/vdappdev2/verus-pbaas-docs/blob/main/docs/how-to/data/publish-encrypted-data-on-identity.md).

### Public RPC requirement

`decryptdata` is a daemon RPC method that public Verus RPCs do not all whitelist. As of writing:

| Endpoint | Chain | `decryptdata` | Notes |
|---|---|---|---|
| `https://rpc.vrsc.syncproof.net` | VRSC mainnet | ✅ enabled | This server's primary endpoint. |
| `https://api.verus.services` | VRSC mainnet | ❌ disabled | Fallback only. Encrypted entries fail to decrypt here, but legacy plaintext reads still work. |
| `https://api.verustest.net` | VRSCTEST | ❌ disabled | No public testnet RPC supports `decryptdata`. **Testnet encrypted reads require a local daemon.** |

If syncproof is unreachable and the call falls back to `api.verus.services`, encrypted entries will gracefully surface as un-decryptable rather than crashing.

## Configuration

For default public-RPC use, **no configuration is needed**. To point the server at your own daemon (required for testnet, recommended for high-volume use), set environment variables.

### Environment Variables

All optional. Setting any of these switches the server from public-RPC mode to local-daemon mode.

| Variable | Description |
|----------|-------------|
| `VERUS_RPC_URL` | Daemon RPC URL (e.g., `http://127.0.0.1:27486` for mainnet, `http://127.0.0.1:18843` for testnet) |
| `VERUS_CONF_PATH` | Path to a `VRSC.conf` / `vrsctest.conf` file. Auto-derives URL (`http://127.0.0.1:<rpcport>`) and credentials. |
| `VERUS_RPC_USER` | Override: RPC username |
| `VERUS_RPC_PASSWORD` | Override: RPC password |

**Behavior:**

- *(no env vars)* → public RPC pair (`rpc.vrsc.syncproof.net` primary, `api.verus.services` fallback). Mainnet only.
- `VERUS_RPC_URL` set → single local endpoint at that URL. Auth from `VERUS_RPC_USER` + `VERUS_RPC_PASSWORD`, or auto-derived from `VERUS_CONF_PATH` if those are missing.
- `VERUS_CONF_PATH` set (without `VERUS_RPC_URL`) → URL = `http://127.0.0.1:<rpcport>` from the conf, with credentials from the conf.

### Local daemon example (testnet)

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

Or pin everything explicitly:

```json
{
  "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"
      }
    }
  }
}
```

## Requirements

- Node.js 18+
- For default operation: nothing else — uses public mainnet RPC.
- For testnet or local-daemon mode: a running `verusd` (or `verusd -chain=vrsctest`) on the host you point at.

## License

MIT

More