内容
# mackit
使用命令行操作原生macOS数据。通过使用结构化的JSON输出，读取和写入日历、提醒事项、联系人、邮件等，使用苹果原生的框架（EventKit、Contacts、ScriptingBridge）。包含一个用于AI代理集成的MCP服务器。
无需icalbuddy。快速、原生的Swift。
## 安装
**发布版本：**
```bash
tmp=$(mktemp -d) && curl -fsSL https://github.com/feedthejim/macos-kit/releases/latest/download/mackit-macos-universal.tar.gz | tar xz -C "$tmp" && "$tmp/install.sh"
```
**从源码安装：**
```bash
git clone https://github.com/feedthejim/macos-kit.git && cd macos-kit && scripts/install-mackit.sh
```
安装程序将`MacKit.app`放置在`~/Applications`中，将`mackit`放置在`~/.local/bin`中。权限敏感的命令会自动启动应用程序。
## 用法
### 日历
```bash
# 今日剩余事件
mackit cal
# 明天/本周
mackit cal tomorrow
mackit cal week
# 下一个事件 + 会议网址
mackit cal next
open $(mackit cal next --url)
# 空闲时间段
mackit cal free --date tomorrow --duration 30m
mackit cal free --work-start 8am --work-end 6pm --buffer 15m -c 工作
# 按日历和日期范围筛选
mackit cal -c 工作 --from monday --to friday
# 创建事件
mackit cal create "与Sarah喝咖啡" --date tomorrow --from 3pm --to 3:30pm
mackit cal create "设计评审" --date friday --from 2pm --to 3pm -c 工作 --location "房间4"
# 重新安排
mackit cal move <事件ID> --date friday --from 3pm
# 更新/删除
mackit cal update <事件ID> --notes "带上笔记本电脑"
mackit cal update <事件ID> --clear-location
mackit cal update <事件ID> --timed --from 9am --to 10am
mackit cal delete <事件ID> --yes
mackit cal delete <事件ID> --scope future --yes
# 带有字段选择的JSON
mackit cal --json title,startDate,meetingURL
```
### 提醒事项
```bash
# 列出（默认为不完整）
mackit rem
mackit rem -l 购物
mackit rem overdue
# 添加
mackit rem add "购买牛奶" --list 购物
mackit rem add "审查PR" --list 工作 --due tomorrow --priority high
# 完成（模糊标题匹配）
mackit rem done "牛奶"
# 移动到其他列表
mackit rem move "购买鸡蛋" --to 蔬菜
# 删除
mackit rem delete <ID> --yes
```
### 联系人
```bash
mackit contacts search "约翰"
mackit contacts search "约翰" --email # 仅限电子邮件，一行一个
mackit contacts search "约翰" --phone # 仅限电话号码
mackit contacts birthdays --days 7
```
### 邮件
```bash
# 列出最近的消息（默认为收件箱）
mackit mail
mackit mail list --unread
mackit mail list -m "已发送邮件" -a Gmail -n 5
# 读取消息
mackit mail read <ID> -m 收件箱 -a iCloud
# 搜索
mackit mail search "发票"
mackit mail search "会议" -a Gmail -n 10
mackit mail search "发票" --sender stripe --from monday --to today
# 分页和线程分组
mackit mail list -n 25 --offset 25
mackit mail list --group-threads
# 附件元数据，无需下载文件
mackit mail list -n 5 --json id,subject,attachmentCount,attachments
# 邮箱和账户
mackit mail mailboxes
mackit mail mailboxes -a iCloud
mackit mail accounts
# 发送
mackit mail send --to bob@test.com --subject "你好" --body "嗨，鲍勃"
mackit mail send --to a@test.com --cc b@test.com --subject "FYI" --body "查看这个"
# 标记为已读/未读
mackit mail mark-read <ID> -a iCloud
mackit mail mark-unread <ID> -a iCloud
# 移动/删除
mackit mail move <ID> --to 存档 -a iCloud
mackit mail delete <ID> -a iCloud --yes
# 带有字段选择的JSON
mackit mail list --json id,subject,sender,isRead
```
列表/搜索JSON输出包括分页元数据。字段选择的 `--json` 输出对于shell管道保持为数组。部分账户失败报告为警告，同时保留成功的账户结果。
### 焦点/请勿打扰
```bash
mackit focus
mackit focus --quiet && echo "请勿打扰已开启" # 脚本退出代码
```
### 诊断
```bash
mackit doctor
MACKIT_TIMEOUT=90 mackit mail search "大型查询"
```
托管命令默认为45秒超时。`MACKIT_TIMEOUT`接受5到300秒。主机限制并发和输出，取消断开的客户端，并在`~/Library/Application Support/MacKit/host.jsonl`中记录元数据诊断。
### 通知
```bash
mackit notify "构建完成" "所有测试通过"
mackit notify "部署" "v2.1.0" --subtitle "us-east-1" --sound default
```
## MCP服务器
mackit包含一个内置的MCP服务器，用于AI代理集成（Claude Code、Claude Desktop等）。
### 设置
**Claude Code** （项目 `.mcp.json`）：
```json
{
"mcpServers": {
"mackit": {
"command": "mackit",
"args": ["mcp"]
}
}
}
```
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`)：
```json
{
"mcpServers": {
"mackit": {
"command": "/Users/YOUR_USERNAME/.local/bin/mackit",
"args": ["mcp"]
}
}
}
```
### 可用MCP工具
| 工具 | 描述 |
|------|-------------|
| `calendar_list` | 列出事件，带日期范围、日历筛选 |
| `calendar_next` | 下一个即将到来的事件，带会议网址 |
| `calendar_free` | 用于调度的空闲时间段 |
| `calendar_calendars` | 列出所有日历 |
| `calendar_create` | 创建日历事件 |
| `calendar_delete` | 删除事件 |
| `calendar_update` | 更新事件字段 |
| `calendar_move` | 重新安排事件 |
| `reminders_list` | 按列表、状态、到期日期列出提醒事项 |
| `reminders_overdue` | 所有逾期提醒事项 |
| `reminders_lists` | 列出所有提醒事项列表，带计数 |
| `reminders_add` | 创建提醒事项 |
| `reminders_complete` | 按标题匹配或ID完成 |
| `reminders_delete` | 删除提醒事项 |
| `reminders_move` | 移动到另一个列表 |
| `contacts_search` | 按姓名、电子邮件、电话号码搜索 |
| `contacts_birthdays` | 即将到来的生日 |
| `mail_list` | 列出消息，带筛选，紧凑视图 |
| `mail_search` | 按关键词搜索消息 |
| `mail_read` | 读取完整消息内容 |
| `mail_mailboxes` | 列出邮箱，带未读计数 |
| `mail_accounts` | 列出邮件账户 |
| `mail_send` | 发送电子邮件 |
| `mail_mark_read` | 标记消息为已读 |
| `mail_mark_unread` | 标记消息为未读 |
| `mail_move` | 移动消息到另一个邮箱 |
| `mail_delete` | 删除消息 |
| `focus_status` | 检查焦点/请勿打扰模式 |
| `notify_send` | 发送macOS通知 |
## 输出格式
自动检测：终端中的文本，管道中的JSON。覆盖 `--format json|text|table`。
**JSON字段选择** （类似 `gh --json`）：
```bash
mackit cal --json title,startDate,meetingURL
mackit contacts search "约翰" --json givenName,emailAddresses
```
## 权限
`MacKit.app`拥有稳定的macOS权限身份。CLI和MCP服务器通过用户专有的本地套接字连接到它，因此访问不依赖于哪个终端或代理启动`mackit`。
| 命令 | 权限 |
|------------|-----------|
| `cal` | 日历 |
| `rem` | 提醒事项 |
| `contacts` | 联系人 |
| `notify` | 通知 |
| `mail` | 自动化（Mail.app） |
| `focus` | 无 |
| `mcp` | 所有（按需） |
## 架构
```
mackit CLI / MCP客户端
│
│ 私有Unix套接字
▼
MacKit.app
│
▼
日历、提醒事项、联系人、邮件、通知
```
套接字模式为 `600`，主机验证客户端具有相同的用户ID。`MacKitCore`保持基于协议且独立可测试，使用模拟。
## 要求
- macOS 13（Ventura）或更高版本
- Swift 6.0+
## 许可证
MIT
