smartapi-mcp 0.3.2__tar.gz → 0.5.0__tar.gz

{smartapi_mcp-0.3.2 → smartapi_mcp-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smartapi-mcp
-Version: 0.3.2
+Version: 0.5.0
 Summary: Create MCP servers for one or multiple APIs registered in SmartAPI registry
 Author-email: BioThings Team <help@biothings.io>
 Maintainer-email: BioThings Team <help@biothings.io>
@@ -25,13 +25,14 @@ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: awslabs_openapi_mcp_server<1,>=0.2.12
-Requires-Dist: fastmcp<3,>=2.14
+Requires-Dist: fastmcp<4,>=3.3.1
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: loguru<1,>=0.7.3
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
-Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: ruff<0.17,>=0.14; extra == "dev"
 Requires-Dist: build>=0.8.0; extra == "dev"
 Requires-Dist: twine>=4.0.0; extra == "dev"
 Provides-Extra: test
@@ -56,15 +57,17 @@ Create MCP (Model Context Protocol) servers for one or multiple APIs registered
 
 The SmartAPI MCP Server enables integration between MCP-compatible clients and APIs registered in the SmartAPI registry. This allows for seamless discovery and interaction with bioinformatics and life sciences APIs through standardized MCP protocols.
 
-Built on top of the [AWS Labs OpenAPI MCP Server](https://github.com/awslabs/openapi-mcp-server), this project extends MCP support to the extensive collection of APIs available in the SmartAPI registry, with special focus on bioinformatics and life sciences APIs.
+Built directly on [FastMCP](https://github.com/jlowin/fastmcp), this project extends MCP support to the extensive collection of APIs available in the SmartAPI registry, with special focus on bioinformatics and life sciences APIs.
+
+Earlier releases (through 0.3.2) wrapped the [AWS Labs OpenAPI MCP Server](https://github.com/awslabs/openapi-mcp-server); parts of `smartapi_mcp/openapi.py` are derived from that project's Apache-2.0 code. Dropping that wrapper reduced a clean install from 87 packages / 91 MB to 68 / 56 MB.
 
 ## Requirements
 
 - Python 3.10 or higher
 - Network access to SmartAPI registry (https://smart-api.info)
-- Dependencies: `awslabs_openapi_mcp_server>=0.2.12,<1` and `fastmcp>=2.14,<3`
-  (awslabs 1.x / fastmcp 3.x are not yet supported — see the dependency notes in
-  `pyproject.toml`)
+- Dependencies: `fastmcp>=3.3.1,<4`, `httpx`, `loguru` (fastmcp 4.x is not yet
+  supported — it moves to the MCP 2.x SDK and `httpx2`; see the dependency notes
+  in `pyproject.toml`)
 
 ## Features
 
@@ -247,6 +250,41 @@ inspect each BioThings spec at startup and serve any API that has extra
 endpoints with faithful per-API tools instead — at the cost of slower startup
 (it downloads the specs upfront).
 
+#### Tool search (`--tool-search`)
+
+The facade solves the tool explosion for BioThings APIs. `--tool-search` solves
+it for everything else, including per-API tools in a hybrid server: instead of
+listing every tool, the server lists two synthetic tools — `search_tools` and
+`call_tool` — and the model discovers what it needs on demand.
+
+```bash
+smartapi-mcp --api_set biothings_all --tool-search bm25
+```
+
+Every tool stays *callable* through `call_tool`; only the listing changes. Facade
+tools (`biothings_query`, `biothings_get`, …) stay listed, so the common path
+remains directly callable and only the per-API long tail is collapsed:
+
+```
+Tool search (bm25) enabled: 13 tools collapsed to 7 listed
+(5 pinned + search_tools/call_tool); max_results=5.
+All 13 tools stay callable via call_tool.
+```
+
+| Mode | Behaviour |
+| --- | --- |
+| `off` (default) | List every tool |
+| `bm25` | Rank matches by keyword relevance |
+| `regex` | Match tool names/descriptions by pattern |
+
+`--tool-search-max-results` (default 5) caps the hits per search. Both options
+have environment equivalents: `SMARTAPI_TOOL_SEARCH` and
+`TOOL_SEARCH_MAX_RESULTS`.
+
+Note that discovery-on-demand costs the model an extra round trip per unfamiliar
+tool, so leave it `off` for small sets where the full list already fits
+comfortably.
+
 #### Development/Testing Setup
 
 ```json
@@ -451,9 +489,10 @@ from smartapi_mcp import (
     load_api_spec,
     get_mcp_server,
     get_merged_mcp_server,
-    PREDEFINED_API_SETS
+    PREDEFINED_API_SETS,
 )
 
+
 async def main():
     # Get SmartAPI IDs using a query
     smartapi_ids = await get_smartapi_ids("tags.name=biothings")
@@ -463,16 +502,15 @@ async def main():
     api_spec = load_api_spec("59dce17363dce279d389100834e43648")  # MyGene.info
     print(f"Loaded API: {api_spec.get('info', {}).get('title', 'Unknown')}")
 
-    # Create MCP server for a single API
-    server = await get_mcp_server(
-        smartapi_id="59dce17363dce279d389100834e43648",
-        server_name="MyGene MCP Server"
-    )
+    # Create MCP server for a single API. The server is named after the
+    # spec's info.title; pass server_name to the merged/`build_server_for_set`
+    # entry points below if you want to choose the name yourself.
+    server = await get_mcp_server("59dce17363dce279d389100834e43648")
 
     # Create merged MCP server for multiple APIs (recommended approach)
     merged_server = await get_merged_mcp_server(
         api_set="biothings_core",  # Use predefined set
-        server_name="BioThings Core MCP Server"
+        server_name="BioThings Core MCP Server",
     )
 
     # Or with specific SmartAPI IDs
@@ -481,7 +519,7 @@ async def main():
             "59dce17363dce279d389100834e43648",  # MyGene.info
             "09c8782d9f4027712e65b95424adba79",  # MyVariant.info
         ],
-        server_name="Custom MCP Server"
+        server_name="Custom MCP Server",
     )
 
     # Show available predefined API sets
@@ -493,6 +531,7 @@ async def main():
     # Or run with HTTP transport
     # merged_server.run(transport="http", host="localhost", port=8000)
 
+
 if __name__ == "__main__":
     asyncio.run(main())
 ```
@@ -715,7 +754,8 @@ This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENS
 - **[SmartAPI Registry](https://smart-api.info/)** - Registry of biomedical and life sciences APIs
 - **[Model Context Protocol (MCP)](https://modelcontextprotocol.io/)** - Standard protocol for AI model-tool integration
 - **[BioThings APIs](https://biothings.io/)** - High-performance bioinformatics APIs
-- **[AWS Labs OpenAPI MCP Server](https://github.com/awslabs/openapi-mcp-server)** - Base MCP server framework
+- **[FastMCP](https://github.com/jlowin/fastmcp)** - MCP server framework this package builds on
+- **[AWS Labs OpenAPI MCP Server](https://github.com/awslabs/openapi-mcp-server)** - Wrapped by releases through 0.3.2; some code in `smartapi_mcp/openapi.py` is derived from it
 
 ## Citation
 

{smartapi_mcp-0.3.2 → smartapi_mcp-0.5.0}/README.md

@@ -11,15 +11,17 @@ Create MCP (Model Context Protocol) servers for one or multiple APIs registered
 
 The SmartAPI MCP Server enables integration between MCP-compatible clients and APIs registered in the SmartAPI registry. This allows for seamless discovery and interaction with bioinformatics and life sciences APIs through standardized MCP protocols.
 
-Built on top of the [AWS Labs OpenAPI MCP Server](https://github.com/awslabs/openapi-mcp-server), this project extends MCP support to the extensive collection of APIs available in the SmartAPI registry, with special focus on bioinformatics and life sciences APIs.
+Built directly on [FastMCP](https://github.com/jlowin/fastmcp), this project extends MCP support to the extensive collection of APIs available in the SmartAPI registry, with special focus on bioinformatics and life sciences APIs.
+
+Earlier releases (through 0.3.2) wrapped the [AWS Labs OpenAPI MCP Server](https://github.com/awslabs/openapi-mcp-server); parts of `smartapi_mcp/openapi.py` are derived from that project's Apache-2.0 code. Dropping that wrapper reduced a clean install from 87 packages / 91 MB to 68 / 56 MB.
 
 ## Requirements
 
 - Python 3.10 or higher
 - Network access to SmartAPI registry (https://smart-api.info)
-- Dependencies: `awslabs_openapi_mcp_server>=0.2.12,<1` and `fastmcp>=2.14,<3`
-  (awslabs 1.x / fastmcp 3.x are not yet supported — see the dependency notes in
-  `pyproject.toml`)
+- Dependencies: `fastmcp>=3.3.1,<4`, `httpx`, `loguru` (fastmcp 4.x is not yet
+  supported — it moves to the MCP 2.x SDK and `httpx2`; see the dependency notes
+  in `pyproject.toml`)
 
 ## Features
 
@@ -202,6 +204,41 @@ inspect each BioThings spec at startup and serve any API that has extra
 endpoints with faithful per-API tools instead — at the cost of slower startup
 (it downloads the specs upfront).
 
+#### Tool search (`--tool-search`)
+
+The facade solves the tool explosion for BioThings APIs. `--tool-search` solves
+it for everything else, including per-API tools in a hybrid server: instead of
+listing every tool, the server lists two synthetic tools — `search_tools` and
+`call_tool` — and the model discovers what it needs on demand.
+
+```bash
+smartapi-mcp --api_set biothings_all --tool-search bm25
+```
+
+Every tool stays *callable* through `call_tool`; only the listing changes. Facade
+tools (`biothings_query`, `biothings_get`, …) stay listed, so the common path
+remains directly callable and only the per-API long tail is collapsed:
+
+```
+Tool search (bm25) enabled: 13 tools collapsed to 7 listed
+(5 pinned + search_tools/call_tool); max_results=5.
+All 13 tools stay callable via call_tool.
+```
+
+| Mode | Behaviour |
+| --- | --- |
+| `off` (default) | List every tool |
+| `bm25` | Rank matches by keyword relevance |
+| `regex` | Match tool names/descriptions by pattern |
+
+`--tool-search-max-results` (default 5) caps the hits per search. Both options
+have environment equivalents: `SMARTAPI_TOOL_SEARCH` and
+`TOOL_SEARCH_MAX_RESULTS`.
+
+Note that discovery-on-demand costs the model an extra round trip per unfamiliar
+tool, so leave it `off` for small sets where the full list already fits
+comfortably.
+
 #### Development/Testing Setup
 
 ```json
@@ -406,9 +443,10 @@ from smartapi_mcp import (
     load_api_spec,
     get_mcp_server,
     get_merged_mcp_server,
-    PREDEFINED_API_SETS
+    PREDEFINED_API_SETS,
 )
 
+
 async def main():
     # Get SmartAPI IDs using a query
     smartapi_ids = await get_smartapi_ids("tags.name=biothings")
@@ -418,16 +456,15 @@ async def main():
     api_spec = load_api_spec("59dce17363dce279d389100834e43648")  # MyGene.info
     print(f"Loaded API: {api_spec.get('info', {}).get('title', 'Unknown')}")
 
-    # Create MCP server for a single API
-    server = await get_mcp_server(
-        smartapi_id="59dce17363dce279d389100834e43648",
-        server_name="MyGene MCP Server"
-    )
+    # Create MCP server for a single API. The server is named after the
+    # spec's info.title; pass server_name to the merged/`build_server_for_set`
+    # entry points below if you want to choose the name yourself.
+    server = await get_mcp_server("59dce17363dce279d389100834e43648")
 
     # Create merged MCP server for multiple APIs (recommended approach)
     merged_server = await get_merged_mcp_server(
         api_set="biothings_core",  # Use predefined set
-        server_name="BioThings Core MCP Server"
+        server_name="BioThings Core MCP Server",
     )
 
     # Or with specific SmartAPI IDs
@@ -436,7 +473,7 @@ async def main():
             "59dce17363dce279d389100834e43648",  # MyGene.info
             "09c8782d9f4027712e65b95424adba79",  # MyVariant.info
         ],
-        server_name="Custom MCP Server"
+        server_name="Custom MCP Server",
     )
 
     # Show available predefined API sets
@@ -448,6 +485,7 @@ async def main():
     # Or run with HTTP transport
     # merged_server.run(transport="http", host="localhost", port=8000)
 
+
 if __name__ == "__main__":
     asyncio.run(main())
 ```
@@ -670,7 +708,8 @@ This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENS
 - **[SmartAPI Registry](https://smart-api.info/)** - Registry of biomedical and life sciences APIs
 - **[Model Context Protocol (MCP)](https://modelcontextprotocol.io/)** - Standard protocol for AI model-tool integration
 - **[BioThings APIs](https://biothings.io/)** - High-performance bioinformatics APIs
-- **[AWS Labs OpenAPI MCP Server](https://github.com/awslabs/openapi-mcp-server)** - Base MCP server framework
+- **[FastMCP](https://github.com/jlowin/fastmcp)** - MCP server framework this package builds on
+- **[AWS Labs OpenAPI MCP Server](https://github.com/awslabs/openapi-mcp-server)** - Wrapped by releases through 0.3.2; some code in `smartapi_mcp/openapi.py` is derived from it
 
 ## Citation
 

{smartapi_mcp-0.3.2 → smartapi_mcp-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "smartapi-mcp"
-version = "0.3.2"
+version = "0.5.0"
 description = "Create MCP servers for one or multiple APIs registered in SmartAPI registry"
 readme = "README.md"
 license = "Apache-2.0"
@@ -32,12 +32,15 @@ classifiers = [
 keywords = ["mcp", "smartapi", "api", "server", "bioinformatics"]
 requires-python = ">=3.10"
 dependencies = [
-    # awslabs 1.x requires fastmcp 3.x, which removed FastMCP.get_tools() and
-    # rejects *args tool functions -- incompatible with this package for now.
-    # fastmcp is also pinned <3 directly because awslabs 0.2.x allows fastmcp>=2.14
-    # with no upper bound and would otherwise resolve to the breaking 3.x.
-    "awslabs_openapi_mcp_server>=0.2.12,<1",
-    "fastmcp>=2.14,<3",
+    # Upper bound: fastmcp 4.x moves to the MCP 2.x SDK and httpx2, which this
+    # package has not been migrated to or tested against.
+    "fastmcp>=3.3.1,<4",
+    # Spec fetching. Also a fastmcp[client] dependency, but declared here
+    # because smartapi_mcp.openapi and smartapi_mcp.smartapi import it directly.
+    "httpx>=0.28.1,<1",
+    # Logging. Kept after dropping awslabs_openapi_mcp_server, which supplied
+    # the preconfigured logger this package's modules were written against.
+    "loguru>=0.7.3,<1",
 ]
 
 [project.optional-dependencies]
@@ -45,7 +48,10 @@ dev = [
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",
     "pytest-cov>=4.0.0",
-    "ruff>=0.1.0",
+    # Upper bound deliberately: an unpinned linter makes CI results drift
+    # with upstream releases, failing on unchanged code. Raise it
+    # intentionally, with a lint/format pass, rather than by surprise.
+    "ruff>=0.14,<0.17",
     "build>=0.8.0",
     "twine>=4.0.0",
 ]
@@ -92,7 +98,6 @@ asyncio_mode = "auto"
 [tool.coverage.run]
 source = ["smartapi_mcp"]
 omit = [
-    "smartapi_mcp/awslabs_server.py",
     "smartapi_mcp/__main__.py",
     "tests/*",
 ]
@@ -199,8 +204,11 @@ ignore = [
     "B027",
     # Allow boolean positional values in function calls
     "FBT003",
-    # Ignore complexity
-    "C901", "PLR0911", "PLR0912", "PLR0913", "PLR0915",
+    # Ignore complexity. PLR0917 (too-many-positional-arguments) is the same
+    # complaint as PLR0913 for the build entry points, which take a set of
+    # mutually exclusive API selectors; making them keyword-only would be a
+    # breaking change to the public API.
+    "C901", "PLR0911", "PLR0912", "PLR0913", "PLR0915", "PLR0917",
     # Allow print statements (useful for CLI tools)
     "T201",
     # Allow assert statements
@@ -246,8 +254,5 @@ max-complexity = 10
 "tests/*" = ["PLR2004", "S101", "PT011", "PT012", "ARG002", "PT019"]
 # CLI module can use print statements and sys.exit
 "smartapi_mcp/cli.py" = ["T201", "PLR0913"]
-# Do not fix linting errors in awslabs_server.py as it's
-# based on the original codebase
-"smartapi_mcp/awslabs_server.py" = ["ALL"]
 # Allow star imports and unused imports in __init__.py
 "__init__.py" = ["F401", "F403", "F405"]

{smartapi_mcp-0.3.2 → smartapi_mcp-0.5.0}/smartapi_mcp/__init__.py

@@ -4,13 +4,19 @@ SmartAPI MCP Server Package
 Create MCP servers for one or multiple APIs registered in SmartAPI registry.
 """
 
-__version__ = "0.3.2"
+__version__ = "0.5.0"
 __author__ = "BioThings Team"
 __email__ = "help@biothings.io"
 
 # Optional imports for when dependencies are available
 try:
     from .biothings import build_biothings_facade, build_registry
+    from .openapi import (
+        SpecError,
+        build_openapi_server,
+        fetch_spec,
+        resolve_internal_refs,
+    )
     from .server import (
         build_server_for_set,
         get_mcp_server,
@@ -28,9 +34,12 @@ try:
 
     __all__ = [
         "PREDEFINED_API_SETS",
+        "SpecError",
         "build_biothings_facade",
+        "build_openapi_server",
         "build_registry",
         "build_server_for_set",
+        "fetch_spec",
         "get_base_server_url",
         "get_mcp_server",
         "get_merged_mcp_server",
@@ -39,6 +48,7 @@ try:
         "get_smartapi_registry",
         "load_api_spec",
         "merge_mcp_servers",
+        "resolve_internal_refs",
     ]
 except ImportError:
     # Dependencies not available, only export version info

{smartapi_mcp-0.3.2 → smartapi_mcp-0.5.0}/smartapi_mcp/biothings.py

@@ -12,15 +12,17 @@ the set, so the server works on every MCP client without depending on runtime
 """
 
 import asyncio
+import math
 import re
 from dataclasses import dataclass, field
 
 import httpx
-from awslabs.openapi_mcp_server import logger
 from fastmcp import FastMCP
 from fastmcp.tools import Tool
 
+from .log import logger
 from .smartapi import (
+    CORE_BIOTHINGS_API_IDS,
     HTTP_TIMEOUT,
     get_base_server_url,
     get_smartapi_registry,
@@ -37,6 +39,20 @@ _MAX_DESC_LEN = 200
 # HTTP methods recognized when enumerating spec operations.
 _HTTP_METHODS = {"get", "post", "put", "delete", "patch", "head", "options"}
 
+# Tags that disqualify an API from the BioThings *annotation-API family* even
+# though it carries the "biothings" tag. TRAPI services (BioThings Explorer,
+# Service Provider) are built by the same team and tagged accordingly, but they
+# speak the Translator Reasoner API -- a query-graph protocol -- not the
+# BioThings annotation interface, so none of the generic facade tools apply to
+# them. They are served with faithful per-API tools instead.
+#
+# This is not a cosmetic distinction: the facade infers an entity type from the
+# first ``/{type}/{id}``-shaped path, and BTE's ``GET /asyncquery_status/{id}``
+# matches that shape. Without this exclusion, ``biothings_get`` would request
+# ``/asyncquery_status/<id>`` and return a job status as though it were an
+# annotation record -- a wrong answer with no error.
+NON_FAMILY_TAGS = frozenset({"trapi"})
+
 
 @dataclass
 class BioThingsAPIEntry:
@@ -96,11 +112,21 @@ async def build_registry(
     return build_registry_from_entries(entries)
 
 
+def is_biothings_family(entry: BioThingsAPIEntry) -> bool:
+    """Whether ``entry`` is a BioThings annotation API the facade can serve.
+
+    Requires the ``biothings`` tag and the absence of any
+    :data:`NON_FAMILY_TAGS`.
+    """
+    tags = {str(tag).strip().lower() for tag in entry.tags}
+    return "biothings" in tags and not (tags & NON_FAMILY_TAGS)
+
+
 def is_biothings_registry(registry: dict[str, BioThingsAPIEntry]) -> bool:
-    """True only if every API in the registry is tagged ``biothings``."""
+    """True only if every API in the registry is a facade-servable BioThings API."""
     if not registry:
         return False
-    return all("biothings" in entry.tags for entry in registry.values())
+    return all(is_biothings_family(entry) for entry in registry.values())
 
 
 def _resolve_endpoints(entry: BioThingsAPIEntry) -> None:
@@ -225,12 +251,146 @@ async def partition_biothings(
     return facade_entries, extra_ids
 
 
-def _score_entry(entry: BioThingsAPIEntry, tokens: list[str]) -> int:
-    """Lexical relevance: count token hits across title/description/tags."""
-    haystack = " ".join(
-        [entry.name, entry.title, entry.description, " ".join(entry.tags)]
-    ).lower()
-    return sum(haystack.count(token) for token in tokens)
+# Words too common to discriminate between APIs. Without this, a natural-language
+# intent like "get a gene annotation by its Entrez gene id" is dominated by
+# "get"/"a"/"by"/"its"/"id" rather than by "gene" and "entrez".
+_STOPWORDS = frozenset(
+    {
+        "a",
+        "an",
+        "and",
+        "are",
+        "as",
+        "at",
+        "be",
+        "by",
+        "for",
+        "from",
+        "get",
+        "how",
+        "in",
+        "into",
+        "is",
+        "it",
+        "its",
+        "of",
+        "on",
+        "or",
+        "that",
+        "the",
+        "their",
+        "them",
+        "there",
+        "these",
+        "this",
+        "to",
+        "what",
+        "when",
+        "where",
+        "which",
+        "who",
+        "with",
+        "api",
+        "apis",
+        "data",
+        "database",
+        "dataset",
+        "info",
+        "information",
+        "record",
+        "records",
+        "service",
+        "services",
+    }
+)
+
+
+def _tokenize(text: str) -> list[str]:
+    """Lower-case word tokens. Word-based, not substring-based, on purpose.
+
+    The previous scorer used ``str.count`` on the raw text, so a query term
+    like "id" also matched inside "identifier", "candidate" and "provide".
+    """
+    return re.findall(r"[a-z0-9]+", text.lower())
+
+
+# How much more a term in the API's name/title counts than one buried in its
+# description. An API *named* for a concept is a far stronger answer to a query
+# about that concept than one merely mentioning it in prose; without this,
+# scores tie constantly and the tie-break (alphabetical) decides, which
+# systematically favours the "biothings_*"-prefixed names over MyGene/MyChem.
+_NAME_FIELD_WEIGHT = 3.0
+
+# Score multiplier for the core BioThings APIs (:data:`CORE_BIOTHINGS_API_IDS`).
+#
+# These are the canonical broad-coverage services, and they are the *worst*
+# served by pure lexical scoring: being general means their descriptions carry
+# the least distinctive vocabulary, while single-source satellite APIs read as
+# highly specific. So a lexical ranker systematically under-ranks exactly the
+# APIs a user most often wants, and needs a prior to correct for it.
+#
+# Measured on 20 BioThings intents. With the registry descriptions as they were
+# before the core-API enrichment, no boost gave recall@5 16/20 (MRR 0.71) and
+# only 3 of the 6 core-API intents were answered; 1.2 gives 19/20 (MRR 0.82).
+# With the enriched descriptions live, no boost already gives 19/20 (MRR 0.92)
+# and 1.2 gives 20/20 (MRR 0.90). Larger values buy nothing on recall and cost
+# ranking quality once the metadata is good -- at 3.0 the post-enrichment MRR
+# falls to 0.81 -- so this is deliberately the smallest value that captures the
+# benefit, and it stays close to neutral as the metadata improves.
+CORE_API_BOOST = 1.2
+
+_CORE_API_IDS = frozenset(CORE_BIOTHINGS_API_IDS)
+
+
+def _entry_terms(entry: BioThingsAPIEntry) -> tuple[set[str], set[str]]:
+    """Return ``(name_terms, all_terms)`` for one API.
+
+    ``name_terms`` covers the short name, title and tags -- the curated labels;
+    ``all_terms`` adds the free-text description.
+    """
+    name_terms = set(
+        _tokenize(" ".join([entry.name, entry.title, " ".join(map(str, entry.tags))]))
+    )
+    return name_terms, name_terms | set(_tokenize(entry.description))
+
+
+def _score_entry(
+    terms: tuple[set[str], set[str]],
+    query_terms: list[str],
+    idf: dict[str, float],
+) -> float:
+    """Score one API against a query. Higher is more relevant.
+
+    ``terms`` is the ``(name_terms, all_terms)`` pair from :func:`_entry_terms`.
+
+    Three deliberate properties:
+
+    * **Binary term frequency.** A term counts once however often it appears, so
+      an API with a long, repetitive description no longer outranks a precisely
+      matching one. This was the concrete defect in the previous scorer:
+      searching "get a gene annotation by its Entrez gene id" ranked MyGeneSet
+      above MyGene, because summed substring counts reward verbosity.
+    * **IDF weighting.** A term shared by most APIs ("gene", "translator")
+      contributes almost nothing, while a rare one ("entrez", "ngd", "taxonomy")
+      dominates -- which is what makes an intent select the API it names.
+    * **Field weighting.** A hit in the name/title/tags counts
+      :data:`_NAME_FIELD_WEIGHT` times one that is only in the description. An
+      API *named* for a concept answers a query about it far better than one
+      merely mentioning it in prose, and without this, scores tie constantly and
+      the alphabetical tie-break decides -- which systematically favoured the
+      ``biothings_*``-prefixed names over MyGene/MyChem/MyVariant.
+    """
+    name_terms, all_terms = terms
+    score = 0.0
+    for term in query_terms:
+        weight = idf.get(term, 0.0)
+        if not weight:
+            continue
+        if term in name_terms:
+            score += weight * _NAME_FIELD_WEIGHT
+        elif term in all_terms:
+            score += weight
+    return score
 
 
 def rank_apis(
@@ -258,11 +418,38 @@ def rank_apis(
     if not keyword or not keyword.strip():
         return [_as_dict(registry[name]) for name in sorted(registry)]
 
-    tokens = [tok for tok in re.split(r"\W+", keyword.lower()) if tok]
-    scored = [(_score_entry(entry, tokens), entry) for entry in registry.values()]
+    query_terms = [t for t in _tokenize(keyword) if t not in _STOPWORDS]
+    if not query_terms:
+        # Nothing discriminating left (e.g. "what data is there?"): fall back to
+        # the full catalog rather than returning an arbitrary subset.
+        return [_as_dict(registry[name]) for name in sorted(registry)]
+
+    terms_by_name = {name: _entry_terms(entry) for name, entry in registry.items()}
+    total = len(registry)
+    idf = {}
+    for term in set(query_terms):
+        seen_in = sum(1 for _, all_terms in terms_by_name.values() if term in all_terms)
+        # Robertson/Sparck-Jones IDF. Chosen over the plain log(N/n) form
+        # because it stays strictly positive even for a term present in every
+        # API: with a small registry (say two APIs that both mention "gene"),
+        # a zero weight would drop every candidate and the search would answer
+        # "nothing found" for a query that in fact matches everything.
+        idf[term] = math.log(1 + (total - seen_in + 0.5) / (seen_in + 0.5))
+
+    scored = []
+    for name, entry in registry.items():
+        score = _score_entry(terms_by_name[name], query_terms, idf)
+        if entry.smartapi_id in _CORE_API_IDS:
+            # Multiplicative, not additive: a zero score stays zero, so the
+            # boost reorders results that already match and never promotes a
+            # core API into a query it has nothing to do with.
+            score *= CORE_API_BOOST
+        scored.append((score, entry))
     scored = [pair for pair in scored if pair[0] > 0]
     scored.sort(key=lambda pair: (-pair[0], pair[1].name))
-    return [{**_as_dict(entry), "score": score} for score, entry in scored[:limit]]
+    return [
+        {**_as_dict(entry), "score": round(score, 3)} for score, entry in scored[:limit]
+    ]
 
 
 def build_biothings_facade(