MCP Server for FVWM3

Model Context Protocol (MCP) server providing access to FVWM3 window manager configuration, state, and control capabilities. This server enables LLMs to interact with FVWM3 for configuration generation, debugging, window management, and development assistance.

Features

Resources

Access to FVWM3 configuration files, documentation, scripts, and runtime state:

• Configuration files: Live and repository versions of FVWM config

• Documentation: Architecture docs, shortcuts reference, smart tiling technical docs

• Scripts: Smart tiling, monitor setup, keyboard layout toggle

• Runtime state: Current monitors, windows, desktops, tile states

• Debug logs: Smart tiling debug information

Tools

Executable tools for FVWM3 control and queries:

• fvwm_execute: Execute any FVWM command via FvwmCommand

• fvwm_get_window_info: Get window details (geometry, class, desktop)

• fvwm_get_monitor_layout: Query current monitor configuration

• fvwm_test_function: Check if FVWM function exists

• fvwm_restart: Restart FVWM3 to apply changes

• fvwm_validate_config: Basic configuration syntax validation

• fvwm_get_keybindings: List all keyboard bindings

• smart_tile_debug: View smart tiling debug logs

• smart_tile_state: View or clear window tiling states

• fvwm_get_desktop_info: Get current desktop and page info

Prompts

Templates for generating FVWM3 configurations:

• create-window-function: Generate new window manipulation functions

• add-keybinding: Create keybindings with conflict checking

• create-tiling-script: Generate bash scripts for tiling operations

• debug-fvwm-issue: Systematic debugging guide

• create-menu: Generate FVWM menu configurations

Installation

Prerequisites

• Node.js 18 or higher

• FVWM3 window manager (version 1.1.5+)

• xrandr for monitor detection

• FvwmCommand for FVWM control

Build from Source

Development Mode

Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Other MCP Clients

The server uses stdio transport and follows the MCP specification. Configure according to your client's documentation.

Usage Examples

Accessing Resources

Using Tools

Using Prompts

Architecture

Directory Structure

Resource URIs

All resources use the fvwm:// URI scheme:

• fvwm://config/* - Configuration files

• fvwm://docs/* - Documentation files

• fvwm://scripts/* - Bash scripts

• fvwm://state/* - Runtime state (dynamic)

• fvwm://logs/* - Debug and error logs

FVWM3 Context

This server is designed for a specific FVWM3 setup:

• Monitors: 3 displays (DP-4, HDMI-0, DP-2) in horizontal arrangement

• Desktops: 4 virtual desktops with 2x2 pages each

• Smart Tiling: Windows 11-style snap with monitor cycling

• Keybinding Scheme: QWAS for desktop navigation

• Theme: Dracula/Nord inspired dark theme

See fvwm://docs/claude for complete architecture documentation.

Development

Project Structure

• Resources: Read-only access to files and runtime state

  • File-based: Direct file system reads

  • Runtime: Execute commands and parse output

• Tools: Execute operations with side effects

  • FVWM commands via FvwmCommand

  • System queries via shell commands

  • State management

• Prompts: LLM-oriented templates

  • Context-aware code generation

  • Best practices included

  • Current setup details embedded

Adding New Resources

1. Add resource definition to getResources() in src/resources.ts

2. Implement handler in readResource() switch statement

3. Use appropriate MIME type (text/plain, application/json, etc.)

Adding New Tools

1. Add tool definition to getTools() in src/tools.ts

2. Define input schema with JSON Schema

3. Implement handler in executeTool() switch statement

4. Return { content: [{ type: "text", text: "..." }] }

Adding New Prompts

1. Add prompt definition to getPrompts() in src/prompts.ts

2. Define arguments with descriptions

3. Implement template in getPrompt() switch statement

4. Include relevant context from FVWM3 setup

Known Limitations

1. FVWM3 Required: Server assumes FVWM3 is installed and running

2. File Paths: Hardcoded to ~/.fvwm/ and ~/repo/utils/desktop-settings/

3. Monitor Setup: Hardcoded monitor names (DP-4, HDMI-0, DP-2)

4. No Config Validation: Basic syntax checking only, not full validation

5. Security: Executes shell commands - use in trusted environments only

Security Considerations

This server executes shell commands and FVWM commands with user privileges:

• Only use in trusted environments

• Review generated commands before execution

• Avoid exposing to untrusted networks

• File system access is limited to user's home directory

Troubleshooting

Server Won't Start

FvwmCommand Not Found

Resource Not Found

• Verify file paths in src/resources.ts match your setup

• Check that FVWM3 config exists at ~/.fvwm/config

• Ensure desktop-settings repo is at ~/repo/utils/desktop-settings/

Tool Execution Fails

• Check that FvwmCommand is accessible

• Verify FVWM3 is running and responsive

• Check debug logs: tail -f ~/.fvwm/smart-tile-debug.log

Contributing

This is a personal project tailored to a specific FVWM3 setup. If you want to adapt it:

1. Fork the repository

2. Update file paths in resources.ts and tools.ts

3. Modify monitor names in tool implementations

4. Adjust prompts to match your setup

5. Update documentation

License

MIT License - See LICENSE file for details

Related Projects

• FVWM3 - F? Virtual Window Manager

• Model Context Protocol - Protocol specification

• MCP SDK - TypeScript SDK

References

• FVWM3 Documentation

• FVWM3 Commands Manual

• MCP Specification

• Claude Desktop MCP Guide

Author

elsanchez

Version History

• 1.0.0 (2025-12-05)

  • Initial release

  • Resources: Configuration, documentation, scripts, state

  • Tools: 10 FVWM control and query tools

  • Prompts: 5 configuration generation templates

  • Smart tiling system integration