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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user