murphys-laws

墨菲定律

全面收录墨菲定律——幽默地观察生活中事与愿违的种种情况。

目前可在 Web 上使用，iOS 和 Android 版本即将推出。

平台

• Web：https://murphys-laws.com（PWA——可安装，支持离线使用）
• iOS：即将推出
• Android：即将推出

AI 与开发者集成

提供四种官方方式来集成墨菲定律。读取数据无需 API 密钥。

Package	npm	用途
murphys-laws-sdk		类型安全的 TypeScript 客户端，无依赖
murphys-laws-cli		命令行界面（npx murphys-laws-cli）
murphys-laws-mcp		面向 AI Agent 的模型上下文协议服务
REST API	-	位于 https://murphys-laws.com/api/v1/ 的公共 HTTP API

详细信息和示例请参阅开发者主页。

REST API

公共 API 位于 https://murphys-laws.com/api/v1/，读取数据无需身份验证。

• 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 服务（模型上下文协议）

MCP 服务让 AI Agent（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 或开发者主页。

仓库结构

这是一个包含以下内容的 monorepo：

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 产品需求文档
• Android：Android 产品需求文档
• 部署：部署指南
• 代码库结构：代码库结构指南

测试

# 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。
• 共享运行时模板使用 TypeScript，位于 shared/modules/*.ts。

部署

详细说明请参阅部署指南。

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

键盘快捷键（Web）

在网站任意位置按 ? 即可查看所有可用快捷键：

快捷键	操作
/	聚焦搜索框
↑ / ↓	浏览搜索建议（自动补全打开时）
Enter	选择搜索建议（自动补全打开时）
Escape	关闭搜索建议 / 模态框 / 弹出层
j	下一张定律卡片
k	上一张定律卡片
?	显示快捷键帮助
Enter / Space	激活当前聚焦的卡片

**搜索自动补全：**在搜索框中输入时，系统会自动显示建议。使用方向键浏览，按 Enter 选择，或按 Escape 关闭。

贡献

1. Fork 代码库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 提交 Pull Request

政策与支持

• 安全：私密漏洞报告与受支持版本。
• 隐私：数据处理政策。
• 支持：帮助与故障排除。
• Agent 指南：AI 编码 Agent 的标准说明。
• 设计系统：令牌和组件契约指南。

许可证

本项目依据 CC0 1.0 Universal（公有领域）授权。

致谢

感谢多年来提交墨菲定律的所有贡献者！

---

用爱打造，献给所有曾亲身经历墨菲定律的人