@proofofprotocol/inscribe-mcp 0.1.0

package/src/cli/commands/init.js

@@ -0,0 +1,186 @@
+/**
+ * init command
+ *
+ * Initialize inscribe-mcp configuration.
+ */
+
+import { Command } from 'commander';
+import { createInterface } from 'readline';
+import { writeConfig, configExists, getConfigPath } from '../lib/config.js';
+import { EXIT_CODES } from '../lib/exit-codes.js';
+
+// Simple prompt helper (no external dependency)
+function prompt(question) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+// ANSI colors
+const colors = {
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  dim: (s) => `\x1b[2m${s}\x1b[0m`
+};
+
+export const initCommand = new Command('init')
+  .description('Initialize inscribe-mcp configuration')
+  .option('-f, --force', 'Overwrite existing configuration')
+  .action(async (options) => {
+    console.log('');
+    console.log(colors.bold('inscribe-mcp Setup'));
+    console.log('─'.repeat(40));
+    console.log('');
+
+    // Check existing config
+    if (configExists() && !options.force) {
+      console.log(colors.yellow('Config already exists: ') + getConfigPath());
+      console.log('');
+      console.log('Use --force to overwrite.');
+      process.exit(EXIT_CODES.SUCCESS);
+    }
+
+    // Network selection
+    console.log(colors.bold('1. Select Network'));
+    console.log('');
+    console.log('  1) testnet ' + colors.dim('(recommended for testing)'));
+    console.log('  2) mainnet ' + colors.dim('(real HBAR costs)'));
+    console.log('');
+
+    let network;
+    while (!network) {
+      const choice = await prompt('Select (1 or 2): ');
+      if (choice === '1') network = 'testnet';
+      else if (choice === '2') network = 'mainnet';
+      else console.log(colors.red('Invalid selection. Enter 1 or 2.'));
+    }
+
+    console.log('');
+    console.log(colors.green('✓') + ` Network: ${network}`);
+    console.log('');
+
+    // Mainnet warning
+    if (network === 'mainnet') {
+      console.log(colors.yellow('⚠ Mainnet Warning'));
+      console.log('─'.repeat(40));
+      console.log('• Real HBAR will be consumed');
+      console.log('• Transactions are irreversible');
+      console.log('• Secure your private key');
+      console.log('');
+      const confirm = await prompt('Continue? (yes/no): ');
+      if (confirm.toLowerCase() !== 'yes') {
+        console.log('Aborted.');
+        process.exit(EXIT_CODES.SUCCESS);
+      }
+      console.log('');
+    }
+
+    // Account setup
+    console.log(colors.bold('2. Hedera Account'));
+    console.log('');
+
+    if (network === 'testnet') {
+      console.log(colors.cyan('Testnet Faucet:'));
+      console.log('  https://portal.hedera.com/faucet');
+      console.log('');
+      console.log('Create an account and get free HBAR for testing.');
+      console.log('');
+    } else {
+      console.log(colors.cyan('Create Mainnet Account:'));
+      console.log('  HashPack: https://www.hashpack.app/');
+      console.log('  Blade: https://www.bladewallet.io/');
+      console.log('');
+      console.log('Transfer a small amount of HBAR (1-5 HBAR recommended).');
+      console.log('');
+    }
+
+    // Account ID input
+    let accountId;
+    while (!accountId) {
+      const input = await prompt('Account ID (e.g., 0.0.123456): ');
+      if (/^0\.0\.\d+$/.test(input)) {
+        accountId = input;
+      } else {
+        console.log(colors.red('Invalid format. Use 0.0.XXXXXX'));
+      }
+    }
+
+    console.log(colors.green('✓') + ` Account ID: ${accountId}`);
+    console.log('');
+
+    // Private key input
+    console.log(colors.bold('3. Private Key'));
+    console.log('');
+    console.log(colors.dim('Your private key is stored locally and never transmitted.'));
+    console.log('');
+
+    let privateKey;
+    while (!privateKey) {
+      const input = await prompt('Private Key (hex or DER format): ');
+      if (input.length >= 32) {
+        privateKey = input;
+      } else {
+        console.log(colors.red('Private key seems too short.'));
+      }
+    }
+
+    console.log(colors.green('✓') + ' Private key received');
+    console.log('');
+
+    // Topic ID (optional)
+    console.log(colors.bold('4. Topic ID (optional)'));
+    console.log('');
+    console.log(colors.dim('Leave empty to auto-create on first inscribe.'));
+    console.log('');
+
+    const topicInput = await prompt('Topic ID (e.g., 0.0.123456) or Enter to skip: ');
+    let topicId = null;
+    if (topicInput && /^0\.0\.\d+$/.test(topicInput)) {
+      topicId = topicInput;
+      console.log(colors.green('✓') + ` Topic ID: ${topicId}`);
+    } else if (topicInput) {
+      console.log(colors.yellow('Invalid format, skipping.'));
+    } else {
+      console.log(colors.dim('Topic will be created on first inscribe.'));
+    }
+
+    console.log('');
+
+    // Build and save config
+    const config = {
+      network,
+      operatorAccountId: accountId,
+      operatorPrivateKey: privateKey
+    };
+
+    if (topicId) {
+      config.defaultTopicId = topicId;
+    }
+
+    writeConfig(config);
+
+    // Summary
+    console.log('─'.repeat(40));
+    console.log(colors.green(colors.bold('✓ Setup Complete!')));
+    console.log('');
+    console.log('Config saved to:');
+    console.log(`  ${getConfigPath()}`);
+    console.log('');
+    console.log('Next steps:');
+    console.log('  • Run ' + colors.cyan('inscribe-mcp config') + ' to verify');
+    console.log('  • Run ' + colors.cyan('inscribe-mcp balance') + ' to check balance');
+    console.log('');
+
+    process.exit(EXIT_CODES.SUCCESS);
+  });

package/src/cli/commands/log.js

@@ -0,0 +1,193 @@
+/**
+ * log command
+ *
+ * Display MCP execution logs (Read-Only).
+ */
+
+import { Command } from 'commander';
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { getLogsDir } from '../../lib/logger.js';
+import { EXIT_CODES } from '../lib/exit-codes.js';
+
+// ANSI colors
+const colors = {
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  dim: (s) => `\x1b[2m${s}\x1b[0m`
+};
+
+/**
+ * Parse time duration string (e.g., "1h", "30m", "7d")
+ * @returns {number} milliseconds
+ */
+function parseDuration(str) {
+  const match = str.match(/^(\d+)([smhd])$/);
+  if (!match) return null;
+
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+
+  const multipliers = {
+    s: 1000,
+    m: 60 * 1000,
+    h: 60 * 60 * 1000,
+    d: 24 * 60 * 60 * 1000
+  };
+
+  return value * multipliers[unit];
+}
+
+/**
+ * Format timestamp for display
+ */
+function formatTime(isoString) {
+  const date = new Date(isoString);
+  return date.toLocaleString('ja-JP', {
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit'
+  });
+}
+
+/**
+ * Format log entry for display
+ */
+function formatLogEntry(entry) {
+  const time = formatTime(entry.timestamp);
+  const cmd = (entry.command || 'unknown').toUpperCase().padEnd(12);
+  const topic = entry.topicId ? `topic=${entry.topicId}` : '';
+  const latency = entry.latency ? `${entry.latency}ms` : '—';
+
+  let status;
+  if (entry.status === 'success') {
+    status = colors.green('OK');
+  } else {
+    status = colors.red('FAILED');
+  }
+
+  let line = `[${time}] ${cmd} ${topic.padEnd(20)} latency=${latency.padEnd(8)} ${status}`;
+
+  if (entry.error) {
+    line += ` (${entry.error})`;
+  }
+
+  return line;
+}
+
+/**
+ * Read all log entries from log files
+ */
+function readLogs(logsDir, options = {}) {
+  const { since, errorOnly } = options;
+  const entries = [];
+
+  if (!existsSync(logsDir)) {
+    return entries;
+  }
+
+  // Get log files sorted by date (newest first)
+  const files = readdirSync(logsDir)
+    .filter(f => f.endsWith('.jsonl'))
+    .sort()
+    .reverse();
+
+  const sinceMs = since ? parseDuration(since) : null;
+  const cutoff = sinceMs ? Date.now() - sinceMs : null;
+
+  for (const file of files) {
+    const filePath = join(logsDir, file);
+    const content = readFileSync(filePath, 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean);
+
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+
+        // Skip debug entries
+        if (entry.level === 'debug') continue;
+
+        // Apply time filter
+        if (cutoff) {
+          const entryTime = new Date(entry.timestamp).getTime();
+          if (entryTime < cutoff) continue;
+        }
+
+        // Apply error filter
+        if (errorOnly && entry.status !== 'error') continue;
+
+        entries.push(entry);
+      } catch {
+        // Skip invalid lines
+      }
+    }
+  }
+
+  // Sort by timestamp descending
+  entries.sort((a, b) =>
+    new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime()
+  );
+
+  return entries;
+}
+
+export const logCommand = new Command('log')
+  .description('Display MCP execution logs')
+  .option('-n, --tail <n>', 'Show last N entries', '20')
+  .option('-s, --since <duration>', 'Show entries since (e.g., 1h, 30m, 7d)')
+  .option('-e, --error', 'Show only errors')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    const logsDir = getLogsDir();
+
+    if (!existsSync(logsDir)) {
+      console.log('');
+      console.log(colors.yellow('No logs found.'));
+      console.log('');
+      console.log('Logs are created when MCP tools are executed.');
+      console.log('');
+      process.exit(EXIT_CODES.LOG_NOT_FOUND);
+    }
+
+    const entries = readLogs(logsDir, {
+      since: options.since,
+      errorOnly: options.error
+    });
+
+    if (entries.length === 0) {
+      console.log('');
+      console.log(colors.yellow('No matching log entries.'));
+      console.log('');
+      process.exit(EXIT_CODES.SUCCESS);
+    }
+
+    // Apply tail limit
+    const limit = parseInt(options.tail, 10) || 20;
+    const displayEntries = entries.slice(0, limit);
+
+    if (options.json) {
+      console.log(JSON.stringify(displayEntries, null, 2));
+      process.exit(EXIT_CODES.SUCCESS);
+    }
+
+    // Display logs
+    console.log('');
+    console.log(colors.bold('inscribe-mcp Logs'));
+    console.log('─'.repeat(80));
+
+    // Reverse for chronological display
+    displayEntries.reverse().forEach(entry => {
+      console.log(formatLogEntry(entry));
+    });
+
+    console.log('─'.repeat(80));
+    console.log(colors.dim(`Showing ${displayEntries.length} of ${entries.length} entries`));
+    console.log('');
+
+    process.exit(EXIT_CODES.SUCCESS);
+  });

package/src/cli/commands/show.js

@@ -0,0 +1,249 @@
+/**
+ * show command
+ *
+ * Display nvidia-smi style dashboard for inscribe-mcp status.
+ */
+
+import { Command } from 'commander';
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { getLogsDir } from '../../lib/logger.js';
+import { configExists, readConfig, maskPrivateKey } from '../lib/config.js';
+import { EXIT_CODES } from '../lib/exit-codes.js';
+
+// ANSI colors
+const colors = {
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  dim: (s) => `\x1b[2m${s}\x1b[0m`
+};
+
+/**
+ * Get Mirror Node URL
+ */
+function getMirrorUrl(network) {
+  return network === 'mainnet'
+    ? 'https://mainnet.mirrornode.hedera.com'
+    : 'https://testnet.mirrornode.hedera.com';
+}
+
+/**
+ * Format relative time
+ */
+function formatRelativeTime(isoString) {
+  if (!isoString) return 'never';
+
+  const diff = Date.now() - new Date(isoString).getTime();
+  const minutes = Math.floor(diff / 60000);
+  const hours = Math.floor(diff / 3600000);
+  const days = Math.floor(diff / 86400000);
+
+  if (days > 0) return `${days}d ago`;
+  if (hours > 0) return `${hours}h ago`;
+  if (minutes > 0) return `${minutes}m ago`;
+  return 'just now';
+}
+
+/**
+ * Read all log entries and compute stats
+ */
+function computeStats(logsDir) {
+  const stats = {
+    total: 0,
+    success: 0,
+    error: 0,
+    byCommand: {},
+    totalLatency: 0,
+    latencyCount: 0,
+    lastInscribe: null,
+    lastVerify: null,
+    lastError: null,
+    lastErrorMessage: null
+  };
+
+  if (!existsSync(logsDir)) {
+    return stats;
+  }
+
+  const files = readdirSync(logsDir).filter(f => f.endsWith('.jsonl'));
+
+  for (const file of files) {
+    const filePath = join(logsDir, file);
+    const content = readFileSync(filePath, 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean);
+
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+
+        // Skip debug entries
+        if (entry.level === 'debug') continue;
+
+        stats.total++;
+
+        if (entry.status === 'success') {
+          stats.success++;
+        } else {
+          stats.error++;
+          if (!stats.lastError || entry.timestamp > stats.lastError) {
+            stats.lastError = entry.timestamp;
+            stats.lastErrorMessage = entry.error;
+          }
+        }
+
+        // Track by command
+        const cmd = entry.command || 'unknown';
+        if (!stats.byCommand[cmd]) {
+          stats.byCommand[cmd] = { success: 0, error: 0 };
+        }
+        if (entry.status === 'success') {
+          stats.byCommand[cmd].success++;
+        } else {
+          stats.byCommand[cmd].error++;
+        }
+
+        // Track latency
+        if (entry.latency) {
+          stats.totalLatency += entry.latency;
+          stats.latencyCount++;
+        }
+
+        // Track last operations
+        if (entry.command === 'inscribe' && entry.status === 'success') {
+          if (!stats.lastInscribe || entry.timestamp > stats.lastInscribe) {
+            stats.lastInscribe = entry.timestamp;
+          }
+        }
+        if (entry.command === 'verify' && entry.status === 'success') {
+          if (!stats.lastVerify || entry.timestamp > stats.lastVerify) {
+            stats.lastVerify = entry.timestamp;
+          }
+        }
+      } catch {
+        // Skip invalid lines
+      }
+    }
+  }
+
+  stats.avgLatency = stats.latencyCount > 0
+    ? Math.round(stats.totalLatency / stats.latencyCount)
+    : 0;
+
+  return stats;
+}
+
+export const showCommand = new Command('show')
+  .description('Display inscribe-mcp status dashboard')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    // Check config
+    if (!configExists()) {
+      console.log('');
+      console.log(colors.red('Config not found.'));
+      console.log('');
+      console.log('Run ' + colors.cyan('inscribe-mcp init') + ' to configure.');
+      console.log('');
+      process.exit(EXIT_CODES.CONFIG_ERROR);
+    }
+
+    const config = readConfig();
+    const { network, operatorAccountId, defaultTopicId } = config;
+
+    // Fetch balance
+    let balance = '—';
+    try {
+      const mirrorUrl = getMirrorUrl(network);
+      const response = await fetch(`${mirrorUrl}/api/v1/accounts/${operatorAccountId}`);
+      if (response.ok) {
+        const data = await response.json();
+        const hbar = (data.balance?.balance || 0) / 100_000_000;
+        balance = hbar.toFixed(2) + ' HBAR';
+      }
+    } catch {
+      balance = colors.red('fetch error');
+    }
+
+    // Compute stats from logs
+    const logsDir = getLogsDir();
+    const stats = computeStats(logsDir);
+
+    if (options.json) {
+      console.log(JSON.stringify({
+        config: {
+          network,
+          operatorAccountId,
+          defaultTopicId,
+          operatorPrivateKey: maskPrivateKey(config.operatorPrivateKey)
+        },
+        balance,
+        stats
+      }, null, 2));
+      process.exit(EXIT_CODES.SUCCESS);
+    }
+
+    // Dashboard display
+    const width = 60;
+    const line = '─'.repeat(width);
+    const doubleLine = '═'.repeat(width);
+
+    console.log('');
+    console.log(colors.bold(`inscribe-mcp status  (network: ${colors.cyan(network)})`));
+    console.log(doubleLine);
+
+    // Account info
+    console.log(`Operator:        ${operatorAccountId}`);
+    console.log(`Balance:         ${colors.green(balance)}`);
+    if (defaultTopicId) {
+      console.log(`Topic:           ${defaultTopicId}`);
+    } else {
+      console.log(`Topic:           ${colors.dim('(not configured)')}`);
+    }
+
+    console.log('');
+    console.log(colors.bold('MCP Activity (total)'));
+    console.log(line);
+
+    // Command stats
+    const inscribeStats = stats.byCommand['inscribe'] || { success: 0, error: 0 };
+    const verifyStats = stats.byCommand['verify'] || { success: 0, error: 0 };
+    const historyStats = stats.byCommand['history'] || { success: 0, error: 0 };
+
+    const formatStat = (s) => `${s.success + s.error} (success ${colors.green(s.success)} / fail ${s.error > 0 ? colors.red(s.error) : s.error})`;
+
+    console.log(`Inscribe calls:  ${formatStat(inscribeStats)}`);
+    console.log(`Verify calls:    ${formatStat(verifyStats)}`);
+    console.log(`History calls:   ${formatStat(historyStats)}`);
+    console.log(`Avg latency:     ${stats.avgLatency || 0} ms`);
+
+    console.log('');
+    console.log(colors.bold('Timeline'));
+    console.log(line);
+
+    console.log(`Last inscribe:   ${stats.lastInscribe ? formatRelativeTime(stats.lastInscribe) : colors.dim('never')}`);
+    console.log(`Last verify:     ${stats.lastVerify ? formatRelativeTime(stats.lastVerify) : colors.dim('never')}`);
+    if (stats.lastError) {
+      console.log(`Last error:      ${colors.red(stats.lastErrorMessage || 'unknown')} (${formatRelativeTime(stats.lastError)})`);
+    } else {
+      console.log(`Last error:      ${colors.dim('none')}`);
+    }
+
+    console.log('');
+    console.log(colors.bold('Links'));
+    console.log(line);
+
+    const hashscanBase = network === 'mainnet'
+      ? 'https://hashscan.io/mainnet'
+      : 'https://hashscan.io/testnet';
+
+    console.log(`Account: ${hashscanBase}/account/${operatorAccountId}`);
+    if (defaultTopicId) {
+      console.log(`Topic:   ${hashscanBase}/topic/${defaultTopicId}`);
+    }
+
+    console.log('');
+
+    process.exit(EXIT_CODES.SUCCESS);
+  });

package/src/cli/index.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+/**
+ * inscribe-mcp CLI
+ *
+ * Observation and configuration layer for inscribe-mcp.
+ * Read-Only: This CLI does not send transactions to Hedera.
+ */
+
+import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+import { initCommand } from './commands/init.js';
+import { configCommand } from './commands/config.js';
+import { balanceCommand } from './commands/balance.js';
+import { logCommand } from './commands/log.js';
+import { showCommand } from './commands/show.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Read version from package.json
+const packageJson = JSON.parse(
+  readFileSync(join(__dirname, '../../package.json'), 'utf-8')
+);
+
+const program = new Command();
+
+program
+  .name('inscribe-mcp')
+  .description('Observation and configuration CLI for inscribe-mcp')
+  .version(packageJson.version);
+
+// Register commands
+program.addCommand(initCommand);
+program.addCommand(configCommand);
+program.addCommand(balanceCommand);
+program.addCommand(logCommand);
+program.addCommand(showCommand);
+
+// Parse and execute
+program.parse();