elsanchez/mcp-server-fvwm3

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

# Clone the repository
git clone https://github.com/elsanchez/mcp-server-fvwm3.git
cd mcp-server-fvwm3

# Install dependencies
npm install

# Build
npm run build

# The server binary will be at build/index.js

Development Mode

# Watch mode (rebuild on changes)
npm run watch

# Run in development mode with source maps
npm run dev

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

{
  "mcpServers": {
    "fvwm3": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-fvwm3/build/index.js"]
    }
  }
}

Other MCP Clients

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

Usage Examples

Accessing Resources

// Read main FVWM configuration
const config = await readResource("fvwm://config/main");

// Get smart tiling documentation
const docs = await readResource("fvwm://docs/smart-tiling");

// Check current monitor layout
const monitors = await readResource("fvwm://state/monitors");

// View tile states for all windows
const states = await readResource("fvwm://state/tile-states");

Using Tools

// Execute FVWM command
await executeTool("fvwm_execute", {
  command: "Restart"
});

// Get info about specific window
await executeTool("fvwm_get_window_info", {
  window_id: "0x9200005"
});

// View last 100 lines of debug log
await executeTool("smart_tile_debug", {
  lines: 100
});

// Clear all tile states
await executeTool("smart_tile_state", {
  action: "clear"
});

Using Prompts

// Generate a new window function
await getPrompt("create-window-function", {
  function_name: "MoveToCenterAndResize",
  description: "move the window to the center of the current monitor and resize to 80% width and height"
});

// Add a keybinding with conflict checking
await getPrompt("add-keybinding", {
  key_combo: "Super_L+m",
  action: "maximize the current window on its current monitor",
  context: "W"
});

// Debug an issue
await getPrompt("debug-fvwm-issue", {
  issue_description: "windows are not tiling correctly on the second monitor"
});

Architecture

Directory Structure

mcp-server-fvwm3/
├── src/
│   ├── index.ts       # Main server entry point
│   ├── resources.ts   # Resource handlers
│   ├── tools.ts       # Tool implementations
│   └── prompts.ts     # Prompt templates
├── build/             # Compiled JavaScript (generated)
├── package.json       # npm configuration
├── tsconfig.json      # TypeScript configuration
└── README.md          # This file

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

# Check Node.js version
node --version  # Should be 18+

# Check build output
npm run build

# Run in dev mode to see errors
npm run dev

FvwmCommand Not Found

# Check FVWM3 installation
which FvwmCommand
fvwm3 --version

# Ensure FVWM3 is running
ps aux | grep fvwm3

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