# Espanso MCP Server

An MCP (Model Context Protocol) server for managing [Espanso](https://espanso.org/) text expansion configurations. This server allows AI assistants like Claude to interact with your Espanso setup, making it easy to create, update, and manage text expansions.

**Espanso Resources:**
- 🌐 [Espanso Website](https://espanso.org/)
- 📚 [Espanso Documentation](https://espanso.org/docs/)
- 💻 [Espanso GitHub Repository](https://github.com/espanso/espanso)

## Features

- **List** all match files and expansions
- **Create** new text expansions with simple or complex patterns
- **Update** existing expansions
- **Delete** expansions you no longer need
- **Templates** for common expansion patterns
- **Cross-platform** support (Linux, macOS, Windows)

## Installation

1. Clone this repository:
```bash
git clone https://github.com/bkaes/espanso-mcp.git
cd espanso-mcp
```

2. Install dependencies and build:
```bash
npm install
npm run build
```

3. Add to your MCP configuration:
```json
{
  "mcpServers": {
    "espanso": {
      "command": "node",
      "args": ["/absolute/path/to/espanso-mcp/dist/index.js"]
    }
  }
}
```

**Note**: The configuration file location varies by platform:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/claude/claude_desktop_config.json`

## Usage

Once configured, you can ask Claude to:

### List all expansions
"Show me all my Espanso text expansions"

### Create a new expansion
"Create an Espanso expansion that types my email signature when I type :sig"

### Create a date expansion
"Add an expansion :today that inserts today's date in YYYY-MM-DD format"

### Update an expansion
"Change the :sig expansion to include my phone number"

### Delete an expansion
"Remove the :old expansion from my Espanso config"

## Available Tools

- `list_match_files` - List all YAML files containing expansions
- `list_matches` - Show all expansions (optionally filtered by file)
- `create_match` - Add a new text expansion
- `update_match` - Modify an existing expansion
- `delete_match` - Remove an expansion
- `get_config_info` - Display Espanso configuration details
- `generate_documentation` - Generate markdown documentation for your expansions

## Documentation Generation

The MCP server can generate comprehensive documentation for your Espanso shortcuts:

### Generate documentation for all expansions
"Create documentation for all my Espanso shortcuts"

### Generate documentation for specific file
"Document just my email expansions"

Documentation is saved in your Espanso config directory under `docs/` by default, making it easy to:
- Keep documentation with your expansions
- Reference from project READMEs
- Share with team members

## Templates

The server provides templates for common expansion patterns:

- **Simple text expansion** - Basic trigger → replacement
- **Date expansion** - Dynamic date insertion with custom formats
- **Form expansion** - Interactive forms with user input

## Requirements

- Node.js 18 or higher
- Espanso installed and configured

## Development

Run the server in development mode:
```bash
npm run dev
```

### Project Structure

The codebase is organized into modular components:
- `src/index.ts` - Entry point
- `src/server.ts` - MCP server implementation
- `src/types/` - TypeScript interfaces
- `src/handlers/` - Business logic for each operation
- `src/utils/` - Utility functions

### Contributing

See [CLAUDE.md](./CLAUDE.md) for detailed architecture and design decisions.


## License

GPL-3.0