Searchloinc

A thin MCP server wrapping the LOINC Search API so LLMs can search LOINC the same way a human does via loinc.org/search — free-text, relevance-ranked, faceted. It targets the documented Search API (https://loinc.regenstrief.org/searchapi/), not the FHIR terminology service.

Setup

uv sync --extra dev
cp .env.example .env   # then fill in your LOINC credentials

Credentials come from a free registration on loinc.org. Set LOINC_USERNAME and LOINC_PASSWORD in the environment (never commit them).

Run

From a checkout (development):

uv run python -m searchloinc

Or install it as a standalone command and run it from anywhere:

uv tool install .          # puts a `searchloinc` executable on PATH
searchloinc                # starts the stdio server

Both run the server over stdio (the transport MCP clients expect). Point your client at the command, or add it to your client's MCP server config. When you use the installed command, supply credentials through the client's env block (sourced from your secret store / shell — never committed):

{
  "mcpServers": {
    "searchloinc": {
      "command": "searchloinc",
      "env": {
        "LOINC_USERNAME": "your-loinc-username",
        "LOINC_PASSWORD": "your-loinc-password"
      }
    }
  }
}

The checked-in .mcp.json uses the dev form (uv run --env-file .env) so a local checkout picks up credentials from .env automatically.

Tools

Two-tier design — cheap compact search for triage, explicit drill-in for detail:

• search_loincs — LOINC terms (lab tests, vitals, measurements, panels, surveys). The main table.
• search_answerlists — enumerated answer sets attached to survey/nominal terms.
• search_parts — the LP-coded building blocks (components, systems, methods, properties).
• search_groups — curated collections of related terms.
• get_loinc(code) — drill into one term by exact code; returns the full flat record.

Each search tool takes query (required), rows, offset, sortorder, language, and include_facets. Pick the scope that matches what you're after; results are relevance-ranked, so if the top hits miss, reformulate rather than deep-page. Triage with a search tool, then get_loinc the code you want.

Output shape

Search responses are a JSON envelope plus a result table:

• The table is serialized as TOON — a compact tabular format that pays the column-name cost once, so wide uniform tables stay small. Columns are fixed per scope; empty fields render as "" to preserve row uniformity. Tab-delimited (LOINC display values contain commas but never tabs).
• The envelope reports requested, returned, total, offset, and truncated.

Character budget & pagination. The whole serialized payload is capped at 9500 characters (a cushion under the ~10K downstream tool-result limit). The row-packing loop encodes and measures the full payload incrementally and stops before the cap; when results don't all fit, truncated is true — page forward with offset. include_facets (filter counts) is off by default and opt-in; facet payloads still respect the budget.

get_loinc returns a single JSON object — the flat search-API record with null/empty fields dropped (always keeping Link), so the field set adapts to the term type. Page-only content (part LP hierarchy, language variants, curated part descriptions) is not in the flat record — follow Link to loinc.org for it.

There is a debug-only raw-JSON path toggled by the SEARCHLOINC_RAW_JSON env var; it is never exposed as an agent-facing tool parameter.

Development

uv run ruff check searchloinc   # lint
uv run pytest                   # tests (no network; API stubbed with fixtures)

The /loinc-search skill drives the live API to validate wrapper output against ground truth.

Status

Wrapper is implemented and validated against the live API. Eventual deployment target is a Databricks app (credentials via secret scope, inference via AI Gateway).

License & attribution

The SearchLOINC code is licensed under the MIT License.

This project wraps the LOINC Search API and includes sample LOINC API responses as test fixtures. That LOINC (and referenced SNOMED CT) content is not covered by the MIT license and remains under its own terms — see NOTICE for the required attributions.

This material contains content from LOINC (http://loinc.org). LOINC is copyright © Regenstrief Institute, Inc. and the Logical Observation Identifiers Names and Codes (LOINC) Committee and is available at no cost under the license at http://loinc.org/license. LOINC® is a registered United States trademark of Regenstrief Institute, Inc.