Hypernym MCP Server

A Model Context Protocol (MCP) server providing semantic text analysis and compression tools via Hypernym AI’s API. This server allows LLMs to access Hypernym’s semantic categorization and compression capabilities through standardized MCP interfaces.

What is Hypernym AI?

Hypernym AI offers advanced semantic analysis tools that can:

• Categorize text into precise semantic buckets
• Generate adaptive compression while maintaining meaning
• Provide similarity scoring for content density
• Extract key details from complex text

Signup!

Learn more about how Hypernym helps your agents to stop losing context and overpaying for it at our Documentation

And sign up for our API waitlist (self serve coming soon!) at the link here!

Features

• Implements the Model Context Protocol (MCP) specification
• Provides MCP tools for text analysis and semantic compression
• Supports both standard MCP CLI interface through stdio transport
• Offers HTTP/HTTPS JSON-RPC 2.0 endpoints via Express
• Includes retry logic with exponential backoff for API requests
• HTTPS support for secure connections
• Properly formatted MCP tool descriptions and schemas

Installation

1. Clone the repository:

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

2. Install dependencies:

   npm install
   

3. Create a .env file:

   touch .env
   

4. Add your Hypernym API key and URL to the .env file:

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

Setting up HTTPS (recommended for production)

Generate self-signed certificates for development:

npm run generate-certs

Or provide your own certificates and update the paths in .env:

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

Usage

1. Build the project:

   npm run build
   

2. Start the server:

   a. HTTP/HTTPS mode:

   npm start
   

   The server will start on port 3000 by default (or the port specified in your .env file).

   b. stdio transport mode (for MCP integration):

   npm run start:stdio
   

   This is the mode you should use when configuring the server in a .mcp.json file.

MCP Tools

The server provides the following tools through the Model Context Protocol:

analyze_text

Full semantic analysis of text including categorization and compression metrics.

Parameters:

• text (required): The input text to analyze
• min_compression_ratio (optional): Target compression ratio (0.0-1.0, default: 0.5)
  • 1.0 = no compression
  • 0.8 = 20% compression
  • 0.5 = 50% compression
  • 0.0 = maximum compression
• min_semantic_similarity (optional): Minimum semantic similarity threshold (0.0-1.0, default: 0.8)