IMO Health MCP Server

Apply refinements as nested GraphQL traversal to find progressively more specific IMO lexicals. IMPORTANT: Use the 'lexical_code' value from normalize_medical_term results as the code parameter (NOT the imo_code). This tool builds a single nested GraphQL query where each refinement level creates a deeper narrower() call. The depth of nesting is determined dynamically by the length of refinement_sequence. Example: refinement_sequence=[["230"], ["362636588"], ["1328819463"]], domain="problem" generates: lexical(code: "601056", domain: problem) { narrower(refinements: ["230"]) { ... on ProblemLexical { allowedRefinements { ... } } narrower(refinements: ["362636588"]) { ... on ProblemLexical { allowedRefinements { ... } } narrower(refinements: ["1328819463"]) { ... on ProblemLexical { allowedRefinements { ... } } } } } } This is ideal for LangChain agents that need to drill down through multiple refinement levels in a single query. The agent determines the depth dynamically based on user requirements.

Get narrower IMO lexicals filtered by specific refinement criteria. IMPORTANT: Use the 'lexical_code' value from normalize_medical_term results as the code parameter (NOT the imo_code). Returns only the narrower (more specific) IMO lexicals that match the given refinement codes. Use this after calling get_allowed_refinements to filter children by specific refinement options (e.g., find all knee pain variants with laterality:right). Note: appliedRefinements are only available for the 'problem' domain. Results are paged: total_matching_available is the true size of the filtered set, total_matching is what this page contains, and `offset` walks further.

Look up all refinements within a specific refinement group. Returns the group title and all available refinement options within the category. Use this to see all possible values for a refinement type (e.g., all laterality options: right, left, bilateral, unilateral, unspecified). Get the group notation from the 'group.code' field in get_allowed_refinements or get_lexical results.

Find the clinical problems related to a procedure or medication (reverse lookup). IMPORTANT: Use the 'lexical_code' value from normalize_medical_term results as the code parameter (NOT the imo_code). This traverses the cross-domain graph in reverse — from a procedure or medication back to the problems that reference it. - procedure: returns associatedProblems, interpretedFindings, determinedProblems (problems this procedure is a finding method for), causedProblems, realizedProblems. - medication: returns treatedProblems, causedProblems (problems this medication is a causative agent for). Use this to answer "what problems is this procedure/medication used for?". Results are paged. These relationships are the largest in the graph — a common medication treats six figures' worth of problems — so `totals` reports the true size, `truncated` how many lie beyond your page, and `offset` walks further.

Get the full content of a specific guideline document by its document_id. Returns document metadata (title, source, authors, page count), a presigned URL for the full PDF, and all text chunks grouped by page with per-page image URLs. Use this tool AFTER search_guidelines when the user wants to drill down into a specific document — e.g. "tell me more about that Crohn's disease guideline" or "show me the full content of that document."

List all available guideline documents with metadata. Returns document_id, document_name, title, source organization, publication_date, and page count for every guideline in the system. Use this tool when the user asks what guidelines are available, or needs to browse the full document catalog.

Search guideline chunks by IMO lexical codes. Returns chunks whose pre-indexed clinical entities match the given codes, with the matched entity and code details per chunk. Use this tool when you have IMO lexical codes from a normalize call and want to find which guidelines mention those concepts.

Search clinical practice guidelines from GuidelineCentral using semantic similarity. Returns ranked guideline chunks with relevance scores, source document metadata, and presigned URLs for the original PDF and page image. Use this tool when the user asks about clinical guidelines, treatment recommendations, or evidence-based medical practices.

Semantic search scoped to a single guideline document. Returns ranked chunks from one specific document using embedding cosine similarity. Use this when the user asks a question about a specific document — e.g. "What does the IBD Care Pathway say about biologic escalation?" or "In the acute pancreatitis guideline, find sections about nutrition."

Discover the shape of the IMO Knowledge Graph before writing a SPARQL query. Run this first to ground your next `run_sparql` call in observed schema instead of guessing predicate names or class IRIs. Sections: - named_graphs: list every named graph in the store (e.g. urn:x-imo:problem, urn:x-imo:procedure, urn:x-imo:subrx, urn:x-imo:modifier). - classes: rdf:type values with instance counts, optionally scoped to a named graph. - predicates: predicates in use with usage counts, optionally scoped to a named graph. - sample_class: 25 triples for an arbitrary instance of `class_iri`, so you can see the predicates and value shapes that class uses.

Execute a read-only SPARQL query against the IMO Knowledge Graph. Call `explore_schema` first if you don't already know the named graphs, classes, or predicates you need. Only SELECT / ASK / CONSTRUCT / DESCRIBE are accepted; INSERT / DELETE / LOAD / CLEAR / DROP and other write / management forms are rejected. A default LIMIT is injected into bare SELECTs so a mistake can't return millions of rows. Returns Neptune's SPARQL 1.1 JSON results envelope verbatim under `result`, plus a `rows` field with a flat list-of-dicts view for SELECT results.

Normalize medical terms using the IMO Precision Normalize API across Problem, Procedure, Medication, and Lab domains. Send one or more medical terms and receive raw normalization results from the API. For Medication domain, returns 20 results per term. For Problem, Procedure, and Lab domains, returns 1 result per term.

Get the AI screening result for one citation: predicted study type and publication type, the AI's explanation, and per protocol section the exclusion criteria it matched (exclusions_set is false when the section has no exclusion criteria).

Get a page of a PLR project's data summary (the extracted data of included studies): the table headers, the rows, and a link that opens the project's data summary page in PLR. A study can span several rows, one per cohort or per instance of a repeated data element; rows with the same id are the same study. total_rows counts rows, not studies, and studies_on_page is the number of studies on this page. PLR sorts all the rows before paging: by default as its data summary table does, by year of publication, newest first; pass sort_by and sort_order when the user asks for another order PLR supports. sorted_by and sort_order report the order used. When you present the data, keep the rows in this order and always show the sorted_by column with each study's title or author; say how many studies and rows the page covers, that it is page N of the rows in that order, and whether there are more (has_more); link the data summary page for the full table.

Get the PRISMA flow of a PLR project exactly as PLR's reporting page draws its PRISMA chart, and a link to that page. Stages in chart order: identification (database search, other sources, all sources, citations removed as duplicates or empty abstracts), screening (citations screened and excluded with reasons), eligibility (full texts assessed and excluded with reasons, including "Full text not available"; null for abstract-only projects, whose chart has no eligibility row) and included. Each box is {label, count, breakdown}. Present these boxes, labels and counts as given; they already apply PLR's arithmetic, so do not derive, add or recombine counts. The reporting page shows the rendered chart and offers it as a PDF download.

Get a PLR project's details: name, description, disease, project type, status, current workflow step, when it was last updated (the creation date if it was never updated) and a link that opens it in PLR.

Get screening counts for one or more PLR projects at a screening step. For each project: AI and human relevant / irrelevant / not screened counts, AI-human agreements and disagreements, and full-text availability (a count PLR does not keep for the step is null), plus links to the step's PLR screening page and its AI predictions page (AI decisions next to human ones - link this when discussing AI and human agreement). Each project has its own status (OK, ACCESS_DENIED, UNAVAILABLE); ids beyond the limit are returned in not_processed_project_ids - call again with those.

Get the study protocols of one or more PLR projects. For each project: the literature search (name, source, query), a link to the protocol page and, for each protocol step (abstract screening, full-text screening, data elements, publication type), the inclusion and exclusion criteria per section, entered values, domain knowledge notes and data elements. Screening steps also have article_types, PLR's "Article type" panel: the publication types the step accepts, as "Group > Type" paths. all_articles true means "All articles" is checked and every listed type is accepted; otherwise only the listed types are. Each step has its own domain_knowledge (PLR's "Domain knowledge" notes for that step; null when the step has none), so report it with the step it belongs to. Data elements are fields to extract from included studies, not eligibility criteria. Each project has its own status (OK, ACCESS_DENIED, UNAVAILABLE); ids beyond the limit are returned in not_processed_project_ids - call again with those.

List the PLR (Precision Literature Review) projects the user owns or that were shared with them. Returns each project's id, name, disease, description, project type, current workflow step, when it was last updated (PLR's "Last updated", the creation date if it was never updated), the user's role (Owner, Editor, Annotator or Viewer) and a link that opens it in PLR. Owned and shared projects are listed together, most recently updated first. Call it without name_filter to get all of the user's projects and decide yourself which ones match a topic; name_filter is a literal substring match on the project name, not a topic search. Use this first to find project ids.

Search a PLR project's citations for one screening step. Returns a page of citations with id, PubMed id, title, authors, publication date, journal, DOI, the AI and human screening decisions (RELEVANT, IRRELEVANT, NOT_SCREENED) for the step and full-text availability, the total number of matches, and a link to the step's PLR screening page.