Hypernym Semantic Analysis MCP server for AI agents

The Hypernym MCP Server provides semantic text analysis and compression tools through Hypernym AI's API. It enables LLMs to access semantic categorization and compression capabilities via the standardized Model Context Protocol (MCP) interfaces, helping prevent context loss while optimizing token usage.

Installation

Prerequisites

Node.js and npm
Hypernym API key

Basic Setup

Clone the repository:

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

Install dependencies:
```
npm install
```
Create a .env file:
```
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

HTTPS Configuration (Recommended for Production)

Generate self-signed certificates for development:

npm run generate-certs

Or use your own certificates by updating the paths in .env:

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

Usage

Starting the Server

Build the project:
```
npm run build
```
Start the server in one of two modes:
- HTTP/HTTPS mode:
```
npm start
```
  The server will start on port 3000 by default (or the port specified in your .env file).
- stdio transport mode (for MCP integration):
```
npm run start:stdio
```
  Use this mode when configuring the server in a .mcp.json file.

Available MCP Tools

analyze_text

Provides 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

Performs direct text compression while maintaining 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: The compressed text that preserves core meaning while maintaining readability.

Environment Variables

HYPERNYM_API_URL (required): URL for the Hypernym API
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

Integrating with MCP

To use this server with MCP-compatible AI platforms, add the following configuration to your .mcp.json file:

{
  "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"]
    }
  }
}

HTTP Endpoints

The server exposes these 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

Example API Calls

List Available Tools

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

Call the Semantic Compression Tool

{
  "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
    }
  }
}

Example Response

When using the analyze_text tool, you'll receive a JSON response like:

{
  "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
      }
    ]
  }
}

Testing the Server

Test various aspects of the server with these commands:

# 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

For more information on the Hypernym API or to obtain an API key, you can sign up through the API waitlist form.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.