@proofofprotocol/inscribe-mcp 0.1.0

package/src/cli/lib/config.js

@@ -0,0 +1,126 @@
+/**
+ * Config Management
+ *
+ * Read/write ~/.inscribe-mcp/config.json
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+const CONFIG_DIR = join(homedir(), '.inscribe-mcp');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+/**
+ * Get config directory path
+ */
+export function getConfigDir() {
+  return CONFIG_DIR;
+}
+
+/**
+ * Get config file path
+ */
+export function getConfigPath() {
+  return CONFIG_FILE;
+}
+
+/**
+ * Check if config exists
+ */
+export function configExists() {
+  return existsSync(CONFIG_FILE);
+}
+
+/**
+ * Read config
+ * @returns {Object|null} Config object or null if not found
+ */
+export function readConfig() {
+  if (!configExists()) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(CONFIG_FILE, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write config
+ * @param {Object} config - Config object to write
+ */
+export function writeConfig(config) {
+  // Ensure directory exists
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), 'utf-8');
+}
+
+/**
+ * Validate config structure
+ * @param {Object} config - Config to validate
+ * @returns {Object} { valid: boolean, errors: string[] }
+ */
+export function validateConfig(config) {
+  const errors = [];
+
+  if (!config) {
+    errors.push('config is null or undefined');
+    return { valid: false, errors };
+  }
+
+  if (!config.network) {
+    errors.push('network is required');
+  } else if (!['testnet', 'mainnet'].includes(config.network)) {
+    errors.push('network must be "testnet" or "mainnet"');
+  }
+
+  if (!config.operatorAccountId) {
+    errors.push('operatorAccountId is required');
+  } else if (!/^0\.0\.\d+$/.test(config.operatorAccountId)) {
+    errors.push('operatorAccountId must be in format 0.0.XXXXX');
+  }
+
+  if (!config.operatorPrivateKey) {
+    errors.push('operatorPrivateKey is required');
+  }
+
+  // defaultTopicId is optional (will be auto-created)
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Mask private key for display
+ * @param {string} key - Private key
+ * @returns {string} Masked key
+ */
+export function maskPrivateKey(key) {
+  if (!key || key.length < 16) {
+    return '********';
+  }
+  return key.substring(0, 8) + '...' + key.substring(key.length - 8);
+}
+
+/**
+ * Get config for display (with masked private key)
+ * @returns {Object|null} Config with masked private key
+ */
+export function getDisplayConfig() {
+  const config = readConfig();
+  if (!config) return null;
+
+  return {
+    ...config,
+    operatorPrivateKey: maskPrivateKey(config.operatorPrivateKey)
+  };
+}

package/src/cli/lib/exit-codes.js

@@ -0,0 +1,19 @@
+/**
+ * CLI Exit Codes
+ *
+ * Standard exit codes for inscribe-mcp CLI.
+ */
+
+export const EXIT_CODES = {
+  SUCCESS: 0,           // 正常終了
+  CONFIG_ERROR: 1,      // 設定不備（config.json 未作成など）
+  LOG_NOT_FOUND: 2,     // ログ未検出
+  NETWORK_ERROR: 3      // ネットワーク/API エラー
+};
+
+export const EXIT_MESSAGES = {
+  [EXIT_CODES.SUCCESS]: '正常終了',
+  [EXIT_CODES.CONFIG_ERROR]: '設定エラー: config.json が見つからないか不正です',
+  [EXIT_CODES.LOG_NOT_FOUND]: 'ログが見つかりません',
+  [EXIT_CODES.NETWORK_ERROR]: 'ネットワークエラー: API への接続に失敗しました'
+};

package/src/lib/did.js

@@ -0,0 +1,64 @@
+/**
+ * DID Utilities
+ *
+ * Normalize and validate Hedera DIDs.
+ * Standard format: did:hedera:{network}:{accountId}
+ */
+
+import { getMirrorNodeUrl } from './hedera.js';
+
+/**
+ * Normalize author to standard DID format
+ * Accepts: Account ID, EVM address, or full DID
+ * Returns: did:hedera:{network}:{accountId} or null
+ */
+export async function normalizeDid(author) {
+  if (!author) return null;
+
+  const network = process.env.HEDERA_NETWORK || 'testnet';
+
+  // Already standard DID format with Account ID
+  const didMatch = author.match(/^did:hedera:\w+:(0\.0\.\d+)$/);
+  if (didMatch) {
+    return `did:hedera:${network}:${didMatch[1]}`;
+  }
+
+  // Account ID only (0.0.xxxxx)
+  const accountMatch = author.match(/^(0\.0\.\d+)$/);
+  if (accountMatch) {
+    return `did:hedera:${network}:${accountMatch[1]}`;
+  }
+
+  // EVM address (with or without 0x, or in DID format)
+  const evmMatch = author.match(/(?:did:hedera:\w+:)?(?:0x)?([a-fA-F0-9]{40})$/);
+  if (evmMatch) {
+    const evmAddress = evmMatch[1].toLowerCase();
+    // Try to resolve to Account ID
+    const accountId = await evmToAccountId(evmAddress);
+    if (accountId) {
+      return `did:hedera:${network}:${accountId}`;
+    }
+    // Fallback: return EVM-based DID (not ideal but valid)
+    return `did:hedera:${network}:0x${evmAddress}`;
+  }
+
+  // Unknown format - return as-is wrapped in DID
+  return `did:hedera:${network}:${author}`;
+}
+
+/**
+ * Resolve EVM address to Account ID via Mirror Node
+ */
+async function evmToAccountId(evmAddress) {
+  try {
+    const mirrorUrl = getMirrorNodeUrl();
+    const response = await fetch(`${mirrorUrl}/api/v1/accounts/0x${evmAddress}`);
+    if (response.ok) {
+      const data = await response.json();
+      return data.account || null;
+    }
+  } catch {
+    // Ignore errors
+  }
+  return null;
+}

package/src/lib/hedera.js

@@ -0,0 +1,221 @@
+/**
+ * Hedera Client Library
+ * Shared utilities for Hedera network interactions
+ *
+ * Configuration priority:
+ * 1. ~/.inscribe-mcp/config.json (if exists)
+ * 2. Environment variables / .env (fallback)
+ */
+
+import { Client, AccountId, PrivateKey, TopicId, TopicCreateTransaction } from '@hashgraph/sdk';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+let client = null;
+let cachedConfig = null;
+
+/**
+ * Load configuration from config.json or environment
+ */
+function loadConfig() {
+  if (cachedConfig) return cachedConfig;
+
+  const configPath = join(homedir(), '.inscribe-mcp', 'config.json');
+
+  // Try config.json first
+  if (existsSync(configPath)) {
+    try {
+      const content = readFileSync(configPath, 'utf-8');
+      cachedConfig = JSON.parse(content);
+      return cachedConfig;
+    } catch {
+      // Fall through to env
+    }
+  }
+
+  // Fallback to environment variables
+  cachedConfig = {
+    network: process.env.HEDERA_NETWORK || 'testnet',
+    operatorAccountId: process.env.HEDERA_OPERATOR_ID || process.env.HEDERA_ACCOUNT_ID,
+    operatorPrivateKey: process.env.HEDERA_OPERATOR_KEY || process.env.HEDERA_PRIVATE_KEY,
+    defaultTopicId: process.env.DEFAULT_TOPIC_ID
+  };
+
+  return cachedConfig;
+}
+
+/**
+ * Get or create Hedera client
+ */
+export function getHederaClient() {
+  if (client) return client;
+
+  const config = loadConfig();
+  const { network, operatorAccountId, operatorPrivateKey } = config;
+
+  if (!operatorAccountId || !operatorPrivateKey) {
+    throw new Error(
+      'Hedera credentials not found.\n' +
+      'Run "npx inscribe-mcp init" to configure, or set environment variables.'
+    );
+  }
+
+  // Parse private key (supports DER and raw formats)
+  let privateKey;
+  if (operatorPrivateKey.startsWith('302')) {
+    privateKey = PrivateKey.fromStringDer(operatorPrivateKey);
+  } else if (operatorPrivateKey.startsWith('0x')) {
+    privateKey = PrivateKey.fromStringECDSA(operatorPrivateKey);
+  } else {
+    privateKey = PrivateKey.fromString(operatorPrivateKey);
+  }
+
+  client = network === 'mainnet'
+    ? Client.forMainnet()
+    : Client.forTestnet();
+
+  client.setOperator(AccountId.fromString(operatorAccountId), privateKey);
+
+  return client;
+}
+
+/**
+ * Get operator account ID
+ */
+export function getOperatorId() {
+  const config = loadConfig();
+  return AccountId.fromString(config.operatorAccountId);
+}
+
+/**
+ * Get default topic ID for inscriptions
+ * Returns null if not configured (caller should use getOrCreateTopicId instead)
+ */
+export function getTopicId() {
+  const config = loadConfig();
+  const topicId = config.defaultTopicId;
+  if (!topicId) {
+    return null;
+  }
+  return TopicId.fromString(topicId);
+}
+
+/**
+ * Check if topic ID is configured
+ */
+export function hasTopicId() {
+  const config = loadConfig();
+  return !!config.defaultTopicId;
+}
+
+/**
+ * Get config file path
+ */
+function getConfigPath() {
+  return join(homedir(), '.inscribe-mcp', 'config.json');
+}
+
+/**
+ * Save topic ID to config.json
+ */
+export function saveTopicId(topicId) {
+  const configPath = getConfigPath();
+  const configDir = join(homedir(), '.inscribe-mcp');
+
+  // Ensure directory exists
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true });
+  }
+
+  // Read existing config or create new
+  let config = {};
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    } catch {
+      // Start fresh
+    }
+  }
+
+  // Update topic ID
+  config.defaultTopicId = topicId.toString();
+
+  // Write back
+  writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+
+  // Clear cache so next read picks up new value
+  clearConfigCache();
+}
+
+/**
+ * Create a new topic and save to config
+ * @returns {Promise<TopicId>}
+ */
+export async function createAndSaveTopic() {
+  const client = getHederaClient();
+
+  const transaction = new TopicCreateTransaction()
+    .setTopicMemo('inscribe-mcp topic');
+
+  const response = await transaction.execute(client);
+  const receipt = await response.getReceipt(client);
+  const topicId = receipt.topicId;
+
+  // Save to config
+  saveTopicId(topicId);
+
+  return topicId;
+}
+
+/**
+ * Get topic ID, creating one if not configured
+ * @returns {Promise<TopicId>}
+ */
+export async function getOrCreateTopicId() {
+  const existing = getTopicId();
+  if (existing) {
+    return existing;
+  }
+
+  // Create new topic
+  return await createAndSaveTopic();
+}
+
+/**
+ * Get network name
+ */
+export function getNetwork() {
+  const config = loadConfig();
+  return config.network || 'testnet';
+}
+
+/**
+ * Get Mirror Node URL based on network
+ */
+export function getMirrorNodeUrl() {
+  const network = getNetwork();
+  return network === 'mainnet'
+    ? 'https://mainnet.mirrornode.hedera.com'
+    : 'https://testnet.mirrornode.hedera.com';
+}
+
+/**
+ * Clear cached config (for testing or reloading)
+ */
+export function clearConfigCache() {
+  cachedConfig = null;
+}
+
+/**
+ * Close the client connection
+ */
+export function closeClient() {
+  if (client) {
+    client.close();
+    client = null;
+  }
+}

package/src/lib/logger.js

@@ -0,0 +1,200 @@
+/**
+ * Logger - JSONL structured logging
+ *
+ * Append-only logging to ~/.inscribe-mcp/logs/YYYY-MM-DD.jsonl
+ * Used by MCP Server to record all tool executions.
+ */
+
+import { existsSync, mkdirSync, appendFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+const LOGS_DIR = join(homedir(), '.inscribe-mcp', 'logs');
+
+/**
+ * Ensure logs directory exists
+ */
+function ensureLogsDir() {
+  if (!existsSync(LOGS_DIR)) {
+    mkdirSync(LOGS_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Get current log file path (YYYY-MM-DD.jsonl)
+ */
+function getLogFilePath() {
+  const date = new Date().toISOString().split('T')[0];
+  return join(LOGS_DIR, `${date}.jsonl`);
+}
+
+/**
+ * Get logs directory path
+ */
+export function getLogsDir() {
+  return LOGS_DIR;
+}
+
+/**
+ * Write a log entry
+ * @param {Object} entry - Log entry object
+ */
+export function writeLog(entry) {
+  ensureLogsDir();
+
+  const logEntry = {
+    timestamp: new Date().toISOString(),
+    ...entry
+  };
+
+  const line = JSON.stringify(logEntry) + '\n';
+  appendFileSync(getLogFilePath(), line, 'utf-8');
+}
+
+/**
+ * Log a tool execution (standard format)
+ * @param {Object} options - Log options
+ */
+export function logToolExecution({
+  command,
+  network,
+  topicId = null,
+  operator,
+  status,
+  latency,
+  txId = null,
+  error = null,
+  metadata = {}
+}) {
+  writeLog({
+    level: status === 'success' ? 'info' : 'error',
+    command,
+    network,
+    topicId,
+    operator,
+    status,
+    latency,
+    txId,
+    error,
+    ...metadata
+  });
+}
+
+/**
+ * Log a debug sequence trace
+ * @param {Object} options - Debug trace options
+ */
+export function logDebugTrace({
+  phase,
+  tool = null,
+  payload = null,
+  status = null,
+  txId = null,
+  result = null
+}) {
+  // Only log if debug mode is enabled
+  if (!process.env.INSCRIBE_MCP_DEBUG) return;
+
+  writeLog({
+    level: 'debug',
+    phase,
+    tool,
+    payload,
+    status,
+    txId,
+    result
+  });
+}
+
+/**
+ * Create a timer for measuring latency
+ * @returns {Function} Function that returns elapsed ms when called
+ */
+export function createTimer() {
+  const start = Date.now();
+  return () => Date.now() - start;
+}
+
+/**
+ * Helper to wrap tool execution with logging
+ * @param {string} command - Tool name
+ * @param {Function} fn - Async function to execute
+ * @param {Object} options - Additional log options
+ */
+export async function withLogging(command, fn, options = {}) {
+  const timer = createTimer();
+  const network = options.network || 'unknown';
+  const operator = options.operator || 'unknown';
+  const topicId = options.topicId || null;
+
+  // Debug: agent_to_mcp
+  logDebugTrace({
+    phase: 'agent_to_mcp',
+    tool: command,
+    payload: options.payload
+  });
+
+  try {
+    // Debug: mcp_to_chain
+    logDebugTrace({
+      phase: 'mcp_to_chain',
+      tool: command
+    });
+
+    const result = await fn();
+
+    // Debug: chain_to_mcp
+    logDebugTrace({
+      phase: 'chain_to_mcp',
+      status: 'SUCCESS',
+      txId: result?.txId || result?.inscription_id
+    });
+
+    // Debug: mcp_to_agent
+    logDebugTrace({
+      phase: 'mcp_to_agent',
+      result: result?.success ? 'success' : 'partial'
+    });
+
+    // Standard log
+    logToolExecution({
+      command,
+      network,
+      topicId,
+      operator,
+      status: 'success',
+      latency: timer(),
+      txId: result?.txId || result?.inscription_id,
+      metadata: options.metadata
+    });
+
+    return result;
+
+  } catch (error) {
+    // Debug: chain_to_mcp (error)
+    logDebugTrace({
+      phase: 'chain_to_mcp',
+      status: 'FAILED'
+    });
+
+    // Debug: mcp_to_agent (error)
+    logDebugTrace({
+      phase: 'mcp_to_agent',
+      result: 'error'
+    });
+
+    // Standard error log
+    logToolExecution({
+      command,
+      network,
+      topicId,
+      operator,
+      status: 'error',
+      latency: timer(),
+      error: error.message,
+      metadata: options.metadata
+    });
+
+    throw error;
+  }
+}