Macos Dev Server

麦基托mcp

模型上下文协议（MCP）服务器，为AI助手提供对macOS开发环境、生产力工具和Chrome浏览器历史的结构化访问。

概述

macchiato mcp是一个本地mcp服务器，通过安全、结构化的界面向AI助手公开终端命令、文件系统操作、git存储库、macOS系统工具和浏览器历史记录。所有操作都限制在具有内置安全机制的配置目录中。

特性

• 终端执行：运行带有安全控制和输出管理的shell命令
• 文件系统操作：在允许的目录中读取、写入、列出和附加文件
• Git集成：检查状态、查看日志、创建提交和推送更改
• 项目管理：发现存储库并检测技术栈
• 记笔记：管理个人笔记并与Apple notes集成
• macOS集成：控制提醒、日历、剪贴板和系统监控
• 网络工具：检查连接、端口、ping主机和测试URL
• 浏览历史：搜索Chrome浏览历史记录和打开的URL

安装

先决条件

• Node.js 18.0.0或更高版本
• macOS（用于系统集成工具）
• 谷歌Chrome浏览器（用于浏览器工具）

设置

1. 克隆或下载此存储库

1. 安装依赖项：

npm install

1. 构建项目：

npm run build

1. 配置MCP客户端（例如，Claude Desktop）：

编辑您的MCP客户端配置文件（适用于Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "macchiato-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/macchiato-mcp/dist/index.js"],
      "env": {}
    }
  }
}

1. 重新启动MCP客户端

配置

允许的目录

编辑 src/config.ts 配置服务器可以访问哪些目录：

export const ALLOWED_ROOTS = [
  path.join(os.homedir(), "dev"),
  path.join(os.homedir(), "projects"),
  path.join(os.homedir(), "Desktop"),
  path.join(os.homedir(), "Documents"),
];

文件系统工具只能访问这些根目录下的路径。这可以防止意外访问敏感的系统文件。

安全配置

这 DANGEROUS_PATTERNS 数组in src/config.ts 定义被阻止的命令模式：

export const DANGEROUS_PATTERNS = [
  /rm\s+-rf\s+\//,           // Prevent root deletion
  /:\(\)\{\s*:\|:&\s*\};:/,  // Block fork bombs
  /mkfs/,                     // Block filesystem formatting
  // ... additional patterns
];

根据需要添加或修改模式以满足您的安全要求。

超时和输出限制

调整命令执行限制 src/config.ts:

export const DEFAULT_COMMAND_TIMEOUT = 10;      // seconds
export const DEFAULT_MAX_OUTPUT_CHARS = 10000;  // characters

可用工具

终端工具

terminal_run_command

• 执行具有安全功能的shell命令
• 支持超时、输出截断和干运行模式
• 自动阻止危险的命令模式

文件系统工具

fs_list_dir

• 列出目录内容及其元数据（大小、修改日期）
• 仅在允许的根目录内工作

fs_read_file

• 将文件内容读取为UTF-8文本
• 自动截断大文件

fs_writefile

• 将内容写入文件
• 如果需要，创建父目录
• 可选覆盖保护

fs_append_file

• 在不覆盖现有文件的情况下附加内容

Git工具

git_status

• 获取存储库状态、当前分支和未提交的更改

git_log

• 使用哈希值、作者、日期和消息检索提交历史记录

git_提交

• 创建提交，并可选择对所有更改进行暂存

git_push

• 将提交推送到远程存储库

项目工具

项目列表

• 递归查找目录下的所有git存储库

project_detect_stack

• 检测语言、框架和常用命令
• 支持JavaScript/TypeScript、Python、Rust、Go、Java、Ruby

项目运行测试

• 运行项目测试，自动检测测试命令

笔记工具

notes_add

• 添加带有可选标签的注释
• 本地存储在 ~/.aashna_dev_mcp/notes.json

notes_list

• 列出注释，可选择按标签筛选

notes_search

• 按文本或子字符串匹配的标签搜索笔记

macOS集成工具

macos_notes_list, macos_notes_create, macos_notes_search

• 与Apple Notes应用程序交互

macos_reminders_list, macos_reminders_create, macos_reminders_完成

• 管理Apple提醒

macos_clipboard_copy, macos_clipboard_read, macos_clipboard_clear

• 系统剪贴板操作

macos_calendar_list_事件, macos_calendar_create_event, macos_calendar_check_availability, macos_calendar_list

• 日历管理

macos_system_stats

• 获取CPU使用率、内存和磁盘空间

macos_process_list, macos_process_find, macos_process_kill

• 过程监控和管理

macos_disk_usage

• 分析目录的磁盘使用情况

macos网络连接, macos_network_check_port, macos_network_list_ports, macos网络ping, macos_network_dns_lookup, macos_network_info, macos_network_test_url

• 网络诊断和监控

浏览器工具

浏览器历史

• 按文本和时间窗口搜索最近的Chrome浏览历史记录
• 搜索页面标题和URL
• 参数：

- query （必填）：搜索匹配的文本 - days （可选）：回顾的天数（默认值：3） - limit （可选）：返回的最大结果数（默认值：10）

• 返回：包含标题、URL、上次访问时间（ISO 8601）和访问次数的结果数组

浏览器_打开url

• 在macOS上的Google Chrome中打开URL
• 参数：

- url （必填）：要打开的URL（必须以http://或https://开头）

• 返回：成功状态和消息

使用示例

基本命令执行

问你的AI助手：

• “在我的项目中运行npm install”
• “检查哪些进程正在使用端口3000”
• “显示我的存储库的git状态”

文件操作

• “从我的项目中读取package.json”
• “使用node_modules和dist创建.gitignore文件”
• “列出src目录中的所有文件”

浏览器集成

• “查找我昨天阅读的TypeScript教程”
• “在我的Chrome历史记录中搜索上周的‘React文档’”
• “打开关于机器学习的YouTube视频”

跨工具工作流

• “找到我观看的强化学习视频，并用URL创建一个注释”
• “在我的历史记录中搜索Python教程，并将前三名添加到提醒中的阅读列表中”
• “本周我访问了哪些文档网站？”

安全特性

路径安全

所有文件系统操作仅限于 ALLOWED_ROOTS。尝试访问这些目录之外的路径将失败，并显示明显的错误。

指挥安全

危险的命令模式会被自动阻止：

• 根删除(rm -rf /)
• 叉式炸弹
• 文件系统格式化(mkfs)
• 直接磁盘写入(dd)
• 管道下载到外壳(curl ... | bash)

输出管理

• 命令在超时后自动终止
• 输出被截断以防止内存问题
• 所有错误都返回结构化响应

浏览器安全

• 对Chrome历史数据库的只读访问
• 打开前的URL验证
• 正确的SQL转义以防止注入
• 创建临时数据库副本以避免锁定

发展

观看模式

根据文件更改自动重建：

npm run dev

手动测试

直接运行服务器：

npm start

测试浏览器工具：

node test-browser.js history "search query"
node test-browser.js open "https://example.com"

添加新工具

1. 在相应的文件中创建工具函数 src/tools/
2. 导出带有JSDoc注释的函数
3. 注册 src/index.ts:

- 增添 ListToolsRequestSchema 处理程序（工具元数据） - 增添 CallToolRequestSchema 处理程序（执行逻辑）

1. 更新类型 src/core/types.ts 如有需要
2. 重建： npm run build

项目结构

macchiato-mcp/
├── src/
│   ├── index.ts              # MCP server entry point & tool registration
│   ├── config.ts             # Configuration (allowed roots, safety rules)
│   ├── core/
│   │   ├── exec.ts           # Safe command execution
│   │   ├── paths.ts          # Path safety & validation
│   │   └── types.ts          # Shared TypeScript types
│   └── tools/
│       ├── terminal.ts       # Terminal command execution
│       ├── filesystem.ts     # File operations
│       ├── git.ts            # Git integration
│       ├── projects.ts       # Repository discovery
│       ├── notes.ts          # Personal notes
│       ├── browser.ts        # Chrome history & URL opening
│       ├── macos-notes.ts    # Apple Notes integration
│       ├── macos-reminders.ts
│       ├── macos-clipboard.ts
│       ├── macos-calendar.ts
│       ├── macos-system.ts
│       └── macos-network.ts
├── dist/                     # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── mcp.config.example.json   # Example MCP client configuration

故障排除

未找到Chrome历史记录

如果您看到“未找到Chrome历史数据库”：

• 确保已安装Google Chrome浏览器
• 至少启动一次Chrome浏览器
• 验证路径是否存在： ~/Library/Application Support/Google/Chrome/Default/History

工具不可用

如果您的MCP客户端中没有显示工具：

• 验证构建是否完成： npm run build
• 检查MCP客户端配置中的路径
• 完全重新启动MCP客户端
• 检查服务器日志（stderr）是否有错误

权限错误

如果您遇到权限错误：

• 验证请求的路径是否在 ALLOWED_ROOT
• 检查文件/目录权限 ls -la
• 确保服务器进程具有读/写访问权限

命令被阻止

如果命令被阻止：

• 审查 DANGEROUS_PATTERNS 在 src/config.ts
• 如果您信任该命令，请删除该模式
• 使用模拟运行模式预览： {"dry_run": true}

贡献

这是一个个人发展工具。您可以根据自己的需求自由分叉和定制。

许可证

麻省理工学院

构建于

• 模型上下文协议SDK
• TypeScript
• Node.js