Introduction

What is TCT?

Translator Component Toolkit (TCT) is a Python library for exploring and using knowledge graphs in the Translator ecosystem. Users can check out the key function documentations here: https://ncatstranslator.github.io/Translator_component_toolkit/

TCT Github repo

Key features for TCT

Allowing users to select APIs, predicates according to the user's intention.
Parallel and fast querying of the selected APIs.
Providing reproducible results by setting constraints.
Faciliting to explore knowledge graphs from both Translator ecosystem and user defined APIs.
Connecting large language models to convert user's questions into TRAPI queries.
Find the identifier given a name using name resolver
Annotate a node using node annotator
Explore knowledge graphs in Translator
Find neighbors in the Translator KGs for a given node
Find paths between node A and node B in the Translator KG
Find a subnetwork given a list of nodes in the Translator KG
Developer-friendly wrappers for resolving labels/CURIEs, caching Translator resources, and returning parsed finder results
Connecting user's API with Translator API
Note: Visualization capabilities (pyvis, matplotlib, seaborn) can be installed separately via the vision extra.

How to use TCT

Install Requirements

To install TCT as a python library:

pip install TCT
# TCT is in development, to get the most recent update, user can install it through the github repo

This is the recommended approach for a minimal installation.

The minimal installation includes both the Python library and the tct command-line interface. Install the optional MCP dependencies when an agent or MCP client will run TCT as a server:

pip install "TCT[mcp]"

Visualization support is optional. Install it with the vision extra when you need the plotting and graph-rendering utilities:

pip install "TCT[vision]"

Development Installation

The TCT is continuously updated, if you would like to use the latest functions, you can clone this repository and install it in development mode:

Using pip: (recommended for development)

git clone https://github.com/NCATSTranslator/Translator_component_toolkit.git
cd Translator_component_toolkit
pip install -e .

Using UV :

git clone https://github.com/NCATSTranslator/Translator_component_toolkit.git
cd Translator_component_toolkit
uv sync

Service environment

TCT uses CI service URLs by default. Select another environment explicitly when needed, for example in Python:

import TCT

TCT.configure(environment="test")

or when starting a process such as the MCP server:

TCT_ENVIRONMENT=test tct-server

Services without a separate CI deployment continue to use their production URL. For discovered providers, TCT falls back to the first available non-test URL; a test URL is used only when no production or CI URL is available. For local testing, individual known services can be replaced explicitly:

TCT.configure(
    environment="test",
    overrides={"arax": "http://localhost:8080/query"},
)

To include visualization support in the UV environment:

uv sync --extra vision

To develop or run the MCP server from a source checkout:

uv sync --extra mcp

Python, CLI, and MCP interfaces

TCT exposes one curated set of well-documented operations through three interfaces:

Interface	Intended use	Starting point
Python	Application and notebook development	import TCT
CLI	Shell scripts, exploration, and agent command execution	tct --help
MCP	Tool discovery and invocation by MCP clients	tct-server

The CLI and MCP server are generated from the same functions in TCT.interfaces.tools. Function names, signatures, annotations, defaults, and docstrings therefore provide the common tool contract. The MCP server remains available from the existing tct-server command and from the compatibility imports in TCT.server.

Explore the CLI

Start at the root help, then ask for help on any listed command:

tct --help

\\\\
tct name-lookup --help
tct normalize-nodes --help

Commands use kebab-case names and long options. List options accept one or more space-separated values, structured options accept JSON, and boolean options support both --option and --no-option. Results are written as JSON so they can be inspected directly or piped to another program. Common TCT results such as dataclasses, mappings, collections, and tables are converted recursively. Tool failures are written concisely to standard error and return a nonzero exit status.

tct name-lookup --query aspirin
tct normalize-nodes --query CHEBI:15365 CHEBI:6801 --no-conflate

See EXAMPLES.md for CLI discovery, structured inputs, finder commands, Python use, and MCP client configuration.

Run the MCP server

After installing the mcp extra, start the stdio server with:

tct-server

MCP clients discover the same tool names, descriptions, input types, required parameters, and defaults shown by the CLI. A typical client configuration is:

{
  "mcpServers": {
    "tct": {
      "command": "uv run tct-server"
    }
  }
}

When running from a source checkout, run uv sync --extra mcp first and use uv run tct-server.

Shared tool capabilities

The table uses CLI kebab-case spellings; MCP publishes the corresponding Python names in snake_case.

Area	Commands
Translator resources	get-translator-resources, get-kp-info, get-metakg-data, get-api-predicates
Name resolution	name-lookup, get-name-synonyms, batch-name-lookup
Node normalization	normalize-nodes
MetaKG extension	add-custom-api-to-metakg, add-plover-apis-to-metakg
TRAPI query preparation and execution	optimize-query-for-api, query-knowledge-provider, parallel-query-apis
Graph finding	neighborhood-finder, path-finder
Legacy compatibility	trapi-query-endpoint

trapi-query-endpoint preserves the existing public tool contract but is a legacy placeholder in this release; its underlying operation also requires a query body that is not present in the public command signature.

Building and Deployment

Using pip:

• Build: python -m build
• Install dependencies: pip install -e .

Using UV:

• Build: uv build
• Install dependencies: uv sync
• Run in UV environment: uv run python your_script.py

Please follow the example notebooks (four utilities) below to explore the Translator APIs.

KG overview

Explore different KGs KG overview

Name Resolver and Node Normalizer

Example notebook for Name Resolver and Node Normalizer

Neighborhood finder

Example notebook for NeighborhoodFinder

Path finder

Example notebook for PathFinder

Network finder

Example notebook for NetworkFinder

Developer-friendly finder APIs

The finder notebooks above include quick-start sections using the developer-friendly pathfinder and neighborhood_finder APIs, now part of TCT's main API surface (from TCT import query_TCT_pathfinder, neighborhood_finder).

Use the detailed NeighborhoodFinder, PathFinder, NetworkFinder, KG overview, and visualization notebooks when you need more fine-grained endpoint selection, predicate control, raw query construction, parser workflows, or visualization setup.

Connecting to a user's API

API should be developed following the standard from TRAPI.
An example notebook for add a user's API can be found here.
Note: It does not work if no user' API is established

Visualize the results

After each pipeline, it will generate a result file for visualization. A user can use the Visualization html file to visulaize the results.

Key Translator components

Connecting to key Translator components can be found here

Contributing

TCT is a tool that helps to explore knowledge graphs developed in the Biomedical Data Translator Consortium. Consortium members and external contributors are encouraged to submit issues and pull requests.

Contact info

Guangrong Qin, guangrong.qin@isbscience.org