---
name: tkoi-knowledge-graph
description: Contextualize saved tKOI enrichment by searching nodes, traversing connection layers and finding paths in the exact igraph used for that analysis. Use for tKOI result interpretation and local graph evidence.
---

# tKOI knowledge graph

The plugin's `tkoi-graph` MCP server bundles the knowledge-graph tools. It opens
the igraph retained in a saved `tKOIList` from tkoi >= 1.3.0. A live SPOKE/Neo4j
connection is not a substitute for that graph. Use external literature or other
knowledge-graph plugins only as separately identified background evidence when
requested; do not merge their edges into the analysis evidence.

## Connect and verify identity

1. Call `connect_analysis(path)` with the absolute path of `analysis.rds` from
   the analysis run. Save the returned `analysis_id`, vertex/edge counts and
   path in the working notes.
2. Pass that ID to **every** subsequent tool. A stale ID or modified analysis
   file is rejected. Connecting another result replaces the current connection;
   explicitly reconnect before returning to an earlier analysis.
3. Call `get_graph_schema(analysis_id)` before querying. Inspect the actual
   node types, relation types, vertex/edge attributes and directionality.
4. Results without a saved graph are refused. Do not fill an old result's empty
   graph slot with the currently installed `tkoi_net` and call it verified.
   Rerun enrichment with the original selected graph to create a complete result.

The ID is an MD5 identity check of the saved file, not a cryptographic signature
or proof that manually edited historical artifacts were generated by tKOI.

## Traverse the connected graph

| Tool | Use |
|---|---|
| `get_enrichment_results(analysis_id, node_type, limit=25)` | Read saved results in tKOI order, including effect size and FDR |
| `search_nodes(analysis_id, query, node_type=None, limit=25)` | Resolve names/identifiers to exact graph `node_id` values |
| `get_node_neighbors(analysis_id, node_id, hops=1, limit=100)` | Inspect 1-3 layers, node hop distances, and stored edge attributes |
| `get_path_between_nodes(analysis_id, source_id, target_id, max_hops=3)` | Retrieve one unweighted shortest path within 1-6 hops |

Start with the relevant enriched category and seed genes. Search to resolve
ambiguous labels before expanding. igraph vertex names are opaque IDs; Ensembl
IDs, Entrez identifiers, symbols and display names are not interchangeable with
`node_id`. Cite returned IDs and `attr_edge_type` values in the interpretation.

The bundled graph is undirected. Its vertices carry `name` (node ID),
`identifier`, `source`, `labels`, and `degree`; its edges carry `edge_type`.
Other supplied graphs may have additional or fewer attributes. Traversal uses
both directions, matching tKOI's undirected enrichment topology, and shortest
paths ignore weights. Preserve actual returned edge attributes; do not infer
causal direction, activation/inhibition, confidence, or an edge-level citation
when the graph does not contain it. A vertex's `source` is not evidence for
every incident edge.

Inspect `nodes_truncated`, `edges_truncated`, `truncated` and counts. A capped
neighborhood is partial; missing returned connections do not establish absence.
Expand focused intermediate nodes or use a specific path query when needed.
The server intentionally does not enumerate all paths, which can grow
combinatorially. `found=false` means no path within the requested hop bound,
not necessarily that the nodes are disconnected.

Compare direct gene-to-term links with paths through intermediate biological
entities. Report what the connected network supports, what the enrichment test
measured, and what remains a biological hypothesis. Enrichment and connectivity
alone do not establish causal mechanisms or validate clinical predictions.

## Direct R access

If the host cannot attach the MCP server, use the same saved graph with its
normal R/shell execution tools:

```r
result = readRDS("/absolute/run/analysis.rds")
graph = tkoi::get_analysis_graph(result)
igraph::vertex_attr_names(graph)
igraph::edge_attr_names(graph)
tkoi::get_neighboring_nodes(node_id, 2, subnetwork = graph)
igraph::shortest_paths(graph, from = source_id, to = target_id,
                       mode = "all", weights = NA, output = "both")
tkoi::plot_network(result, target_node_id = node_id)
```

Never omit `subnetwork = graph` from the generic neighbor helper. The result-aware
plot defaults to the stored graph. See the analysis skill's
[setup guide](../tkoi-analysis/references/setup.md) for dependencies and MCP startup.