mirror of
https://github.com/hanzoai/python-sdk.git
synced 2026-10-23 20:23:00 +00:00
docs: replace all placeholder content with real documentation
MCP docs: - quickstart.md - Installation, basic usage, transport modes - configuration.md - CLI options, env vars, config files - vscode.md - VS Code, Cursor, Windsurf integration Agent SDK docs: - agents.md - Creating and configuring agents - running_agents.md - Runner, RunConfig, async/sync - tools.md - Function tools, context, custom tools - guardrails.md - Input/output validation - handoffs.md - Agent delegation patterns - streaming.md - Stream events and responses - tracing.md - Observability and debugging - context.md - Mutable run context - config.md - RunConfig and ModelSettings - results.md - RunResult, items, usage - models.md - Providers and model selection - multi_agent.md - Complex multi-agent patterns
This commit is contained in:
+224
-2
@@ -1,2 +1,224 @@
|
||||
# configuration
|
||||
Documentation coming soon.
|
||||
# MCP Configuration
|
||||
|
||||
Comprehensive configuration options for hanzo-mcp.
|
||||
|
||||
## Configuration Sources
|
||||
|
||||
Configuration is loaded in order of precedence (highest first):
|
||||
|
||||
1. CLI arguments
|
||||
2. Environment variables
|
||||
3. Project config (`.hanzo/config.json`)
|
||||
4. Global config (`~/.config/hanzo/mcp-settings.json`)
|
||||
5. Default settings
|
||||
|
||||
## CLI Options
|
||||
|
||||
```bash
|
||||
hanzo-mcp [OPTIONS]
|
||||
|
||||
Options:
|
||||
--transport [stdio|sse] Transport mode (default: stdio)
|
||||
--host TEXT Host for SSE server (default: 127.0.0.1)
|
||||
--port INTEGER Port for SSE server (default: 8888)
|
||||
--allow-path PATH Allowed file system paths (repeatable)
|
||||
--project-path PATH Project paths for context (repeatable)
|
||||
--project-dir PATH Project root directory
|
||||
--command-timeout FLOAT Command timeout in seconds (default: 30)
|
||||
--disable-write-tools Disable file write operations
|
||||
--disable-search-tools Disable search operations
|
||||
--install Install Claude Desktop configuration
|
||||
--dev Enable development mode
|
||||
--version Show version
|
||||
--help Show help
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Core Settings
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `HANZO_MCP_TRANSPORT` | `stdio` | Transport mode |
|
||||
| `HANZO_MCP_HOST` | `127.0.0.1` | SSE server host |
|
||||
| `HANZO_MCP_PORT` | `8888` | SSE server port |
|
||||
| `HANZO_AUTO_BACKGROUND_TIMEOUT` | `30` | Command auto-background timeout (seconds) |
|
||||
| `HANZO_DEFAULT_SHELL` | `zsh` | Default shell for commands |
|
||||
|
||||
### Agent Settings
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `HANZO_AGENT_MODEL` | - | Default model for agent tools |
|
||||
| `HANZO_AGENT_API_KEY` | - | API key for agent |
|
||||
| `HANZO_AGENT_BASE_URL` | - | Custom API base URL |
|
||||
| `HANZO_AGENT_MAX_ITERATIONS` | `10` | Max agent iterations |
|
||||
| `HANZO_AGENT_MAX_TOOL_USES` | `30` | Max tool uses per run |
|
||||
|
||||
### LLM API Keys
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `OPENAI_API_KEY` | OpenAI API key |
|
||||
| `ANTHROPIC_API_KEY` | Anthropic API key |
|
||||
| `TOGETHER_API_KEY` | Together AI API key |
|
||||
| `GROQ_API_KEY` | Groq API key |
|
||||
|
||||
## Config File Format
|
||||
|
||||
### Global Config
|
||||
|
||||
Location: `~/.config/hanzo/mcp-settings.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"server": {
|
||||
"name": "hanzo-mcp",
|
||||
"host": "127.0.0.1",
|
||||
"port": 8888,
|
||||
"transport": "stdio"
|
||||
},
|
||||
"tools": {
|
||||
"command_timeout": 30,
|
||||
"disable_write_tools": false,
|
||||
"disable_search_tools": false
|
||||
},
|
||||
"paths": {
|
||||
"allowed": ["~"],
|
||||
"project": []
|
||||
},
|
||||
"agent": {
|
||||
"enabled": true,
|
||||
"model": "claude-3-5-sonnet-20241022",
|
||||
"max_iterations": 10,
|
||||
"max_tool_uses": 30
|
||||
},
|
||||
"mcp_servers": []
|
||||
}
|
||||
```
|
||||
|
||||
### Project Config
|
||||
|
||||
Location: `.hanzo/config.json` in project root
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-project",
|
||||
"enabled_tools": {
|
||||
"browser": true,
|
||||
"database": false
|
||||
},
|
||||
"disabled_tools": ["vector"],
|
||||
"rules": [
|
||||
"Use TypeScript for all new files",
|
||||
"Follow existing code style"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Tool Configuration
|
||||
|
||||
### Enable/Disable Tools
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"enabled": ["shell", "filesystem", "memory", "reasoning"],
|
||||
"disabled": ["browser", "database", "vector"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Tool-Specific Settings
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"shell": {
|
||||
"default_shell": "zsh",
|
||||
"timeout": 30
|
||||
},
|
||||
"browser": {
|
||||
"headless": true,
|
||||
"default_viewport": "desktop"
|
||||
},
|
||||
"memory": {
|
||||
"scope": "project"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Security
|
||||
|
||||
### Path Restrictions
|
||||
|
||||
By default, the server restricts file access. Use `--allow-path` to grant access:
|
||||
|
||||
```bash
|
||||
# Allow home directory
|
||||
hanzo-mcp --allow-path ~
|
||||
|
||||
# Allow specific project
|
||||
hanzo-mcp --allow-path /path/to/project
|
||||
|
||||
# Allow multiple paths
|
||||
hanzo-mcp --allow-path ~/work --allow-path /tmp
|
||||
```
|
||||
|
||||
### Disable Dangerous Tools
|
||||
|
||||
```bash
|
||||
# Read-only mode
|
||||
hanzo-mcp --disable-write-tools
|
||||
|
||||
# No search (for sensitive codebases)
|
||||
hanzo-mcp --disable-search-tools
|
||||
```
|
||||
|
||||
## Claude Desktop Integration
|
||||
|
||||
### Auto-Install
|
||||
|
||||
```bash
|
||||
hanzo-mcp --install
|
||||
```
|
||||
|
||||
This creates the configuration at:
|
||||
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
|
||||
- Linux: `~/.config/claude/claude_desktop_config.json`
|
||||
|
||||
### Manual Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"hanzo": {
|
||||
"command": "uvx",
|
||||
"args": ["hanzo-mcp", "--allow-path", "~"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Debugging
|
||||
|
||||
### Enable Verbose Logging
|
||||
|
||||
```bash
|
||||
# SSE mode (logging visible)
|
||||
hanzo-mcp --transport sse
|
||||
|
||||
# Check version and config
|
||||
hanzo-mcp --version
|
||||
```
|
||||
|
||||
### View Running Processes
|
||||
|
||||
Once connected, use the `ps` tool:
|
||||
|
||||
```
|
||||
ps() # List all background processes
|
||||
ps(logs="id") # View process output
|
||||
```
|
||||
|
||||
+117
-2
@@ -1,2 +1,117 @@
|
||||
# quickstart
|
||||
Documentation coming soon.
|
||||
# MCP Quickstart
|
||||
|
||||
Get started with hanzo-mcp in under 5 minutes.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# With pip
|
||||
pip install hanzo-mcp[tools-all]
|
||||
|
||||
# With uv (recommended)
|
||||
uv pip install hanzo-mcp[tools-all]
|
||||
```
|
||||
|
||||
## Running the Server
|
||||
|
||||
### With Claude Code
|
||||
|
||||
```bash
|
||||
# Run directly
|
||||
uvx hanzo-mcp
|
||||
|
||||
# Or with Python
|
||||
python -m hanzo_mcp
|
||||
```
|
||||
|
||||
### With Claude Desktop
|
||||
|
||||
Install the configuration automatically:
|
||||
|
||||
```bash
|
||||
hanzo-mcp --install
|
||||
```
|
||||
|
||||
Or manually add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"hanzo": {
|
||||
"command": "uvx",
|
||||
"args": ["hanzo-mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Restart Claude Desktop after configuration.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
Once running, you have access to 30+ tools:
|
||||
|
||||
### File Operations
|
||||
|
||||
```
|
||||
Read a file: read("/path/to/file.py")
|
||||
Write a file: write("/path/to/file.py", "content")
|
||||
Edit a file: edit("/path/to/file.py", "old", "new")
|
||||
```
|
||||
|
||||
### Command Execution
|
||||
|
||||
```
|
||||
Run command: cmd("ls -la")
|
||||
Run parallel: cmd(["npm install", "cargo build"], parallel=True)
|
||||
```
|
||||
|
||||
### Search
|
||||
|
||||
```
|
||||
Search files: search("pattern", path="./src")
|
||||
Find files: find("*.py", path=".")
|
||||
AST search: ast("def test_", path="./tests")
|
||||
```
|
||||
|
||||
### Memory
|
||||
|
||||
```
|
||||
Store memory: create_memories(["User prefers dark mode"])
|
||||
Recall: recall_memories(["user preferences"])
|
||||
```
|
||||
|
||||
## Transport Modes
|
||||
|
||||
### stdio (default)
|
||||
|
||||
Used by Claude Code and Claude Desktop:
|
||||
|
||||
```bash
|
||||
hanzo-mcp --transport stdio
|
||||
```
|
||||
|
||||
### SSE (Server-Sent Events)
|
||||
|
||||
For web clients and debugging:
|
||||
|
||||
```bash
|
||||
hanzo-mcp --transport sse --port 8888
|
||||
```
|
||||
|
||||
Access at `http://localhost:8888`
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `HANZO_AUTO_BACKGROUND_TIMEOUT` | Auto-background timeout (default: 30s, 0 to disable) |
|
||||
| `HANZO_DEFAULT_SHELL` | Default shell (default: zsh) |
|
||||
| `OPENAI_API_KEY` | For LLM tools |
|
||||
| `ANTHROPIC_API_KEY` | For LLM tools |
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Configuration](configuration.md) - Detailed configuration options
|
||||
- [Tools Reference](../tools/index.md) - All available tools
|
||||
- [VS Code Setup](vscode.md) - IDE integration
|
||||
|
||||
+176
-2
@@ -1,2 +1,176 @@
|
||||
# vscode
|
||||
Documentation coming soon.
|
||||
# VS Code Integration
|
||||
|
||||
Set up hanzo-mcp with VS Code, Cursor, and other MCP-compatible editors.
|
||||
|
||||
## VS Code with Continue
|
||||
|
||||
[Continue](https://continue.dev) is an open-source AI code assistant that supports MCP.
|
||||
|
||||
### Installation
|
||||
|
||||
1. Install Continue extension from VS Code marketplace
|
||||
2. Configure MCP in `~/.continue/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"models": [...],
|
||||
"mcpServers": [
|
||||
{
|
||||
"name": "hanzo",
|
||||
"command": "uvx",
|
||||
"args": ["hanzo-mcp"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
3. Restart VS Code
|
||||
|
||||
## Cursor
|
||||
|
||||
Cursor has built-in MCP support.
|
||||
|
||||
### Configuration
|
||||
|
||||
Add to Cursor settings (`~/.cursor/mcp.json`):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"hanzo": {
|
||||
"command": "uvx",
|
||||
"args": ["hanzo-mcp", "--allow-path", "~"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Windsurf (Codeium)
|
||||
|
||||
### Configuration
|
||||
|
||||
Add to `~/.codeium/windsurf/mcp_config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"hanzo": {
|
||||
"command": "uvx",
|
||||
"args": ["hanzo-mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Generic MCP Client
|
||||
|
||||
For any MCP-compatible client:
|
||||
|
||||
### stdio Transport
|
||||
|
||||
```json
|
||||
{
|
||||
"command": "uvx",
|
||||
"args": ["hanzo-mcp", "--transport", "stdio"]
|
||||
}
|
||||
```
|
||||
|
||||
### SSE Transport
|
||||
|
||||
Start the server:
|
||||
|
||||
```bash
|
||||
hanzo-mcp --transport sse --port 8888
|
||||
```
|
||||
|
||||
Connect to: `http://localhost:8888/sse`
|
||||
|
||||
## Project-Specific Configuration
|
||||
|
||||
Create `.hanzo/config.json` in your project root:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-project",
|
||||
"rules": [
|
||||
"Use TypeScript",
|
||||
"Follow existing patterns"
|
||||
],
|
||||
"enabled_tools": {
|
||||
"shell": true,
|
||||
"browser": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The MCP server will automatically detect and apply project settings.
|
||||
|
||||
## Recommended Extensions
|
||||
|
||||
### VS Code
|
||||
|
||||
- **Continue** - AI assistant with MCP support
|
||||
- **Claude Dev** - Claude integration
|
||||
- **GitLens** - Git integration (works well with hanzo tools)
|
||||
|
||||
### Cursor
|
||||
|
||||
Built-in AI features work with hanzo-mcp out of the box.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Server Not Starting
|
||||
|
||||
```bash
|
||||
# Check if hanzo-mcp is installed
|
||||
uvx hanzo-mcp --version
|
||||
|
||||
# Test manually
|
||||
uvx hanzo-mcp --transport sse --port 8888
|
||||
# Then open http://localhost:8888 in browser
|
||||
```
|
||||
|
||||
### Permission Errors
|
||||
|
||||
Ensure paths are allowed:
|
||||
|
||||
```json
|
||||
{
|
||||
"args": ["hanzo-mcp", "--allow-path", "/path/to/project"]
|
||||
}
|
||||
```
|
||||
|
||||
### Tool Not Available
|
||||
|
||||
Some tools require additional dependencies:
|
||||
|
||||
```bash
|
||||
# Full installation with all tools
|
||||
pip install hanzo-mcp[tools-all]
|
||||
|
||||
# Or specific tools
|
||||
pip install hanzo-mcp[browser] # Playwright
|
||||
pip install hanzo-mcp[llm] # LiteLLM
|
||||
```
|
||||
|
||||
### Logs and Debugging
|
||||
|
||||
For SSE transport, logs appear in terminal. For stdio:
|
||||
|
||||
```bash
|
||||
# Redirect stderr to file
|
||||
hanzo-mcp 2>/tmp/hanzo-mcp.log
|
||||
```
|
||||
|
||||
## Performance Tips
|
||||
|
||||
1. **Use uvx** - Faster startup than pip-installed version
|
||||
2. **Limit paths** - Only allow necessary directories
|
||||
3. **Disable unused tools** - Reduces memory usage
|
||||
4. **Use project config** - Faster tool discovery
|
||||
|
||||
## See Also
|
||||
|
||||
- [Quickstart](quickstart.md) - Getting started
|
||||
- [Configuration](configuration.md) - All configuration options
|
||||
- [Tools Reference](../tools/index.md) - Available tools
|
||||
|
||||
Reference in New Issue
Block a user