{
  "markdown": "# vtimestamp-mcp-write\r\n\r\nMCP server for **creating** [vtimestamp](https://vtimestamp.com) proofs on the Verus blockchain.\r\n\r\nEnables AI agents (Claude Desktop, VS Code, etc.) to create document timestamps on a VerusID — writing directly to the Verus blockchain via a local or remote daemon.\r\n\r\n> **Looking for the read-only server?** See [vtimestamp-mcp](https://www.npmjs.com/package/vtimestamp-mcp) — no daemon or wallet required.\r\n\r\n## Prerequisites\r\n\r\n- **Node.js 18+**\r\n- **Verus daemon (`verusd`)** running with:\r\n  - The identity's private key imported into the wallet\r\n  - RPC access enabled (default on localhost)\r\n\r\n## Installation\r\n\r\n### Claude Code\r\n\r\n```bash\r\nclaude mcp add --transport stdio --scope user vtimestamp-write -- npx vtimestamp-mcp-write@latest\r\n```\r\n\r\n### Claude Desktop\r\n\r\nAdd to your `claude_desktop_config.json`:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"vtimestamp-write\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"vtimestamp-mcp-write@latest\"]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nThat's it — the server auto-detects your RPC credentials from `VRSC.conf` (see [Configuration](#configuration) below).\r\n\r\n### VS Code\r\n\r\nAdd to your VS Code MCP settings:\r\n\r\n```json\r\n{\r\n  \"mcp\": {\r\n    \"servers\": {\r\n      \"vtimestamp-write\": {\r\n        \"command\": \"npx\",\r\n        \"args\": [\"-y\", \"vtimestamp-mcp-write@latest\"]\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## Configuration\r\n\r\nThe server automatically reads RPC credentials from your local `VRSC.conf` file. No manual configuration is needed for most users.\r\n\r\n**Auto-detected `VRSC.conf` paths:**\r\n- **macOS:** `~/Library/Application Support/Komodo/VRSC/VRSC.conf`\r\n- **Linux:** `~/.komodo/VRSC/VRSC.conf`\r\n- **Windows:** `%AppData%\\Roaming\\Komodo\\VRSC\\VRSC.conf`\r\n\r\n### Environment Variables\r\n\r\nAll optional — only needed for non-standard setups or remote daemons.\r\n\r\n| Variable | Description |\r\n|----------|-------------|\r\n| `VERUS_CONF_PATH` | Custom path to `VRSC.conf` |\r\n| `VERUS_RPC_URL` | Override: daemon RPC URL (for remote daemons) |\r\n| `VERUS_RPC_USER` | Override: RPC username (for remote daemons) |\r\n| `VERUS_RPC_PASSWORD` | Override: RPC password (for remote daemons) |\r\n\r\n## Tools\r\n\r\n### `vtimestamp_create`\r\n\r\nCreate a new timestamp on a VerusID. Provide either a file path or text — the server computes the SHA-256 hash automatically.\r\n\r\n| Parameter | Type | Required | Description |\r\n|-----------|------|----------|-------------|\r\n| `identity` | string | Yes | VerusID name (e.g., `alice@`) |\r\n| `file_path` | string | One of | Path to a file to hash and timestamp |\r\n| `text` | string | One of | Text to hash and timestamp (e.g., an attestation or report) |\r\n| `title` | string | Yes | Title for the timestamp |\r\n| `description` | string | No | Description of the content |\r\n| `filename` | string | No | Original filename (auto-detected when using `file_path`) |\r\n| `filesize` | number | No | File size in bytes (auto-detected when using `file_path`) |\r\n| `sourceoffunds` | string | No | Funding address (R-address, z-address, or ID@) |\r\n| `feeoffer` | number | No | Fee offer in VRSC (default: 0.0001) |\r\n\r\nEither `file_path` or `text` must be provided (mutually exclusive).\r\n\r\n**Example prompts:**\r\n- \"Timestamp the file at /path/to/report.pdf on alice@\"\r\n- \"Timestamp this text on alice@: I attest that invoice #4521 was approved\"\r\n\r\n**Success response:**\r\n```json\r\n{\r\n  \"success\": true,\r\n  \"identity\": \"alice@\",\r\n  \"hash\": \"a7f3b2c1...\",\r\n  \"title\": \"Q4 Report\",\r\n  \"transaction_id\": \"abc123...\",\r\n  \"message\": \"Timestamp created successfully\"\r\n}\r\n```\r\n\r\n**Error cases:**\r\n- Identity not found → error with identity name\r\n- Duplicate hash → error with existing block height and txid\r\n- File not found → `InvalidParams` error\r\n- RPC failure → error with daemon message\r\n\r\n## How It Works\r\n\r\nThe server connects to your Verus daemon (local or remote) to create on-chain timestamps. The daemon must have the identity's private key in its wallet to sign the `updateidentity` transaction.\r\n\r\n```\r\nAI Agent (Claude Desktop, VS Code, etc.)\r\n    │ stdio (JSON-RPC)\r\n    ▼\r\nvtimestamp-mcp-write (local)\r\n    │ HTTP (JSON-RPC 1.0, with auth)\r\n    ▼\r\nYour Verus Daemon (verusd)\r\n    ├── Has identity's private key in wallet\r\n    ├── Signs and broadcasts updateidentity tx\r\n    └── Local (127.0.0.1) or remote (VPS)\r\n```\r\n\r\n## On-chain storage shape\r\n\r\nAs of **v1.2.0**, this server writes timestamps as **public-encrypted** entries under the VerusID's `contentmultimap`. Each timestamp produces a single entry under the `proof.basic` outer key (`iJvkQ3uTKmRoFiE3rtP8YJxryLBKu8enmX`) using the daemon's `{data: {...}}` envelope shorthand. The daemon expands that to an on-chain DataDescriptor with `flags: 13` (HAS_OBJECTDATA | ENCRYPTED | HAS_IVK) — ciphertext in `objectdata`, plus published `epk` and `ivk` fields.\r\n\r\nThe metadata (sha256, title, description, filename, filesize) is JSON-stringified into a single message before encryption, so one decrypt call recovers all fields. Because the IVK is published on-chain (public-encrypted mode), **anyone** can decrypt these entries — no key sharing or wallet access is required for readers. See [vtimestamp-mcp](https://www.npmjs.com/package/vtimestamp-mcp) for the read side.\r\n\r\n**What this means for inspection:**\r\n\r\n- Inspecting the cmm via any read RPC (`getidentity`, `getidentityhistory`, `getidentitycontent`) returns the ciphertext descriptor, not readable strings.\r\n- Recovering the original fields requires a `decryptdata` call passing the descriptor + the originating txid + `retrieve: true`. The daemon stores ciphertext as an indirect reference back to the writing transaction — the txid is part of the decrypt input.\r\n- Verifying a hash against an identity does not require a wallet — only daemon RPC access to a node that has `decryptdata` whitelisted.\r\n\r\n**Legacy entries continue to work.** Timestamps written by `1.1.x` and earlier (plaintext per-field DataDescriptors with `flags: 0`) remain on-chain forever (cmm is append-only), and `vtimestamp-mcp@1.2.0+` reads both shapes transparently.\r\n\r\n**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).\r\n\r\n## Daemon Setup\r\n\r\n### Local daemon\r\n\r\nThe simplest setup — `verusd` runs on the same machine as the MCP server. No configuration needed — credentials are auto-detected from `VRSC.conf`.\r\n\r\n### Remote daemon (VPS)\r\n\r\nYou can point the MCP server at a `verusd` instance running on another machine (e.g., a VPS). The daemon needs two config changes in its `VRSC.conf`:\r\n\r\n1. **Allow your IP:** Add `rpcallowip=<your-ip>` (the daemon only accepts localhost by default)\r\n2. **Open the port:** Ensure the RPC port (27486) is reachable through any firewalls\r\n\r\nThen set the env var overrides (`VERUS_RPC_URL`, `VERUS_RPC_USER`, `VERUS_RPC_PASSWORD`) in your MCP config.\r\n\r\n**Important:** RPC credentials are sent over plain HTTP. If connecting over the open internet (not a local network), use an SSH tunnel to secure the connection:\r\n\r\n```bash\r\nssh -L 27486:127.0.0.1:27486 user@your-vps\r\n```\r\n\r\nThen use `VERUS_RPC_URL=http://127.0.0.1:27486` as if it were local — the tunnel handles the rest.\r\n\r\n## Security Notes\r\n\r\n- This server **reads your `VRSC.conf`** to auto-detect RPC credentials — no secrets are copied or stored elsewhere\r\n- This server performs **on-chain writes** that cost a small transaction fee (default 0.0001 VRSC)\r\n- The server only connects to your local daemon (or the URL you configure) — no data is sent elsewhere\r\n- If connecting to a remote daemon, use an SSH tunnel rather than exposing the RPC port directly\r\n- The `sourceoffunds` parameter can be used to control which address pays fees\r\n\r\n## License\r\n\r\nMIT\r\n",
  "bytes": 7757,
  "sha": "21580849e47edfe3296ba9bde985d09503f3073c7c634f94274d69a39e9cc44f",
  "repo_slug": "vdappdev2/vtimestamp-mcp-write",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vdappdev2_vtimestamp_write_69608375/readme"
}