# Keyboard Shortcuts MCP Server

A Model Context Protocol (MCP) server that provides keyboard shortcuts for various operating systems, desktop environments, and applications. Uses Claude Opus for intelligent natural language querying of shortcuts.

**Primary Use Case**: Designed to support [Claude's Computer Use tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/computer-use-tool) by providing accurate, context-aware keyboard shortcuts for automated computer interactions.

## Features

- 🔍 **Intelligent Search**: Uses Claude Opus to understand natural language queries
- 🖥️ **Multi-Platform**: Support for Ubuntu (GNOME desktop), with architecture for macOS/Windows
- 📱 **App-Specific**: Desktop apps (Firefox, VS Code), CLI tools (tmux, vim), and system shortcuts
- 🚀 **Fast**: All shortcut data loaded in-memory for quick filtering

## Installation

```bash
# Install dependencies
pnpm install

# Build the server
pnpm build
```

## Configuration

Set your Anthropic API key as an environment variable:

```bash
export ANTHROPIC_API_KEY="your-api-key-here"
```

## Usage

### Running Standalone

```bash
pnpm start
```

### Integrating with Claude Desktop

Add to your Claude Desktop MCP configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "keyboard-shortcuts": {
      "command": "node",
      "args": ["/path/to/keyboard-shortcuts-mcp/dist/index.js"],
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Tool: `get_shortcuts`

Query keyboard shortcuts using natural language.

### Parameters

- `os` (required): Operating system - `"ubuntu"`, `"macos"`, or `"windows"`
- `query` (required): Natural language question about shortcuts
- `desktop` (optional): Desktop environment - `"gnome"`, `"kde"`, etc.
- `application` (optional): Specific application - `"firefox"`, `"tmux"`, etc.

### Examples

```typescript
// Query tmux shortcuts (no desktop needed for CLI tools)
{
  "os": "ubuntu",
  "application": "tmux",
  "query": "how do I split a pane vertically?"
}

// Query Firefox shortcuts on GNOME
{
  "os": "ubuntu",
  "desktop": "gnome",
  "application": "firefox",
  "query": "how to open a new private window"
}

// Query GNOME window management
{
  "os": "ubuntu",
  "desktop": "gnome",
  "query": "tile window to left half of screen"
}
```

## Data Structure

Shortcuts are organized as:

```
data/
└── ubuntu/
    ├── desktops/
    │   └── gnome/
    │       ├── window-management.json
    │       ├── system-functions.json
    │       └── ...
    ├── apps/
    │   ├── browser/
    │   │   ├── firefox.json
    │   │   └── chrome.json
    │   ├── editor/
    │   │   ├── vscode.json
    │   │   └── vim.json
    │   └── ...
    └── tools/
        ├── tmux.json
        ├── vim.json
        └── ...
```

Each JSON file contains:

```json
{
  "os": "ubuntu",
  "desktop": "gnome" | null,
  "application": "firefox" | null,
  "file": "firefox",
  "categories": [
    {
      "name": "Tab Management",
      "shortcuts": [
        {
          "keys": "Ctrl + T",
          "description": "New tab"
        }
      ]
    }
  ]
}
```

## Development

```bash
# Watch mode (auto-reload on changes)
pnpm dev

# Build TypeScript
pnpm build

# Run built server
pnpm start
```

## Architecture

1. **Data Loader** (`src/data-loader.ts`): Loads all JSON files at startup into memory
2. **Opus Client** (`src/opus-client.ts`): Wraps Anthropic SDK for intelligent queries
3. **MCP Server** (`src/index.ts`): Exposes `get_shortcuts` tool via MCP protocol

The server filters shortcuts by OS/desktop/app, then passes relevant data + user query to Claude Opus for intelligent matching.

## License

MIT