Hypernym MCP Server

Hypernym MCP 服务

一个通过 Hypernym AI 的 API 提供语义文本分析和压缩工具的 Model Context Protocol（MCP）服务。此服务允许大模型通过标准化的 MCP 接口使用 Hypernym 的语义分类和压缩功能。

什么是 Hypernym AI？

Hypernym AI 提供先进的语义分析工具，可以：

• 将文本归类到精确的语义类别
• 在保留含义的同时生成自适应压缩结果
• 提供内容密度的相似度评分
• 从复杂文本中提取关键信息

注册！

了解 Hypernym 如何帮助您的 Agent 不再丢失上下文，也不再为此支付过高费用，请参阅我们的文档

并通过此链接！加入我们的 API 候补名单（即将支持自助注册！）

功能

• 实现 Model Context Protocol（MCP）规范
• 提供用于文本分析和语义压缩的 MCP 工具
• 支持通过 stdio 传输使用标准 MCP 命令行接口
• 通过 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（可选）：设为 'true' 可强制使用 stdio 传输模式

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 团队。