Murphys Laws

Murphy's Laws

[Web CI] [Dependency Audit]

[PRs Welcome] [Maintenance] [License: CC0-1.0] [Node.js] [iOS] [Android]

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.

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 randomnpx 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 backendnpm installnpm run build:db # Build SQLite databasenpm run dev # Start API servernpm start # Run API from src/server/api-server.ts via tsx

Web Application

cd webnpm installnpm run dev # Start dev server

iOS App

cd iosopen 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 onlynpm run test:backend   # Backend Vitest suitenpm 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 individuallycd backend && npm installcd web && npm install

Run Development Servers

# Run backend + web concurrentlynpm run dev
# Or run individuallynpm run dev:backendnpm 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 portsnpm run cleanup-ports
# Automatically kill processes using development portsnpm run cleanup-ports -- --kill
# Or manually check and killlsof -i :8787  # Check API portlsof -i :5175  # Check frontend portkill <PID>     # Kill the process

Building

# Generate OpenAPI and build the web appnpm run build
# Build specific platformnpm run build:webnpm 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:

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