@proofofprotocol/inscribe-mcp 0.3.2 → 0.3.4

package/README.md

@@ -236,6 +236,72 @@ Account: https://hashscan.io/testnet/account/0.0.7455134
 Topic:   https://hashscan.io/testnet/topic/0.0.7503789
 ```
 
+## Debug Mode (Learning Material)
+
+MCPのシーケンスを詳細に追跡できるデバッグモードを搭載。学習教材として活用できます。
+
+### デバッグモードの有効化（CLI推奨）
+
+```bash
+# デバッグモードをON（1時間後に自動OFF）
+inscribe-mcp debug on
+
+# 30分間だけON
+inscribe-mcp debug on --time 30
+
+# 状態確認
+inscribe-mcp debug
+
+# 手動でOFF
+inscribe-mcp debug off
+```
+
+デバッグ設定後、Claude Desktopを再起動してください。
+
+### 環境変数での有効化（上級者向け）
+
+```json
+{
+  "mcpServers": {
+    "inscribe": {
+      "command": "npx",
+      "args": ["-y", "-p", "@proofofprotocol/inscribe-mcp", "inscribe-mcp-server"],
+      "env": {
+        "INSCRIBE_MCP_DEBUG": "1"
+      }
+    }
+  }
+}
+```
+
+### デバッグ出力の確認
+
+```bash
+# デバッグトレースを表示
+inscribe-mcp show --debug
+```
+
+### MCPシーケンス図
+
+```
+  ┌─────────┐      ┌─────────┐      ┌─────────┐
+  │  Agent  │  →   │   MCP   │  →   │  Chain  │
+  │(Claude) │  ←   │ Server  │  ←   │ (Hedera)│
+  └─────────┘      └─────────┘      └─────────┘
+
+[12:34:56] inscribe
+  → Agent → MCP    {"content":"Hello World"}
+  → MCP → Chain    processing...
+  ← Chain → MCP    SUCCESS txId: 0.0.xxx-123...
+  ← MCP → Agent    result: success
+```
+
+デバッグモードでは以下の情報が記録されます：
+- `agent_to_mcp`: AIエージェントからMCPサーバーへのリクエスト
+- `mcp_to_chain`: MCPサーバーからHederaへの送信
+- `chain_to_mcp`: Hederaからの応答
+- `mcp_to_agent`: AIエージェントへの結果返却
+
 ## Configuration
 
 設定は `~/.inscribe-mcp/config.json` に保存されます：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proofofprotocol/inscribe-mcp",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Verifiable inscription for AI agents - inscribe anything to blockchain with Hedera HCS",
   "type": "module",
   "main": "src/server.js",

package/src/cli/commands/debug.js

@@ -0,0 +1,117 @@
+/**
+ * debug command
+ *
+ * Toggle debug mode on/off with auto-expiry.
+ */
+
+import { Command } from 'commander';
+import { getDebugSettings, setDebugEnabled, configExists } 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`
+};
+
+/**
+ * Format remaining time
+ */
+function formatRemainingTime(expiresAt) {
+  if (!expiresAt) return '';
+
+  const remaining = new Date(expiresAt).getTime() - Date.now();
+  if (remaining <= 0) return 'expired';
+
+  const minutes = Math.floor(remaining / 60000);
+  const hours = Math.floor(minutes / 60);
+
+  if (hours > 0) {
+    const remainingMins = minutes % 60;
+    return `${hours}h ${remainingMins}m remaining`;
+  }
+  return `${minutes}m remaining`;
+}
+
+export const debugCommand = new Command('debug')
+  .description('Toggle debug mode on/off')
+  .argument('[action]', 'on, off, or status (default: status)')
+  .option('-t, --time <minutes>', 'Auto-off after N minutes (default: 60)', '60')
+  .action(async (action, 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 durationMinutes = parseInt(options.time, 10) || 60;
+
+    // Default to status if no action provided
+    if (!action || action === 'status') {
+      const settings = getDebugSettings();
+      console.log('');
+      console.log(colors.bold('Debug Mode Status'));
+      console.log('─'.repeat(40));
+
+      if (settings.enabled) {
+        console.log(`Status:    ${colors.green('ON')}`);
+        console.log(`Expires:   ${formatRemainingTime(settings.expiresAt)}`);
+        console.log('');
+        console.log(colors.dim('Debug logs will be recorded by MCP server.'));
+        console.log(colors.dim('Use ') + colors.cyan('inscribe-mcp show --debug') + colors.dim(' to view.'));
+      } else {
+        console.log(`Status:    ${colors.dim('OFF')}`);
+        console.log('');
+        console.log('To enable: ' + colors.cyan('inscribe-mcp debug on'));
+        console.log('           ' + colors.cyan('inscribe-mcp debug on --time 30') + colors.dim(' (30 min)'));
+      }
+      console.log('');
+      process.exit(EXIT_CODES.SUCCESS);
+    }
+
+    if (action === 'on') {
+      setDebugEnabled(true, durationMinutes);
+      console.log('');
+      console.log(colors.green('✓') + ' Debug mode ' + colors.green('ON'));
+      console.log('');
+      console.log(`Auto-off:  in ${durationMinutes} minutes`);
+      console.log('');
+      console.log(colors.bold('Next steps:'));
+      console.log('  1. Use inscribe tools to generate debug traces');
+      console.log('  2. ' + colors.cyan('inscribe-mcp show --debug') + ' to view traces');
+      console.log('');
+      console.log(colors.dim('No restart required - takes effect immediately.'));
+      console.log('');
+      process.exit(EXIT_CODES.SUCCESS);
+    }
+
+    if (action === 'off') {
+      setDebugEnabled(false);
+      console.log('');
+      console.log(colors.green('✓') + ' Debug mode ' + colors.dim('OFF'));
+      console.log('');
+      console.log(colors.dim('Takes effect immediately.'));
+      console.log('');
+      process.exit(EXIT_CODES.SUCCESS);
+    }
+
+    // Unknown action
+    console.log('');
+    console.log(colors.red('Unknown action: ' + action));
+    console.log('');
+    console.log('Usage:');
+    console.log('  ' + colors.cyan('inscribe-mcp debug') + '           Show status');
+    console.log('  ' + colors.cyan('inscribe-mcp debug on') + '        Enable (auto-off in 1h)');
+    console.log('  ' + colors.cyan('inscribe-mcp debug on -t 30') + ' Enable for 30 minutes');
+    console.log('  ' + colors.cyan('inscribe-mcp debug off') + '       Disable');
+    console.log('');
+    process.exit(EXIT_CODES.ERROR);
+  });

package/src/cli/commands/show.js

@@ -135,9 +135,80 @@ function computeStats(logsDir) {
   return stats;
 }
 
+/**
+ * Read debug trace entries from logs
+ */
+function getDebugTraces(logsDir, limit = 20) {
+  const traces = [];
+
+  if (!existsSync(logsDir)) {
+    return traces;
+  }
+
+  // Get log files sorted by date (newest first)
+  const files = readdirSync(logsDir)
+    .filter(f => f.endsWith('.jsonl'))
+    .sort()
+    .reverse();
+
+  for (const file of files) {
+    if (traces.length >= limit) break;
+
+    const filePath = join(logsDir, file);
+    const content = readFileSync(filePath, 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean).reverse();
+
+    for (const line of lines) {
+      if (traces.length >= limit) break;
+
+      try {
+        const entry = JSON.parse(line);
+        if (entry.level === 'debug') {
+          traces.push(entry);
+        }
+      } catch {
+        // Skip invalid lines
+      }
+    }
+  }
+
+  return traces.reverse(); // Chronological order
+}
+
+/**
+ * Format MCP sequence trace for display
+ */
+function formatSequenceTrace(traces) {
+  const sequences = [];
+  let currentSequence = null;
+
+  for (const trace of traces) {
+    if (trace.phase === 'agent_to_mcp') {
+      // Start new sequence
+      if (currentSequence) {
+        sequences.push(currentSequence);
+      }
+      currentSequence = {
+        tool: trace.tool,
+        timestamp: trace.timestamp,
+        phases: [trace]
+      };
+    } else if (currentSequence) {
+      currentSequence.phases.push(trace);
+    }
+  }
+
+  if (currentSequence) {
+    sequences.push(currentSequence);
+  }
+
+  return sequences;
+}
+
 export const showCommand = new Command('show')
   .description('Display inscribe-mcp status dashboard')
   .option('--json', 'Output as JSON')
+  .option('--debug', 'Show MCP sequence debug traces')
   .action(async (options) => {
     // Check config
     if (!configExists()) {
@@ -243,6 +314,82 @@ export const showCommand = new Command('show')
       console.log(`Topic:   ${hashscanBase}/topic/${defaultTopicId}`);
     }
 
+    // Debug trace section
+    if (options.debug) {
+      console.log('');
+      console.log(colors.bold('MCP Sequence Debug Traces'));
+      console.log(line);
+
+      const traces = getDebugTraces(logsDir, 50);
+
+      if (traces.length === 0) {
+        console.log(colors.dim('No debug traces found.'));
+        console.log('');
+        console.log('To enable debug logging, set environment variable:');
+        console.log(colors.cyan('  export INSCRIBE_MCP_DEBUG=1'));
+        console.log('');
+        console.log('Then restart the MCP server (restart Claude Desktop).');
+      } else {
+        const sequences = formatSequenceTrace(traces);
+
+        if (sequences.length === 0) {
+          console.log(colors.dim('No complete sequences found.'));
+        } else {
+          // Phase symbols for visual diagram
+          const phaseSymbols = {
+            'agent_to_mcp': '→',
+            'mcp_to_chain': '→',
+            'chain_to_mcp': '←',
+            'mcp_to_agent': '←'
+          };
+
+          const phaseLabels = {
+            'agent_to_mcp': 'Agent → MCP',
+            'mcp_to_chain': 'MCP → Chain',
+            'chain_to_mcp': 'Chain → MCP',
+            'mcp_to_agent': 'MCP → Agent'
+          };
+
+          console.log('');
+          console.log(colors.dim('  ┌─────────┐      ┌─────────┐      ┌─────────┐'));
+          console.log(colors.dim('  │  Agent  │  →   │   MCP   │  →   │  Chain  │'));
+          console.log(colors.dim('  │(Claude) │  ←   │ Server  │  ←   │ (Hedera)│'));
+          console.log(colors.dim('  └─────────┘      └─────────┘      └─────────┘'));
+          console.log('');
+
+          for (const seq of sequences.slice(-5)) { // Last 5 sequences
+            const time = new Date(seq.timestamp).toLocaleTimeString();
+            console.log(colors.bold(`[${time}] ${colors.cyan(seq.tool)}`));
+
+            for (const phase of seq.phases) {
+              const symbol = phaseSymbols[phase.phase] || '?';
+              const label = phaseLabels[phase.phase] || phase.phase;
+              let detail = '';
+
+              if (phase.payload) {
+                const payloadStr = JSON.stringify(phase.payload);
+                detail = colors.dim(` ${payloadStr.slice(0, 40)}${payloadStr.length > 40 ? '...' : ''}`);
+              }
+              if (phase.status) {
+                detail = phase.status === 'SUCCESS'
+                  ? colors.green(` ${phase.status}`)
+                  : colors.red(` ${phase.status}`);
+              }
+              if (phase.txId) {
+                detail += colors.dim(` txId: ${phase.txId}`);
+              }
+              if (phase.result) {
+                detail += colors.dim(` result: ${phase.result}`);
+              }
+
+              console.log(`  ${symbol} ${label}${detail}`);
+            }
+            console.log('');
+          }
+        }
+      }
+    }
+
     console.log('');
 
     process.exit(EXIT_CODES.SUCCESS);

package/src/cli/index.js

@@ -18,6 +18,7 @@ import { balanceCommand } from './commands/balance.js';
 import { logCommand } from './commands/log.js';
 import { showCommand } from './commands/show.js';
 import { setupMcpCommand } from './commands/setup-mcp.js';
+import { debugCommand } from './commands/debug.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -41,6 +42,7 @@ program.addCommand(configCommand);
 program.addCommand(balanceCommand);
 program.addCommand(logCommand);
 program.addCommand(showCommand);
+program.addCommand(debugCommand);
 
 // Parse and execute
 program.parse();

package/src/cli/lib/config.js

@@ -124,3 +124,64 @@ export function getDisplayConfig() {
     operatorPrivateKey: maskPrivateKey(config.operatorPrivateKey)
   };
 }
+
+/**
+ * Update a specific field in config
+ * @param {string} key - Config key to update
+ * @param {any} value - New value
+ */
+export function updateConfig(key, value) {
+  const config = readConfig() || {};
+  config[key] = value;
+  writeConfig(config);
+}
+
+/**
+ * Get debug settings
+ * @returns {Object} { enabled: boolean, expiresAt: string|null }
+ */
+export function getDebugSettings() {
+  const config = readConfig();
+  if (!config || !config.debug) {
+    return { enabled: false, expiresAt: null };
+  }
+
+  const { enabled, expiresAt } = config.debug;
+
+  // Check if expired
+  if (enabled && expiresAt) {
+    const expiry = new Date(expiresAt);
+    if (Date.now() > expiry.getTime()) {
+      // Expired - auto disable
+      setDebugEnabled(false);
+      return { enabled: false, expiresAt: null };
+    }
+  }
+
+  return { enabled: !!enabled, expiresAt: expiresAt || null };
+}
+
+/**
+ * Set debug enabled/disabled
+ * @param {boolean} enabled - Enable debug mode
+ * @param {number} durationMinutes - Auto-off duration in minutes (default: 60)
+ */
+export function setDebugEnabled(enabled, durationMinutes = 60) {
+  const config = readConfig() || {};
+
+  if (enabled) {
+    const expiresAt = new Date(Date.now() + durationMinutes * 60 * 1000);
+    config.debug = {
+      enabled: true,
+      expiresAt: expiresAt.toISOString(),
+      durationMinutes
+    };
+  } else {
+    config.debug = {
+      enabled: false,
+      expiresAt: null
+    };
+  }
+
+  writeConfig(config);
+}

package/src/server.js

@@ -3,6 +3,10 @@
  * inscribe-mcp Server (stdio transport)
  *
  * MCP Server for verifiable inscriptions on Hedera blockchain.
+ *
+ * Debug mode:
+ *   - CLI: inscribe-mcp debug on
+ *   - Environment: INSCRIBE_MCP_DEBUG=1
  */
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -12,6 +16,62 @@ import {
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import dotenv from 'dotenv';
+import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+/**
+ * Check if debug mode is enabled (config or env)
+ */
+function isDebugEnabled() {
+  // Environment variable takes precedence
+  if (process.env.INSCRIBE_MCP_DEBUG === '1' || process.env.INSCRIBE_MCP_DEBUG === 'true') {
+    return true;
+  }
+
+  // Check config file
+  const configPath = join(homedir(), '.inscribe-mcp', 'config.json');
+  if (!existsSync(configPath)) {
+    return false;
+  }
+
+  try {
+    const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    if (!config.debug || !config.debug.enabled) {
+      return false;
+    }
+
+    // Check expiry
+    if (config.debug.expiresAt) {
+      const expiry = new Date(config.debug.expiresAt);
+      if (Date.now() > expiry.getTime()) {
+        return false; // Expired
+      }
+    }
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Debug log to stderr (safe for MCP stdio transport)
+ * Checks config on each call for hot-reload support
+ */
+function debugLog(phase, data = {}) {
+  if (!isDebugEnabled()) return;
+
+  const timestamp = new Date().toISOString();
+  const message = {
+    timestamp,
+    phase,
+    ...data
+  };
+
+  // Output to stderr to avoid interfering with MCP JSON-RPC over stdout
+  console.error(`[DEBUG] ${JSON.stringify(message)}`);
+}
 
 // Layer 1 Tools (Primary)
 import { inscribeUrlTool } from './tools/layer1/inscribe_url.js';
@@ -58,6 +118,11 @@ const server = new Server(
 
 // List Tools Handler
 server.setRequestHandler(ListToolsRequestSchema, async () => {
+  debugLog('list_tools', {
+    toolCount: allTools.length,
+    tools: allTools.map(t => t.name)
+  });
+
   return {
     tools: allTools.map(t => ({
       name: t.name,
@@ -70,9 +135,22 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 // Call Tool Handler
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
+  const startTime = Date.now();
+
+  // Debug: Agent → MCP (request received)
+  debugLog('agent_to_mcp', {
+    tool: name,
+    args: args ? Object.keys(args) : []
+  });
+
   const tool = allTools.find(t => t.name === name);
 
   if (!tool) {
+    debugLog('mcp_error', {
+      tool: name,
+      error: 'Unknown tool'
+    });
+
     return {
       content: [{ type: 'text', text: `Unknown tool: ${name}` }],
       isError: true
@@ -80,11 +158,52 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 
   try {
+    // Debug: MCP → Chain (processing)
+    debugLog('mcp_to_chain', {
+      tool: name,
+      processing: true
+    });
+
     const result = await tool.handler(args || {});
+    const duration = Date.now() - startTime;
+
+    // Debug: Chain → MCP (response)
+    debugLog('chain_to_mcp', {
+      tool: name,
+      status: 'SUCCESS',
+      duration,
+      hasResult: !!result
+    });
+
+    // Debug: MCP → Agent (returning result)
+    debugLog('mcp_to_agent', {
+      tool: name,
+      status: 'SUCCESS',
+      duration
+    });
+
     return {
       content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
     };
   } catch (error) {
+    const duration = Date.now() - startTime;
+
+    // Debug: Chain → MCP (error)
+    debugLog('chain_to_mcp', {
+      tool: name,
+      status: 'FAILED',
+      duration,
+      error: error.message
+    });
+
+    // Debug: MCP → Agent (returning error)
+    debugLog('mcp_to_agent', {
+      tool: name,
+      status: 'ERROR',
+      duration,
+      error: error.message
+    });
+
     return {
       content: [{ type: 'text', text: `Error: ${error.message}` }],
       isError: true
@@ -96,7 +215,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
+
+  // Log startup (debug mode is now hot-reloadable)
   console.error('inscribe-mcp server started (stdio)');
+
+  // Initial debug log if enabled
+  if (isDebugEnabled()) {
+    console.error('Debug mode is currently ON (hot-reloadable)');
+    debugLog('server_start', {
+      version: '0.3.4',
+      tools: allTools.map(t => t.name)
+    });
+  }
 }
 
 main().catch(console.error);