Full-text search one DocuSky database; returns metadata plus a short excerpt per hit.

Full document text is deliberately omitted — call get_document with a hit's n (and the same db/corpus/query/page_size) to read one in full.

For a public ("OPEN") database, the result also carries a webUrl to the same search on docusky.org.tw — MCP Apps-capable hosts render it inline.

Args: db: Database title. query: Search terms. +term requires, -term excludes, .all matches everything. corpus: Corpus title, or "[ALL]" for every corpus in the database. page: 1-based page number. page_size: Hits per page (1-100). target: "OPEN" or "USER". excerpt_chars: Characters of body text to preview per hit; 0 disables excerpts. owner_username: Owner of a friend-shared database, when applicable.

Break a query's hits down by DocuSky's post-classification facets.

Returns, per facet (corpus, period, place, category…), a distribution of [value, document count, hit count] — the quickest way to see how a term is spread across a database. Facet codes returned here (e.g. "COMP", "TP1") are also what twodim_analysis's dim1/dim2 arguments expect.

For a public ("OPEN") database, the result also carries a webUrl to the same breakdown on docusky.org.tw — MCP Apps-capable hosts render it inline.

Args: db: Database title. query: Search terms, or ".all" for the whole database. corpus: Corpus title, or "[ALL]". target: "OPEN" or "USER". owner_username: Owner of a friend-shared database, when applicable.

Summarize the DocuXML tags (people, places, dates, custom markup) in a query's hits.

Only meaningful for databases whose documents carry inline tagging; returns an empty result otherwise.

For a public ("OPEN") database, the result also carries a webUrl to the same summary on docusky.org.tw — MCP Apps-capable hosts render it inline.

Args: db: Database title. query: Search terms, or ".all" for the whole database. corpus: Corpus title, or "[ALL]". target: "OPEN" or "USER". owner_username: Owner of a friend-shared database, when applicable.

Draw a word cloud of term frequencies in DocuSky's own WordCloudLite tool.

Takes numbers you already have and turns them into a DocuSky visualization: tag counts from tag_analysis, a facet distribution from post_classification (its value / docCount pairs), or terms you counted yourself in text from get_document. This tool does no counting and no searching of its own.

Returns a webUrl to the rendered cloud — MCP Apps-capable hosts show it inline, other hosts can offer it as a link. The rendered page also has buttons for bubble, top-10 bar and table views of the same data, plus Save.

WordCloudLite draws a random subset of a large term list, so pass roughly 20-40 terms when every word should appear.

Args: terms: Term -> weight, e.g. {"針灸": 120, "湯液": 48}. Weights must be positive; non-integers are rescaled proportionally. Commas and semicolons in a term are replaced with spaces (the tool's URL format uses them as separators). max_terms: Keep at most this many of the heaviest terms (default 150). A very long list is also trimmed further to fit DocuSky's URL limit.

Put places on a map in DocuSky's own DocuGIS2 tool.

Takes coordinates you already have — from the user, from a placeInfo in search_documents, from a gazetteer, or from your own knowledge of where a place is — and returns the TSV that DocuGIS2's import box accepts. This tool does no geocoding and no searching: never invent coordinates for a place you are unsure of; leave that row out, or ask the user.

DocuGIS2 cannot be fed data through a URL, so the last step belongs to the user: MCP Apps-capable hosts show the TSV with a copy button next to the embedded tool, and the user pastes it into DocuGIS2's box and presses 匯入 (the rendered map then does time filtering, routes, clustering, heatmaps and export). Other hosts get the same TSV as text plus webUrl, to paste into DocuGIS2 in a browser. Tell the user that paste step is theirs.

Args: rows: One entry per place. name plus x (WGS84 longitude) and y (latitude) are required; date, text and any other keys are optional and become extra columns in DocuGIS2's popups. Common aliases are understood (lng/lon/經度 -> x, lat/緯度 -> y, 地名 -> name). Example: [{"name": "鹿港", "x": 120.434, "y": 24.057, "date": "1784-01-01", "text": "鹿港開港"}]. title: A name for this map, shown above the tool. include_dates: Leave unset to decide automatically. DocuGIS2 drops any row whose date cell is empty or a bare year, so a half-dated set ships without the date column (every place on the map, no time axis). Pass true to keep the timeline and lose the undated rows, false to drop dates entirely. max_rows: Keep at most this many places (default 2000).

List DocuSky databases available to this server.

Args: target: "OPEN" for public databases, "USER" for the logged-in account's own. include_friend_db: Also list databases shared by DocuSky "friends" (USER only).

List the corpora inside one database, with document counts.

Args: db: Database title, exactly as returned by list_databases. target: "OPEN" or "USER". include_friend_db: Include databases shared by friends (USER only).

Fetch the full text of one search hit, identified by its position in the result set.

result_number is the global 1-based rank of the document for this query — the n field of a search_documents hit. Pass the same db, query, corpus and page_size that produced it, or the ranking will not line up.

Long documents are returned in slices: raise offset by max_chars to page through the body.

Args: db: Database title. result_number: 1-based rank of the document within the query's results. query: The same query string used in search_documents. corpus: The same corpus used in search_documents. target: "OPEN" or "USER". page_size: The same page_size used in search_documents. offset: Character offset into the document body. max_chars: Maximum characters of body text to return. include_raw_xml: Also return the untouched DocuXML content. owner_username: Owner of a friend-shared database, when applicable.

Cross-tabulate a query's hits by two DocuSky classification facets at once.

EXPERIMENTAL: DocuSky added this endpoint on 2026-01-28, but live testing on 2026-09-11 found it rejects every dim1/dim2 pair tried so far — including facet codes taken straight from post_classification's own output, such as "COMP"/"TP1" — with {"code": 1, "message": "Currently not support ..."}. DocuSky's own front-end has not wired up a UI for it yet either. Call post_classification first to see which facet codes exist for a database, try them here, and expect DocuSky may still refuse the combination while this feature is unfinished on their end.

Args: db: Database title. dim1: First classification facet code (a key from post_classification's "facets", e.g. "COMP" or "TP1"). dim2: Second classification facet code to cross with the first. query: Search terms, or ".all" for the whole database. corpus: Corpus title, or "[ALL]". target: "OPEN" or "USER". owner_username: Owner of a friend-shared database, when applicable.

Report whether DocuSky credentials are configured and whether they work.

Public databases need no login; run this only when private ("USER") databases are unreachable.