Background
The CLI and MCP server are both generated from a single list of tool definitions in schema.py (REGISTRY). When you add a tool there, it automatically shows up as a CLI subcommand and an MCP tool. This issue covers four changes to that registry plus one bug fix in the CLI generator.
What was missing
-
No way to run the neighborhood finder or path finder from the CLI. These are two of the most useful operations in the toolkit (find what connects to a node, and find paths between two nodes), but they only existed as functions in TCT.py and were never added to the registry, so neither the CLI nor the MCP server could call them.
-
Name lookup could not filter by type or species. The underlying name_resolver.lookup function accepts filters like biolink_type (e.g. only diseases) and only_taxa (e.g. only human), but the registered lookup_name / lookup_names tools did not pass those through, so users could not reach them.
-
A bug made every multi-argument CLI command read its positional arguments backwards. For example query-kp expected QUERY_JSON first and API_NAME second, which is the reverse of how the tool is defined. This affected every command that takes more than one positional argument.
What we changed
1. Added two new tools to the registry
find_neighborhood (CLI: tct query find-neighborhood) — given a node CURIE and the categories you want its neighbors to be, returns the connected nodes with scores.find_path (CLI: tct query find-path) — given two node CURIEs and the category of the bridging node, returns the paths between them with scores. Takes an optional --scoring-method of infores or edges.
Both tools call the existing refactored modules (TCT_neighborhood_finder.py, TCT_pathfinder.py) rather than the older TCT.py functions. The refactored versions return a single structured dictionary (a TRAPI-style message with query_graph, knowledge_graph, and scored results) instead of a large tuple of mixed values. This is easier to consume and has no side effects. The older TCT.py versions returned wide tuples and, in the path finder's case, also drew a chart and wrote a PNG file to disk on every call, which is not appropriate for a CLI/server tool.
2. Added type and species filters to name lookup
lookup_name now accepts --biolink-type, --only-taxa, --limit, and --autocomplete.lookup_names (batch) now accepts --biolink-types, --only-taxa, and --autocomplete.
These are passed through to the name resolver only when set, so default behavior is unchanged.
3. Fixed the reversed argument order
In cli.py, the command builder applied argument definitions to an already-built command object. Because of how the CLI library records arguments in that situation, looping over them in reverse put the positional arguments in the wrong order. The fix is to loop in normal order. After the fix, query-kp correctly reads API_NAME QUERY_JSON, add-metakg-api lists its seven arguments in the defined order, and the new find-path reads INPUT_NODE1 INPUT_NODE2 INTERMEDIATE_CATEGORIES.
Note: this changes the argument order for existing multi-argument commands. Anyone who previously worked around the reversed order will need to update to the correct order.
4. Updated the registry tests
tests/test_schema.py checks the exact set of tools, their backward-compatible aliases, and the list of allowed naming verbs. Updated it to include the two new tools, their aliases (neighborhood_finder, path_finder), and find as an allowed verb.
Testing
- Full test suite passes (121 passed, 1 skipped).
- Confirmed via
--help that the new commands appear and that positional arguments are now in the correct order.
Follow-up (not in this change)
TCT_neighborhood_finder.py and TCT_pathfinder.py currently have no unit tests. The wiring and signatures are verified, but their end-to-end logic (which calls live Translator APIs) is not covered. Worth adding tests with mocked API responses.
Background
The CLI and MCP server are both generated from a single list of tool definitions in
schema.py(REGISTRY). When you add a tool there, it automatically shows up as a CLI subcommand and an MCP tool. This issue covers four changes to that registry plus one bug fix in the CLI generator.What was missing
No way to run the neighborhood finder or path finder from the CLI. These are two of the most useful operations in the toolkit (find what connects to a node, and find paths between two nodes), but they only existed as functions in
TCT.pyand were never added to the registry, so neither the CLI nor the MCP server could call them.Name lookup could not filter by type or species. The underlying
name_resolver.lookupfunction accepts filters likebiolink_type(e.g. only diseases) andonly_taxa(e.g. only human), but the registeredlookup_name/lookup_namestools did not pass those through, so users could not reach them.A bug made every multi-argument CLI command read its positional arguments backwards. For example
query-kpexpectedQUERY_JSONfirst andAPI_NAMEsecond, which is the reverse of how the tool is defined. This affected every command that takes more than one positional argument.What we changed
1. Added two new tools to the registry
find_neighborhood(CLI:tct query find-neighborhood) — given a node CURIE and the categories you want its neighbors to be, returns the connected nodes with scores.find_path(CLI:tct query find-path) — given two node CURIEs and the category of the bridging node, returns the paths between them with scores. Takes an optional--scoring-methodofinforesoredges.Both tools call the existing refactored modules (
TCT_neighborhood_finder.py,TCT_pathfinder.py) rather than the olderTCT.pyfunctions. The refactored versions return a single structured dictionary (a TRAPI-style message withquery_graph,knowledge_graph, and scoredresults) instead of a large tuple of mixed values. This is easier to consume and has no side effects. The olderTCT.pyversions returned wide tuples and, in the path finder's case, also drew a chart and wrote a PNG file to disk on every call, which is not appropriate for a CLI/server tool.2. Added type and species filters to name lookup
lookup_namenow accepts--biolink-type,--only-taxa,--limit, and--autocomplete.lookup_names(batch) now accepts--biolink-types,--only-taxa, and--autocomplete.These are passed through to the name resolver only when set, so default behavior is unchanged.
3. Fixed the reversed argument order
In
cli.py, the command builder applied argument definitions to an already-built command object. Because of how the CLI library records arguments in that situation, looping over them in reverse put the positional arguments in the wrong order. The fix is to loop in normal order. After the fix,query-kpcorrectly readsAPI_NAME QUERY_JSON,add-metakg-apilists its seven arguments in the defined order, and the newfind-pathreadsINPUT_NODE1 INPUT_NODE2 INTERMEDIATE_CATEGORIES.Note: this changes the argument order for existing multi-argument commands. Anyone who previously worked around the reversed order will need to update to the correct order.
4. Updated the registry tests
tests/test_schema.pychecks the exact set of tools, their backward-compatible aliases, and the list of allowed naming verbs. Updated it to include the two new tools, their aliases (neighborhood_finder,path_finder), andfindas an allowed verb.Testing
--helpthat the new commands appear and that positional arguments are now in the correct order.Follow-up (not in this change)
TCT_neighborhood_finder.pyandTCT_pathfinder.pycurrently have no unit tests. The wiring and signatures are verified, but their end-to-end logic (which calls live Translator APIs) is not covered. Worth adding tests with mocked API responses.