npm package: @proofofprotocol/inscribe-mcp
Description: Verifiable inscription for AI agents - inscribe anything to blockchain with Hedera HCS
Author: POP@AI
Latest version: 0.3.10

# 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 に接続

```bash
# 自動設定（推奨）
inscribe-mcp setup-mcp --claude-desktop

# または手動設定
inscribe-mcp setup-mcp --show-json
```

`claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "inscribe": {
      "command": "npx",
      "args": ["-y", "-p", "@proofofprotocol/inscribe-mcp", "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
```

## 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` に保存されます：

```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