Hoist framework documentation and API reference for AI coding agents, over MCP. One tool serves
hoist-react, hoist-core and hoist-chat-kit, replacing the stdio MCP servers those libraries used to bundle, with
the same tools: hoist-search-docs, hoist-list-docs, hoist-read-doc, hoist-search-symbols,
hoist-get-symbol, hoist-get-members, hoist-ping. Built on the MCP TypeScript SDK v2
(@modelcontextprotocol/server): the 2026-07-28 MCP spec, and the 2025 handshake older clients
use.
This repo also holds the builders that make the index files the tool reads. Each library runs
the builder in its own publish job and ships its index the way it ships itself: inside its npm
package for hoist-react and the other TypeScript libraries, and as a docs-index Maven artifact
beside the jar for hoist-core. XH's libraries are listed in src/libraries.ts.
See docs/design.md for the design and
docs/index-schema.md for the index format.
Add the tool as a dev dependency of the app's client:
cd client-app && pnpm add -D @xh/hoist-docsand point the agent at it in .mcp.json, at the project root:
{
"mcpServers": {
"hoist-docs": {"command": "node", "args": ["client-app/node_modules/@xh/hoist-docs/bin/hoist-docs.mjs"]}
}
}The agent launches it over stdio. On start it:
- reads the index inside each installed package that declares one (
hoistDocsin itspackage.json):@xh/hoist,@xh/hoist-chat-kitif the app uses it, and any other library that ships an index; - fetches hoist-core's index for
hoistCoreVersioningradle.propertiesfrom Maven - Maven Central for releases, Sonatype's snapshot repository for snapshots, or an organization's mirror (HOIST_DOCS_MAVEN_REPO,HOIST_DOCS_MAVEN_SNAPSHOT_REPO, withHOIST_DOCS_MAVEN_USERandHOIST_DOCS_MAVEN_PASSWORDif needed) - and caches it in~/.cache/hoist-docs; - serves them.
Every index is exactly the installed build, snapshots included. After a Hoist upgrade, restart the agent.
The Maven fetch is the tool's only network call. Set the variables above in the env of the
.mcp.json entry, or in the developer's environment. Behind an HTTP proxy, also set
NODE_USE_ENV_PROXY=1, since Node ignores HTTPS_PROXY without it.
To try it without adding a dependency: npx @xh/hoist-docs from the project root.
hoist-docs --http serves MCP over Streamable HTTP at /mcp (port 8081, or PORT). It fetches
each library's index from the library's own channel as agents ask for it: a TypeScript library's
npm package (through the server's own .npmrc), keeping only its index, or hoist-core's Maven
artifact. It serves the newest release by default, or the release an agent names with library
and version. Fetched indexes are cached in HOIST_DOCS_CACHE. It keeps at most 12 parsed indexes in memory, or MAX_LOADED_INDEXES. Without registry access, give it a directory of index files
instead (--index-dir, or INDEX_DIR), which may hold several versions of each library.
GET /health reports what is loaded. Browser requests are checked against allowed origins
(localhost, plus ALLOWED_ORIGINS, comma-separated); agents and gateways send no Origin and
pass. Each release publishes the Dockerfile's image as ghcr.io/xh/hoist-docs (tags X.Y.Z,
X.Y, X and latest); its header lists the mounts and variables. To serve a directory instead,
set INDEX_DIR and mount it.
@xh/hoist-docs/docs is a browser-safe library for docs viewers such as Toolbox's: registry,
content and ranked search, with the same ranking as the MCP tools. Feed it docs payloads written
by:
hoist-docs export-docs --out <dir> # <dir>/<library>.json for each library, plus <dir>/index.json
# For doc authors: straight from checkouts, in well under a second, so edits show up live.
hoist-docs export-docs --out <dir> --from-checkout ../hoist-react --from-checkout ../hoist-coreimport {DocsCatalog} from '@xh/hoist-docs/docs';
const catalog = new DocsCatalog([reactPayload, corePayload]);
catalog.search('grid column renderer');Development requires Node 24 and pnpm; the published package runs on Node 20 or later. Node runs
the TypeScript source directly; the published package is
compiled (pnpm build, run automatically on pack).
pnpm install
pnpm build:react --root ../hoist-react # build indexes from sibling checkouts into ./indexes
pnpm build:core --root ../hoist-core
pnpm build:react --root ../hoist-chat-kit
pnpm build:watch # rebuild ./indexes as the checkouts or builders change
pnpm dev # HTTP on 8081 from ./indexes, restarting on changes
pnpm mcp --index-dir indexes # stdio, as an agent would run itRebuilt or added index files are picked up within a few seconds, without a restart.
pnpm test- unit tests; golden-set retrieval checks for each library (test/golden/,VERBOSE=1prints every query's top 3); and a parity spec that checks search ranks exactly as hoist-react's original search did.HOIST_REACT_ROOT=../hoist-react pnpm test- also runs the hoist-react builder's schema conformance spec against that checkout.pnpm typecheck,pnpm lint,pnpm format.
The builders live in builders/: builders/react/ (Node, ts-morph), for hoist-react and the other
TypeScript libraries, and builders/core/ (a Java program written in Groovy, built with Gradle;
needs a JDK 17 or later). Each takes a library checkout and writes <library>-<version>.json to
./indexes (--out to change, --gzip to compress):
pnpm build:react --root <hoist-react checkout> [--version 91.0.0]
pnpm build:react --root <hoist-chat-kit checkout> --library chat-kit [--version 2.0.0]
pnpm build:core --root <hoist-core checkout> [--version 45.0.0]A TypeScript library's checkout needs its dependencies installed first, for type resolution.
Each library builds its index in its own publish job, on the commit it is publishing, with the version it is about to publish, for releases and snapshots alike.
- TypeScript libraries: add
@xh/hoist-docs-builderas a dev dependency, run it beforenpm publishto write the gzipped index into the package, list it infiles, and declare it inpackage.json:An organization's own library does the same and is found the same way. Agent instructions in an index are used only from"hoistDocs": {"id": "react", "index": "hoist-docs/index.json.gz"}
@xhpackages. - hoist-core, and any Grails library: depend on
io.xh:hoist-docs-builderin adocsBuilderconfiguration, run it from aJavaExectask, and attach its output to the Maven publication with classifierdocs-indexand extensionjson.gz(seebuildDocsIndexin hoist-core'sbuild.gradle).
The library also needs its docs and a docs/doc-registry.json. An XH library gets a row in
src/libraries.ts and a golden set in test/golden/.
- Releases: change the top heading of
CHANGELOG.mdto the release version and date, mergedevelopintomaster, then run theDeploy Releaseworkflow frommasterwith the version. It tests, publishes the tool (@xh/hoist-docs) and the TypeScript builder (@xh/hoist-docs-builder) to npm, the Grails builder (io.xh:hoist-docs-builder) to Maven Central and the gateway image to GHCR, all at that version, then tags the commit and creates a GitHub release.package.jsonstays on its-SNAPSHOTversion: the workflow sets the release version for the run, as hoist-react's does. Hotfixes run from their own branch withis-hotfixchecked. Entries followdocs/changelog-format.md. - Snapshots: every push to
developpublishes all three through theDeploy Snapshotworkflow - the npm packages as<version>.<timestamp>under thenextdist-tag, the Grails builder atpackage.json's-SNAPSHOTversion to Sonatype's snapshot repository. Libraries depend on the builder'snext(or, for hoist-core, its-SNAPSHOT), so each of their builds uses the newest builder.