Handyman-MCP

A high-performance Model Context Protocol (MCP) engineered to transform LLMs into autonomous agents with persistent memory and secure system access. Handyman-MCP provides the "executive function" layer for AI models, combining a sophisticated SQLite-backed long-term memory with a hardened execution sandbox.

Features

• 🧠 Persistent Context Engine – SQLite + FTS5 knowledge base with project isolation and alias resolution for cross-session agent "memory."
• 🛡️ Secure Execution Layer – Strict isolation via Bubblewrap sandbox; features a read-only root filesystem and disposable /tmp for safe command execution.
• 📈 Project Lifecycle Auditor – A structured changelog system with timeline tracking for bugs, refactors, and milestones, enabling self-documenting development.
• 🔍 Advanced Information Retrieval – Live web intelligence via DDGS and high-fidelity content extraction using Trafilatura.
• 📂 Filesystem Agency – Full CRUD operations and regex-powered Grep search, optimized with line-based windowing for LLM efficiency.
• 🏗️ Modular Design – A clean, FastAPI-based architecture where each tool is an independent, hot-swappable module for easy extensibility.

Tools

Tool	Description
today	Get today's date and time
add	Add two numbers together
web_search	Search the live web for information
fetch_content	Scrape a URL and extract content
list_files	List files and directories (use recursive=true for tree view)
read_file	Read files with AI-friendly line-based windowing
write_file	Write text to files
append_to_file	Append text to existing files
replace_in_file	Find and replace text in files
insert_after_marker	Insert text after a marker line
search_files	Search for text patterns within files (exact or regex)
delete_file	Delete a file from the sandbox directory
remove_directory	Remove a directory (with optional recursive flag)
run_command	Execute shell commands in sandbox
md_to_pdf	Convert a Markdown file to a styled PDF document
store_context	Store project-specific context in SQLite knowledge base
query_context	Query stored context — supports keyword search (FTS5), direct key lookup, or lists all keys
clear_context	Clear stored context entries by key or wipe all entries for a project
add_project_alias	Register an alternate name (alias) for a project identifier
list_projects	List all known projects with last update timestamps
add_project_change	Record a new change entry (bugfix, refactor, feature, milestone, config, other)
add_change_step	Add a timeline step to an existing project change
list_project_changes	List changes for a project with filters by type and date range
get_change_history	Get full history for one change including timeline steps
search_project_changes	FTS search across project change summaries
store_issue	Store or update an issue with status, title, description, commit link
query_issues	Query issues filtered by project, status, or key
get_issue_details	Get full details for a single issue including description and commit link
update_issue_status	Transition issue status (open → closed / not-relevant)
list_issues	List all issues for a project, optionally filtered by status
update_issue_project	Move an issue from one project to another (change ownership)

🛠 Installation

1. The Standard Way

# Clone the repository
git clone <repository-url>
cd Handyman-MCP

# Install dependencies using uv
uv sync

2. 👨‍🍳 The "Author's Choice" (Recommended for Security)

For maximum isolation and a clean host OS, I recommend running Handyman-MCP inside a Podman Toolbox. This ensures a consistent environment for the Bubblewrap sandbox and prevents dependency drift.

# Create and enter a dedicated toolbox
toolbox create -c handyman-dev
toolbox enter -c handyman-dev

# Install system dependencies & uv
sudo dnf install bubblewrap  # If not present
curl -LsSf https://astral.sh | sh

# Sync and Run
uv sync
uv run main.py

Usage

# Start the server
uv run main.py

The server will start on http://0.0.0.0:8000.

Test Mode

# Start in test mode (port 9000)
uv run main.py --test

Environment Variables

Variable	Default	Description
MCP_BASE_DIR	Project root	Base directory for all tool operations
HOME	(from env)	Home directory for sandbox configuration

Create a .env file from the example:

cp .env.example .env

Architecture

The server implements the Model Context Protocol (MCP) using JSON-RPC 2.0 over HTTP. It exposes 31 tools organized into logical modules, backed by a relational SQLite store with FTS5 full-text search.

Directory Structure

mcp_copy/
├── main.py              # FastAPI app, MCP endpoint (/mcp), tool dispatcher
├── tools.json           # Tool schema definitions (source of truth for client capabilities)
├── config.py            # Configuration — BASE_DIR, env loading
├── tools/               # MCP tool implementations (7 modules)
│   ├── add.py           # Math: add two numbers
│   ├── today.py         # Utility: UTC date/time
│   ├── web_research.py  # Web search (DDGS) + URL scraping (Trafilatura)
│   ├── files.py         # File ops: list, read, write, append, replace, insert, search, delete, remove dir
│   ├── run_command.py   # Shell command execution via Bubblewrap sandbox
│   ├── md_to_pdf.py     # Markdown → PDF conversion via WeasyPrint
│   └── sqlite_store.py  # Persistent context store + project change tracker (FTS5 indexed)
├── .env                 # Environment variables (optional; see `.env.example`)
└── .mcp_cache/          # Persistent SQLite database (context.db)

Key Design Decisions

• Single MCP endpoint at POST /mcp handling initialize, tools/list, and tools/call methods
• Manual tool registration — each handler must be imported in main.py, exported in init.py, and defined in tools.json (31 entries to keep in sync)
• tools.json as schema source — clients discover available tools from this file
• Bubblewrap isolation for run_command — read-only root filesystem, disposable /tmp, writable BASE_DIR bind mount
• Relational SQLite store — proper foreign keys (projects table → context/issues/project_changes), FTS5 indexes rebuilt without content= param, backward-compat views for legacy queries
• Issue-change linking — junction table exists but currently requires manual population (known issue: junction-table-empty)
• Project auto-detection — pyproject.toml → git remote → directory name fallback chain

Persistent Context Store

The sqlite_store module provides a cross-session knowledge base for LLM context using SQLite with FTS5 full-text search.

Project Identification & Storage

Projects are auto-detected and stored as rows in a dedicated projects table (INTEGER PK), referenced via foreign keys across all related tables (context, issues, project_changes). This eliminates fragile text comparisons and enables proper referential integrity.

Detection priority:

1. pyproject.toml[project].name — Python-native, structured
2. Git remote origin URL — extracts repo name
3. Directory name — last resort fallback

Storing & Querying Context

// Store a new entry
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"store_context","arguments":{"key":"auth-flow","content":"User logs in with email/password","project":"my-app"}}}

// Query by canonical key
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"query_context","arguments":{"key":"auth-flow","project":"my-app"}}}

// Add an alias — now "login" resolves to the same entry
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add_project_alias","arguments":{"context_key":"auth-flow","alias_name":"login","project":"my-app"}}}

// Query by alias — returns the same entry, shows "Matched via: alias 'login'"
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"query_context","arguments":{"key":"login","project":"my-app"}}}

Project Change Tracker

A structured changelog system for tracking work progress, bugs fixed, refactors done, and milestones reached. Each change has timeline steps documenting what was done and when. Changes are stored with proper foreign key references to the projects table.

Auto-Linking with Issues

The issue_change_links junction table exists but currently requires manual population. A database trigger mechanism is planned but not yet implemented.

Recording a Change

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"add_project_change","arguments":{"project":"bob","key":"accordion-refactor","change_type":"refactor","summary":"Move accordion from Tabs.js into TablesContainer"}}}

Adding Timeline Steps

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"add_change_step","arguments":{"change_key":"accordion-refactor","project":"bob","step":"investigate","date":"2026-05-03","details":"Found Tabs.js uses querySelectorAll at page load — breaks with .map() output","files_changed":"app/static/js/Tabs.js, app/ts/TablesContainer.tsx"}}}

Viewing & Searching Changes

Tool	Purpose
list_project_changes	List changes with filters by type (bugfix, refactor, feature, milestone, config, other) and date range
get_change_history	Get full history for one change including all timeline steps
search_project_changes	Full-text search across change summaries (optionally scoped to project or type)

Issues Tracker

A structured system for tracking bugs and observations with lifecycle status. Issues link to project changes via a many-to-many junction table.

Storing an Issue

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"store_issue","arguments":{"project":"mcp-server","key":"db-path-race","status":"open","title":"DB_PATH singleton race condition","description":"Module-level DB_PATH=None global causes duplicate connections under concurrent requests."}}}

Updating Status

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"update_issue_status","arguments":{"project":"mcp-server","key":"db-path-race","status":"closed"}}}

Querying Issues

Tool	Purpose
query_issues	Filter by project, status, or exact key; shows truncated descriptions and related change count
get_issue_details	Get full details for a single issue including complete description and commit link
list_issues	List all issues for a project with optional status filter

Status values: open, closed, not-relevant. The issue_change_links junction table tracks which project changes relate to which issues (many-to-many). Currently not auto-populated — a known issue tracked as junction-table-empty.

Todo Project Pattern

The todo project is used as a cross-cutting task list. Use descriptive keys so tasks are findable:

// Store a pending task
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"store_context","arguments":{"key":"review-bob-metrics","content":"Review metrics section in BOB dashboard for accuracy before Friday review","project":"todo"}}}

// Mark as done
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"store_context","arguments":{"key":"review-bob-metrics","content":"DONE: Reviewed metrics, flagged 3 inconsistencies in citizenship data","project":"todo"}}}

Sandbox Configuration

The run_command tool uses Bubblewrap for isolation:

• Read-only root filesystem (--ro-bind / /)
• Disposable temp directory (--tmpfs /tmp)
• Writable BASE_DIR mount (--bind <BASE_DIR> <BASE_DIR>)
• DNS resolution enabled (no /etc restriction)

Environment Variables Passed to Sandbox

Variable	Value	Purpose
PATH	/usr/local/bin:/usr/bin:<user>/.local/bin	Includes user-installed tools (e.g., uv)
HOME	<user>	User home directory (derived from env or BASE_DIR)
UV_CACHE_DIR	/tmp/uv-cache	Redirects uv's cache (host ~/.cache is read-only)

All other environment variables from the parent process are inherited but not explicitly set.

MCP Client Connection

Endpoint

POST http://localhost:8000/mcp
Content-Type: application/json

Supported Methods

Method	Purpose
initialize	Handshake — returns server info and capabilities
tools/list	Returns all available tools from tools.json
tools/call	Execute a tool by name with arguments

Example: Initialize Connection

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

Example: List Tools

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Connecting via llama-cpp-web

Add your MCP server URL (http://localhost:8000/mcp) in the settings under Tools → MCP Servers.

Disclaimer

This project was developed with assistance from Qwen 3.6, a large language model by Alibaba Group's Tongyi Lab. While AI assisted in code generation, documentation, and refactoring, all technical decisions and final implementations were reviewed and validated by the human developer.

License

MIT License