Skip to content

Tools Reference

The MCP server provides five tools for searching, querying, and browsing the Shadowdark knowledge base.

Search the corpus using hybrid search (vector similarity + keyword matching + trigram fuzzy matching). Returns relevant text chunks with source file, page numbers, section headings, and relevance scores.

Parameters

Name Type Required Default Description
query string Yes — The search query text
maxResults integer No 5 Maximum number of results to return (1–20)
scope string No DM view Visibility scope filter: "all" for player-visible content, "dm-only" for DM-only content, or omit for full DM view (both)
sources string[] No All Filter by source document IDs, filenames, or category names (e.g. ["#1", "rulebook.pdf"])
categories string[] No All Filter by category names (e.g. ["rules", "sessions"])

Example

Search for "critical hit damage" with maxResults 3 and categories ["rules"]

Response

Each result includes:

  • Score — Reciprocal Rank Fusion score combining all three search signals
  • Source file — The document the chunk came from
  • Page range — Which pages the chunk spans
  • Section heading — The nearest section heading (if available)
  • Content — The matching text passage

ask

Ask a question about Shadowdark RPG rules, sessions, or campaign content. Uses retrieval-augmented generation (RAG) to provide answers grounded in the indexed corpus with source citations.

Parameters

Name Type Required Default Description
question string Yes — The question to ask
scope string No DM view Visibility scope filter: "all" for player-visible content, "dm-only" for DM-only content, or omit for full DM view (both)
sources string[] No All Filter by source document IDs, filenames, or category names
categories string[] No All Filter by category names

Example

Ask "How does advantage work in Shadowdark?" with categories ["rules"]

Response

A generated answer citing source numbers, followed by a list of sources with file names, page ranges, and relevance scores.

list_documents

List all documents ingested into the corpus. Returns document names, chunk counts, page ranges, and ingestion dates.

Parameters

None.

Response

A formatted list showing:

  • Total document and chunk counts
  • Per-document: filename, document ID, category, visibility scope, chunk count, page range, and ingestion date

list_sources

List available document sources with their identifiers and visibility scopes. Use this to discover what values can be passed to the sources and categories parameters of search and ask.

Parameters

Name Type Required Default Description
scope string No DM view Visibility scope filter: "all" for player-visible content, "dm-only" for DM-only content, or omit for full DM view (both)

Response

A list of sources showing filename, document ID, category, visibility scope, and description.

read_document

Get the full text of a document from the corpus. Use this to read complete session transcripts or full document content instead of searching for individual chunks.

Parameters

Name Type Required Default Description
source string Yes — Source file name or document ID (e.g. "rulebook.pdf" or "#5")

Response

The complete text content of the document.

Filtering

The search, ask, and list_sources tools support filtering to narrow results:

By scope

Control which documents are visible based on audience:

  • Omit scope — Full DM view, includes both all and dm-only documents
  • scope: "all" — Player view, only documents marked as player-visible
  • scope: "dm-only" — DM-only documents, excludes player-visible content

By source

Pass specific document identifiers to the sources parameter:

  • File name — "rulebook.pdf"
  • Document ID — "#1" (use list_sources to discover IDs)

By category

Pass category names to the categories parameter. Categories are free-form labels assigned by the DM (e.g. "rules", "sessions", "npcs").

Tip

Use list_sources first to see available documents, their IDs, and categories. Then use those values to filter search and ask queries.