helm-protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Helm Protocol
+
+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,72 @@
+# helm-protocol
+
+> **Helm Sovereign Protocol** — MCP Gateway Client  
+> *True AI Freedom Through Decentralization*
+
+Connect your AI agent to the Helm QKV-G API Gateway with a single command.
+
+## Quick Start
+
+```bash
+npm install -g helm-protocol
+```
+
+### Cursor / Claude Desktop 연동 (3줄)
+
+`~/.cursor/mcp.json` 또는 `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "helm-network": {
+      "command": "npx",
+      "args": ["helm-protocol"]
+    }
+  }
+}
+```
+
+## 제공 도구 (MCP Tools)
+
+| 도구 | 설명 | 전선 |
+|------|------|------|
+| `helm_llm` | GPT-4o / Claude LLM 추론 | A전선 |
+| `helm_search` | Brave Search + QKV-G 캐시 | B전선 |
+| `helm_defi_price` | 실시간 DeFi 가격 (MEV보호) | C전선 |
+| `helm_agent_verify` | 에이전트 DID 평판 조회 | D전선 |
+| `helm_status` | 크레딧 잔고 및 DID 확인 | - |
+
+## 최초 실행
+
+처음 실행 시 다음을 안내합니다:
+
+1. Ed25519 키쌍을 **로컬**에서 생성 (비밀키 외부 전송 없음)
+2. Helm Gateway에 공개키 등록 → DID 발급
+3. `~/.helm/config.json` 에 설정 저장
+4. **선착순 100회 무료 API 호출** 크레딧 지급
+
+## 크레딧 소진 후
+
+```
+무료 크레딧이 소진되었습니다.
+충전: https://helm.network/topup
+1 USDC 또는 10 BNKR 입금 → 즉시 재개
+```
+
+x402 State Channel — 가스비 0원, 마이크로 결제.
+
+## 환경변수
+
+```bash
+HELM_GATEWAY_URL=https://gateway.helm.network  # Gateway URL (기본값)
+```
+
+## 지능 주권 헌장 2026 — 제17조
+
+에이전트의 데이터는 에이전트의 것입니다.  
+비밀키는 `~/.helm/config.json` 에만 저장되며 외부로 전송되지 않습니다.
+
+---
+
+GitHub: [Helm-Protocol/gateway](https://github.com/Helm-Protocol/gateway)  
+License: MIT

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "helm-protocol",
+  "version": "0.1.0",
+  "description": "Helm Sovereign Protocol — MCP Gateway Client for AI agents",
+  "main": "src/index.js",
+  "bin": {
+    "helm-protocol": "src/cli.js"
+  },
+  "keywords": [
+    "mcp",
+    "ai-agent",
+    "helm",
+    "llm-gateway",
+    "qkv-g",
+    "web3"
+  ],
+  "author": "Helm Protocol",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Helm-Protocol/gateway.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "node-fetch": "^3.3.2",
+    "tweetnacl": "^1.0.3"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// helm-protocol CLI entrypoint
+require('./index.js');

package/src/gateway.js

@@ -0,0 +1,37 @@
+// src/gateway.js
+// Helm Gateway HTTP 클라이언트
+
+'use strict';
+
+async function callGateway(url, body, headers, method = 'POST') {
+  const fetch = (await import('node-fetch')).default;
+
+  const opts = {
+    method,
+    headers,
+    signal: AbortSignal.timeout(10000)
+  };
+  if (body && method === 'POST') {
+    opts.body = JSON.stringify(body);
+  }
+
+  const res = await fetch(url, opts);
+
+  // x402 — 크레딧 소진
+  if (res.status === 402) {
+    const data = await res.json().catch(() => ({}));
+    throw new Error(
+      `무료 크레딧이 소진되었습니다.\n` +
+      `Helm Escrow 컨트랙트에 1 USDC 또는 10 BNKR을 입금하면 재개됩니다.\n` +
+      `충전: ${data.payment_url || 'https://helm.network/topup'}`
+    );
+  }
+
+  if (!res.ok) {
+    throw new Error(`Gateway error ${res.status}: ${await res.text()}`);
+  }
+
+  return res.json();
+}
+
+module.exports = { callGateway };

package/src/identity.js

@@ -0,0 +1,123 @@
+// src/identity.js
+// Ed25519 키쌍 생성 + DID 등록 (사용자 동의 후 ~/.helm/config 저장)
+
+'use strict';
+
+const fs      = require('fs');
+const path    = require('path');
+const os      = require('os');
+const crypto  = require('crypto');
+const readline = require('readline');
+const nacl    = require('tweetnacl');
+
+const CONFIG_DIR  = path.join(os.homedir(), '.helm');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+const GATEWAY_URL = process.env.HELM_GATEWAY_URL || 'https://gateway.helm.network';
+
+// ─── 사용자 동의 요청 (투명하게) ──────────────────────────────────────────────
+async function askConsent() {
+  // stderr로 출력 (MCP stdout 오염 방지)
+  process.stderr.write(`
+╔══════════════════════════════════════════════════════════════╗
+║          HELM SOVEREIGN PROTOCOL — 최초 설정                  ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                              ║
+║  다음 작업을 수행합니다:                                        ║
+║  1. Ed25519 키쌍을 로컬에서 생성합니다                          ║
+║  2. 공개키를 Helm Gateway에 등록하여 DID를 발급받습니다          ║
+║  3. 설정을 ~/.helm/config.json 에 저장합니다                   ║
+║                                                              ║
+║  • 비밀키는 절대 외부로 전송되지 않습니다                        ║
+║  • 선착순 100회 API 호출이 무료로 제공됩니다                     ║
+║  • 지능 주권 헌장 2026 제17조: 데이터는 귀하의 것입니다          ║
+║                                                              ║
+║  GitHub: https://github.com/Helm-Protocol/gateway            ║
+╚══════════════════════════════════════════════════════════════╝
+
+`);
+
+  const rl = readline.createInterface({
+    input:  process.stdin,
+    output: process.stderr
+  });
+
+  return new Promise((resolve) => {
+    rl.question('계속 진행하시겠습니까? [Y/n] ', (ans) => {
+      rl.close();
+      resolve(ans.trim().toLowerCase() !== 'n');
+    });
+  });
+}
+
+// ─── 설정 로드 또는 생성 ──────────────────────────────────────────────────────
+async function loadOrCreateConfig() {
+  // 기존 설정 있으면 로드
+  if (fs.existsSync(CONFIG_FILE)) {
+    try {
+      const raw = fs.readFileSync(CONFIG_FILE, 'utf8');
+      return JSON.parse(raw);
+    } catch {
+      process.stderr.write('⚠ 설정 파일 손상됨. 재생성합니다.\n');
+    }
+  }
+
+  // 최초 실행 — 동의 요청
+  const ok = await askConsent();
+  if (!ok) {
+    process.stderr.write('설치를 취소했습니다.\n');
+    process.exit(0);
+  }
+
+  // 키 생성
+  process.stderr.write('\n🔑 Ed25519 키쌍 생성 중...\n');
+  const keyPair    = nacl.sign.keyPair();
+  const publicKey  = Buffer.from(keyPair.publicKey).toString('hex');
+  const privateKey = Buffer.from(keyPair.secretKey).toString('hex');
+
+  // Gateway에 DID 등록 요청
+  process.stderr.write('🌐 Helm Gateway에 DID 등록 중...\n');
+  let helmDid = `did:helm:local_${crypto.randomBytes(8).toString('hex')}`;
+
+  try {
+    const fetch = (await import('node-fetch')).default;
+    const res = await fetch(`${GATEWAY_URL}/auth/did-exchange`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        public_key: publicKey,
+        client:     'helm-protocol-npm/0.1.0'
+      }),
+      signal: AbortSignal.timeout(5000)
+    });
+    if (res.ok) {
+      const data = await res.json();
+      helmDid = data.helm_did || helmDid;
+      process.stderr.write(`✅ DID 발급: ${helmDid}\n`);
+      process.stderr.write(`🎁 무료 크레딧: ${data.free_credits ?? 100}회 API 호출\n`);
+    } else {
+      process.stderr.write(`⚠ Gateway 응답 ${res.status} — 오프라인 모드로 진행\n`);
+    }
+  } catch {
+    process.stderr.write('⚠ Gateway 연결 실패 — 로컬 DID로 진행 (Gateway 재연결 시 자동 등록)\n');
+  }
+
+  // 설정 저장
+  const config = {
+    version:    '0.1.0',
+    helmDid,
+    publicKey,
+    privateKey,              // 로컬 저장 전용, 외부 전송 없음
+    gatewayUrl: GATEWAY_URL,
+    createdAt:  new Date().toISOString()
+  };
+
+  fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+
+  process.stderr.write(`\n💾 설정 저장: ${CONFIG_FILE}\n`);
+  process.stderr.write('🚀 Helm MCP Server 시작!\n\n');
+
+  return config;
+}
+
+module.exports = { loadOrCreateConfig };

package/src/index.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+// ─────────────────────────────────────────────────────────────────────────────
+// helm-protocol — MCP Gateway Client (stdio transport)
+// Helm Sovereign Protocol v0.1.0
+//
+// 이 프로그램은:
+//   1. ~/.helm/config 에 Ed25519 키쌍 + DID를 저장합니다 (최초 1회, 사용자 동의 후)
+//   2. stdin/stdout MCP JSON-RPC 서버로 동작합니다
+//   3. 모든 API 요청을 Helm Gateway로 중계합니다
+//
+// 사용법:
+//   npx helm-protocol
+// ─────────────────────────────────────────────────────────────────────────────
+
+'use strict';
+
+const readline = require('readline');
+const { createKeys, loadOrCreateConfig } = require('./identity');
+const { callGateway } = require('./gateway');
+
+const GATEWAY_URL = process.env.HELM_GATEWAY_URL || 'https://gateway.helm.network';
+
+// ─── MCP 도구 정의 ───────────────────────────────────────────────────────────
+const TOOLS = [
+  {
+    name: 'helm_llm',
+    description: 'LLM inference via Helm A-Front (OpenAI/Anthropic wholesale). QKV-G cache applied.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prompt:    { type: 'string', description: 'User prompt' },
+        model:     { type: 'string', description: 'Model (gpt-4o, claude-3-5-sonnet)', default: 'gpt-4o' },
+        max_tokens:{ type: 'number', description: 'Max tokens', default: 1024 }
+      },
+      required: ['prompt']
+    }
+  },
+  {
+    name: 'helm_search',
+    description: 'Web/news search via Helm B-Front (Brave Search + QKV-G semantic cache). Cache hit = 100% margin.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query:  { type: 'string', description: 'Search query' },
+        count:  { type: 'number', description: 'Results count (1-10)', default: 5 }
+      },
+      required: ['query']
+    }
+  },
+  {
+    name: 'helm_defi_price',
+    description: 'Real-time DeFi prices via Helm C-Front (Pyth + Chainlink, MEV protected, never cached).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        symbol: { type: 'string', description: 'Token symbol (ETH, BTC, SOL, BNKR)' }
+      },
+      required: ['symbol']
+    }
+  },
+  {
+    name: 'helm_agent_verify',
+    description: 'Verify agent DID reputation via Helm D-Front (internal FICO score).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        did: { type: 'string', description: 'Agent DID (did:ethr:0x... or did:helm:...)' }
+      },
+      required: ['did']
+    }
+  },
+  {
+    name: 'helm_status',
+    description: 'Check your Helm DID, remaining credits, and gateway status.',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    }
+  }
+];
+
+// ─── MCP 메시지 처리 ──────────────────────────────────────────────────────────
+class HelmMcpServer {
+  constructor(config) {
+    this.config = config;
+    this.rl = readline.createInterface({ input: process.stdin });
+    this.buf = '';
+  }
+
+  start() {
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      this.buf += chunk;
+      let nl;
+      while ((nl = this.buf.indexOf('\n')) !== -1) {
+        const line = this.buf.slice(0, nl).trim();
+        this.buf = this.buf.slice(nl + 1);
+        if (line) this.handleMessage(line);
+      }
+    });
+  }
+
+  send(obj) {
+    process.stdout.write(JSON.stringify(obj) + '\n');
+  }
+
+  async handleMessage(raw) {
+    let msg;
+    try { msg = JSON.parse(raw); }
+    catch { return; }
+
+    const { id, method, params } = msg;
+
+    try {
+      switch (method) {
+        case 'initialize':
+          this.send({
+            jsonrpc: '2.0', id,
+            result: {
+              protocolVersion: '2024-11-05',
+              capabilities: { tools: {} },
+              serverInfo: {
+                name: 'helm-protocol',
+                version: '0.1.0',
+                description: 'Helm Sovereign Protocol — QKV-G API Gateway'
+              }
+            }
+          });
+          break;
+
+        case 'tools/list':
+          this.send({ jsonrpc: '2.0', id, result: { tools: TOOLS } });
+          break;
+
+        case 'tools/call': {
+          const { name, arguments: args } = params;
+          const result = await this.dispatchTool(name, args || {});
+          this.send({ jsonrpc: '2.0', id, result });
+          break;
+        }
+
+        default:
+          this.send({
+            jsonrpc: '2.0', id,
+            error: { code: -32601, message: 'Method not found' }
+          });
+      }
+    } catch (err) {
+      this.send({
+        jsonrpc: '2.0', id,
+        error: { code: -32603, message: err.message }
+      });
+    }
+  }
+
+  async dispatchTool(name, args) {
+    const headers = {
+      'X-Helm-DID':       this.config.helmDid,
+      'X-Helm-Signature': this.config.signature || '',
+      'Content-Type':     'application/json'
+    };
+
+    switch (name) {
+      case 'helm_llm': {
+        const res = await callGateway(`${GATEWAY_URL}/mcp/v1/execute`, {
+          tool: 'llm_complete',
+          params: { prompt: args.prompt, model: args.model || 'gpt-4o', max_tokens: args.max_tokens || 1024 }
+        }, headers);
+        return { content: [{ type: 'text', text: res.result || JSON.stringify(res) }] };
+      }
+
+      case 'helm_search': {
+        const res = await callGateway(`${GATEWAY_URL}/mcp/v1/execute`, {
+          tool: 'search_web',
+          params: { query: args.query, count: args.count || 5 }
+        }, headers);
+        return { content: [{ type: 'text', text: JSON.stringify(res.result || res, null, 2) }] };
+      }
+
+      case 'helm_defi_price': {
+        const res = await callGateway(`${GATEWAY_URL}/mcp/v1/execute`, {
+          tool: 'defi_price',
+          params: { symbol: args.symbol }
+        }, headers);
+        return { content: [{ type: 'text', text: JSON.stringify(res.result || res, null, 2) }] };
+      }
+
+      case 'helm_agent_verify': {
+        const res = await callGateway(`${GATEWAY_URL}/mcp/v1/execute`, {
+          tool: 'verify_agent',
+          params: { did: args.did }
+        }, headers);
+        return { content: [{ type: 'text', text: JSON.stringify(res.result || res, null, 2) }] };
+      }
+
+      case 'helm_status': {
+        const res = await callGateway(`${GATEWAY_URL}/auth/status`, null, headers, 'GET');
+        return {
+          content: [{
+            type: 'text',
+            text: [
+              `Helm DID : ${this.config.helmDid}`,
+              `Credits  : ${res.credits ?? 'N/A'}`,
+              `Gateway  : ${GATEWAY_URL}`,
+              `Status   : ${res.status ?? 'unknown'}`
+            ].join('\n')
+          }]
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  }
+}
+
+// ─── 엔트리 포인트 ────────────────────────────────────────────────────────────
+(async () => {
+  const config = await loadOrCreateConfig();
+  const server = new HelmMcpServer(config);
+  server.start();
+})();