murphys-laws

Murphy's Laws

A comprehensive collection of Murphy's Laws - humorous observations about life's tendency for things to go wrong.

Available on the Web, with iOS and Android releases forthcoming.

Platforms

• Web: https://murphys-laws.com (PWA - installable, works offline)
• iOS: Coming Soon
• Android: Coming Soon

AI & Developer Integration

Four official ways to integrate Murphy's Laws. No API key for reads.

Package	npm	Purpose
murphys-laws-sdk		Typed TypeScript client, zero deps
murphys-laws-cli		Command-line interface (npx murphys-laws-cli)
murphys-laws-mcp		Model Context Protocol server for AI agents
REST API	-	Public HTTP API at https://murphys-laws.com/api/v1/

Full details and examples on the developer landing page.

REST API

Public API at https://murphys-laws.com/api/v1/, no auth required for reads.

• API Documentation
• OpenAPI spec
• llms.txt | llms-full.txt

TypeScript SDK

murphys-laws-sdk on npm is a tiny typed client over the REST API with zero runtime dependencies.

import { MurphysLawsClient } from 'murphys-laws-sdk';
const law = await new MurphysLawsClient().getRandomLaw();

Command-line interface

murphys-laws-cli on npm wraps the API for scripts and terminal use.

npx murphys-laws-cli random
npx murphys-laws-cli search "computer" --limit 3

MCP Server (Model Context Protocol)

An MCP server lets AI agents (Claude Desktop, Cursor, VS Code Copilot) query Murphy's Laws directly.

Quick start, no clone needed:

{
  "mcpServers": {
    "murphys-laws": {
      "command": "npx",
      "args": ["-y", "murphys-laws-mcp"]
    }
  }
}

7 tools: search_laws, get_random_law, get_law_of_the_day, get_law, list_categories, get_laws_by_category, submit_law.

See mcp/README.md or npm, or the developer landing page for the full picture.

Repository Structure

This is a monorepo containing:

murphys-laws/
├── backend/        # Node.js API server (TypeScript runtime via tsx)
├── web/            # Web application (TypeScript + Vite)
├── mcp/            # MCP server for AI agent integration (npm: murphys-laws-mcp)
├── sdk/            # TypeScript SDK over the public REST API (npm: murphys-laws-sdk)
├── cli/            # Command-line interface (npm: murphys-laws-cli)
├── ios/            # iOS app (Swift + SwiftUI)
├── android/        # Android app (Kotlin + Jetpack Compose)
└── shared/         # Shared resources and documentation

Quick Start

Backend (API Server)

cd backend
npm install
npm run build:db # Build SQLite database
npm run dev # Start API server
npm start # Run API from src/server/api-server.ts via tsx

Web Application

cd web
npm install
npm run dev # Start dev server

iOS App

cd ios
open MurphysLaws.xcodeproj
# Press ⌘R to run

Android App

cd android
./gradlew assembleDebug
# Or open in Android Studio

Documentation

• Architecture: Mobile Architecture Guide
• MCP Server: MCP README
• API: API Documentation
• iOS: iOS PRD
• Android: Android PRD
• Deployment: Deployment Guide
• Repository Structure: Repository Structure Guide

Testing

# Run all tests (backend, web, SDK, CLI, and MCP)
npm test

# Test a subset only
npm run test:backend   # Backend Vitest suite
npm run test:web       # Web Vitest suite only (no E2E)
npm run test:web:e2e   # Web E2E (Playwright) only

Development

Prerequisites

• Node.js 22+
• For iOS: macOS, Xcode 15+
• For Android: Android Studio Hedgehog+, JDK 17+

Install Dependencies

# Install all dependencies (root and workspaces)
npm run install:all

# Or install individually
cd backend && npm install
cd web && npm install

Run Development Servers

# Run backend + web concurrently
npm run dev

# Or run individually
npm run dev:backend
npm run dev:web

Note: The predev script automatically cleans up any orphaned processes using ports 8787 and 5175 before starting.

Troubleshooting Port Issues

If you encounter EADDRINUSE errors (port already in use):

# Check which processes are using development ports
npm run cleanup-ports

# Automatically kill processes using development ports
npm run cleanup-ports -- --kill

# Or manually check and kill
lsof -i :8787  # Check API port
lsof -i :5175  # Check frontend port
kill <PID>     # Kill the process

Building

# Generate OpenAPI and build the web app
npm run build

# Build specific platform
npm run build:web
npm run build:backend:db

TypeScript Runtime Architecture

• Backend runs TypeScript source directly with tsx (no JS build step required for startup).
• Canonical backend runtime entrypoint: backend/src/server/api-server.ts.
• PM2 runtime uses Node loader: node --import tsx.
• Shared runtime templates are TypeScript in shared/modules/*.ts.

Deployment

See Deployment Guide for detailed instructions.

# Deploy web app (builds and syncs to production)
npm run deploy

Keyboard Shortcuts (Web)

Press ? anywhere on the site to see all available shortcuts:

Shortcut	Action
/	Focus search
↑ / ↓	Navigate search suggestions (when autocomplete is open)
Enter	Select search suggestion (when autocomplete is open)
Escape	Close search suggestions / modal / popover
j	Next law card
k	Previous law card
?	Show shortcuts help
Enter / Space	Activate focused card

Search Autocomplete: When typing in the search field, suggestions appear automatically. Use arrow keys to navigate, Enter to select, or Escape to close.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Policies and Support

• Security: Private vulnerability reporting and supported versions.
• Privacy: Data-handling policy.
• Support: Help and troubleshooting.
• Agent Guide: Canonical instructions for AI coding agents.
• Design System: Token and component-contract guidance.

License

This project is licensed under CC0 1.0 Universal (Public Domain).

Acknowledgments

Thanks to all contributors who have submitted Murphy's Laws over the years!

---

Made with love for anyone who's ever experienced Murphy's Law in action