# 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