@proofofprotocol/inscribe-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 POP@AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+# inscribe-mcp
+
+> Verifiable inscription for AI agents - inscribe anything to blockchain
+
+「刻む」という行為を、ブロックチェーンを意識せずに。
+
+## What is inscribe?
+
+**inscribe** = 残す・刻む・あとから消せない形で書く
+
+- SNS投稿を刻む（削除される前に）
+- ニュース記事をアーカイブ
+- 予言・予測を証明
+- AIの判断を記録
+- 契約書にタイムスタンプ
+
+すべて、**あとから検証できる**。改ざん不可能。
+
+## Quick Start
+
+### 1. インストール
+
+```bash
+# npx で直接実行（推奨）
+npx @proofofprotocol/inscribe-mcp init
+
+# または npm でグローバルインストール
+npm install -g @proofofprotocol/inscribe-mcp
+inscribe-mcp init
+```
+
+### 2. 初期設定
+
+`inscribe-mcp init` を実行すると対話形式で設定できます：
+
+```
+? Select network: testnet
+? Enter your Hedera Account ID: 0.0.XXXXXX
+? Enter your Hedera Private Key: 302e...
+
+Config saved to ~/.inscribe-mcp/config.json
+```
+
+Hedera Testnet アカウントは [portal.hedera.com](https://portal.hedera.com) で無料作成。
+
+### 3. Claude Desktop に接続
+
+`claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "inscribe": {
+      "command": "npx",
+      "args": ["@proofofprotocol/inscribe-mcp-server"]
+    }
+  }
+}
+```
+
+設定は `~/.inscribe-mcp/config.json` から自動的に読み込まれます。
+
+### 4. 使う
+
+```
+User: このツイートを刻んで
+      https://x.com/elonmusk/status/xxx
+
+Claude: inscribe_url を使います
+        → 投稿内容を自動取得: "Going to Mars in 2025"
+        → inscription_id: "0.0.7503789-1703412000.123456789"
+        → この投稿が存在した証拠を刻みました！
+```
+
+## Layer 1 API（推奨）
+
+| ツール | 説明 |
+|--------|------|
+| `inscribe_url` | **URLを刻む**（SNS、記事、動画など）|
+| `inscribe` | テキストを刻む |
+| `verify` | 刻んだ内容を検証 |
+| `history` | 履歴を取得 |
+| `identity` | 信頼IDを作成（DID） |
+
+### inscribe_url - キラーフィーチャー
+
+```javascript
+// 自動取得
+inscribe_url({ url: "https://x.com/user/status/xxx" })
+
+// 目撃証言（自動取得できない場合）
+inscribe_url({
+  url: "https://example.com/page",
+  content: "このページに〇〇と書いてあった",
+  note: "スクショも撮った"
+})
+```
+
+**対応プラットフォーム:**
+- ✅ X/Twitter (oEmbed)
+- ✅ YouTube (oEmbed)
+- 📝 その他（手動で content 指定）
+
+### inscribe - テキストを刻む
+
+```javascript
+inscribe({
+  content: "2025年にビットコインは10万ドルを超える",
+  type: "prediction",
+  author: "did:hedera:testnet:0.0.1234567"
+})
+```
+
+### verify - 検証
+
+```javascript
+verify({
+  inscription_id: "0.0.7503789-1703412000.123456789",
+  content: "検証したい元テキスト"  // オプション
+})
+```
+
+## Layer 2 API（開発者向け）
+
+通常は不要。デバッグや直接操作が必要な場合のみ。
+
+| ツール | 説明 |
+|--------|------|
+| `hcs_create_topic` | HCS トピック作成 |
+| `hcs_submit_message` | HCS メッセージ送信 |
+| `hcs_get_messages` | HCS メッセージ取得 |
+| `account_get_balance` | HBAR 残高確認 |
+| `account_send_hbar` | HBAR 送金 |
+| `account_get_info` | アカウント情報取得 |
+
+## Philosophy
+
+```
+┌─────────────────────────────────────────────┐
+│  あなたが呼ぶもの                            │
+│  inscribe / verify / history / identity     │
+├─────────────────────────────────────────────┤
+│  内部で起きていること（見えない）             │
+│  Hedera Consensus Service                   │
+│  Cryptographic Hashing                      │
+│  DID / Decentralized Identity               │
+└─────────────────────────────────────────────┘
+```
+
+**ブロックチェーンは手段。信頼が目的。**
+
+## Use Cases
+
+### SNS投稿の証拠保全
+
+```
+User: イーロン・マスクのこのツイートを刻んで
+      https://x.com/elonmusk/status/xxx
+
+→ 後で削除されても「この時点で存在した」証明になる
+```
+
+### 予言・予測の証明
+
+```
+User: 「2025年末にHBARは$1を超える」と刻んで
+
+→ 後から「俺は言ってた」と証明できる
+```
+
+### AI判断の記録
+
+```
+User: この分析結果を刻んで
+      {"analysis": "...", "confidence": 0.95}
+
+→ AIの判断過程を検証可能な形で記録
+```
+
+## CLI Commands
+
+観測・設定用のCLIツールを提供します（Read-Only、トランザクションは送信しません）。
+
+```bash
+# 初期設定
+inscribe-mcp init
+
+# 設定確認
+inscribe-mcp config
+
+# 残高確認
+inscribe-mcp balance
+
+# ダッシュボード表示
+inscribe-mcp show
+
+# ログ表示
+inscribe-mcp log              # 最新10件
+inscribe-mcp log --tail 20    # 最新20件
+inscribe-mcp log --since 1h   # 過去1時間
+inscribe-mcp log --error      # エラーのみ
+```
+
+### ダッシュボード例
+
+```
+inscribe-mcp status  (network: testnet)
+════════════════════════════════════════════════════════════
+Operator:        0.0.7455134
+Balance:         985.63 HBAR
+Topic:           0.0.7503789
+
+MCP Activity (total)
+────────────────────────────────────────────────────────────
+Inscribe calls:  3 (success 2 / fail 1)
+Verify calls:    1 (success 1 / fail 0)
+History calls:   0 (success 0 / fail 0)
+Avg latency:     1460 ms
+
+Timeline
+────────────────────────────────────────────────────────────
+Last inscribe:   1m ago
+Last verify:     8m ago
+Last error:      none
+
+Links
+────────────────────────────────────────────────────────────
+Account: https://hashscan.io/testnet/account/0.0.7455134
+Topic:   https://hashscan.io/testnet/topic/0.0.7503789
+```
+
+## Configuration
+
+設定は `~/.inscribe-mcp/config.json` に保存されます：
+
+```json
+{
+  "network": "testnet",
+  "operatorAccountId": "0.0.XXXXXX",
+  "operatorPrivateKey": "302e...",
+  "defaultTopicId": "0.0.XXXXXX"
+}
+```
+
+- `defaultTopicId` は初回 inscribe 時に自動作成されます
+- 環境変数（`.env`）からのフォールバックもサポート
+
+## Links
+
+- [POP@AI](https://popatai.com) - Proof of Protocol for AI
+- [Hedera](https://hedera.com) - The trust layer of the internet
+- [HashScan](https://hashscan.io) - Hedera Explorer
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@proofofprotocol/inscribe-mcp",
+  "version": "0.1.0",
+  "description": "Verifiable inscription for AI agents - inscribe anything to blockchain with Hedera HCS",
+  "type": "module",
+  "main": "src/server.js",
+  "bin": {
+    "inscribe-mcp": "./src/cli/index.js",
+    "inscribe-mcp-server": "./src/server.js"
+  },
+  "scripts": {
+    "start": "node src/server.js",
+    "start:sse": "node src/server-sse.js",
+    "cli": "node src/cli/index.js",
+    "test": "node src/test.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "hedera",
+    "hcs",
+    "inscription",
+    "verifiable",
+    "trust",
+    "blockchain",
+    "timestamp",
+    "proof",
+    "ai-agent",
+    "did",
+    "decentralized-identity"
+  ],
+  "author": "POP@AI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/proofofprotocol/inscribe-mcp.git"
+  },
+  "homepage": "https://github.com/proofofprotocol/inscribe-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/proofofprotocol/inscribe-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@hashgraph/sdk": "^2.51.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "commander": "^12.1.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.3.1",
+    "express": "^4.18.2"
+  }
+}

package/src/cli/commands/balance.js

@@ -0,0 +1,151 @@
+/**
+ * balance command
+ *
+ * Display current account balance via Mirror Node API.
+ * Read-Only: No transactions sent.
+ */
+
+import { Command } from 'commander';
+import { configExists, readConfig, validateConfig } 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 for network
+ */
+function getMirrorUrl(network) {
+  return network === 'mainnet'
+    ? 'https://mainnet.mirrornode.hedera.com'
+    : 'https://testnet.mirrornode.hedera.com';
+}
+
+/**
+ * Format tinybars to HBAR
+ */
+function formatHbar(tinybars) {
+  const hbar = tinybars / 100_000_000;
+  return hbar.toFixed(8) + ' HBAR';
+}
+
+/**
+ * Format tinybars to HBAR (short)
+ */
+function formatHbarShort(tinybars) {
+  const hbar = tinybars / 100_000_000;
+  if (hbar >= 1) {
+    return hbar.toFixed(2) + ' HBAR';
+  }
+  return hbar.toFixed(6) + ' HBAR';
+}
+
+export const balanceCommand = new Command('balance')
+  .description('Display current account balance')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    // Check if config exists
+    if (!configExists()) {
+      console.log('');
+      console.log(colors.red('Config not found.'));
+      console.log('');
+      console.log('Run ' + colors.cyan('inscribe-mcp init') + ' to create configuration.');
+      console.log('');
+      process.exit(EXIT_CODES.CONFIG_ERROR);
+    }
+
+    // Validate config
+    const config = readConfig();
+    const validation = validateConfig(config);
+
+    if (!validation.valid) {
+      console.log('');
+      console.log(colors.red('Invalid configuration.'));
+      console.log('');
+      process.exit(EXIT_CODES.CONFIG_ERROR);
+    }
+
+    const { network, operatorAccountId } = config;
+    const mirrorUrl = getMirrorUrl(network);
+
+    try {
+      // Fetch account info from Mirror Node
+      const response = await fetch(`${mirrorUrl}/api/v1/accounts/${operatorAccountId}`);
+
+      if (!response.ok) {
+        if (response.status === 404) {
+          console.log('');
+          console.log(colors.red('Account not found: ') + operatorAccountId);
+          console.log('');
+          console.log('Make sure the account exists on ' + network);
+          console.log('');
+          process.exit(EXIT_CODES.NETWORK_ERROR);
+        }
+        throw new Error(`HTTP ${response.status}`);
+      }
+
+      const data = await response.json();
+      const balance = data.balance?.balance || 0;
+
+      if (options.json) {
+        console.log(JSON.stringify({
+          network,
+          accountId: operatorAccountId,
+          balance: formatHbar(balance),
+          balanceTinybars: balance
+        }, null, 2));
+        process.exit(EXIT_CODES.SUCCESS);
+      }
+
+      // Pretty print
+      console.log('');
+      console.log(colors.bold('Account Balance'));
+      console.log('─'.repeat(40));
+      console.log('');
+      console.log(`  ${colors.dim('Network:')} ${colors.cyan(network)}`);
+      console.log(`  ${colors.dim('Account:')} ${operatorAccountId}`);
+      console.log('');
+      console.log(`  ${colors.dim('Balance:')} ${colors.green(colors.bold(formatHbarShort(balance)))}`);
+      console.log(`           ${colors.dim('(' + balance.toLocaleString() + ' tinybars)')}`);
+      console.log('');
+
+      // Estimate inscriptions
+      const costPerInscribe = 0.0001; // ~$0.0001 per HCS message
+      const hbar = balance / 100_000_000;
+      const estimatedInscriptions = Math.floor(hbar / costPerInscribe);
+
+      console.log(`  ${colors.dim('Estimated inscriptions:')} ~${estimatedInscriptions.toLocaleString()}`);
+      console.log('');
+
+      // Low balance warning
+      if (hbar < 0.1) {
+        console.log(colors.yellow('⚠ Low balance warning'));
+        console.log('  Consider adding more HBAR to continue inscribing.');
+        console.log('');
+      }
+
+      // HashScan link
+      const hashscanUrl = network === 'mainnet'
+        ? `https://hashscan.io/mainnet/account/${operatorAccountId}`
+        : `https://hashscan.io/testnet/account/${operatorAccountId}`;
+
+      console.log(`  ${colors.dim('HashScan:')} ${hashscanUrl}`);
+      console.log('');
+
+      process.exit(EXIT_CODES.SUCCESS);
+
+    } catch (error) {
+      console.log('');
+      console.log(colors.red('Failed to fetch balance:'));
+      console.log('  ' + error.message);
+      console.log('');
+      process.exit(EXIT_CODES.NETWORK_ERROR);
+    }
+  });

package/src/cli/commands/config.js

@@ -0,0 +1,87 @@
+/**
+ * config command
+ *
+ * Display current configuration (with masked private key).
+ */
+
+import { Command } from 'commander';
+import { configExists, getDisplayConfig, getConfigPath, validateConfig, readConfig } 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`
+};
+
+export const configCommand = new Command('config')
+  .description('Display current configuration')
+  .option('--json', 'Output as JSON (private key still masked)')
+  .action(async (options) => {
+    // Check if config exists
+    if (!configExists()) {
+      console.log('');
+      console.log(colors.red('Config not found.'));
+      console.log('');
+      console.log('Run ' + colors.cyan('inscribe-mcp init') + ' to create configuration.');
+      console.log('');
+      process.exit(EXIT_CODES.CONFIG_ERROR);
+    }
+
+    // Validate config
+    const rawConfig = readConfig();
+    const validation = validateConfig(rawConfig);
+
+    if (!validation.valid) {
+      console.log('');
+      console.log(colors.red('Invalid configuration:'));
+      validation.errors.forEach(err => {
+        console.log('  • ' + err);
+      });
+      console.log('');
+      console.log('Run ' + colors.cyan('inscribe-mcp init --force') + ' to reconfigure.');
+      console.log('');
+      process.exit(EXIT_CODES.CONFIG_ERROR);
+    }
+
+    // Get display config (masked)
+    const config = getDisplayConfig();
+
+    if (options.json) {
+      console.log(JSON.stringify(config, null, 2));
+      process.exit(EXIT_CODES.SUCCESS);
+    }
+
+    // Pretty print
+    console.log('');
+    console.log(colors.bold('inscribe-mcp Configuration'));
+    console.log('─'.repeat(40));
+    console.log('');
+    console.log(`  ${colors.dim('File:')}     ${getConfigPath()}`);
+    console.log('');
+    console.log(`  ${colors.dim('Network:')} ${colors.cyan(config.network)}`);
+    console.log(`  ${colors.dim('Account:')} ${config.operatorAccountId}`);
+    console.log(`  ${colors.dim('Key:')}     ${config.operatorPrivateKey}`);
+
+    if (config.defaultTopicId) {
+      console.log(`  ${colors.dim('Topic:')}   ${config.defaultTopicId}`);
+    } else {
+      console.log(`  ${colors.dim('Topic:')}   ${colors.dim('(auto-create on first inscribe)')}`);
+    }
+
+    console.log('');
+
+    // HashScan link
+    const hashscanUrl = config.network === 'mainnet'
+      ? `https://hashscan.io/mainnet/account/${config.operatorAccountId}`
+      : `https://hashscan.io/testnet/account/${config.operatorAccountId}`;
+
+    console.log(`  ${colors.dim('HashScan:')} ${hashscanUrl}`);
+    console.log('');
+
+    process.exit(EXIT_CODES.SUCCESS);
+  });