# mcp-macos-utils
A Model Context Protocol (MCP) server that provides macOS utility tools for AI assistants.
## Features
- **Native macOS Notifications**: Send system notifications with different types (success, error, info, warning)
- **Auto Project Detection**: Automatically detects and includes the current project name in notifications
- **Notification Logging**: All notifications are logged to `~/.mcp-notifications.log` for audit trail
- **TypeScript Support**: Fully typed for better development experience
## Installation
1. Clone this repository:
```bash
git clone <repository-url>
cd mcp-macos-utils
```
2. Run the install script:
```bash
./install.sh
```
This will:
- Install npm dependencies
- Build the TypeScript code
- Create an example configuration file
## Configuration
Add the following to your MCP client's configuration file:
```json
{
"mcpServers": {
"macos-utils": {
"command": "node",
"args": ["/absolute/path/to/mcp-macos-utils/dist/index.js"],
"env": {}
}
}
}
```
Replace `/absolute/path/to/mcp-macos-utils` with the actual path to this directory.
## Usage
Once configured, the following tool will be available to AI assistants:
### notify
Send a macOS notification with project context.
**Parameters:**
- `title` (required): The notification title
- `message` (required): The notification message
- `type` (optional): Type of notification - `success`, `error`, `info`, or `warning` (default: `info`)
- `sound` (optional): Whether to play a sound (default: `true`)
- `subtitle` (optional): Custom subtitle (defaults to current project name)
**Example:**
```javascript
await notify({
title: "Build Complete",
message: "Your project has been built successfully",
type: "success"
});
```
## Notification Types
- **Success** (✅): For successful operations
- **Error** (❌): For errors or failures
- **Warning** (⚠️): For warnings or cautions
- **Info** (ℹ️): For general information
## Logging
All notifications are logged to `~/.mcp-notifications.log` in JSON format, including:
- Timestamp
- Project name
- Notification type
- Title and message
- Any errors that occurred
## Development
### Building
```bash
npm run build
```
### Development Mode
```bash
npm run dev
```
### Clean Build
```bash
npm run clean
npm run build
```
## Requirements
- macOS (uses native `osascript` for notifications)
- Node.js 20+
- TypeScript 5.5+
## License
MIT
