hekkova

Hekkova MCP サーバー

AI エージェントの永続メモリレイヤーです。MCP に対応したあらゆる AI（Claude、ChatGPT、Gemini、Cursor、カスタムエージェント）を接続して、写真、動画、音声、テキストなどの瞬間を、IPFS + Filecoin ストレージ、Lit Protocol による暗号化、閲覧者を制御できるプライバシーレベルとともに Polygon ブロックチェーンへ永久に記録します。

---

クイックスタート

# 1. Install dependencies
npm install

# 2. Copy and configure environment variables
cp .env.example .env
# Edit .env with your Supabase, Thirdweb, Pinata, and Stripe credentials

# 3. Seed the local test account and API key
npm run seed

# 4. Start the development server
npm run dev
# → Server running at http://localhost:3000/mcp

---

Claude Desktop との接続

Claude Desktop の設定ファイルに以下を追加します。

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hekkova": {
      "type": "url",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer hk_test_local_dev_key_12345678"
      }
    }
  }
}

本番環境では、URL と API キーを置き換えます。

{
  "mcpServers": {
    "hekkova": {
      "type": "url",
      "url": "https://mcp.hekkova.com/mcp",
      "headers": {
        "Authorization": "Bearer hk_live_YOUR_API_KEY"
      }
    }
  }
}

API キーは hekkova.com/dashboard/keys で取得できます。

---

ツールリファレンス

ツール	説明
mint_moment	メディア（写真、動画、音声、テキスト）を Polygon に永久に記録します。フェーズに応じて暗号化し、IPFS に固定して、ERC-721 NFT を発行します。Block ID を返します。
mint_from_url	公開 URL（ツイート、Instagram の投稿、画像、ウェブページ）を取得して記録します。og:title と og:image を自動的に抽出します。
list_moments	記録されたすべての瞬間をページ分割して一覧表示します。フェーズ、カテゴリー、検索クエリで絞り込めます。
get_moment	Block ID を指定して、単一の瞬間の詳細（CID、トランザクションハッシュ、フェーズ、タグなど）を取得します。
update_phase	瞬間のプライバシーフェーズを変更します。1 クレジット（テキスト／画像）または 2 クレジット（動画）が必要です。Legacy Plan には月 10 回の無料 Phase Shift が含まれます。
export_moments	すべての瞬間を JSON または CSV でエクスポートします。すべての Block ID と IPFS CID を含む、24 時間有効のダウンロード URL を返します。
get_balance	残りの記録クレジット、現在のプラン（free / arc_builder / legacy）、フェーズ変更の残高を確認します。
get_account	アカウント情報（Light ID、表示名、ウォレットアドレス、デフォルトのフェーズ、Legacy Plan のステータス）を取得します。

---

プライバシーフェーズ

フェーズ	アクセス	暗号化
new_moon	所有者のみ	Lit Protocol（所有者のウォレット ACC）
crescent	親しいグループ（2～10 人）	Lit Protocol（共有アクセス条件）
gibbous	拡張グループ（最大 50 人）	Hekkova ERC-721 によるトークンゲート
full_moon	完全公開	なし

---

瞬間のカテゴリー

カテゴリー	意味
super_moon	人生の大きな出来事
blue_moon	珍しい瞬間
super_blue_moon	一生に一度の出来事
eclipse	時間ロック付き — eclipse_reveal_date まで封印
null	未分類

---

レート制限

プラン	リクエスト/分	記録/分
Sandbox（テストキー）	10	1
Standard（有料パックすべて）	60	10
Legacy Plan	120	20

すべてのレスポンスにレート制限ヘッダーが含まれます。

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1710680460

---

テストの実行

# Make sure the server is running in another terminal
npm run dev

# Run the test client
npm run test-client

---

デプロイ

Vercel（サーバーレス）

npm install -g vercel
vercel

vercel.json を追加します。

{
  "builds": [{ "src": "src/server.ts", "use": "@vercel/node" }],
  "routes": [{ "src": "/(.*)", "dest": "src/server.ts" }]
}

Vercel ダッシュボードの Project → Settings → Environment Variables ですべての環境変数を設定します。

Railway

npm install -g @railway/cli
railway login
railway init
railway up

Railway ダッシュボードで環境変数を設定します。Railway が npm start スクリプトを自動検出します。

Fly.io

npm install -g flyctl
fly auth login
fly launch

Fly が fly.toml を生成します。以下のコマンドでシークレットを設定します。

fly secrets set SUPABASE_URL=... SUPABASE_SERVICE_KEY=... THIRDWEB_SECRET_KEY=...
fly deploy

---

プロジェクト構成

hekkova-mcp/
├── src/
│   ├── server.ts          # Express + MCP server, auth middleware, rate limiter
│   ├── config.ts          # Typed config from environment variables
│   ├── types/index.ts     # TypeScript interfaces (Account, Moment, ApiKey, etc.)
│   ├── services/
│   │   ├── auth.ts        # API key validation and hashing
│   │   ├── database.ts    # Supabase queries (moments, accounts, API keys)
│   │   ├── blockchain.ts  # Thirdweb/Polygon minting (stub → real)
│   │   ├── storage.ts     # Pinata IPFS pinning (stub → real)
│   │   └── encryption.ts  # Lit Protocol encryption (stub → real)
│   └── tools/
│       ├── mint-moment.ts
│       ├── mint-from-url.ts
│       ├── list-moments.ts
│       ├── get-moment.ts
│       ├── update-phase.ts
│       ├── export-moments.ts
│       ├── get-balance.ts
│       └── get-account.ts
├── scripts/
│   ├── seed.ts            # Creates test account + API key in Supabase
│   └── test-client.ts     # Exercises all 8 tools against the running server
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

---

Supabase スキーマ

Supabase プロジェクトに以下のテーブルが必要です。

-- Accounts
create table accounts (
  id text primary key default gen_random_uuid()::text,
  display_name text not null,
  light_id text,
  wallet_address text,
  mints_remaining integer not null default 0,
  total_minted integer not null default 0,
  default_phase text not null default 'new_moon',
  legacy_plan boolean not null default false,
  created_at timestamptz not null default now()
);

-- API Keys
create table api_keys (
  id text primary key default gen_random_uuid()::text,
  account_id text not null references accounts(id) on delete cascade,
  key_hash text not null unique,
  key_prefix text not null,
  environment text not null default 'live',
  created_at timestamptz not null default now(),
  revoked_at timestamptz
);

-- Moments
create table moments (
  id text primary key default gen_random_uuid()::text,
  account_id text not null references accounts(id) on delete cascade,
  block_id text not null unique,
  token_id integer not null,
  title text not null,
  description text,
  phase text not null,
  category text,
  encrypted boolean not null default false,
  media_cid text not null,
  metadata_cid text not null,
  media_type text not null,
  polygon_tx text not null,
  source_url text,
  source_platform text,
  eclipse_reveal_date timestamptz,
  tags text[] not null default '{}',
  timestamp timestamptz not null default now(),
  created_at timestamptz not null default now()
);

-- Indexes
create index on api_keys(key_hash);
create index on moments(account_id, timestamp desc);
create index on moments(block_id);

---

完全な仕様

技術仕様の全文は、hekkova-mcp-server-spec.md を参照してください。

本番エンドポイント：https://mcp.hekkova.com/mcp