Trials & Drug Resolver

Free Model Context Protocol server that harmonises drug and clinical-trial facts from licence-clean public sources. It is the v1 open-source resolver for Biolyt AI.

The server speaks MCP over stdio. It runs with no API keys. Optional LLM and embedding steps are off unless you turn them on.

This package is not published, and this repository is private. Nothing here publishes to npm or the MCP registry, and nothing changes repository visibility.

Tools

Tool	What it returns
resolve_drug	Verified UNII, ChEMBL ID, and RxCUI (when one exists), a canonical name, the match method, and a confidence flag. Combinations come back as one component each. none means the server will not guess.
search_trials	ClinicalTrials.gov v2 studies. A drug argument is resolved first and the search uses those synonyms. Duplicate NCT records are merged. Sponsor names are normalised.
competitive_landscape	Drugs in development for a target or an indication, with mechanisms, sponsors, and trial phases. ChEMBL supplies targets and mechanisms. ClinicalTrials.gov supplies sponsors and phases. Results are capped.
drug_profile	One resolved drug: synonyms, identifiers, mechanisms, linked trials, and sponsors.
get_eu_trial_sites	Authorised EU CTIS sites for one CT number: organisation, ORG key, address, department, city, postcode, country, principal investigator, and per-country dates. Emails and phone numbers are removed.
search_eu_trials	EU CTIS overviews by condition, sponsor, country, or public status. Country is filtered from the overview rows. Pages past the 10,000-row cap use the opposite sort.
find_trials_at_site	CTIS trials whose authorised sites match an organisation name. Pass the name; OMS ORG- keys are not in the public search index.

resolve_drug confidence is high for a verified exact synonym, medium for a verified non-exact pick, and none when nothing is returned. matchMethod is one of exact_synonym, deterministic_rank, embedding_assisted_rank, or llm_pick.

Resolution pipeline

1. Clean the input. Dose, dosage form, route, and trademark marks are removed. Combinations split on /, +, and, with, and plus. Hyphens inside a code stay intact.
2. Exact synonym lookup across FDA GSRS, ChEMBL, and RxNorm. A hit is kept only when the source record really contains that name.
3. Code names never take the fuzzy path. MK-3475, MK3475, and BMS-936558 are looked up as exact strings (hyphen inserted or removed only). If that misses, the answer is none. RxNorm's approximate index maps MK-3475 toward vitamin MK products; that match is not used.
4. For an ordinary miss, candidates come from RxNorm approximate match, ChEMBL search, and, if configured, an embedding retriever.
5. An optional LLM may choose only an id from that list, or none. If it names anything else, the answer is none.
6. With the LLM off, a deterministic ranker accepts one clear string neighbour above a conservative threshold (stricter for short strings, and stricter still for embedding-only hits). Otherwise it returns none.
7. Chosen UNII, ChEMBL, and RxCUI values are fetched again from the source API and dropped if the record does not agree.

ChEMBL ATC classifications are not copied into results. WHO ATC is out of scope even when a ChEMBL payload happens to contain the field.

Data sources

Responses include a short attribution list for the sources that actually contributed.

Source	Use	Attribution
ClinicalTrials.gov API v2	Trial search	U.S. National Library of Medicine. Public-domain federal work.
ChEMBL	Molecules, synonyms, targets, mechanisms	EMBL-EBI. Data licence: CC BY-SA 3.0.
UniChem	Structure crosswalk for small molecules (UCI, InChIKey, PubChem CID, FDA SRS UNII)	EMBL-EBI. DrugBank identifiers in the payload are discarded. Biologics such as pembrolizumab have no UniChem structure and are not queried.
FDA GSRS / UNII	Substance names and Unique Ingredient Identifiers	U.S. government public-domain data, served by NIH/NCATS.
RxNorm API	Exact and approximate RxCUI lookup	U.S. National Library of Medicine. No UMLS key is sent. Atom strings whose RxNorm source is DrugBank are ignored.
EU CTIS	Trial overviews and authorised sites for trials under Regulation 536/2014	European Medicines Agency. Credit EMA/CTIS when you store or republish results. Investigator emails and telephone numbers are stripped. Protocol and consent documents are not downloaded.

Please keep those attributions if you store or republish tool output. The code in this repository is under the MIT placeholder below. That licence does not relicense upstream data. ChEMBL excerpts remain under CC BY-SA 3.0.

The client sends BiolytTrialsDrugResolver/1.1 as its User-Agent, caches successful JSON (default 6 hours, 300 entries), and spaces calls per host (ClinicalTrials.gov 350 ms, GSRS 400 ms, EU CTIS 400 ms, EMBL-EBI 200 ms, RxNorm 120 ms). Retries cover 429 and 5xx.

EU CTIS sites

Version 1.1.0 adds the public CTIS API used by the portal at euclinicaltrials.eu. v1 did not call it. The API is unauthenticated and undocumented; these tools use the same POST /ctis-public-api/search and GET /ctis-public-api/retrieve/{ctNumber} calls the portal makes.

• get_eu_trial_sites reads one full record and returns sites under each member state, with decision and recruitment dates.
• search_eu_trials searches overviews. medicalCondition, sponsor, and numeric status are sent to CTIS. There is no reliable country parameter, so a country name or code such as FR is applied to the returned overviews. A country-only search scans at most 400 recent overviews. The service stops after 10,000 overviews in one sort direction; a later page is read with the sort reversed, which is how the 10,000-row cap is covered.
• find_trials_at_site searches overview text for an organisation name, then retrieves a few full records (default 8, maximum 15) and keeps sites whose name matches. An ORG- or ORL- key alone cannot be resolved: those keys are not in the search index, and this server does not crawl all 12,000 trials.

Sites are the locations named at authorisation, not a live recruiting-status feed. The code after a country in an overview, such as France:2, is a public status code, not a count of sites.

Emails and telephone numbers on investigators and site records are dropped, including addresses or department text that contain them. Do not treat the result as a contact list.

Excluded sources

These are intentionally not called:

• WHO ICTRP. The WHO trial registry's terms do not give a clean licence to redistribute registry extracts inside an open tool. Trial search uses ClinicalTrials.gov instead.
• WHO ATC / DDD. The ATC classification is not freely redistributable. This server does not query it and does not emit ATC codes from ChEMBL records.
• DrugBank (full database). DrugBank is proprietary. Academic access does not allow shipping it in an open-source product. UniChem DrugBank crosswalks and RxNorm DrugBank atom strings are dropped.
• Legacy EU CTR / EudraCT (clinicaltrialsregister.eu). Public records give a count of sites per member state, not organisation or investigator names. This server does not call it. CTIS, above, covers trials under Regulation 536/2014.

Install

Requires Node.js 20 or newer.

git clone https://github.com/Postlytllp/trials-drug-resolver-mcp.git
cd trials-drug-resolver-mcp
npm install
npm run build

The stdio entry point is dist/index.js. A global install after a future npm publish would expose trials-drug-resolver-mcp. Do not publish from this tree unless you mean to.

Claude Desktop

{
  "mcpServers": {
    "trials-drug-resolver": {
      "command": "node",
      "args": ["/absolute/path/to/trials-drug-resolver-mcp/dist/index.js"],
      "env": {
        "BIOLYT_CTA": "0",
        "RESOLVER_LLM": "off",
        "RESOLVER_EMBEDDINGS": "off"
      }
    }
  }
}

Cursor

Put the same mcpServers object in ~/.cursor/mcp.json (or the project .cursor/mcp.json). Restart Cursor after saving. The process must stay on stdio: logs go to stderr, not stdout.

After the package is published, npx -y trials-drug-resolver-mcp can replace the node command. It is not on npm yet.

Optional LLM and embeddings

Both are off by default, so the server answers with no keys.

Variable	Default	Meaning
RESOLVER_LLM	off	openai, anthropic, or http
RESOLVER_LLM_API_KEY	empty	Key for OpenAI or Anthropic. Optional bearer token for http
RESOLVER_LLM_MODEL	empty	Required for openai and anthropic. Missing model or key falls back to deterministic ranking
RESOLVER_LLM_BASE_URL	OpenAI https://api.openai.com/v1	OpenAI-compatible base, or the full URL for RESOLVER_LLM=http
RESOLVER_EMBEDDINGS	off	http posts { "query", "limit" } and expects { "candidates": [...] }
RESOLVER_EMBEDDINGS_URL	empty	Retriever endpoint
RESOLVER_EMBEDDINGS_API_KEY	empty	Optional bearer token
RESOLVER_CACHE_TTL_MS	21600000	Cache lifetime
RESOLVER_CACHE_MAX	300	Cache entries
RESOLVER_HTTP_TIMEOUT_MS	20000	Per-request timeout

The HTTP LLM contract is a POST of { "query", "candidates": [{ "id", "name", "source", "synonyms" }] } returning { "choice": "<id>" } or { "choice": "none" }. The picker cannot introduce an identifier that was not in candidates.

Embedding candidates are only another retrieval source. Without an LLM they still have to pass the string-similarity threshold. With an LLM, the model may pick one, and the identifier is still re-fetched from GSRS, ChEMBL, or RxNorm.

Optional teaser footer

Disabled by default. Set BIOLYT_CTA=1 to add a second text block after the JSON:

Trials & Drug Resolver is a Biolyt AI project. https://biolytai.com

That sentence is fixed. The hook does not invent news, trial readouts, or other promotional copy. The implementation is marked in src/cta.ts.

Development

npm test          # unit tests, mocked HTTP, plus the hand-checked set
npm run lint
npm run build
BIOLYT_LIVE=1 npm run test:live
npm run smoke     # live: MK-3475 must resolve to pembrolizumab

The hand-checked set lives in tests/fixtures/resolution-set.json. It includes MK-3475 (pembrolizumab), BMS-936558 / ONO-4538 / MDX1106 (nivolumab), brand and dose strings, misspellings (pembrolizamab, nivolamab), and negatives (MK-999999, notadrugzzzz, the stem pembro). Code-name cases assert that RxNorm approximate match is never called.

Live tests are skipped unless BIOLYT_LIVE=1. CI runs lint, unit tests, and the TypeScript build. It does not call the upstream APIs.

Licence

The LICENSE file is the MIT licence as a placeholder. Biolyt AI may replace it. See the open questions below before treating tool output as MIT-licensed data.

Open licence and attribution questions

• ChEMBL is CC BY-SA 3.0. Shipping queries live is not the same as redistributing the ChEMBL database, but saved tool output can be a CC BY-SA excerpt. Confirm whether downstream storage needs share-alike, and whether the code licence should stay MIT.
• UniChem's current data licence should be confirmed with EMBL-EBI. v1 keeps only UCI, standard InChIKey, PubChem CID, and FDA SRS UNII, and drops every other source, including DrugBank.
• RxNorm is free to call, but some constituent vocabularies are not. Without a UMLS key the API omits those strings. v1 does not ask for a UMLS key. Say if a key should be optional later.
• GSRS search responses include full substance records (protein sequence included). v1 keeps names and the UNII only, but the transfer is larger than the fields we use. A slimmer view, if NCATS offers one, would be kinder.
• The MIT file is a placeholder. The npm name trials-drug-resolver-mcp and the registry name io.github.Postlytllp/trials-drug-resolver are reserved in metadata only. They have not been published.
• EU CTIS has no separate API terms. The EMA legal notice allows EMA webpage content to be reproduced for non-commercial and commercial purposes when EMA is acknowledged as the source. It does not clearly say that this covers the undocumented JSON API, and it does not cover third-party content such as sponsor protocols or consent forms. This server does not download those documents. EMA written confirmation is still the safe step before large-scale redistribution. Investigator names are published by CTIS and are returned; emails and telephone numbers are personal data and are stripped here. That is a product choice, not legal advice.