mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
hanzoskills.com/llms.txt now opens with the install line, the API reference index and the company index, so an agent that lands on any one of the three can find the rest. robots.txt claimed 537 documents while llms.txt counts 920. The number is gone from robots.txt; llms.txt derives it. public/ is regenerated from scripts/site.py, which it had fallen behind: the copy-prompt menu and agent bar were in the generator and not in the committed pages. tests/site.mjs passes against the result. Co-authored-by: Hanzo Dev <[email protected]>
684 lines
31 KiB
HTML
684 lines
31 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>hip-0010</title>
|
|
<meta name="color-scheme" content="dark">
|
|
<style>
|
|
/* Committed to one visual world: a dark instrument panel. No light variant —
|
|
the dot field and the hairline rules only read on black, and a naive
|
|
inversion would wash both out. Every colour is painted explicitly so the page
|
|
never borrows a host background. */
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
|
|
|
:root{
|
|
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
|
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
|
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
|
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
|
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
|
--mono:var(--font-zen-mono);
|
|
--sans:var(--font-zen-sans);
|
|
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
|
--r:999px; --r-soft:14px;
|
|
}
|
|
*{box-sizing:border-box}
|
|
html{-webkit-text-size-adjust:100%}
|
|
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
|
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
|
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
|
|
|
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
|
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
|
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
|
would cut off the copy-prompt menu. */
|
|
.hero{position:relative;border-bottom:1px solid var(--line)}
|
|
.hero::before{content:"";position:absolute;inset:0;
|
|
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
|
background-size:7px 7px;
|
|
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
pointer-events:none}
|
|
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
|
|
|
nav{border-bottom:1px solid var(--line)}
|
|
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
|
justify-content:space-between;align-items:center;gap:1rem}
|
|
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
|
display:inline-flex;align-items:center;gap:.6rem}
|
|
.brand i{font-style:normal;color:var(--faint)}
|
|
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
|
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
|
nav a.up:hover{color:var(--ink)}
|
|
|
|
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
|
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
|
h1 em{font-style:normal;color:var(--faint)}
|
|
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
|
|
|
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
|
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
|
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
|
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
|
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
|
line-height:1.2;font-weight:400}
|
|
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
|
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
|
.btn.solid:hover{background:#d8d8d4}
|
|
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
|
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
|
|
|
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
|
.copy{position:relative;display:inline-flex}
|
|
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
|
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
|
padding:.4rem;display:flex;flex-direction:column;
|
|
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
|
.menu[hidden]{display:none}
|
|
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
|
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
|
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
|
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
|
white-space:nowrap}
|
|
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
|
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
|
.mi:hover .mark{color:var(--ink)}
|
|
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
|
letter-spacing:.1em;text-transform:uppercase}
|
|
|
|
/* Works-with bar: one scrolling row, name and mark per agent. */
|
|
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
|
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
|
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
|
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
|
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
|
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
|
display:flex;align-items:center}
|
|
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
|
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
|
-webkit-overflow-scrolling:touch;
|
|
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
|
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
|
.bar::-webkit-scrollbar{display:none}
|
|
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
|
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
|
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
|
text-decoration:none;background:var(--ground)}
|
|
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
|
.agent .mark{width:.95rem;height:.95rem}
|
|
|
|
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
|
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
|
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
|
p{margin:0 0 1rem;max-width:70ch}
|
|
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
|
li{margin:.22rem 0}
|
|
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
|
text-decoration-color:var(--line-hi)}
|
|
a:hover{text-decoration-color:var(--ink)}
|
|
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
|
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
|
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
|
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
|
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
|
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
|
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
|
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
|
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
|
display:block;overflow-x:auto}
|
|
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
|
|
|
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
|
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
|
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
|
white-space:pre;line-height:1.9}
|
|
.curl b{color:var(--ink);font-weight:400}
|
|
.curl i{font-style:normal;color:var(--faint)}
|
|
|
|
/* index */
|
|
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
|
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
|
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
|
#q:focus{outline:none;border-color:var(--soft)}
|
|
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
|
text-transform:uppercase;margin:0 0 2rem}
|
|
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
|
padding-bottom:.45rem}
|
|
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
|
border-radius:var(--r-soft);text-decoration:none}
|
|
.row:hover{background:#0a0a0a}
|
|
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
|
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
|
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
|
color:var(--faint);font-size:.85rem}
|
|
footer a{color:var(--soft)}
|
|
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
|
margin:0 0 2rem;font-size:.85rem}
|
|
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
|
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
|
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
|
.fmap a:hover{text-decoration:underline}
|
|
.fmap div{color:var(--faint);line-height:1.5}
|
|
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
|
|
|
@media (max-width:640px){
|
|
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
|
.btns{gap:.5rem}
|
|
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
|
.copy,.copy .btn{width:100%;justify-content:center}
|
|
.menu{left:0;right:0;min-width:0}
|
|
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
|
.strip b{border-right:0;padding-right:0}
|
|
.bar{width:100%}
|
|
}
|
|
</style>
|
|
<link rel="alternate" type="text/markdown" href="/hip-0010.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/hip-0010">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/hip-0010.md
|
|
Index: https://hanzoskills.com/llms.txt
|
|
Corpus: https://hanzoskills.com/all.md
|
|
Append .md to any path for the markdown twin. -->
|
|
<body>
|
|
<nav><div class="in">
|
|
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
|
<a class="up" href="/">All skills</a>
|
|
</div></nav>
|
|
|
|
<div class="wrap">
|
|
<h1>hip-0010</h1><p class="lede">HIP-10: Model Context Protocol (MCP) Integration Standards. Status Final. Hanzo architectural specification.</p><h1>HIP-0010: Model Context Protocol (MCP) Integration Standards</h1>
|
|
<h2>Abstract</h2>
|
|
<p>This proposal defines the Model Context Protocol (MCP) integration standards for the Hanzo ecosystem. MCP enables seamless tool use, context management, and extensibility for AI models through a standardized protocol for connecting models to external tools and data sources.</p>
|
|
<h2>Implementations</h2>
|
|
<p>Where the code is. How far it has got is the front matter's <code>implementation-go</code>, <code>implementation-cpp</code> and <code>implementation-rust</code>, which every HIP carries in the same three words and the index counts.</p>
|
|
<p>| Language | Repository | Package | |----------|------------|---------| | <strong>Python</strong> | <a href="https://github.com/hanzoai/mcp">github.com/hanzoai/mcp</a> | <code>hanzo-mcp</code> (PyPI) | | <strong>TypeScript</strong> | <a href="https://github.com/hanzoai/mcp">github.com/hanzoai/mcp</a> | <code>@hanzoai/mcp</code> (NPM) | | <strong>Rust</strong> | <a href="https://github.com/hanzoai/mcp/tree/main/rust">github.com/hanzoai/mcp/rust</a> | <code>hanzo-mcp</code> (crates.io) | | <strong>Go</strong> | <a href="https://github.com/hanzoai/mcp/tree/main/go">github.com/hanzoai/mcp/go</a> | <code>github.com/hanzoai/mcp/go</code> |</p>
|
|
<p><strong>CLI</strong>: <code>hanzo-mcp</code> (available via <code>pip install hanzo-mcp</code> or <code>cargo install hanzo-mcp</code>)</p>
|
|
<h3>Core Tools (All Implementations)</h3>
|
|
<p>| Tool | Python | Rust | TypeScript | Description | |------|--------|------|------------|-------------| | <strong>proc</strong> | ✅ | ✅ | ✅ | Process execution (shell, ps, kill) | | <strong>fs</strong> | ✅ | ✅ | ✅ | Filesystem (read, write, edit, search) | | <strong>think</strong> | ✅ | ✅ | ✅ | Reasoning (think, critic, review) | | <strong>memory</strong> | ✅ | ✅ | ✅ | Persistent memory & knowledge bases | | <strong>browser</strong> | ✅ | ⚠️ | ✅ | Browser automation (90+ Playwright actions) | | <strong>ui</strong> | ✅ | ✅ | ⚠️ | Native UI automation (click, type, screenshot) | | <strong>mode</strong> | ✅ | ✅ | ✅ | Developer personality modes | | <strong>plan</strong> | ✅ | ✅ | ✅ | Task/plan management |</p>
|
|
<h3>Rust-Specific Features</h3>
|
|
<ul><li><strong>Tree-sitter AST search</strong>: 8 languages (Rust, JS, TS, Python, Go, Java, C, C++)</li><li><strong>Native macOS UI</strong>: Quartz backend for high-performance automation</li><li><strong>Process auto-backgrounding</strong>: Commands exceeding 45s auto-background</li><li><strong>Unified search</strong>: Multi-modal search (Text, AST, Symbol, Vector, Memory, File)</li><li><strong>Zero-copy parsing</strong>: Efficient JSON-RPC handling</li></ul>
|
|
<p>The tool surface itself is whatever <code>hanzo/mcp</code> ships; this HIP governs the protocol, not the catalogue.</p>
|
|
<h2>Specification</h2>
|
|
<h3>Protocol Overview</h3>
|
|
<pre><code class="lang-yaml">MCP Architecture:
|
|
Transport Layer:
|
|
- JSON-RPC 2.0
|
|
- WebSocket/HTTP
|
|
- Bidirectional communication
|
|
|
|
Session Management:
|
|
- Persistent connections
|
|
- Context preservation
|
|
- State synchronization
|
|
|
|
Tool Registry:
|
|
- Dynamic discovery
|
|
- Capability negotiation
|
|
- Version management
|
|
|
|
Security:
|
|
- Permission system
|
|
- Sandboxed execution
|
|
- Audit logging</code></pre>
|
|
<h3>Core MCP Messages</h3>
|
|
<pre><code class="lang-typescript">// Tool Registration
|
|
interface ToolRegistration {
|
|
jsonrpc: "2.0";
|
|
method: "tools/register";
|
|
params: {
|
|
name: string;
|
|
description: string;
|
|
input_schema: JSONSchema;
|
|
output_schema: JSONSchema;
|
|
permissions: Permission[];
|
|
};
|
|
}
|
|
|
|
// Tool Execution
|
|
interface ToolExecution {
|
|
jsonrpc: "2.0";
|
|
method: "tools/execute";
|
|
params: {
|
|
tool: string;
|
|
arguments: any;
|
|
context?: Context;
|
|
};
|
|
}
|
|
|
|
// Context Update
|
|
interface ContextUpdate {
|
|
jsonrpc: "2.0";
|
|
method: "context/update";
|
|
params: {
|
|
entries: ContextEntry[];
|
|
merge_strategy: "replace" | "merge" | "append";
|
|
};
|
|
}</code></pre>
|
|
<h3>Tool Definition Standard</h3>
|
|
<pre><code class="lang-yaml"># Tool manifest (mcp-tool.yaml)
|
|
name: web_search
|
|
version: 1.0.0
|
|
description: Search the web for information
|
|
|
|
input:
|
|
type: object
|
|
properties:
|
|
query:
|
|
type: string
|
|
description: Search query
|
|
max_results:
|
|
type: integer
|
|
default: 10
|
|
required: [query]
|
|
|
|
output:
|
|
type: object
|
|
properties:
|
|
results:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
title: string
|
|
url: string
|
|
snippet: string
|
|
|
|
permissions:
|
|
- network:http
|
|
- rate_limit:100/min
|
|
|
|
implementation:
|
|
runtime: node
|
|
handler: ./search.js
|
|
timeout: 30000</code></pre>
|
|
<h3>Hanzo MCP Server</h3>
|
|
<pre><code class="lang-python">class HanzoMCPServer:
|
|
"""
|
|
MCP server implementation for Hanzo
|
|
"""
|
|
def __init__(self):
|
|
self.tools = {}
|
|
self.contexts = {}
|
|
self.sessions = {}
|
|
|
|
async def handle_request(self, request):
|
|
"""Route JSON-RPC requests"""
|
|
if request.method == "tools/list":
|
|
return self.list_tools()
|
|
elif request.method == "tools/execute":
|
|
return await self.execute_tool(request.params)
|
|
elif request.method == "context/get":
|
|
return self.get_context(request.params)
|
|
elif request.method == "context/update":
|
|
return self.update_context(request.params)
|
|
|
|
async def execute_tool(self, params):
|
|
"""Execute tool with sandboxing"""
|
|
tool = self.tools[params.tool]
|
|
|
|
# Validate permissions
|
|
if not self.check_permissions(tool, params.session_id):
|
|
raise PermissionError(f"Tool {tool.name} not authorized")
|
|
|
|
# Sandbox execution
|
|
sandbox = ToolSandbox(
|
|
memory_limit="512MB",
|
|
cpu_limit="1 core",
|
|
timeout=tool.timeout
|
|
)
|
|
|
|
result = await sandbox.execute(
|
|
tool.handler,
|
|
params.arguments,
|
|
context=self.contexts[params.session_id]
|
|
)
|
|
|
|
return result</code></pre>
|
|
<h3>Built-in Tools</h3>
|
|
<pre><code class="lang-yaml">Core Tools:
|
|
filesystem:
|
|
- read_file
|
|
- write_file
|
|
- list_directory
|
|
- create_directory
|
|
|
|
network:
|
|
- http_request
|
|
- websocket_connect
|
|
- dns_lookup
|
|
|
|
database:
|
|
- sql_query
|
|
- redis_get/set
|
|
- mongodb_find
|
|
|
|
compute:
|
|
- execute_code
|
|
- run_notebook
|
|
- shell_command
|
|
|
|
ai:
|
|
- call_model
|
|
- generate_embedding
|
|
- semantic_search</code></pre>
|
|
<h3>Language Intelligence</h3>
|
|
<p>Language intelligence is one tool, not one tool per language. The <code>lsp</code> tool takes an action, a file, and a position, and returns the same shapes whichever server answers. The server for a file's language is installed and started on first use and reused for the rest of the session.</p>
|
|
<p>| Language | Server | Features | |----------|--------|----------| | Go | <code>gopls</code> | Definition, references, rename, diagnostics, formatting | | Python | <code>pyright</code> | Type checking, definition, references, completions | | TypeScript/JavaScript | <code>typescript-language-server</code> | Full TS/JS intelligence | | Rust | <code>rust-analyzer</code> | Comprehensive Rust support | | Java | <code>jdtls</code> | Eclipse JDT-based Java support | | C/C++ | <code>clangd</code> | LLVM-based C/C++ intelligence | | Ruby | <code>solargraph</code> | Ruby language server | | Lua | <code>lua-language-server</code> | Lua intelligence |</p>
|
|
<pre><code class="lang-python">lsp(action="definition", file="main.go", line=42, character=15)
|
|
# -> Starts gopls if not running
|
|
# -> Returns: {"file": "handler.go", "line": 10, "character": 5}
|
|
|
|
lsp(action="references", file="auth.py", line=20, character=8)
|
|
# -> Starts pyright if not running
|
|
# -> Returns: [{"file": "auth.py", "line": 20}, {"file": "test_auth.py", "line": 5}, ...]
|
|
|
|
lsp(action="diagnostics", file="server.ts")
|
|
# -> Returns: [{"line": 15, "message": "Type 'string' is not assignable to type 'number'", "severity": "error"}]</code></pre>
|
|
<h3>Structural Search</h3>
|
|
<p>The <code>ast</code> tool parses with tree-sitter — incremental and error-tolerant, so a file that does not compile is still searchable — across Rust, JavaScript, TypeScript, Python, Go, Java, C and C++. Queries match syntax rather than text:</p>
|
|
<pre><code class="lang-python"># Find all async functions in Python files
|
|
ast("async def", "./src", line_number=True)
|
|
|
|
# Find all struct definitions in Go
|
|
ast("type.*struct", "./pkg", line_number=True)
|
|
|
|
# Find all test functions
|
|
ast("func Test", "./tests")
|
|
|
|
# Find all React components (capitalized function exports)
|
|
ast("export.*function [A-Z]", "./components")</code></pre>
|
|
<h3>Tool Implementation Examples</h3>
|
|
<h4>Web Search Tool</h4>
|
|
<pre><code class="lang-javascript">// search.js
|
|
export default async function search({ query, max_results = 10 }) {
|
|
// Use Hanzo search service
|
|
const response = await fetch('https://api.hanzo.ai/search', {
|
|
method: 'POST',
|
|
headers: {
|
|
'Content-Type': 'application/json',
|
|
'Authorization': `Bearer ${process.env.HANZO_API_KEY}`
|
|
},
|
|
body: JSON.stringify({ query, limit: max_results })
|
|
});
|
|
|
|
const data = await response.json();
|
|
|
|
return {
|
|
results: data.results.map(r => ({
|
|
title: r.title,
|
|
url: r.url,
|
|
snippet: r.snippet
|
|
}))
|
|
};
|
|
}</code></pre>
|
|
<h4>Code Execution Tool</h4>
|
|
<pre><code class="lang-python"># code_executor.py
|
|
import subprocess
|
|
import tempfile
|
|
import os
|
|
|
|
async def execute_code(language: str, code: str, timeout: int = 30):
|
|
"""Execute code in sandboxed environment"""
|
|
|
|
# Create temporary file
|
|
with tempfile.NamedTemporaryFile(
|
|
mode='w',
|
|
suffix=_get_extension(language),
|
|
delete=False
|
|
) as f:
|
|
f.write(code)
|
|
temp_file = f.name
|
|
|
|
try:
|
|
# Execute based on language
|
|
if language == "python":
|
|
result = subprocess.run(
|
|
["python", temp_file],
|
|
capture_output=True,
|
|
text=True,
|
|
timeout=timeout
|
|
)
|
|
elif language == "javascript":
|
|
result = subprocess.run(
|
|
["node", temp_file],
|
|
capture_output=True,
|
|
text=True,
|
|
timeout=timeout
|
|
)
|
|
else:
|
|
raise ValueError(f"Unsupported language: {language}")
|
|
|
|
return {
|
|
"stdout": result.stdout,
|
|
"stderr": result.stderr,
|
|
"returncode": result.returncode
|
|
}
|
|
finally:
|
|
os.unlink(temp_file)</code></pre>
|
|
<h3>Context Management</h3>
|
|
<pre><code class="lang-python">class MCPContext:
|
|
"""
|
|
Manages context across tool executions
|
|
"""
|
|
def __init__(self):
|
|
self.entries = {}
|
|
self.history = []
|
|
self.metadata = {}
|
|
|
|
def add_entry(self, key: str, value: Any, type: str = "text"):
|
|
"""Add context entry"""
|
|
entry = ContextEntry(
|
|
key=key,
|
|
value=value,
|
|
type=type,
|
|
timestamp=time.time()
|
|
)
|
|
self.entries[key] = entry
|
|
self.history.append(entry)
|
|
|
|
def get_relevant_context(self, query: str, max_entries: int = 10):
|
|
"""Retrieve relevant context for query"""
|
|
# Semantic search through context
|
|
embeddings = self.generate_embeddings([query] + [e.value for e in self.entries.values()])
|
|
|
|
similarities = cosine_similarity(embeddings[0], embeddings[1:])
|
|
top_indices = np.argsort(similarities)[-max_entries:]
|
|
|
|
return [list(self.entries.values())[i] for i in top_indices]</code></pre>
|
|
<h3>The Agent Loop</h3>
|
|
<p>A model driving these tools follows one loop, and the server enforces the order rather than trusting the model to keep it:</p>
|
|
<p><strong>1. Think</strong>: Analyze the request. Identify constraints, dependencies, and risks. Use the <code>think</code> tool to record reasoning without taking action.</p>
|
|
<p><strong>2. Plan</strong>: Outline the sequence of changes. Identify files to read, edits to make, tests to run. Summarize the plan for human review.</p>
|
|
<p><strong>3. Implement</strong>: Execute the plan through tool calls. Make changes incrementally — one file at a time, one logical edit at a time. Prefer <code>edit</code> (surgical string replacement) over <code>write</code> (full file overwrite).</p>
|
|
<p><strong>4. Validate</strong>: Run tests, linters, type checkers and build commands. Observe the output. If validation fails, return to step 1 with the error context.</p>
|
|
<p><strong>5. Learn</strong>: Record insights, architectural decisions and project conventions in the memory system, so the next session starts where this one ended.</p>
|
|
<p>Validation cannot be skipped and planning cannot be bypassed. The agent summarizes what it did and awaits confirmation before starting the next task.</p>
|
|
<h3>Claude Desktop Integration</h3>
|
|
<pre><code class="lang-json">// Claude Desktop config (~/.claude/config.json)
|
|
{
|
|
"mcpServers": {
|
|
"hanzo": {
|
|
"command": "hanzo-mcp",
|
|
"args": ["serve"],
|
|
"env": {
|
|
"HANZO_API_KEY": "sk-hanzo-..."
|
|
}
|
|
}
|
|
}
|
|
}</code></pre>
|
|
<h3>Security Model</h3>
|
|
<pre><code class="lang-python">class MCPSecurity:
|
|
"""
|
|
Security layer for MCP
|
|
"""
|
|
def __init__(self):
|
|
self.permissions = PermissionManager()
|
|
self.sandbox = Sandbox()
|
|
self.audit = AuditLogger()
|
|
|
|
def check_permission(self, tool: str, action: str, session: Session):
|
|
"""Check if action is permitted"""
|
|
# Default deny
|
|
if not session.authenticated:
|
|
return False
|
|
|
|
# Check tool permissions
|
|
tool_perms = self.permissions.get_tool_permissions(tool)
|
|
if action not in tool_perms:
|
|
return False
|
|
|
|
# Check user permissions
|
|
user_perms = self.permissions.get_user_permissions(session.user_id)
|
|
if not user_perms.can_execute(tool, action):
|
|
return False
|
|
|
|
# Log for audit
|
|
self.audit.log(session.user_id, tool, action)
|
|
|
|
return True</code></pre>
|
|
<h3>Performance Optimization</h3>
|
|
<pre><code class="lang-yaml">Caching:
|
|
Tool Results:
|
|
- Cache deterministic tool outputs
|
|
- TTL based on tool type
|
|
- Invalidation on context change
|
|
|
|
Context:
|
|
- In-memory context cache
|
|
- Persistent context storage
|
|
- Lazy loading of large contexts
|
|
|
|
Connection Pooling:
|
|
- Reuse WebSocket connections
|
|
- Connection multiplexing
|
|
- Automatic reconnection
|
|
|
|
Batching:
|
|
- Batch multiple tool calls
|
|
- Parallel execution when possible
|
|
- Result aggregation</code></pre>
|
|
<h3>SDK Usage</h3>
|
|
<h4>Python SDK</h4>
|
|
<pre><code class="lang-python">from hanzoai.mcp import MCPClient, Tool
|
|
|
|
# Initialize client
|
|
client = MCPClient("ws://localhost:3000/mcp")
|
|
|
|
# Register custom tool
|
|
@client.tool(
|
|
name="calculator",
|
|
description="Perform calculations"
|
|
)
|
|
async def calculator(expression: str) -> float:
|
|
return eval(expression) # Simplified example
|
|
|
|
# Use in agent
|
|
result = await client.execute_tool(
|
|
"web_search",
|
|
{"query": "Hanzo AI"}
|
|
)</code></pre>
|
|
<h4>TypeScript SDK</h4>
|
|
<pre><code class="lang-typescript">import { MCPClient, Tool } from '@hanzoai/mcp';
|
|
|
|
// Initialize client
|
|
const client = new MCPClient('ws://localhost:3000/mcp');
|
|
|
|
// Register tool
|
|
client.registerTool({
|
|
name: 'calculator',
|
|
description: 'Perform calculations',
|
|
handler: async (expression: string) => {
|
|
return eval(expression); // Simplified
|
|
}
|
|
});
|
|
|
|
// Execute tool
|
|
const result = await client.executeTool('web_search', {
|
|
query: 'Hanzo AI'
|
|
});</code></pre>
|
|
<h4>Rust SDK</h4>
|
|
<pre><code class="lang-rust">use hanzo_mcp::{MCPServer, Config};
|
|
use hanzo_mcp::tools::{ShellTool, FsTool, ThinkTool, MemoryTool};
|
|
|
|
// Initialize server with tools
|
|
let config = Config::default();
|
|
let mut server = MCPServer::new(config);
|
|
|
|
// Add built-in tools
|
|
server.add_tool(ShellTool::new());
|
|
server.add_tool(FsTool::new());
|
|
server.add_tool(ThinkTool::new());
|
|
server.add_tool(MemoryTool::new());
|
|
|
|
// Start server
|
|
server.serve("127.0.0.1:3000").await?;</code></pre>
|
|
<p><strong>Using tools directly:</strong></p>
|
|
<pre><code class="lang-rust">use hanzo_mcp::tools::{ShellTool, ProcToolArgs};
|
|
use serde_json::Value;
|
|
|
|
// Execute shell command
|
|
let tool = ShellTool::new();
|
|
let args = ProcToolArgs {
|
|
action: "exec".to_string(),
|
|
command: Some(Value::String("echo hello".to_string())),
|
|
..Default::default()
|
|
};
|
|
|
|
let result = tool.execute(args).await?;
|
|
let json: serde_json::Value = serde_json::from_str(&result)?;
|
|
println!("stdout: {}", json["stdout"]);</code></pre>
|
|
<p><strong>Search with modality detection:</strong></p>
|
|
<pre><code class="lang-rust">use hanzo_mcp::search::{detect_modalities, SearchModality, AstSearcher};
|
|
|
|
// Auto-detect search modalities
|
|
let modalities = detect_modalities("class UserService");
|
|
assert!(modalities.contains(&SearchModality::Ast));
|
|
assert!(modalities.contains(&SearchModality::Text));
|
|
|
|
// AST search with tree-sitter
|
|
let searcher = AstSearcher::new();
|
|
let results = searcher
|
|
.search("handleClick", path, Some("typescript"), 10)
|
|
.await?;</code></pre>
|
|
<p><strong>Cargo.toml:</strong></p>
|
|
<pre><code class="lang-toml">[dependencies]
|
|
hanzo-mcp = "0.12"
|
|
|
|
# Optional features
|
|
[features]
|
|
default = []
|
|
vector-store = ["qdrant-client"]
|
|
computer-control = ["enigo", "screenshots"]</code></pre>
|
|
<ol><li><a href="https://claude.ai/docs/mcp">Claude Desktop MCP</a></li><li><a href="./hip-0009-agent-sdk-multi-agent-orchestration-framework.md">HIP-0009: Agent SDK - Multi-Agent Orchestration Framework</a></li><li><a href="https://github.com/hanzoai/mcp">MCP Repository</a></li></ol>
|
|
<h2>Copyright</h2>
|
|
<p>Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p>
|
|
<footer>
|
|
<div class="fmap">
|
|
<div><b>Build</b>
|
|
<a href="https://hanzo.app">hanzo.app</a> app builder
|
|
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
|
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
|
<div><b>Run</b>
|
|
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
|
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
|
<div><b>Account</b>
|
|
<a href="https://hanzo.id">hanzo.id</a> sign in
|
|
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
|
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
|
<div><b>Company</b>
|
|
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
|
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
|
</div>
|
|
<div class="fend"><a href="/hip-0010.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |