zeekay
fe2e8c2a02
A search with a limit now runs in two passes: every file is weighed (matching lines counted, definitions as 2^32) without holding a hit, then hits are read from the heaviest files until the limit is met. The answer is the head of the unlimited list, checked for limits from 0 to the whole list over text, symbol, context, ties and documents. Before, every hit of every file was built, sorted and deduplicated before the limit applied: a pattern matching 1.28 million lines of a 112 MB tree took 15.6 s where it now takes 0.14 s, and rg's --max-count had bounded that case before this crate replaced it. When there is a tgrep index at or above the searched directory the search asks it which files can match. Candidates are matched against current bytes, and files whose content or name changed at or after the build are read from disk whether or not the index lists them, so the answer is the scan's. Index::Skip scans, Index::Only refuses to; the tests ask every query all three ways on the same tree, before and after edits, creations, deletions and renames, and fail if the freshness walk is disabled. hanzo-mcp index [DIR] builds one. Measured on 112 MB / 9,026 files, cores 0-4: rg 43-55 ms, scan 75-93, indexed 28-50. Without a watcher the index costs a metadata walk.
@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