Hypernym MCP 服务器

一个模型上下文协议 (MCP) 服务器，通过 Hypernym AI 的 API 提供语义文本分析和压缩工具。该服务器允许 LLM 通过标准化的 MCP 接口访问 Hypernym 的语义分类和压缩功能。

什么是 Hypernym AI？

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

• 将文本分类到精确的语义桶中
• 生成自适应压缩，同时保持含义
• 提供内容密度的相似性评分
• 从复杂文本中提取关键细节

注册！

了解更多关于 Hypernym 如何帮助您的代理停止丢失上下文并为之过度付费的信息，请访问我们的 文档。

并在 此链接 注册我们的 API 等候名单（自助服务即将推出！）

功能

• 实现了模型上下文协议 (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 工具

服务器通过模型上下文协议提供以下工具：

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 语义分析和压缩工具",
      "tools": ["analyze_text", "semantic_compression"]
    }
  }
}

这允许 AI 模型通过 MCP 的标准化工具接口访问 Hypernym 的功能。

HTTP 端点

服务器公开以下 HTTP 端点：

• POST / - 用于工具调用和列表的 MCP JSON-RPC 2.0 端点
• POST /analyze_sync - 直接 Hypernym API 直通
• GET /health - 健康检查端点

测试

使用提供的示例文本测试服务器：

# 测试服务器健康状况
npm run test:server

# 测试直接 API 端点
npm run test:analyze

# 测试 MCP 语义压缩
npm run test:semantic

# 测试 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 团队。