vtimestamp-mcp

Instructions

Implementation Reference

• src/tools.ts:165-254 (handler)

  The implementation of the `vtimestamp_list` MCP tool, which lists all timestamps recorded on a VerusID.

  server.tool(
    'vtimestamp_list',
    'List all timestamps recorded on a VerusID. Returns an array of timestamps with hash, title, metadata, and blockchain proof details.',
    {
      identity: z.string().describe('VerusID name (e.g., "alice@")'),
    },
    async ({ identity }) => {
      if (!isValidIdentity(identity)) {
        throw new McpError(
          ErrorCode.InvalidParams,
          'Invalid identity format — must be a VerusID name ending with @ (e.g., "alice@")'
        );
      }
  
      try {
        const keys = getVdxfKeys();
        const historyResponse = await getIdentityHistory(identity);
        const timestamps = parseAllTimestamps(historyResponse.history, keys);
  
        // Fetch block times for all timestamps
        const results = await Promise.all(
          timestamps.map(async (ts) => {
            let blocktime: number | undefined;
            try {
              const block = await getBlock(ts.blockhash);
              blocktime = block.time;
            } catch {
              // Block time is optional
            }
  
            return {
              hash: ts.data.sha256,
              title: ts.data.title,
              description: ts.data.description ?? null,
              filename: ts.data.filename ?? null,
              filesize: ts.data.filesize ?? null,
              block_height: ts.blockheight,
              block_time: blocktime
                ? new Date(blocktime * 1000).toISOString()
                : null,
              transaction_id: ts.txid,
            };
          })
        );
  
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify(
                {
                  identity: historyResponse.fullyqualifiedname,
                  timestamp_count: results.length,
                  timestamps: results,
                },
                null,
                2
              ),
            },
          ],
        };
      } catch (err) {
        if (err instanceof VerusRpcError && err.code === RPC_ERROR_CODES.IDENTITY_NOT_FOUND) {
          return {
            content: [
              {
                type: 'text' as const,
                text: JSON.stringify({
                  error: `Identity '${identity}' not found`,
                }),
              },
            ],
            isError: true,
          };
        }
  
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify({
                error: `Failed to list timestamps: ${err instanceof Error ? err.message : 'Unknown error'}`,
              }),
            },
          ],
          isError: true,
        };
      }
    }
  );