mirror of
https://github.com/hanzoai/python-sdk.git
synced 2026-10-23 20:23:00 +00:00
docs(tools): add database, editor, jupyter, mcp, vector tool docs
- database.md: SQL query/search/stats and graph database tools - editor.md: Neovim integration (edit, command, session) - jupyter.md: Notebook read/edit/create/execute operations - mcp-tools.md: MCP server management and configuration - vector.md: Semantic search with vector embeddings
This commit is contained in:
@@ -0,0 +1,235 @@
|
||||
# Database Tools
|
||||
|
||||
The database tools (`hanzo-tools-database`) provide SQL and graph database operations for project-embedded databases.
|
||||
|
||||
## Overview
|
||||
|
||||
Each project can have an embedded SQLite database with tables for metadata, files, and symbols. The database tools also support graph database operations for tracking code relationships.
|
||||
|
||||
## SQL Tools
|
||||
|
||||
### sql_query - Execute SQL Queries
|
||||
|
||||
Execute raw SQL on the project database:
|
||||
|
||||
```python
|
||||
# Read query (default safe mode)
|
||||
sql_query(query="SELECT * FROM files LIMIT 10")
|
||||
|
||||
# Query with specific project
|
||||
sql_query(query="SELECT name, type FROM symbols WHERE type='function'", project_path="/project")
|
||||
|
||||
# Write query (requires read_only=False)
|
||||
sql_query(
|
||||
query="INSERT INTO metadata (key, value) VALUES ('version', '1.0')",
|
||||
read_only=False
|
||||
)
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `query` | str | required | SQL query to execute |
|
||||
| `project_path` | str | cwd | Project path |
|
||||
| `read_only` | bool | `True` | Block write operations |
|
||||
|
||||
#### Database Schema
|
||||
|
||||
Default tables in project databases:
|
||||
|
||||
```sql
|
||||
-- Key-value metadata
|
||||
CREATE TABLE metadata (
|
||||
key TEXT PRIMARY KEY,
|
||||
value TEXT
|
||||
);
|
||||
|
||||
-- File information
|
||||
CREATE TABLE files (
|
||||
path TEXT PRIMARY KEY,
|
||||
content TEXT,
|
||||
modified_at TEXT
|
||||
);
|
||||
|
||||
-- Code symbols
|
||||
CREATE TABLE symbols (
|
||||
id INTEGER PRIMARY KEY,
|
||||
name TEXT,
|
||||
type TEXT, -- function, class, variable
|
||||
file_path TEXT,
|
||||
line_number INTEGER
|
||||
);
|
||||
```
|
||||
|
||||
### sql_search - Full-Text Search
|
||||
|
||||
Search database content with text matching:
|
||||
|
||||
```python
|
||||
sql_search(pattern="error", table="files")
|
||||
sql_search(pattern="TODO", column="content")
|
||||
```
|
||||
|
||||
### sql_stats - Database Statistics
|
||||
|
||||
Get database statistics and schema info:
|
||||
|
||||
```python
|
||||
sql_stats()
|
||||
sql_stats(project_path="/project")
|
||||
```
|
||||
|
||||
## Graph Tools
|
||||
|
||||
The graph database stores relationships between code entities (files, functions, classes).
|
||||
|
||||
### graph_add - Add Nodes/Edges
|
||||
|
||||
Add nodes and edges to the graph:
|
||||
|
||||
```python
|
||||
# Add a node
|
||||
graph_add(node_id="main.py", node_type="file")
|
||||
|
||||
# Add an edge
|
||||
graph_add(
|
||||
source="main.py",
|
||||
target="utils.py",
|
||||
relationship="imports"
|
||||
)
|
||||
|
||||
# Add with properties
|
||||
graph_add(
|
||||
node_id="MyClass",
|
||||
node_type="class",
|
||||
properties={"methods": 5, "lines": 120}
|
||||
)
|
||||
```
|
||||
|
||||
### graph_remove - Remove from Graph
|
||||
|
||||
Remove nodes or edges:
|
||||
|
||||
```python
|
||||
graph_remove(node_id="deprecated_file.py")
|
||||
graph_remove(source="a.py", target="b.py", relationship="imports")
|
||||
```
|
||||
|
||||
### graph_query - Query Graph Database
|
||||
|
||||
Execute graph traversal queries:
|
||||
|
||||
```python
|
||||
# Find neighbors
|
||||
graph_query(query="neighbors", node_id="main.py")
|
||||
|
||||
# Find path between nodes
|
||||
graph_query(query="path", node_id="main.py", target_id="utils.py")
|
||||
|
||||
# Get subgraph
|
||||
graph_query(query="subgraph", node_id="MyClass", depth=3)
|
||||
|
||||
# Find ancestors (nodes pointing TO this node)
|
||||
graph_query(query="ancestors", node_id="error_handler", relationship="calls")
|
||||
|
||||
# Find descendants (nodes this node points TO)
|
||||
graph_query(query="descendants", node_id="BaseClass", relationship="inherits")
|
||||
|
||||
# Find all connected nodes
|
||||
graph_query(query="connected", node_id="main.py", direction="both")
|
||||
```
|
||||
|
||||
#### Query Types
|
||||
|
||||
| Query | Description | Required Params |
|
||||
|-------|-------------|-----------------|
|
||||
| `neighbors` | Direct neighbors | `node_id` |
|
||||
| `path` | Shortest path | `node_id`, `target_id` |
|
||||
| `subgraph` | Subgraph around node | `node_id` |
|
||||
| `connected` | All connected nodes | `node_id` |
|
||||
| `ancestors` | Incoming edges | `node_id` |
|
||||
| `descendants` | Outgoing edges | `node_id` |
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `query` | str | required | Query type |
|
||||
| `node_id` | str | - | Starting node |
|
||||
| `target_id` | str | - | Target node (for path) |
|
||||
| `depth` | int | `2` | Max traversal depth |
|
||||
| `relationship` | str | - | Filter by edge type |
|
||||
| `node_type` | str | - | Filter by node type |
|
||||
| `direction` | str | `both` | `both`, `incoming`, `outgoing` |
|
||||
|
||||
### graph_search - Search Graph
|
||||
|
||||
Search for nodes by properties:
|
||||
|
||||
```python
|
||||
graph_search(pattern="Service", node_type="class")
|
||||
graph_search(pattern="test_*", relationship="depends_on")
|
||||
```
|
||||
|
||||
### graph_stats - Graph Statistics
|
||||
|
||||
Get graph statistics:
|
||||
|
||||
```python
|
||||
graph_stats()
|
||||
# Returns: nodes count, edges count, relationship types, node types
|
||||
```
|
||||
|
||||
## Relationship Types
|
||||
|
||||
Common relationship types in code graphs:
|
||||
|
||||
| Relationship | Description |
|
||||
|--------------|-------------|
|
||||
| `imports` | File imports another file |
|
||||
| `calls` | Function calls another function |
|
||||
| `inherits` | Class inherits from another |
|
||||
| `implements` | Class implements interface |
|
||||
| `depends_on` | General dependency |
|
||||
| `contains` | File contains symbol |
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install hanzo-tools-database
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Use Read-Only Mode
|
||||
|
||||
```python
|
||||
# Default: safe read-only queries
|
||||
sql_query(query="SELECT * FROM files")
|
||||
|
||||
# Only disable when necessary
|
||||
sql_query(query="UPDATE ...", read_only=False)
|
||||
```
|
||||
|
||||
### 2. Filter Graph Queries
|
||||
|
||||
```python
|
||||
# Avoid unbounded traversals
|
||||
graph_query(query="subgraph", node_id="main.py", depth=2)
|
||||
|
||||
# Filter by relationship type
|
||||
graph_query(query="neighbors", node_id="func", relationship="calls")
|
||||
```
|
||||
|
||||
### 3. Index Before Querying
|
||||
|
||||
Ensure the project is indexed before running database queries:
|
||||
|
||||
```python
|
||||
# Index project first
|
||||
index(path="/project")
|
||||
|
||||
# Then query
|
||||
sql_query(query="SELECT * FROM symbols WHERE type='function'")
|
||||
```
|
||||
@@ -0,0 +1,176 @@
|
||||
# Editor Tools
|
||||
|
||||
The editor tools (`hanzo-tools-editor`) provide integration with external code editors, currently focused on Neovim.
|
||||
|
||||
## Overview
|
||||
|
||||
These tools enable opening files in your preferred editor with precise cursor positioning, split modes, and session management.
|
||||
|
||||
## Neovim Integration
|
||||
|
||||
### neovim_edit - Open Files
|
||||
|
||||
Open files in Neovim with advanced options:
|
||||
|
||||
```python
|
||||
# Basic file open
|
||||
neovim_edit(file_path="main.py")
|
||||
|
||||
# Open at specific line
|
||||
neovim_edit(file_path="main.py", line_number=42)
|
||||
|
||||
# Open at specific line and column
|
||||
neovim_edit(file_path="main.py", line_number=42, column_number=10)
|
||||
|
||||
# Open in read-only mode
|
||||
neovim_edit(file_path="config.json", read_only=True)
|
||||
|
||||
# Open in vertical split
|
||||
neovim_edit(file_path="test.py", split="vsplit")
|
||||
|
||||
# Open in new tab
|
||||
neovim_edit(file_path="README.md", split="tab")
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `file_path` | str | required | Path to the file |
|
||||
| `line_number` | int | - | Line to jump to |
|
||||
| `column_number` | int | - | Column to jump to |
|
||||
| `read_only` | bool | `False` | Open in view mode |
|
||||
| `split` | str | - | `vsplit`, `split`, or `tab` |
|
||||
| `wait` | bool | `True` | Wait for editor to close |
|
||||
| `in_terminal` | bool | `True` | Open in terminal window |
|
||||
|
||||
#### Split Modes
|
||||
|
||||
| Mode | Description |
|
||||
|------|-------------|
|
||||
| `vsplit` | Vertical split (side by side) |
|
||||
| `split` | Horizontal split (top/bottom) |
|
||||
| `tab` | New tab |
|
||||
|
||||
### neovim_command - Execute Commands
|
||||
|
||||
Execute Neovim Ex commands:
|
||||
|
||||
```python
|
||||
# Run command in current buffer
|
||||
neovim_command(command=":w")
|
||||
|
||||
# Search and replace
|
||||
neovim_command(command=":%s/old/new/g")
|
||||
|
||||
# Run Lua code
|
||||
neovim_command(command=":lua print('Hello')")
|
||||
|
||||
# Source configuration
|
||||
neovim_command(command=":source ~/.config/nvim/init.lua")
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `command` | str | required | Ex command to execute |
|
||||
| `file_path` | str | - | File to run command on |
|
||||
|
||||
### neovim_session - Manage Sessions
|
||||
|
||||
Manage Neovim sessions for persistent workspaces:
|
||||
|
||||
```python
|
||||
# Save current session
|
||||
neovim_session(action="save", name="project-alpha")
|
||||
|
||||
# Load session
|
||||
neovim_session(action="load", name="project-alpha")
|
||||
|
||||
# List sessions
|
||||
neovim_session(action="list")
|
||||
|
||||
# Delete session
|
||||
neovim_session(action="delete", name="old-session")
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `action` | str | required | `save`, `load`, `list`, `delete` |
|
||||
| `name` | str | - | Session name |
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Basic install
|
||||
pip install hanzo-tools-editor
|
||||
|
||||
# With Neovim support
|
||||
pip install hanzo-tools-editor[neovim]
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Neovim** must be installed and available in PATH
|
||||
- Installation varies by platform:
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install neovim
|
||||
|
||||
# Ubuntu/Debian
|
||||
sudo apt install neovim
|
||||
|
||||
# Arch Linux
|
||||
sudo pacman -S neovim
|
||||
|
||||
# Windows (Chocolatey)
|
||||
choco install neovim
|
||||
```
|
||||
|
||||
## Terminal Integration
|
||||
|
||||
On macOS, the tool integrates with:
|
||||
- **iTerm2** (preferred if installed)
|
||||
- **Terminal.app** (fallback)
|
||||
|
||||
On Linux:
|
||||
- **gnome-terminal**
|
||||
- **xterm** (fallback)
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Use Line/Column for Error Navigation
|
||||
|
||||
```python
|
||||
# Jump directly to error location
|
||||
neovim_edit(file_path="src/main.py", line_number=42, column_number=15)
|
||||
```
|
||||
|
||||
### 2. Use Splits for Comparison
|
||||
|
||||
```python
|
||||
# Open original and new file side by side
|
||||
neovim_edit(file_path="original.py")
|
||||
neovim_edit(file_path="modified.py", split="vsplit")
|
||||
```
|
||||
|
||||
### 3. Use Sessions for Projects
|
||||
|
||||
```python
|
||||
# Save state when switching projects
|
||||
neovim_session(action="save", name="current-work")
|
||||
|
||||
# Restore when returning
|
||||
neovim_session(action="load", name="current-work")
|
||||
```
|
||||
|
||||
### 4. Read-Only for Config Files
|
||||
|
||||
```python
|
||||
# Prevent accidental changes
|
||||
neovim_edit(file_path="/etc/config", read_only=True)
|
||||
```
|
||||
@@ -0,0 +1,213 @@
|
||||
# Jupyter Tools
|
||||
|
||||
The Jupyter tools (`hanzo-tools-jupyter`) provide comprehensive Jupyter notebook operations including reading, editing, creating, and executing notebooks.
|
||||
|
||||
## Overview
|
||||
|
||||
Work with `.ipynb` files programmatically - read cell contents, modify cells, create new notebooks, and execute code cells.
|
||||
|
||||
## jupyter - Unified Notebook Tool
|
||||
|
||||
The unified `jupyter` tool handles all notebook operations through an action parameter.
|
||||
|
||||
### Read Notebook
|
||||
|
||||
```python
|
||||
# Read entire notebook
|
||||
jupyter(notebook_path="analysis.ipynb")
|
||||
|
||||
# Read specific cell by index
|
||||
jupyter(notebook_path="analysis.ipynb", cell_index=2)
|
||||
|
||||
# Read specific cell by ID
|
||||
jupyter(notebook_path="analysis.ipynb", cell_id="abc123")
|
||||
```
|
||||
|
||||
### Edit Notebook
|
||||
|
||||
```python
|
||||
# Replace cell content
|
||||
jupyter(
|
||||
action="edit",
|
||||
notebook_path="analysis.ipynb",
|
||||
cell_index=0,
|
||||
source="print('Hello, World!')"
|
||||
)
|
||||
|
||||
# Insert new cell
|
||||
jupyter(
|
||||
action="edit",
|
||||
notebook_path="analysis.ipynb",
|
||||
edit_mode="insert",
|
||||
cell_index=2,
|
||||
cell_type="code",
|
||||
source="import pandas as pd"
|
||||
)
|
||||
|
||||
# Delete cell
|
||||
jupyter(
|
||||
action="edit",
|
||||
notebook_path="analysis.ipynb",
|
||||
edit_mode="delete",
|
||||
cell_index=3
|
||||
)
|
||||
|
||||
# Change cell type
|
||||
jupyter(
|
||||
action="edit",
|
||||
notebook_path="analysis.ipynb",
|
||||
cell_index=0,
|
||||
cell_type="markdown",
|
||||
source="# Analysis Results"
|
||||
)
|
||||
```
|
||||
|
||||
### Create Notebook
|
||||
|
||||
```python
|
||||
# Create empty notebook
|
||||
jupyter(action="create", notebook_path="new_analysis.ipynb")
|
||||
```
|
||||
|
||||
### Delete Notebook
|
||||
|
||||
```python
|
||||
# Delete entire notebook
|
||||
jupyter(action="delete", notebook_path="old.ipynb")
|
||||
|
||||
# Delete specific cell
|
||||
jupyter(action="delete", notebook_path="analysis.ipynb", cell_index=5)
|
||||
```
|
||||
|
||||
### Execute Notebook
|
||||
|
||||
```python
|
||||
# Execute all cells
|
||||
jupyter(action="execute", notebook_path="analysis.ipynb")
|
||||
|
||||
# Execute with custom timeout
|
||||
jupyter(action="execute", notebook_path="analysis.ipynb", timeout=600)
|
||||
|
||||
# Execute with specific kernel
|
||||
jupyter(action="execute", notebook_path="analysis.ipynb", kernel_name="python3")
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `action` | str | `read` | `read`, `edit`, `create`, `delete`, `execute` |
|
||||
| `notebook_path` | str | required | Path to .ipynb file |
|
||||
| `cell_id` | str | - | Cell ID for targeted operations |
|
||||
| `cell_index` | int | - | Cell index (0-based) |
|
||||
| `cell_type` | str | - | `code` or `markdown` |
|
||||
| `source` | str | - | New cell content |
|
||||
| `edit_mode` | str | `replace` | `replace`, `insert`, `delete` |
|
||||
| `timeout` | int | `600` | Execution timeout (seconds) |
|
||||
| `kernel_name` | str | `python3` | Jupyter kernel to use |
|
||||
|
||||
## Edit Modes
|
||||
|
||||
| Mode | Description |
|
||||
|------|-------------|
|
||||
| `replace` | Replace existing cell content |
|
||||
| `insert` | Insert new cell at index |
|
||||
| `delete` | Delete cell at index |
|
||||
|
||||
## Cell Types
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| `code` | Executable Python code |
|
||||
| `markdown` | Markdown text/documentation |
|
||||
|
||||
## Output Format
|
||||
|
||||
When reading notebooks, output includes:
|
||||
|
||||
```
|
||||
Notebook with 5 cells
|
||||
==================================================
|
||||
|
||||
Cell 0 (code)
|
||||
ID: abc123
|
||||
----------------------------------------
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
|
||||
Outputs:
|
||||
[Out 1]: <module 'pandas'>
|
||||
|
||||
Cell 1 (markdown)
|
||||
----------------------------------------
|
||||
# Data Analysis
|
||||
This notebook analyzes...
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install hanzo-tools-jupyter
|
||||
```
|
||||
|
||||
For notebook execution, also install:
|
||||
|
||||
```bash
|
||||
pip install nbclient
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `nbformat` - Notebook file format handling
|
||||
- `nbclient` (optional) - For notebook execution
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Use Cell IDs for Stability
|
||||
|
||||
```python
|
||||
# Prefer cell IDs over indices when available
|
||||
jupyter(action="edit", notebook_path="nb.ipynb", cell_id="stable-id", source="...")
|
||||
```
|
||||
|
||||
### 2. Validate Before Executing
|
||||
|
||||
```python
|
||||
# Read first to check cell contents
|
||||
result = jupyter(notebook_path="analysis.ipynb")
|
||||
print(result)
|
||||
|
||||
# Then execute
|
||||
jupyter(action="execute", notebook_path="analysis.ipynb")
|
||||
```
|
||||
|
||||
### 3. Set Appropriate Timeouts
|
||||
|
||||
```python
|
||||
# Long-running analysis
|
||||
jupyter(action="execute", notebook_path="ml_training.ipynb", timeout=3600)
|
||||
```
|
||||
|
||||
### 4. Use Markdown for Documentation
|
||||
|
||||
```python
|
||||
# Add documentation cells
|
||||
jupyter(
|
||||
action="edit",
|
||||
notebook_path="analysis.ipynb",
|
||||
edit_mode="insert",
|
||||
cell_index=0,
|
||||
cell_type="markdown",
|
||||
source="# Analysis Report\n\nGenerated by automated pipeline."
|
||||
)
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
Common errors and solutions:
|
||||
|
||||
| Error | Cause | Solution |
|
||||
|-------|-------|----------|
|
||||
| `nbclient not installed` | Missing execution dependency | `pip install nbclient` |
|
||||
| `Cell index out of range` | Invalid cell index | Check notebook length first |
|
||||
| `Kernel not found` | Invalid kernel name | Use `python3` or check available kernels |
|
||||
@@ -0,0 +1,253 @@
|
||||
# MCP Management Tools
|
||||
|
||||
The MCP tools (`hanzo-tools-mcp`) provide management capabilities for MCP (Model Context Protocol) servers and configurations.
|
||||
|
||||
## Overview
|
||||
|
||||
These tools allow you to manage MCP server connections, add new servers, remove servers, and monitor statistics.
|
||||
|
||||
## mcp - Server Management
|
||||
|
||||
The main MCP management tool:
|
||||
|
||||
```python
|
||||
# List configured MCP servers
|
||||
mcp(action="list")
|
||||
|
||||
# Get server status
|
||||
mcp(action="status")
|
||||
|
||||
# Get specific server info
|
||||
mcp(action="info", server_name="filesystem")
|
||||
|
||||
# Restart a server
|
||||
mcp(action="restart", server_name="browser")
|
||||
```
|
||||
|
||||
### Actions
|
||||
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| `list` | List all configured servers |
|
||||
| `status` | Show running status of servers |
|
||||
| `info` | Get detailed server information |
|
||||
| `restart` | Restart a specific server |
|
||||
|
||||
## mcp_add - Add Servers
|
||||
|
||||
Add new MCP server configurations:
|
||||
|
||||
```python
|
||||
# Add stdio server
|
||||
mcp_add(
|
||||
name="my-server",
|
||||
command="uvx my-mcp-server",
|
||||
transport="stdio"
|
||||
)
|
||||
|
||||
# Add SSE server
|
||||
mcp_add(
|
||||
name="remote-server",
|
||||
url="http://localhost:8080/sse",
|
||||
transport="sse"
|
||||
)
|
||||
|
||||
# Add with environment variables
|
||||
mcp_add(
|
||||
name="api-server",
|
||||
command="node server.js",
|
||||
env={"API_KEY": "secret123"}
|
||||
)
|
||||
|
||||
# Add with arguments
|
||||
mcp_add(
|
||||
name="custom-server",
|
||||
command="python",
|
||||
args=["-m", "my_mcp", "--port", "9000"]
|
||||
)
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `name` | str | required | Server identifier |
|
||||
| `command` | str | - | Command to spawn server |
|
||||
| `url` | str | - | URL for SSE/HTTP transport |
|
||||
| `transport` | str | `stdio` | `stdio`, `sse`, `http` |
|
||||
| `args` | list | - | Additional command arguments |
|
||||
| `env` | dict | - | Environment variables |
|
||||
|
||||
## mcp_remove - Remove Servers
|
||||
|
||||
Remove MCP server configurations:
|
||||
|
||||
```python
|
||||
# Remove by name
|
||||
mcp_remove(name="old-server")
|
||||
|
||||
# Remove with confirmation
|
||||
mcp_remove(name="important-server", confirm=True)
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `name` | str | required | Server to remove |
|
||||
| `confirm` | bool | `False` | Require confirmation |
|
||||
|
||||
## mcp_stats - Statistics
|
||||
|
||||
Get MCP usage statistics:
|
||||
|
||||
```python
|
||||
# Overall statistics
|
||||
mcp_stats()
|
||||
|
||||
# Per-server statistics
|
||||
mcp_stats(server_name="filesystem")
|
||||
|
||||
# Stats for time period
|
||||
mcp_stats(period="1h")
|
||||
```
|
||||
|
||||
### Output
|
||||
|
||||
```
|
||||
MCP Statistics
|
||||
==============
|
||||
|
||||
Servers: 5 configured, 4 running
|
||||
|
||||
Tool Calls (last hour):
|
||||
filesystem: 142 calls
|
||||
browser: 38 calls
|
||||
shell: 256 calls
|
||||
memory: 24 calls
|
||||
|
||||
Errors: 3 total
|
||||
- filesystem: 1 (permission denied)
|
||||
- browser: 2 (timeout)
|
||||
```
|
||||
|
||||
## Transport Types
|
||||
|
||||
| Transport | Use Case | Requirements |
|
||||
|-----------|----------|--------------|
|
||||
| `stdio` | Local servers | Executable command |
|
||||
| `sse` | Remote servers | HTTP endpoint |
|
||||
| `http` | Streamable HTTP | HTTP endpoint |
|
||||
|
||||
### stdio Transport
|
||||
|
||||
Spawns server as subprocess:
|
||||
|
||||
```python
|
||||
mcp_add(
|
||||
name="local",
|
||||
command="uvx hanzo-mcp",
|
||||
transport="stdio"
|
||||
)
|
||||
```
|
||||
|
||||
### SSE Transport
|
||||
|
||||
Connects to Server-Sent Events endpoint:
|
||||
|
||||
```python
|
||||
mcp_add(
|
||||
name="remote",
|
||||
url="http://api.example.com/mcp/sse",
|
||||
transport="sse"
|
||||
)
|
||||
```
|
||||
|
||||
### HTTP Transport
|
||||
|
||||
Streamable HTTP transport:
|
||||
|
||||
```python
|
||||
mcp_add(
|
||||
name="http-server",
|
||||
url="http://localhost:8080/mcp",
|
||||
transport="http"
|
||||
)
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install hanzo-tools-mcp
|
||||
```
|
||||
|
||||
## Configuration File
|
||||
|
||||
MCP servers are typically configured in:
|
||||
- `~/.config/hanzo/mcp.json` (global)
|
||||
- `.hanzo/mcp.json` (project-local)
|
||||
|
||||
Example configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"filesystem": {
|
||||
"command": "uvx hanzo-tools-fs",
|
||||
"transport": "stdio"
|
||||
},
|
||||
"browser": {
|
||||
"command": "uvx hanzo-tools-browser",
|
||||
"transport": "stdio",
|
||||
"env": {
|
||||
"BROWSER_HEADLESS": "true"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Use Environment Variables for Secrets
|
||||
|
||||
```python
|
||||
mcp_add(
|
||||
name="api-server",
|
||||
command="my-server",
|
||||
env={"API_KEY": "${API_KEY}"} # Reference from environment
|
||||
)
|
||||
```
|
||||
|
||||
### 2. Group Related Servers
|
||||
|
||||
Organize servers by function:
|
||||
|
||||
```python
|
||||
# Development servers
|
||||
mcp_add(name="dev-db", command="...")
|
||||
mcp_add(name="dev-cache", command="...")
|
||||
|
||||
# Production servers (separate config)
|
||||
mcp_add(name="prod-db", command="...", env={"ENV": "production"})
|
||||
```
|
||||
|
||||
### 3. Monitor Statistics
|
||||
|
||||
```python
|
||||
# Regular health checks
|
||||
stats = mcp_stats()
|
||||
if stats.error_count > threshold:
|
||||
alert("MCP errors detected")
|
||||
```
|
||||
|
||||
### 4. Use Local Config for Projects
|
||||
|
||||
```python
|
||||
# Project-specific servers in .hanzo/mcp.json
|
||||
mcp_add(
|
||||
name="project-specific",
|
||||
command="./scripts/mcp-server.sh",
|
||||
config_path=".hanzo/mcp.json"
|
||||
)
|
||||
```
|
||||
@@ -0,0 +1,256 @@
|
||||
# Vector Tools
|
||||
|
||||
The vector tools (`hanzo-tools-vector`) provide semantic search capabilities using vector embeddings and the Infinity embedded database.
|
||||
|
||||
## Overview
|
||||
|
||||
These tools enable indexing documents and searching by semantic similarity rather than keyword matching. Perfect for finding conceptually related content.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Basic install
|
||||
pip install hanzo-tools-vector
|
||||
|
||||
# Full install with all dependencies
|
||||
pip install hanzo-tools-vector[full]
|
||||
```
|
||||
|
||||
## index - Project Indexing
|
||||
|
||||
Index project files for search:
|
||||
|
||||
```python
|
||||
# Index current project
|
||||
index(path=".")
|
||||
|
||||
# Index specific directory
|
||||
index(path="/project/src")
|
||||
|
||||
# Index with file filter
|
||||
index(path=".", include="*.py,*.md")
|
||||
|
||||
# Re-index (force update)
|
||||
index(path=".", force=True)
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `path` | str | `.` | Directory to index |
|
||||
| `include` | str | - | File patterns to include |
|
||||
| `exclude` | str | - | File patterns to exclude |
|
||||
| `force` | bool | `False` | Force re-indexing |
|
||||
|
||||
## vector_index - Document Indexing
|
||||
|
||||
Add documents to the vector index:
|
||||
|
||||
```python
|
||||
# Index a single document
|
||||
vector_index(
|
||||
content="This is the document content...",
|
||||
file_path="/docs/guide.md"
|
||||
)
|
||||
|
||||
# Index with metadata
|
||||
vector_index(
|
||||
content="API documentation...",
|
||||
file_path="/docs/api.md",
|
||||
metadata={"category": "api", "version": "2.0"}
|
||||
)
|
||||
|
||||
# Index multiple documents
|
||||
vector_index(
|
||||
documents=[
|
||||
{"content": "Doc 1...", "file_path": "/a.md"},
|
||||
{"content": "Doc 2...", "file_path": "/b.md"}
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `content` | str | - | Document content |
|
||||
| `file_path` | str | - | Source file path |
|
||||
| `metadata` | dict | - | Additional metadata |
|
||||
| `documents` | list | - | Batch of documents |
|
||||
|
||||
## vector_search - Semantic Search
|
||||
|
||||
Search indexed documents by meaning:
|
||||
|
||||
```python
|
||||
# Basic semantic search
|
||||
vector_search(query="How do I authenticate users?")
|
||||
|
||||
# Search with limit
|
||||
vector_search(query="error handling patterns", limit=5)
|
||||
|
||||
# Search with score threshold
|
||||
vector_search(query="database optimization", score_threshold=0.7)
|
||||
|
||||
# Search specific project
|
||||
vector_search(query="API endpoints", search_scope="my-project")
|
||||
|
||||
# Filter by file pattern
|
||||
vector_search(query="testing patterns", file_filter="test_*.py")
|
||||
|
||||
# Search all projects
|
||||
vector_search(query="configuration", search_scope="all")
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `query` | str | required | Search query |
|
||||
| `limit` | int | `10` | Max results to return |
|
||||
| `score_threshold` | float | `0.0` | Min similarity score (0-1) |
|
||||
| `include_content` | bool | `True` | Include document content |
|
||||
| `file_filter` | str | - | Filter by file path pattern |
|
||||
| `project_filter` | list | - | Filter by project names |
|
||||
| `search_scope` | str | `all` | `all`, `global`, `current`, or project name |
|
||||
|
||||
### Search Scopes
|
||||
|
||||
| Scope | Description |
|
||||
|-------|-------------|
|
||||
| `all` | Search all indexed projects |
|
||||
| `global` | Search only global index |
|
||||
| `current` | Search current project (auto-detected) |
|
||||
| `<name>` | Search specific project by name |
|
||||
|
||||
### Output Format
|
||||
|
||||
```
|
||||
Found 3 results for query: 'authentication patterns'
|
||||
|
||||
Result 1 (Score: 87.3%) - Project: my-api - src/auth/handler.py [Chunk 2]
|
||||
------------------------------------------------------------------
|
||||
Metadata: {"category": "auth"}
|
||||
Content:
|
||||
def authenticate_user(token: str) -> User:
|
||||
"""Authenticate user from JWT token..."""
|
||||
...
|
||||
|
||||
Result 2 (Score: 82.1%) - Project: my-api - docs/auth.md [Chunk 0]
|
||||
------------------------------------------------------------------
|
||||
Content:
|
||||
# Authentication Guide
|
||||
|
||||
This guide explains how to authenticate users...
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
### Embedding Generation
|
||||
|
||||
Documents are converted to vector embeddings that capture semantic meaning:
|
||||
|
||||
1. **Chunking**: Large documents split into smaller chunks
|
||||
2. **Embedding**: Each chunk converted to vector representation
|
||||
3. **Storage**: Vectors stored in Infinity database
|
||||
4. **Indexing**: HNSW index for fast similarity search
|
||||
|
||||
### Similarity Search
|
||||
|
||||
Queries are embedded and compared against document vectors:
|
||||
|
||||
1. **Query Embedding**: Convert query to vector
|
||||
2. **Nearest Neighbors**: Find most similar document vectors
|
||||
3. **Scoring**: Calculate similarity scores (0-1)
|
||||
4. **Ranking**: Return top results by score
|
||||
|
||||
## Project Detection
|
||||
|
||||
Projects are automatically detected by looking for `LLM.md` files:
|
||||
|
||||
```
|
||||
/home/user/projects/
|
||||
├── project-a/
|
||||
│ ├── LLM.md <- Project root detected
|
||||
│ └── src/
|
||||
├── project-b/
|
||||
│ ├── LLM.md <- Project root detected
|
||||
│ └── lib/
|
||||
```
|
||||
|
||||
Each project gets its own isolated vector index.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Index Before Searching
|
||||
|
||||
```python
|
||||
# Initial indexing
|
||||
index(path="/project")
|
||||
|
||||
# Then search
|
||||
vector_search(query="your query")
|
||||
```
|
||||
|
||||
### 2. Use Appropriate Score Thresholds
|
||||
|
||||
```python
|
||||
# High precision (fewer results, more relevant)
|
||||
vector_search(query="...", score_threshold=0.8)
|
||||
|
||||
# High recall (more results, some noise)
|
||||
vector_search(query="...", score_threshold=0.5)
|
||||
```
|
||||
|
||||
### 3. Combine with Keyword Search
|
||||
|
||||
```python
|
||||
# Semantic search for concepts
|
||||
vector_search(query="error handling best practices")
|
||||
|
||||
# Keyword search for exact matches
|
||||
grep(pattern="raise ValueError")
|
||||
```
|
||||
|
||||
### 4. Filter by File Type
|
||||
|
||||
```python
|
||||
# Search only documentation
|
||||
vector_search(query="setup instructions", file_filter="*.md")
|
||||
|
||||
# Search only code
|
||||
vector_search(query="authentication", file_filter="*.py")
|
||||
```
|
||||
|
||||
### 5. Use Project Scope for Speed
|
||||
|
||||
```python
|
||||
# Faster: search specific project
|
||||
vector_search(query="...", search_scope="my-project")
|
||||
|
||||
# Slower: search all projects
|
||||
vector_search(query="...", search_scope="all")
|
||||
```
|
||||
|
||||
## Comparison: Vector vs Keyword Search
|
||||
|
||||
| Feature | vector_search | grep |
|
||||
|---------|---------------|------|
|
||||
| Match type | Semantic similarity | Exact text pattern |
|
||||
| Finds synonyms | Yes | No |
|
||||
| Requires indexing | Yes | No |
|
||||
| Speed (large corpus) | Fast (indexed) | Slower |
|
||||
| Best for | Concepts, questions | Exact code, identifiers |
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
# Semantic search finds conceptually related content
|
||||
vector_search(query="how to handle errors")
|
||||
# Finds: exception handling, try/catch blocks, error recovery
|
||||
|
||||
# Keyword search finds exact patterns
|
||||
grep(pattern="except Exception")
|
||||
# Finds: only lines with "except Exception"
|
||||
```
|
||||
Reference in New Issue
Block a user