mirror of
https://github.com/hanzoai/mcp.git
synced 2026-10-15 12:30:12 +00:00
The README registers the server the way that works, and lists its tools
The README said `npx -y @hanzo/mcp serve` runs an unrelated `serve` package. With npm 11 it starts this server, and it is the form `claude mcp add` writes; both forms answered initialize and tools/list the same way from an empty npm cache, and claude mcp list reports the added server connected. The tool section now lists what serve offers, in the groups src/tools/unified/index.ts defines, and gives the pipe that prints the names. The "13 tools" and "260+" counts, a --legacy flag the CLI does not have, the installer steps and the CI claims are gone: list-tools prints category headers with no tools under them, install --claude-code writes a file Claude Code does not read, and no workflow runs smoke-mcp.mjs. Co-authored-by: Hanzo Dev <[email protected]>
This commit is contained in:
Hanzo Dev
@@ -2,209 +2,114 @@
|
||||
|
||||
# @hanzo/mcp
|
||||
|
||||
The canonical Model Context Protocol server for the Hanzo AI Cloud — one action-routed tool surface every Hanzo agent runs on.
|
||||
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`.
|
||||
|
||||
[](https://www.npmjs.com/package/@hanzo/mcp)
|
||||
[](https://pypi.org/project/hanzo-mcp/)
|
||||
[]()
|
||||
[]()
|
||||
|
||||
## Quick start
|
||||
## Register it with an agent
|
||||
|
||||
The package declares Node 18 or newer. For Claude Code:
|
||||
|
||||
```bash
|
||||
npm install -g @hanzo/mcp
|
||||
hanzo-mcp serve
|
||||
claude mcp add hanzo -- npx -y @hanzo/mcp serve
|
||||
```
|
||||
|
||||
## What this is
|
||||
|
||||
`@hanzo/mcp` is the canonical MCP server for the Hanzo platform. It collapses a 260+ tool catalog into **13 HIP-0300 action-routed tools** (`fs`, `exec`, `code`, `git`, `fetch`, `workspace`, `ui`, plus optional `think`, `memory`, `hanzo`, `plan`, `tasks`, `mode`) served over the MCP stdio / streamable-http transports.
|
||||
|
||||
Every Hanzo agent speaks this same tool surface. The Python SDK (`hanzo-mcp` on PyPI) and the Rust crate (`hanzo-mcp::brain`) mirror it 1-to-1, so a tool name and its action schema are identical across all three runtimes.
|
||||
|
||||
Implements:
|
||||
- **HIP-0300** — Unified MCP Tools
|
||||
- **HIP-0106** — Unified Cloud Binary (`mcp` subsystem)
|
||||
|
||||
## Tool surface (HIP-0300)
|
||||
|
||||
13 canonical tools organized by axis. Each tool uses action-routed dispatch — one tool name, many verbs.
|
||||
|
||||
### Core tools (7)
|
||||
|
||||
| Tool | Axis | Key actions |
|
||||
|------|------|-------------|
|
||||
| `fs` | Bytes + paths | read, write, stat, list, mkdir, rm, mv, apply_patch, search_text |
|
||||
| `exec` | Execution | run, background, ps, kill, logs |
|
||||
| `code` | Symbols + semantics | parse, search, transform, summarize |
|
||||
| `git` | Diffs + history | status, diff, log, commit, branch, stash |
|
||||
| `fetch` | HTTP | get, post, put, delete, download |
|
||||
| `workspace` | Project context | info, config, env, dependencies |
|
||||
| `ui` | UI components | list_components, fetch_component, search, install |
|
||||
|
||||
### Optional tools (6)
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `think` | Structured reasoning |
|
||||
| `memory` | Persistent storage |
|
||||
| `hanzo` | Hanzo platform surface (iam, kms, paas, commerce) |
|
||||
| `plan` | Task planning |
|
||||
| `tasks` | Task tracking |
|
||||
| `mode` | Developer modes |
|
||||
|
||||
### Community tools (opt-in)
|
||||
|
||||
Third-party descriptors that shell out to externally-installed binaries. Off by default; enable individually.
|
||||
|
||||
| Tool | Source | Purpose |
|
||||
|------|--------|---------|
|
||||
| `tesseract.deploy` | [kcolbchain/tesseract](https://github.com/kcolbchain/tesseract) | Deploy zk-OCR relayer to a target chain |
|
||||
| `tesseract.health_check` | [kcolbchain/tesseract](https://github.com/kcolbchain/tesseract) | Probe deployed relayer addresses |
|
||||
| `tesseract.monitor` | [kcolbchain/tesseract](https://github.com/kcolbchain/tesseract) | Poll matching contract events |
|
||||
| `compress.solana` | [kcolbchain/blockchain-compression](https://github.com/kcolbchain/blockchain-compression) | Compress blob with Solana-tuned compressor |
|
||||
|
||||
Enable with `hanzo-mcp serve --enable-community-cryptuon`. See `src/tools/community/cryptuon/` for descriptors and per-tool env overrides (e.g. `$CRYPTUON_TESSERACT_DEPLOY`).
|
||||
|
||||
## Usage
|
||||
|
||||
### CLI
|
||||
|
||||
```bash
|
||||
# Default: HIP-0300 unified surface (13 tools)
|
||||
hanzo-mcp serve
|
||||
|
||||
# Legacy individual tools (read_file, write_file, bash, …)
|
||||
hanzo-mcp serve --legacy
|
||||
|
||||
# UI extensions
|
||||
hanzo-mcp serve --enable-ui --enable-desktop
|
||||
|
||||
# Disable specific tools
|
||||
hanzo-mcp serve --disable-tools plan,tasks
|
||||
|
||||
# List available tools
|
||||
hanzo-mcp list-tools
|
||||
|
||||
# Install for Claude Desktop
|
||||
hanzo-mcp install-desktop
|
||||
```
|
||||
|
||||
### Programmatic
|
||||
|
||||
```typescript
|
||||
import { getConfiguredTools } from '@hanzo/mcp';
|
||||
|
||||
// HIP-0300 unified surface (default)
|
||||
const tools = getConfiguredTools({ unified: true });
|
||||
|
||||
// Legacy individual tools
|
||||
const legacy = getConfiguredTools({ enableLegacy: true });
|
||||
|
||||
// With UI extensions
|
||||
const withUI = getConfiguredTools({
|
||||
unified: true,
|
||||
enableUI: true,
|
||||
enableDesktop: true,
|
||||
});
|
||||
```
|
||||
|
||||
## Client configuration
|
||||
|
||||
### Claude Desktop / Cursor / Code
|
||||
|
||||
Add to `.mcp.json`:
|
||||
`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:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"hanzo": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "--package=@hanzo/mcp", "hanzo-mcp", "serve"]
|
||||
"args": ["-y", "@hanzo/mcp", "serve"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Why `--package=`?** Without it, `npx -y @hanzo/mcp serve` resolves `serve` as a *separate* npm package (the unrelated static-file server) and runs that instead of `hanzo-mcp`. The `--package=` form binds npx to the right binary. This matters on every platform — Windows, macOS, and Linux.
|
||||
The first start downloads the package; with an empty npm cache that took 80 to
|
||||
100 seconds.
|
||||
|
||||
## Troubleshooting
|
||||
## Tools
|
||||
|
||||
If MCP "doesn't work" in Claude Desktop, Claude Code, Cursor, or any other client:
|
||||
`serve` with no flags offers these, in the groups `src/tools/unified/index.ts`
|
||||
defines:
|
||||
|
||||
1. **Verify the stdio handshake from the command line:**
|
||||
```bash
|
||||
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
|
||||
| npx -y --package=@hanzo/mcp@latest hanzo-mcp serve
|
||||
```
|
||||
A working install prints a JSON-RPC response with `"serverInfo":{"name":"hanzo-mcp","version":"…"}` within ~10 s. Silence (or a long hang) means the wrong binary is running.
|
||||
| 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` |
|
||||
|
||||
2. **Turn on debug logging** by setting `HANZO_MCP_DEBUG=1` in the client's MCP server env block. Stderr will then include the resolved CLI path, cwd, argv, and PATH prefix — usually enough to tell whether a stray `serve` binary, a wrong `npx` arg form, or a port conflict is shadowing the server.
|
||||
The core and optional tools take an `action` argument that picks the operation;
|
||||
`ui` takes `method`. The code intelligence and tracker tools call
|
||||
`https://api.hanzo.ai` with the key in `HANZO_API_KEY`, and `API_URL` points
|
||||
them at another host.
|
||||
|
||||
```json
|
||||
"hanzo": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "--package=@hanzo/mcp", "hanzo-mcp", "serve"],
|
||||
"env": { "HANZO_MCP_DEBUG": "1" }
|
||||
}
|
||||
```
|
||||
Flags on `serve` change the set:
|
||||
|
||||
In Claude Desktop the stderr lands in `~/Library/Logs/Claude/mcp-server-hanzo.log` (macOS) or `%APPDATA%\Claude\logs\mcp-server-hanzo.log` (Windows).
|
||||
| flag | effect |
|
||||
|---|---|
|
||||
| `--disable-tools plan,tasks` | removes the named tools |
|
||||
| `--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 |
|
||||
|
||||
3. **Rerun the installer** to overwrite a stale (2.4.1 or earlier) config:
|
||||
```bash
|
||||
npx -y --package=@hanzo/mcp@latest hanzo-mcp install --claude-desktop
|
||||
```
|
||||
Then restart Claude Desktop.
|
||||
|
||||
4. **Windows specifics.** `npx.cmd` shells out to `cmd.exe` for arg parsing, which is sensitive to quoting. If the JSON config uses single quotes anywhere, switch to double quotes.
|
||||
|
||||
5. **CI invariants.** The protocol-level contract is exercised on every push to main, on native Linux amd64 + arm64 (Hanzo self-hosted runners, no QEMU), via `scripts/smoke-mcp.mjs` and an e2e test against the *published* npm package using the same npx invocation shipped to clients. If MCP works locally but fails for you, open an issue with the `HANZO_MCP_DEBUG=1` log attached.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Claude Desktop / Cursor / Code -> stdio MCP transport
|
||||
|
|
||||
hanzo-mcp serve
|
||||
|
|
||||
+-------------------+-------------------+
|
||||
| |
|
||||
HIP-0300 unified tools legacy individual tools (--legacy)
|
||||
fs / exec / code / git / read_file, write_file, bash, …
|
||||
fetch / workspace / ui +
|
||||
optional think / memory /
|
||||
hanzo / plan / tasks / mode
|
||||
|
|
||||
TS runtime (today) | Rust runtime (latency-sensitive)
|
||||
|
|
||||
Go runtime under hanzoai/cloud (HIP-0106 in flight)
|
||||
```
|
||||
|
||||
Source layout:
|
||||
|
||||
```
|
||||
src/tools/unified/ # HIP-0300 action-routed tools (fs, exec, code, fetch, workspace, hanzo)
|
||||
src/tools/ # Individual tools (git, think, memory, tasks, plan, mode, …)
|
||||
rust/src/tools/ # Rust native tools (exec, git, fetch, code, computer, …)
|
||||
```
|
||||
|
||||
The Rust runtime provides native performance for latency-sensitive operations (<5 ms clicks, <2 ms keypress, <50 ms screenshots).
|
||||
|
||||
## Python SDK parity
|
||||
|
||||
The Python implementation (`hanzo-mcp` on PyPI) exposes the same 13 HIP-0300 tools via entry-point discovery from `hanzo-tools-*` packages. Tool names and action schemas are identical across both runtimes.
|
||||
`npx -y @hanzo/mcp serve --help` lists every flag. This prints the tool names a
|
||||
server offers; put any flags after `serve`:
|
||||
|
||||
```bash
|
||||
pip install hanzo-mcp
|
||||
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
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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](https://github.com/hanzoai/python-sdk).
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm build
|
||||
pnpm smoke # runs dist/cli.js over stdio: initialize, tools/call, resources
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
## Hanzo — the Open AI Cloud
|
||||
|
||||
Open source · every language · on-chain settlement. [hanzo.ai](https://hanzo.ai) · [docs.hanzo.ai](https://docs.hanzo.ai)
|
||||
|
||||
**SDKs in every language** — [Python](https://github.com/hanzoai/python-sdk) (flagship) · [TypeScript](https://github.com/hanzo-js/sdk) · [Go](https://github.com/hanzo-go/sdk) · [Rust](https://github.com/hanzo-rs/sdk) · [C++](https://github.com/hanzo-cpp/sdk) · [Swift](https://github.com/hanzo-swift/sdk) · [Kotlin](https://github.com/hanzo-kt/sdk) · [umbrella](https://github.com/hanzoai/sdk)
|
||||
|
||||
Reference in New Issue
Block a user