zeekay
e9e6096ce4
hanzo-trigram is the one search engine behind both actions: tgrep-core
(the hanzoai fork, MIT, pinned by commit, feature docs) linked as a
library, so a search is a call, not an rg spawn. It is its own crate so
Dev can link it without this crate's browser and parser dependencies;
hanzo_mcp::trigram re-exports it.
Results are ranked (matching lines a file, or definitions before uses
for a symbol), then path, then line, so a page is an offset into one
fixed list and the cursor really pages: before, rg stopped at limit and
a cursor repeated the first page. .gitignore, hidden and binary files
are skipped as rg skips them. A glob that names a document type (*.pdf,
*.docx, *.zip) reads documents too, and a hit inside one carries the
archive members and its page, slide, paragraph or cell.
fs and code keep their names, schemas and answer shapes; entry and place
appear on a document hit only. search_symbol now reads definitions by
the engine's declaration patterns, not the first-keyword guess.
Linking tgrep-core brings libsqlite3-sys (its managed-index code), which
needs a newer cc than the tree-sitter grammars allow, so Cargo resolves
tree-sitter-{c,cpp,javascript,python,rust,typescript} to their previous
patch releases. 241 library tests and the code tool's pass on them.
Gating managed/ behind a feature in the fork removes both.
@hanzo/mcp
An MCP server for coding agents: files, shell, code, git, HTTP, project context
and UI components, plus tools that call the Hanzo API. It speaks MCP over stdio,
or over streamable HTTP with --transport http.
Register it with an agent
The package declares Node 18 or newer. For Claude Code:
claude mcp add hanzo -- npx -y @hanzo/mcp serve
npx -y @hanzo/mcp install --claude-code runs that command with --scope user,
which registers the server for every project.
claude mcp list then reports hanzo: npx -y @hanzo/mcp serve - ✔ Connected.
With --scope project the entry goes into the project's .mcp.json instead,
and Claude Code asks before it starts a server from that file. Other MCP clients
take the same command in their server config:
{
"mcpServers": {
"hanzo": {
"command": "npx",
"args": ["-y", "@hanzo/mcp", "serve"]
}
}
}
The first start downloads the package; with an empty npm cache that took 80 to 100 seconds.
Tools
serve with no flags offers these, in the groups src/tools/unified/index.ts
defines:
| group | tools |
|---|---|
| core | fs, exec, code, git, fetch, workspace, ui |
| optional | think, memory, hanzo, plan, tasks, mode, gimp |
| code intelligence | code_search, code_context, code_ask, code_index |
| tracker | tracker_boards, tracker_issues, tracker_create, tracker_update |
| kai | kai_decide, kai_choice, kai_score, kai_noul |
The core and optional tools take an action argument that picks the operation;
ui takes method. The code intelligence, tracker and kai tools call
https://api.hanzo.ai with the key in HANZO_API_KEY, and API_URL points
them at another host.
The kai tools ask Kai, Hanzo's decision model, typed questions about a case
(POST /v1/decisions) and answer with calibrated probabilities: kai_choice
picks a label, kai_score an ordinal level, kai_noul the probability that a
statement holds, and kai_decide asks up to 100 of them in one call.
instructions is optional on every question and recommended. A kai_choice
call:
{ "state": "I was charged twice for my March invoice. Please refund the duplicate.",
"instructions": "Which team should handle this ticket?",
"criteria": { "billing": "charges, invoices and refunds", "product": "how to use the product" } }
hanzo reaches every Hanzo Cloud subsystem: resource names one, action one
of its operations, args that operation's arguments. With no action it lists
the resource's operations, and resource: "describe" with args: {subsystem, op}
says what one takes. The list is generated from cloud's catalog.
{ "resource": "graph", "action": "graphResolve",
"args": { "entity": "acme/svc/api", "relation": "owner", "as_of": "2026-09-01T00:00:00Z" } }
Flags on serve change the set:
| flag | effect |
|---|---|
--disable-tools plan,tasks |
removes the named tools |
--core-only |
only the core group |
--enable-ui |
adds the ui_* component tools |
--enable-desktop |
adds hanzo_desktop and playwright_control |
--enable-autogui, --enable-orchestration, --enable-ui-registry, --enable-github-ui, --enable-community-cryptuon |
add those tool sets |
--full-surface |
adds the UI, AutoGUI, orchestration, UI registry and GitHub UI sets together |
npx -y @hanzo/mcp serve --help lists every flag. This prints the tool names a
server offers; put any flags after serve:
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| npx -y @hanzo/mcp serve 2>/dev/null \
| node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{for(const l of s.split("\n"))if(l.includes("\"id\":2"))console.log(JSON.parse(l).result.tools.map(t=>t.name).join(" "))})'
Over HTTP
npx -y @hanzo/mcp serve --transport http --port 3000
The endpoint is the root path, http://127.0.0.1:3000/. POST JSON-RPC to it
with Accept: application/json, text/event-stream; answers come back as
server-sent events.
When a client shows no tools
Start the server by hand. A working one answers initialize with its name and
version:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
| npx -y @hanzo/mcp serve
With HANZO_MCP_DEBUG=1 in the server's environment, stderr also shows its
working directory, the resolved binary, its arguments and the start of PATH.
Python
hanzo-mcp on PyPI is a separate server, built from
hanzoai/python-sdk.
Development
pnpm install
pnpm build
pnpm smoke # runs dist/cli.js over stdio: initialize, tools/call, resources
License
MIT