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

🛠 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

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

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

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

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

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