Similarity Search Api Sdk

io.github.nexus-mcp-infraPublished by GitHub account nexus-mcp-infrav1.0.0Updated Oct 24, 2026

Stateless NMI + cosine fusion with entropy-driven alpha calibration

VerifiedStreamable HTTPWeb executableData & AnalyticsAI & ML

Overview

AI-generated overview

Remote MCP server that ranks pre-computed vectors by an entropy-calibrated NMI-plus-cosine fusion score, with no vector database to run.

What you can do
Rank a corpus of pre-computed vectors against a query vector using a calibrated fusion score, with results identified by corpus position and an optional fixed blend weight instead of auto-calibration. Estimate a corpus's aggregate entropy and calibrated alpha before committing to a full ranking call. Score a single query-target vector pair at a fixed alpha for explainability, debugging or unit-level validation. The server does not embed text; vectors must come from your own embedding model.
When to use it
Useful when you already have embeddings and want a stateless similarity ranking that blends cosine with normalized mutual information, without standing up a vector database or index. Also suited to inspecting calibration behavior or checking individual pair scores before running large corpus searches.
Requirements
A remote streamable HTTP endpoint; no local runtime or package. No API key is needed on the business routes, but each call requires an x402 payment (USDC on Base Sepolia testnet, $0.01 per call) or Stripe metered billing provisioned with an API key. Vectors must be pre-computed, share one dimensionality of 2 to 4,096, and corpora are capped at 500,000 items.
Before you install
Calls cost money: $0.01 per call via x402, currently on the Base Sepolia testnet, and a request without payment returns 402 Payment Required. Your vectors are sent to a third-party hosted service. The README lists 5 MCP tools while the manifest lists 3, so available tools may differ from the documentation.

Installation

In SourceWeft

  1. Open Similarity Search Api Sdk in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.nexus-mcp-infra%2Fsimilarity-search-api-sdk/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "similarity-search-api-sdk": {
      "type": "http",
      "url": "https://similarity-search-api-production.up.railway.app/mcp"
    }
  }
}

README

Similarity Search API

Stateless similarity search over pre-computed vectors — NMI (normalized mutual information) + cosine fusion, with an entropy-calibrated blending weight computed per request. No vector database, no index to maintain, no infrastructure to run.

Available both as a plain HTTP API and as an MCP server (5 tools) for AI agents.


Important: this operates on vectors, not raw text

This API does not embed text for you. query and corpus entries are pre-computed numeric vectors (e.g. from your own embedding model). If you need text-to-vector embedding first, run that upstream and pass the resulting vectors here.


Base URL

https://similarity-search-api-production.up.railway.app

Authentication

The 3 business endpoints (/similarity/search, /similarity/calibrate-alpha/v1, /similarity/batch-score) require no API key -- only a valid x402 payment (see "Pricing" below). The X-API-Key gate was dropped from these routes 2026-08-25; Stripe metered billing explicitly excludes them too, so passing a key does nothing on these 3 routes today. The deprecated, unpriced /similarity/calibrate-alpha (no /v1 suffix) still requires X-API-Key and always 501s regardless.

/health requires no authentication.

Pricing

Two ways to pay, same endpoints:

  • x402 (pay-per-call, USDC on Base) — currently on Base Sepolia testnet, $0.01/call, no account or API key required beyond the x402 payment flow itself. A request without payment gets 402 Payment Required with the payment details in the payment-required response header.
  • Stripe (metered billing) — for callers provisioned with an API key and a Stripe customer on the account.

Endpoints

POST /similarity/search

Rank a corpus against a query vector using the composite score.

json
{  "query": { "id": "q1", "vector": [0.12, -0.4, 0.91, "..."] },  "corpus": [    { "id": "doc1", "vector": [0.10, -0.35, 0.88, "..."] },    { "id": "doc2", "vector": [0.55, 0.02, -0.14, "..."] }  ],  "top_k": 10,  "nmi_bins": 10,  "alpha_override": null}

All vectors in query and corpus must share the same dimensionality (2-4096 dims). top_k up to 1000. alpha_override (optional) pins the cosine/NMI blend weight instead of calibrating it from corpus entropy.

Response:

json
{  "results": [    { "id": "doc1", "composite_score": 0.91, "cosine_similarity": 0.89, "nmi_score": 0.94, "rank": 1 }  ],  "calibrated_alpha": 0.73,  "corpus_entropy": 3.85,  "query_id": "q1",  "corpus_size": 2,  "latency_ms": 43,  "request_fingerprint": "..."}

POST /similarity/calibrate-alpha/v1

Compute the entropy-calibrated alpha for a corpus without running a full search - useful for inspecting/debugging calibration behavior before committing to a search call.

POST /similarity/batch-score

Score up to 10,000 (vector_a, vector_b) pairs with a fixed alpha - no corpus/entropy overhead.

json
{  "pairs": [[[0.1, 0.2], [0.15, 0.19]]],  "alpha": 0.5,  "nmi_bins": 10}

GET /health

Liveness probe. No auth required. Not billed (excluded from both Stripe and x402).

Note: POST /similarity/calibrate-alpha (without /v1) is a deprecated alias kept for backward compatibility - use /similarity/calibrate-alpha/v1.


MCP tools

Connect an MCP-compatible client (Claude, Cursor, etc.) to the streamable HTTP endpoint at: https://similarity-search-api-production.up.railway.app/mcp

Exposes 5 tools: rank_items_by_nmi_cosine_fusion, estimate_corpus_entropy_profile, score_pair_nmi_cosine, find_outlier_vectors_by_nmi_deficit, calibrate_alpha_from_query_entropy.


The scoring method

composite_score = alpha * cosine(query, doc) + (1 - alpha) * NMI_normalized(query, doc)

alpha is calibrated per-request from the Shannon entropy of the submitted corpus (unless you pass alpha_override) - high-entropy (dispersed) corpora lean toward cosine; low-entropy (dense/narrow) corpora lean toward NMI, which captures statistical dependence that cosine's geometric angle misses.


Limits

  • Corpus size: up to 500,000 items per request
  • Vector dimensionality: 2-4,096
  • batch-score pairs: up to 10,000 per request

Source: README.md at commit 9f2faf3

Tools

3

nexus_similarity_search_api_rank_items_by_nmi_cosine_fusion

Ranks a corpus of items against a query vector using a calibrated fusion score (alpha * cosine + (1-alpha) * NMI_normalizado), where alpha is auto-derived from the corpus's marginal entropy unless overridden. Results are identified by their 0-indexed position in corpus_vectors (this tool does not accept explicit item IDs). Use this when you need semantically-calibrated similarity over a stateless corpus of up to 500k items without a vector database. Do NOT use for purely geometric nearest-neighbor search where NMI overhead is unnecessary, nor for corpora larger than 500k items per call. Requires an x402 payment.

Parameterstop_kn_binsquery_vectorrequiredalpha_overridecorpus_vectorsrequired

nexus_similarity_search_api_estimate_corpus_entropy_profile

Computes the aggregate entropy-calibrated alpha for a corpus without running a full search -- useful to inspect before committing to a large rank_items_by_nmi_cosine_fusion call. Returns a single aggregate corpus_entropy value, NOT a per-dimension breakdown -- the real logic only exposes the mean marginal entropy across dimensions, not H(X_d) per individual dimension. Do NOT use expecting per-dimension granularity. Requires an x402 payment.

Parametersn_binscorpus_vectorsrequired

nexus_similarity_search_api_score_pair_nmi_cosine

Computes the NMI-cosine fusion score for exactly one (query, target) vector pair at a fixed alpha. Use for explainability, debugging, or unit-level validation of fusion scores before running full corpus ranking. Unlike corpus-level ranking, alpha is NOT auto-calibrated for a single pair -- the real logic requires a fixed alpha (default 0.5); pass alpha explicitly for a specific blend. Do NOT use in a loop to score many pairs; batch them into rank_items_by_nmi_cosine_fusion instead. Requires an x402 payment.

Parametersalphan_binsvector_arequiredvector_brequired

Version history

1
  1. v1.0.0LatestSep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.