Files
skills/public/hip-0010.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
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]>
2026-09-11 00:27:59 -07:00

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&#x27;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 &amp; 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: &quot;2.0&quot;;
method: &quot;tools/register&quot;;
params: {
name: string;
description: string;
input_schema: JSONSchema;
output_schema: JSONSchema;
permissions: Permission[];
};
}
// Tool Execution
interface ToolExecution {
jsonrpc: &quot;2.0&quot;;
method: &quot;tools/execute&quot;;
params: {
tool: string;
arguments: any;
context?: Context;
};
}
// Context Update
interface ContextUpdate {
jsonrpc: &quot;2.0&quot;;
method: &quot;context/update&quot;;
params: {
entries: ContextEntry[];
merge_strategy: &quot;replace&quot; | &quot;merge&quot; | &quot;append&quot;;
};
}</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:
&quot;&quot;&quot;
MCP server implementation for Hanzo
&quot;&quot;&quot;
def __init__(self):
self.tools = {}
self.contexts = {}
self.sessions = {}
async def handle_request(self, request):
&quot;&quot;&quot;Route JSON-RPC requests&quot;&quot;&quot;
if request.method == &quot;tools/list&quot;:
return self.list_tools()
elif request.method == &quot;tools/execute&quot;:
return await self.execute_tool(request.params)
elif request.method == &quot;context/get&quot;:
return self.get_context(request.params)
elif request.method == &quot;context/update&quot;:
return self.update_context(request.params)
async def execute_tool(self, params):
&quot;&quot;&quot;Execute tool with sandboxing&quot;&quot;&quot;
tool = self.tools[params.tool]
# Validate permissions
if not self.check_permissions(tool, params.session_id):
raise PermissionError(f&quot;Tool {tool.name} not authorized&quot;)
# Sandbox execution
sandbox = ToolSandbox(
memory_limit=&quot;512MB&quot;,
cpu_limit=&quot;1 core&quot;,
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&#x27;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=&quot;definition&quot;, file=&quot;main.go&quot;, line=42, character=15)
# -&gt; Starts gopls if not running
# -&gt; Returns: {&quot;file&quot;: &quot;handler.go&quot;, &quot;line&quot;: 10, &quot;character&quot;: 5}
lsp(action=&quot;references&quot;, file=&quot;auth.py&quot;, line=20, character=8)
# -&gt; Starts pyright if not running
# -&gt; Returns: [{&quot;file&quot;: &quot;auth.py&quot;, &quot;line&quot;: 20}, {&quot;file&quot;: &quot;test_auth.py&quot;, &quot;line&quot;: 5}, ...]
lsp(action=&quot;diagnostics&quot;, file=&quot;server.ts&quot;)
# -&gt; Returns: [{&quot;line&quot;: 15, &quot;message&quot;: &quot;Type &#x27;string&#x27; is not assignable to type &#x27;number&#x27;&quot;, &quot;severity&quot;: &quot;error&quot;}]</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(&quot;async def&quot;, &quot;./src&quot;, line_number=True)
# Find all struct definitions in Go
ast(&quot;type.*struct&quot;, &quot;./pkg&quot;, line_number=True)
# Find all test functions
ast(&quot;func Test&quot;, &quot;./tests&quot;)
# Find all React components (capitalized function exports)
ast(&quot;export.*function [A-Z]&quot;, &quot;./components&quot;)</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(&#x27;https://api.hanzo.ai/search&#x27;, {
method: &#x27;POST&#x27;,
headers: {
&#x27;Content-Type&#x27;: &#x27;application/json&#x27;,
&#x27;Authorization&#x27;: `Bearer ${process.env.HANZO_API_KEY}`
},
body: JSON.stringify({ query, limit: max_results })
});
const data = await response.json();
return {
results: data.results.map(r =&gt; ({
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):
&quot;&quot;&quot;Execute code in sandboxed environment&quot;&quot;&quot;
# Create temporary file
with tempfile.NamedTemporaryFile(
mode=&#x27;w&#x27;,
suffix=_get_extension(language),
delete=False
) as f:
f.write(code)
temp_file = f.name
try:
# Execute based on language
if language == &quot;python&quot;:
result = subprocess.run(
[&quot;python&quot;, temp_file],
capture_output=True,
text=True,
timeout=timeout
)
elif language == &quot;javascript&quot;:
result = subprocess.run(
[&quot;node&quot;, temp_file],
capture_output=True,
text=True,
timeout=timeout
)
else:
raise ValueError(f&quot;Unsupported language: {language}&quot;)
return {
&quot;stdout&quot;: result.stdout,
&quot;stderr&quot;: result.stderr,
&quot;returncode&quot;: result.returncode
}
finally:
os.unlink(temp_file)</code></pre>
<h3>Context Management</h3>
<pre><code class="lang-python">class MCPContext:
&quot;&quot;&quot;
Manages context across tool executions
&quot;&quot;&quot;
def __init__(self):
self.entries = {}
self.history = []
self.metadata = {}
def add_entry(self, key: str, value: Any, type: str = &quot;text&quot;):
&quot;&quot;&quot;Add context entry&quot;&quot;&quot;
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):
&quot;&quot;&quot;Retrieve relevant context for query&quot;&quot;&quot;
# 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)
{
&quot;mcpServers&quot;: {
&quot;hanzo&quot;: {
&quot;command&quot;: &quot;hanzo-mcp&quot;,
&quot;args&quot;: [&quot;serve&quot;],
&quot;env&quot;: {
&quot;HANZO_API_KEY&quot;: &quot;sk-hanzo-...&quot;
}
}
}
}</code></pre>
<h3>Security Model</h3>
<pre><code class="lang-python">class MCPSecurity:
&quot;&quot;&quot;
Security layer for MCP
&quot;&quot;&quot;
def __init__(self):
self.permissions = PermissionManager()
self.sandbox = Sandbox()
self.audit = AuditLogger()
def check_permission(self, tool: str, action: str, session: Session):
&quot;&quot;&quot;Check if action is permitted&quot;&quot;&quot;
# 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(&quot;ws://localhost:3000/mcp&quot;)
# Register custom tool
@client.tool(
name=&quot;calculator&quot;,
description=&quot;Perform calculations&quot;
)
async def calculator(expression: str) -&gt; float:
return eval(expression) # Simplified example
# Use in agent
result = await client.execute_tool(
&quot;web_search&quot;,
{&quot;query&quot;: &quot;Hanzo AI&quot;}
)</code></pre>
<h4>TypeScript SDK</h4>
<pre><code class="lang-typescript">import { MCPClient, Tool } from &#x27;@hanzoai/mcp&#x27;;
// Initialize client
const client = new MCPClient(&#x27;ws://localhost:3000/mcp&#x27;);
// Register tool
client.registerTool({
name: &#x27;calculator&#x27;,
description: &#x27;Perform calculations&#x27;,
handler: async (expression: string) =&gt; {
return eval(expression); // Simplified
}
});
// Execute tool
const result = await client.executeTool(&#x27;web_search&#x27;, {
query: &#x27;Hanzo AI&#x27;
});</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(&quot;127.0.0.1:3000&quot;).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: &quot;exec&quot;.to_string(),
command: Some(Value::String(&quot;echo hello&quot;.to_string())),
..Default::default()
};
let result = tool.execute(args).await?;
let json: serde_json::Value = serde_json::from_str(&amp;result)?;
println!(&quot;stdout: {}&quot;, json[&quot;stdout&quot;]);</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(&quot;class UserService&quot;);
assert!(modalities.contains(&amp;SearchModality::Ast));
assert!(modalities.contains(&amp;SearchModality::Text));
// AST search with tree-sitter
let searcher = AstSearcher::new();
let results = searcher
.search(&quot;handleClick&quot;, path, Some(&quot;typescript&quot;), 10)
.await?;</code></pre>
<p><strong>Cargo.toml:</strong></p>
<pre><code class="lang-toml">[dependencies]
hanzo-mcp = &quot;0.12&quot;
# Optional features
[features]
default = []
vector-store = [&quot;qdrant-client&quot;]
computer-control = [&quot;enigo&quot;, &quot;screenshots&quot;]</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>