murphys-laws

マーフィーの法則

マーフィーの法則を幅広く集めたコレクションです。物事がうまくいかないという人生の傾向を、ユーモラスに観察しています。

Web で利用でき、iOS および Android 版も近日公開予定です。

プラットフォーム

• Web：https://murphys-laws.com（PWA — インストール可能、オフラインでも動作）
• iOS：近日公開
• Android：近日公開

AI と開発者向けの連携

マーフィーの法則を連携するための公式な方法が 4 つあります。読み取りに API キーは不要です。

パッケージ	npm	用途
murphys-laws-sdk		型定義付きの TypeScript クライアント。依存関係なし
murphys-laws-cli		コマンドラインインターフェース（npx murphys-laws-cli）
murphys-laws-mcp		AI エージェント向けの Model Context Protocol サーバー
REST API	-	https://murphys-laws.com/api/v1/ にある公開 HTTP API

詳しい情報と使用例は、開発者向けランディングページをご覧ください。

REST API

https://murphys-laws.com/api/v1/ にある公開 API です。読み取りに認証は不要です。

• API ドキュメント
• OpenAPI 仕様
• llms.txt | llms-full.txt

TypeScript SDK

npm の murphys-laws-sdk は、実行時の依存関係がない、REST API 向けの小型で型定義付きのクライアントです。

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

コマンドラインインターフェース

npm の murphys-laws-cli は、スクリプトやターミナルから API を利用できるようにします。

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

MCP サーバー（Model Context Protocol）

MCP サーバーを使うと、AI エージェント（Claude Desktop、Cursor、VS Code Copilot）からマーフィーの法則を直接検索できます。

クローン不要で、すぐに始められます。

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

7 つのツール：search_laws、get_random_law、get_law_of_the_day、get_law、list_categories、get_laws_by_category、submit_law。

詳しくは、mcp/README.md、npm、または開発者向けランディングページをご覧ください。

リポジトリの構成

このリポジトリは、以下を含むモノレポです。

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

クイックスタート

バックエンド（API サーバー）

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 アプリケーション

cd web
npm install
npm run dev # Start dev server

iOS アプリ

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

Android アプリ

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

ドキュメント

• アーキテクチャ：モバイルアーキテクチャガイド
• MCP サーバー：MCP README
• API：API ドキュメント
• iOS：iOS PRD
• Android：Android PRD
• デプロイ：デプロイガイド
• リポジトリ構成：リポジトリ構成ガイド

テスト

# 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

開発

前提条件

• Node.js 22+
• iOS の場合：macOS、Xcode 15+
• Android の場合：Android Studio Hedgehog+、JDK 17+

依存関係のインストール

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

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

開発サーバーの起動

# Run backend + web concurrently
npm run dev

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

注：predev スクリプトは、起動前にポート 8787 と 5175 を使用している孤立プロセスを自動的にクリーンアップします。

ポートの問題のトラブルシューティング

EADDRINUSE エラー（ポートがすでに使用中）が発生した場合：

# 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

ビルド

# Generate OpenAPI and build the web app
npm run build

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

TypeScript ランタイムアーキテクチャ

• バックエンドは tsx を使って TypeScript ソースを直接実行します（起動時に JS のビルド手順は不要です）。
• バックエンドの正式なランタイムエントリーポイント：backend/src/server/api-server.ts。
• PM2 ランタイムは Node ローダー node --import tsx を使用します。
• 共有ランタイムテンプレートは shared/modules/*.ts 内の TypeScript です。

デプロイ

詳しい手順については、デプロイガイドを参照してください。

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

キーボードショートカット（Web）

サイト上のどこでも ? を押すと、利用可能なショートカットをすべて確認できます。

ショートカット	操作
/	検索にフォーカス
↑ / ↓	検索候補を移動（オートコンプリートが開いている場合）
Enter	検索候補を選択（オートコンプリートが開いている場合）
Escape	検索候補／モーダル／ポップオーバーを閉じる
j	次の法則カード
k	前の法則カード
?	ショートカットのヘルプを表示
Enter / Space	フォーカス中のカードを有効化

**検索オートコンプリート：**検索フィールドに入力すると、候補が自動的に表示されます。矢印キーで移動し、Enter で選択するか、Escape で閉じます。

貢献

1. リポジトリをフォークする
2. フィーチャーブランチを作成する（git checkout -b feature/amazing-feature）
3. 変更をコミットする（git commit -m 'Add amazing feature'）
4. ブランチにプッシュする（git push origin feature/amazing-feature）
5. プルリクエストを作成する

ポリシーとサポート

• セキュリティ：非公開の脆弱性報告とサポート対象バージョン。
• プライバシー：データ取り扱いポリシー。
• サポート：ヘルプとトラブルシューティング。
• エージェントガイド：AI コーディングエージェント向けの正式な手順。
• デザインシステム：トークンとコンポーネントの契約に関するガイダンス。

ライセンス

このプロジェクトは CC0 1.0 Universal（パブリックドメイン）の下でライセンスされています。

謝辞

長年にわたってマーフィーの法則を投稿してくださったすべての貢献者に感謝します！

---

マーフィーの法則を実際に経験したことのあるすべての人へ、愛を込めて作りました