promptbin: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

PromptBin is the easiest way to run a Model Context Protocol (MCP) server with full prompt management capabilities. It's designed as a reference implementation and example for MCP server integration.

Primary use case: uv add promptbin && uv run promptbin

Modes:

• Both Mode (default): MCP server + auto-launching web interface
• MCP Server Mode: MCP protocol only with --mcp flag
• Web Mode: Web interface only with --web flag

Development Commands

For PyPI distribution (recommended):

# Install from PyPI
uv add promptbin

# Run both MCP server + web interface (primary use case)
uv run promptbin

# Run only MCP server
uv run promptbin --mcp

# Run only web interface
uv run promptbin --web

# Setup verification
uv run promptbin-setup

# Install Dev Tunnels CLI
uv run promptbin-install-tunnel

For development:

# Clone and develop
git clone https://github.com/ianphil/promptbin
cd promptbin
uv sync
uv run promptbin

Architecture Overview

Core Components

• Flask Web App (app.py): HTMX-powered interface on localhost:5000
• MCP Server (mcp_server.py): Model Context Protocol integration with auto-lifecycle management
• File-Based Storage: JSON files in ~/promptbin-data/{category}/{prompt_id}.json
• Microsoft Dev Tunnels: Secure sharing with automatic security protections

Data Organization

~/promptbin-data/
├── coding/     # Development-related prompts
├── writing/    # Content creation prompts  
├── analysis/   # Data analysis prompts
└── shares.json # Share token management

Key Design Principles

• Local-First: All data stored locally by default
• Zero Database: File-based storage only
• HTMX Integration: No full page reloads, dynamic interactions
• Security by Design: Rate limiting (5 attempts per IP kills tunnel)
• Template Variables: Support for {{variable}} syntax with special highlighting