CLAUDE.md•3.08 kB
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
An MCP (Model Context Protocol) server that provides keyboard shortcuts for operating systems, desktop environments, and applications. The server uses **Claude Opus** for intelligent natural language query resolution rather than procedural searching.
**Key Philosophy**: KISS - Keep it simple. This is a relay server that forwards user queries + filtered data to Opus for intelligent matching.
## Commands
```bash
# Development (watch mode with auto-reload)
pnpm dev
# Build TypeScript → JavaScript
pnpm build
# Run production server
pnpm start
# Convert markdown shortcuts to JSON (if adding new data)
node scripts/convert-md-to-json.js
```
## Architecture
**Two-Stage Query Pipeline:**
1. **Filter Phase** (`src/data-loader.ts`):
- All 30 JSON files loaded into memory at startup
- Fast filtering by OS/desktop/application parameters
- Returns only relevant shortcut files to reduce Opus context
2. **LLM Resolution Phase** (`src/opus-client.ts`):
- Filtered data + user query sent to Claude Opus (claude-opus-4-20250514)
- Opus intelligently matches shortcuts based on natural language
- Response relayed back through MCP protocol
**Critical**: `desktop` parameter is **optional** because CLI tools (tmux, vim) have the same shortcuts regardless of desktop environment, while desktop-specific apps may vary.
## Data Model
**Three-tier hierarchy:**
- `data/{os}/desktops/{desktop}/` - Desktop environment shortcuts (desktop: "gnome", application: null)
- `data/{os}/apps/{category}/` - Application shortcuts (desktop: null, application: "firefox")
- `data/{os}/tools/` - CLI tools (desktop: null, application: "tmux")
**JSON Schema:**
```json
{
"os": "ubuntu",
"desktop": "gnome" | null,
"application": "firefox" | null,
"file": "firefox",
"categories": [
{
"name": "Tab Management",
"shortcuts": [
{"keys": "Ctrl + T", "description": "New tab"}
]
}
]
}
```
## Environment Variables
`ANTHROPIC_API_KEY` - Required for Opus API access. Set in MCP client configuration or shell environment.
## Adding New Shortcuts
1. Create markdown file in `docs/` with format: `- \`keys\` - description`
2. Run conversion script: `node scripts/convert-md-to-json.js`
3. Place generated JSON in appropriate `data/{os}/` subdirectory
4. Rebuild: `pnpm build`
## MCP Integration
Server communicates via **stdio transport** (not HTTP). Configure in Claude Desktop:
```json
{
"mcpServers": {
"keyboard-shortcuts": {
"command": "node",
"args": ["/absolute/path/to/dist/index.js"],
"env": {"ANTHROPIC_API_KEY": "sk-..."}
}
}
}
```
## Design Constraints
- **No procedural search implementation** - Opus handles all query logic
- **In-memory data only** - No database (designed for future SQLite migration)
- **Simple filtering** - Exact match on os/desktop/application, no fuzzy logic
- **Single tool** - `get_shortcuts` is the only exposed MCP tool