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](https://www.hypernym.ai/docs/api)
And sign up for our API waitlist (self serve coming soon!) at the [link here!](https://forms.gle/1CBrdeBVEVC5KJAX6)
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
- Clone the repository: ```bash git clone https://github.com/hypernym/hypernym-mcp-server.git cd hypernym-mcp-server ```
- Install dependencies: ```bash npm install ```
- Create a `.env` file: ```bash touch .env ```
- 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:
Or provide your own certificates and update the paths in `.env`:
Usage
- Build the project: ```bash npm run build ```
- Start the server: a. HTTP/HTTPS mode: ```bash 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): ```bash 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) - Higher values preserve more original meaning
**Returns:**
Complete JSON analysis including semantic categories, compression metrics, and reconstructed text.
semantic_compression
Direct text compression that maintains semantic meaning.
**Parameters:**
- `text` (required): The input text to compress
- `min_compression_ratio` (optional): Target compression ratio (0.0-1.0, default: 0.5)
- `min_semantic_similarity` (optional): Minimum semantic similarity threshold (0.0-1.0, default: 0.8)
**Returns:**
Only the compressed text that preserves core meaning while maintaining readability.
Environment Variables
- `HYPERNYM_API_URL` (required): URL for the Hypernym API (default: https://fc-api-development.hypernym.ai)
- `HYPERNYM_API_KEY` (required): Your Hypernym AI API key
- `PORT` (optional): Port to run the server on (default: 3000)
- `SSL_KEY_PATH` (optional): Path to SSL key file
- `SSL_CERT_PATH` (optional): Path to SSL certificate file
- `MCP_USE_STDIO` (optional): Set to 'true' to force stdio transport mode
MCP Integration
To use this server with MCP-compatible AI platforms, add the following configuration to your `.mcp.json` file:
This allows AI models to access Hypernym's capabilities through MCP's standardized tool interface.
HTTP Endpoints
The server exposes these HTTP endpoints:
- `POST /` - MCP JSON-RPC 2.0 endpoint for tool calls and listings
- `POST /analyze_sync` - Direct Hypernym API passthrough
- `GET /health` - Health check endpoint
Testing
Test the server with provided sample texts:
JSON-RPC 2.0 Examples
List available tools:
Call the semantic_compression tool:
API Response Example
When using the `analyze_text` tool, you'll receive a JSON response like:
For more information on the Hypernym API or to obtain an API key, contact the Hypernym team at [this link here!](https://forms.gle/1CBrdeBVEVC5KJAX6)