Skip to main content
Glama
SPOKEAgent

SPOKEAgent

Official
by BaranziniLab

SPOKEAgent

Current version: 0.5.0. Small queries stay on MCP; long queries and full exports run as monitored local jobs without tying up an MCP request.

Install in BioRouter

  1. Download spokeagent.brxt from Releases. The same current bundle is committed under extensions/.

  2. In BioRouter, open Extensions → Add extension, select the BRXT and install. BioRouter creates the Python environment; uv and Python 3.11+ are required.

  3. Enter credentials in BioRouter's own configuration dialog, never in chat.

  4. Enable the extension in your chat. Verify a small query before a larger export.

Terminal installation uses the same installer:

biorouter extension install ./extensions/spokeagent.brxt
biorouter extension configure spokeagent

Configure SPOKEAGENT_PASSCODE. Alternatively provide KNOWLEDGE_GRAPH_URI, KNOWLEDGE_GRAPH_USERNAME, KNOWLEDGE_GRAPH_PASSWORD, and optionally KNOWLEDGE_GRAPH_DATABASE (default neo4j). Direct settings take precedence; use one route consistently. Because either route is valid, manifest fields are optional individually; startup validates that one complete route exists.

The Desktop installer discovers bundled skills/*/SKILL.md. If using a BioRouter CLI version that does not copy bundled skills, the MCP server still provides the job-routing instructions; the skill folders can also be installed separately.

Related MCP server: BioBTree

Long queries, CLI and progress

Use spoke-submit_query_job for an export or a query that could exceed the interactive timeout. It returns a job ID immediately. Poll spoke-query_job_status at its recommended interval; use spoke-cancel_query_job to stop. Only completed means the file is complete. Status includes rows, bytes, elapsed time, phase and an advisory ETA when known. Set mode="explain" to obtain a plan without running the query.

From a source checkout, or BioRouter's installed extension directory:

uv sync --locked
# Standalone CLI only: configure its OS-keyring profile interactively once.
# BioRouter MCP jobs already receive credentials and do not need this command.
uv run spokeagent auth
uv run spokeagent submit --query-file query.cypher --format jsonl --timeout-seconds 3600
uv run spokeagent watch JOB_ID

No-argument uv run spokeagent continues to start the MCP server. status, watch, list, cancel and purge need no database credentials. Results remain in the local private job directory and are not sent to chat. Database/server limits can still fail a query; jobs report those failures instead of silently truncating.

See architecture, storage, security and release details. To rebuild the tracked bundle: uv run python scripts/build_brxt.py.

A structure-aware MCP (Model Context Protocol) server for querying the SPOKE biomedical knowledge graph for rapid biomedical knowledge inference. Points to the official release of SPOKE.

SPOKEAgent doesn't just expose raw Cypher — it understands SPOKE's structure. It introspects the live schema (so it tolerates schema changes), resolves entity names / synonyms / identifiers to canonical nodes via the graph's indexes, profiles a node's real relationships, finds shortest paths between entities, and guards every query against the pitfalls of a 43-million-node graph (case-sensitivity, expensive edges, unbounded scans). See docs/CHANGELOG.md and docs/TEST_FINDINGS.md for the design rationale, validated over 100 natural-language questions through BioRouter.

Features

  • Compact, cached schema — a curated node table + Source-[:REL]->Target edge directory with counts and cost flags, derived live from the database.

  • Entity resolution — name / synonym / brand / identifier → canonical SPOKE node(s), case- and apostrophe-safe, across DOID / Entrez / Ensembl / DrugBank / UMLS / UBERON / GO, ranked by connectivity.

  • Node profiling — a node's real relationship types, directions, and counts.

  • Path finding — shortest connecting path(s) between two entities.

  • Guarded querying — read-only Cypher with auto safety-LIMIT, transaction timeout, and trimmed output.

Alternative install (custom extension via uvx)

If you prefer not to use the .brxt bundle, you can register SPOKEAgent as a custom extension command:

  1. In BioRouter, go to Add custom extension

  2. Fill in the extension name and description

  3. For the command, use the following:

uvx --from git+https://github.com/BaranziniLab/SPOKEAgent spokeagent
  1. Add an environment variable:

    a. Variable name = SPOKEAGENT_PASSCODE

    b. Value = <your-passcode> (from the credentials page)

    c. Click + Add to add the variable.

  2. Click Add extension — you're ready to go

Available Tools

The recommended workflow is schema once → resolve_entity → query / describe / find_path, passing string literals through parameters.

1. get_spoke_schema(refresh=false)

Returns a compact, cached map of the current graph: node_labels (by count), an edge_directory of {source, rel, target, count, expensive}, and usage_notes (identifier namespaces, edge properties, vestige filtering, performance rules). Call once near the start of a task.

2. resolve_entity(query, label?, limit?)

Maps a free-text name, synonym, brand, or identifier to canonical node(s). Handles case-sensitivity, apostrophes, and cross-vocabulary identifiers (DOID, Entrez, Ensembl, DrugBank, UMLS CUI, UBERON, GO). Returns ranked candidates {label, name, identifier, matched_on, score} (degree may also be present). Use it before querying.

3. describe_node(query, label?)

Returns a node's real relationship profile {dir, rel, neighbor_label, count} — to pick the right edge. If truncated=true, the profile contains only the top 60 groups; do not conclude that an unlisted edge is absent.

4. find_path(source, target, source_label?, target_label?, max_hops?, max_paths?)

Resolves both endpoints and returns the shortest connecting path(s) as node + relationship-type sequences — the right tool for "how are X and Y connected".

5. query_spoke(cypher_query, parameters?)

Execute a read-only Cypher query. Behaviour built in: writes rejected; a safety LIMIT auto-applied to unbounded non-aggregate queries; a transaction timeout; trimmed, size-capped output; coaching metadata on empty/limited results.

Example (resolve first, then query by the resolved value via parameters):

MATCH (d:Disease {name: $name})-[:ASSOCIATES_DaG]->(g:Gene)
RETURN g.name AS gene, g.identifier AS entrez
LIMIT 10

parameters = {"name": "Alzheimer's disease"}. Note ASSOCIATES_DaG carries diseases_scores/gwas_pvalue (not a score property), and drug→gene targets go (:Compound)-[:BINDS_CbP]->(:Protein)<-[:ENCODES_GeP]-(:Gene) — there is no TARGETS_CtG edge.

Security

A conservative query guard rejects writes and procedure calls in user-supplied Cypher. Use a database principal with read-only permissions: the guard supplements server authorization. Entity labels are validated before interpolation, and resolver steps share a total timeout budget rather than accumulating long waits.

License

Apache-2.0

Authors

Editors

About SPOKE

SPOKE (Scalable Precision medicine Oriented Knowledge Engine) is a large-scale biomedical knowledge graph that integrates data from multiple sources to support precision medicine research.

Available Tools

5 tools
describe_nodeDescribe a SPOKE node's actual relationships (degree profile)A
Read-onlyIdempotent

Show what a node is ACTUALLY connected to: its relationship types, the neighbour label on the other end, the direction, and the count for each.

Use this to (a) decide which relationship to traverse for a question, and (b) avoid thrashing - if a node has no edge of the type you expected (e.g. a disease with no PRESENTS_DpS symptoms, or no LOCALIZES_DlA anatomy), this tells you immediately so you can report the absence instead of guessing more queries. Also ideal for open-ended "how is X connected / what is near X" questions. The node is resolved first (handles case / apostrophes / ids).

Returns {node:{label,name,identifier}, relationships:[{dir, rel, neighbor_label, count}]}.

Inputs: query (required), label.

find_pathFind shortest path(s) between two SPOKE nodesA
Read-onlyIdempotent

Find the shortest connecting path(s) between two entities in SPOKE - the right tool for "how are X and Y connected / what links X to Y / shortest path" and subgraph-bridge questions. Both endpoints are resolved first (case / apostrophe / id safe), then a bounded bidirectional allShortestPaths search runs (anchored, so it is fast and cannot scan the graph). Returns each path as an ordered list of nodes and the relationship types between them - so you can read off the intermediate nodes and mechanism in ONE call instead of probing many queries.

If no path is found within max_hops, that is reported (try a larger max_hops, or the entities are only distantly connected). Returns {source, target, max_hops, paths:[{hops, nodes:[...], rels:[...]}]}.

Inputs: source (required), target (required), max_hops, max_paths, +2 more.

get_spoke_schemaGet SPOKE Knowledge Graph Schema (compact)A
Read-onlyIdempotent

Return a COMPACT, curated map of the current SPOKE graph: node labels with counts and a Source->REL->Target edge directory with counts and cost flags.

This is derived live from the database, so it reflects the real, current schema (robust to new/renamed labels or edges). It is small and cached - call it ONCE near the start of a task, then rely on resolve_entity + query_spoke. Use the edge_directory to pick the exact relationship type that connects two entity types before writing Cypher.

Inputs: refresh.

query_spokeQuery SPOKE Biomedical Knowledge GraphA
Read-onlyIdempotent

Execute a read-only Cypher query on SPOKE for biomedical knowledge inference.

Behaviour built in for you:

  • Only read queries are allowed (writes are rejected).

  • An unbounded, non-aggregate query gets a safety LIMIT appended so it cannot accidentally scan the 43M-node graph; aggregations and queries with your own LIMIT are left as-is.

  • A transaction timeout aborts pathological queries instead of hanging.

  • Output is trimmed (noisy HTML/link fields removed, long strings cut) and capped in size to stay efficient.

Tips: resolve names first with resolve_entity; use the edge_directory from get_spoke_schema to choose relationship types; pass literals via parameters.

Inputs: cypher_query (required), parameters.

resolve_entityResolve a name/identifier to canonical SPOKE node(s)A
Read-onlyIdempotent

Map a free-text name, synonym, or identifier to the canonical SPOKE node(s).

Use this BEFORE query_spoke. It handles the things that make naive queries fail: case-sensitivity (exact {name:...} is case-sensitive), apostrophes, synonyms/brand names, and cross-vocabulary identifiers (DOID, Entrez, Ensembl, DrugBank, UMLS CUI, UBERON, GO). It uses SPOKE's range and full-text indexes, so it is fast and never scans the whole graph.

Returns ranked candidates: {label, name, identifier, matched_on, score}. Then query by the returned exact name or identifier via the parameters argument of query_spoke. If several candidates look plausible, state which one you picked and why.

Inputs: query (required), label, limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool serves a clearly distinct purpose: schema discovery (get_spoke_schema), entity resolution (resolve_entity), neighborhood inspection (describe_node), pathfinding (find_path), and arbitrary querying (query_spoke). The only mild overlap is describe_node vs query_spoke for inspecting connections, but descriptions clearly guide when to use which.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern (get_spoke_schema, resolve_entity, describe_node, find_path, query_spoke). The domain-specific inclusion of 'spoke' in two names does not break the pattern's predictability.

    Tool Count5/5

    Five tools is well-scoped for a read-only graph query server, covering essential operations (schema, resolution, neighborhood, path, query) without redundancy or bloat. Each tool earns its place in the workflow.

    Completeness4/5

    The surface covers schema discovery, entity resolution, neighborhood inspection, pathfinding, and raw Cypher—near-complete for read-only exploration. A minor gap is the lack of a dedicated tool to retrieve node properties directly, though query_spoke can serve as a workaround; write operations are intentionally absent.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      A unified biomedical graph database that integrates 50+ primary data sources — genes, proteins, compounds, diseases, pathways, and clinical data — into a single queryable graph with billions of cross-reference edges. Its native MCP server gives LLMs direct access to structured, authoritative biomedical data, complementing their reasoning with reliable identifiers and up-to-date database content.
      20
      AGPL 3.0
    • A
      license
      A
      quality
      B
      maintenance
      A high-performance MCP server that gives LLMs access to 25 biomedical tools federated across 50+ upstream APIs for genes, variants, drugs, diseases, literature, clinical trials, and structural biology.
      43
      138 npm
      12
      Apache 2.0