Similarity Search Api Sdk

io.github.nexus-mcp-infra由 GitHub 帳號 nexus-mcp-infra 發布v1.0.0更新於 Oct 24, 2026

Stateless NMI + cosine fusion with entropy-driven alpha calibration

已驗證Streamable HTTP可網頁執行資料與分析AI 與機器學習

概覽

AI 產生的概覽

遠端 MCP 伺服器,以熵校準的 NMI 與餘弦融合分數為預先計算的向量排序,無須自行架設向量資料庫。

可以做什麼
以校準後的融合分數,將一批預先計算的向量與查詢向量排序,結果以語料中的位置標示,也可固定混合權重而不自動校準。在送出完整排序前,先估算語料的聚合熵與校準後的 alpha。以固定 alpha 為單一查詢與目標向量對評分,用於可解釋性、除錯或單元層級驗證。此伺服器不負責文字嵌入,向量須來自你自己的嵌入模型。
適用情境
當你已有嵌入向量,想要一種無狀態、融合餘弦與正規化互資訊的相似度排序,而不想架設向量資料庫或索引時適用。也適合在執行大規模語料搜尋前檢查校準行為或驗證單對分數。
執行需求
遠端 streamable HTTP 端點,無須本機執行環境或套件。業務路由不需要 API 金鑰,但每次呼叫需透過 x402 付款(Base Sepolia 測試網上的 USDC,每次 0.01 美元),或使用已設定 API 金鑰的 Stripe 用量計費。向量須預先計算,維度一致且在 2 至 4,096 之間,單次語料上限 500,000 筆。
安裝前請注意
呼叫會產生費用:x402 每次 0.01 美元,目前位於 Base Sepolia 測試網;未付款的請求會回傳 402 Payment Required。你的向量會傳送到第三方託管服務。README 列出 5 個 MCP 工具,而清單只列出 3 個,實際可用工具可能與文件不一致。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Similarity Search Api Sdk,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Web executable,透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

交給代理程式安裝

把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式,或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南,先向你展示發布者、端點和登入方式,經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。

閱讀 https://sourceweft.com/mcp/io.github.nexus-mcp-infra%2Fsimilarity-search-api-sdk/install.md,並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前,先告訴我它的發布者、端點和登入方式,等我確認。不要把 API 金鑰寫進命令或我會提交的檔案;問我金鑰應從哪裡取得。

檢視代理程式所依據的安裝指南

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

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

來源:README.md,提交 9f2faf3

工具

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.

輸入參數top_kn_binsquery_vector必填alpha_overridecorpus_vectors必填

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.

輸入參數n_binscorpus_vectors必填

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.

輸入參數alphan_binsvector_a必填vector_b必填

版本歷史

1
  1. v1.0.0最新Sep 16, 2026

評分

已滿足適用檢查項的 90%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通必需25 分
  • 已宣告認證方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分

    請在儲存庫或註冊中心條目中宣告授權條款。