Hypernym MCP Server

Hypernym MCP サーバー

Hypernym AI の API を介して、セマンティックテキスト分析と圧縮ツールを提供する Model Context Protocol（MCP）サーバーです。このサーバーを使用すると、LLM は標準化された MCP インターフェースを通じて、Hypernym のセマンティック分類と圧縮機能にアクセスできます。

Hypernym AI とは？

Hypernym AI は、次の機能を備えた高度なセマンティック分析ツールを提供します。

• テキストを精緻な意味カテゴリに分類する
• 意味を維持しながら、適応型の圧縮を行う
• コンテンツ密度の類似度スコアを提供する
• 複雑なテキストから重要な詳細を抽出する

登録！

Hypernym がエージェントのコンテキスト喪失や過剰なコストをどのように防ぐか、詳しくはドキュメントをご覧ください。

また、API のウェイトリスト（セルフサービスは近日公開予定！）への登録はこちらのリンクからどうぞ。

機能

• Model Context Protocol（MCP）仕様を実装
• テキスト分析とセマンティック圧縮のための MCP ツールを提供
• stdio トランスポートを介した標準 MCP CLI インターフェースに対応
• Express を介して HTTP/HTTPS JSON-RPC 2.0 エンドポイントを提供
• API リクエストに指数バックオフを用いた再試行ロジックを実装
• 安全な接続のための HTTPS に対応
• MCP ツールの説明とスキーマを適切な形式で提供

インストール

1. リポジトリをクローンします。

   git clone https://github.com/hypernym/hypernym-mcp-server.git
   cd hypernym-mcp-server
   

2. 依存関係をインストールします。

   npm install
   

3. .env ファイルを作成します。

   touch .env
   

4. Hypernym API キーと URL を .env ファイルに追加します。

   HYPERNYM_API_URL=https://fc-api-development.hypernym.ai
   HYPERNYM_API_KEY=your_api_key_here
   PORT=3000
   

HTTPS の設定（本番環境では推奨）

開発用の自己署名証明書を生成します。

npm run generate-certs

または、独自の証明書を用意し、.env 内のパスを更新します。

SSL_KEY_PATH=/path/to/your/server.key
SSL_CERT_PATH=/path/to/your/server.crt

使用方法

1. プロジェクトをビルドします。

   npm run build
   

2. サーバーを起動します。

   a. HTTP/HTTPS モード：

   npm start
   

   サーバーはデフォルトでポート 3000（または .env ファイルで指定したポート）で起動します。

   b. stdio トランスポートモード（MCP 統合用）：

   npm run start:stdio
   

   .mcp.json ファイルでサーバーを設定する際は、このモードを使用してください。

MCP ツール

このサーバーは、Model Context Protocol を通じて次のツールを提供します。

analyze_text

分類と圧縮指標を含む、テキストの完全なセマンティック分析を行います。

パラメーター：

• text（必須）：分析する入力テキスト
• min_compression_ratio（任意）：目標圧縮率（0.0～1.0、デフォルト：0.5）
  • 1.0 = 圧縮なし
  • 0.8 = 20% 圧縮
  • 0.5 = 50% 圧縮
  • 0.0 = 最大圧縮
• min_semantic_similarity（任意）：セマンティック類似度の最小しきい値（0.0～1.0、デフォルト：0.8）
  • 値が高いほど、元の意味をより多く維持します

戻り値： セマンティックカテゴリ、圧縮指標、再構成されたテキストを含む完全な JSON 分析結果です。

semantic_compression

セマンティックな意味を維持しながら、テキストを直接圧縮します。

パラメーター：

• text（必須）：圧縮する入力テキスト
• min_compression_ratio（任意）：目標圧縮率（0.0～1.0、デフォルト：0.5）
• min_semantic_similarity（任意）：セマンティック類似度の最小しきい値（0.0～1.0、デフォルト：0.8）

戻り値： 読みやすさを維持しながら、核心的な意味を保った圧縮テキストのみです。

環境変数

• HYPERNYM_API_URL（必須）：Hypernym API の URL（デフォルト：https://fc-api-development.hypernym.ai）
• HYPERNYM_API_KEY（必須）：お使いの Hypernym AI API キー
• PORT（任意）：サーバーの実行ポート（デフォルト：3000）
• SSL_KEY_PATH（任意）：SSL キーファイルのパス
• SSL_CERT_PATH（任意）：SSL 証明書ファイルのパス
• MCP_USE_STDIO（任意）：stdio トランスポートモードを強制するには 'true' に設定します

MCP 統合

このサーバーを MCP 対応 AI プラットフォームで使用するには、次の設定を .mcp.json ファイルに追加します。

{
  "mcpServers": {
    "hypernym": {
      "type": "stdio",
      "command": "cd /path/to/hypernym-mcp-server && npm run start:stdio",
      "description": "Hypernym semantic analysis and compression tool",
      "tools": ["analyze_text", "semantic_compression"]
    }
  }
}

これにより、AI モデルは MCP の標準化されたツールインターフェースを通じて Hypernym の機能にアクセスできます。

HTTP エンドポイント

サーバーは次の HTTP エンドポイントを公開しています。

• POST / - ツールの呼び出しと一覧表示に使用する MCP JSON-RPC 2.0 エンドポイント
• POST /analyze_sync - Hypernym API への直接パススルー
• GET /health - ヘルスチェックエンドポイント

テスト

付属のサンプルテキストを使ってサーバーをテストします。

# Test server health
npm run test:server

# Test direct API endpoint
npm run test:analyze

# Test MCP semantic compression
npm run test:semantic

# Test MCP analyze_text
npm run test:analyze-mcp

JSON-RPC 2.0 の例

利用可能なツールを一覧表示する：

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/list"
}

semantic_compression ツールを呼び出す：

{
  "jsonrpc": "2.0",
  "id": "2", 
  "method": "tools/call",
  "params": {
    "name": "semantic_compression",
    "arguments": {
      "text": "Your text to compress here",
      "min_compression_ratio": 0.5,
      "min_semantic_similarity": 0.8
    }
  }
}

API レスポンスの例

analyze_text ツールを使用すると、次のような JSON レスポンスが返されます。

{
  "metadata": {
    "version": "0.1.0",
    "timestamp": "2024-03-21T00:00:00Z",
    "tokens": {
      "in": 1000,
      "out": 500,
      "total": 1500
    }
  },
  "response": {
    "meta": {
      "embedding": {
        "version": "0.1.0",
        "dimensions": 512
      }
    },
    "texts": {
      "compressed": "Philosophy::subject=existence;theme=mortality",
      "suggested": "To be or not to be - an examination of human mortality and the consequences of action versus inaction."
    },
    "segments": [
      {
        "was_compressed": true,
        "semantic_category": "Philosophical contemplation of existence",
        "semantic_similarity": 0.81,
        "compression_ratio": 0.61
      }
    ]
  }
}

Hypernym API の詳細や API キーの取得については、こちらのリンクから Hypernym チームにお問い合わせください。