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 分

    请在仓库或注册中心条目中声明许可证。