PC Controller MCP Server

# Clone or download this repository
cd pc-controller-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Production mode
npm start

# Development mode (with hot reload)
npm run dev

# Watch mode (auto-rebuild on changes)
npm run watch

{
  "mcpServers": {
    "pc-controller": {
      "command": "node",
      "args": ["<path-to-repo>\\dist\\index.js"]
    }
  }
}

{
  "mcpServers": {
    "pc-controller": {
      "command": "node",
      "args": ["<path-to-repo>\\dist\\index.js"]
    }
  }
}

{
  "mcpServers": {
    "pc-controller": {
      "command": "node",
      "args": ["<path-to-repo>\\dist\\index.js"]
    }
  }
}

{
  "mcpServers": {
    "pc-controller": {
      "command": "node",
      "args": ["<path-to-repo>\\dist\\index.js"]
    }
  }
}

"Run npm install in D:\Projects\myapp"
"Execute git status"
"Check disk space with PowerShell"

"Read the contents of C:\config.json"
"Create a new file at D:\output.txt with 'Hello World'"
"List all files on my Desktop"
"Search for all .log files in D:\logs"

"Show me my system information"
"What processes are using the most memory?"
"List all running Chrome processes"

"Take a screenshot of my screen"
"Capture the screen and save it to D:\screenshots\screen.png"

"Kill the notepad process"
"Terminate process with PID 1234"

"Open https://github.com in my browser"
"Copy 'Hello World' to clipboard"
"What's currently in my clipboard?"

┌─────────────────────────────────────────────────────────────┐
│                    AI Client (Claude, Cursor, etc.)          │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              MCP Protocol (JSON-RPC 2.0)              │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼ stdio transport
┌─────────────────────────────────────────────────────────────┐
│              PC Controller MCP Server (Node.js)              │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ tools/       │  │ tools/       │  │ tools/       │      │
│  │  shell.ts    │  │  files.ts    │  │  system.ts   │      │
│  │ run_command  │  │ file_read    │  │ screen_      │      │
│  │ run_command_ │  │ file_write   │  │ capture      │      │
│  │ long         │  │ file_edit    │  │ sys_info     │      │
│  │ execute_code │  │ file_move    │  │ process_list │      │
│  │              │  │ file_info    │  │ process_kill │      │
│  │              │  │ file_tail    │  │ open_path    │      │
│  │              │  │ file_search  │  │ clipboard_*  │      │
│  │              │  │ content_     │  │ window_focus │      │
│  │              │  │ search       │  │ key_type     │      │
│  │              │  │ read_multi   │  │ notify       │      │
│  │              │  │ dir_list     │  │ zip_*        │      │
│  │              │  │ create_dir   │  │              │      │
│  │              │  │ copy_file    │  │              │      │
│  │              │  │ delete_file  │  │              │      │
│  │              │  │ preview_file │  │              │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ tools/       │  │ tools/       │  │ state.ts     │      │
│  │  sessions.ts │  │  admin.ts    │  │ helpers.ts   │      │
│  │ list_sessions│  │ config_get   │  │ (shared)     │      │
│  │ read_process_│  │ config_set   │  │              │      │
│  │ output       │  │ get_usage_   │  │              │      │
│  │ interact_    │  │ stats        │  │              │      │
│  │ with_process │  │ get_recent_  │  │              │      │
│  │              │  │ tool_calls   │  │              │      │
│  │              │  │ read_url     │  │              │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼ PowerShell / Windows API
┌─────────────────────────────────────────────────────────────┐
│                    Windows Operating System                   │
│                                                              │
│  File System │ Processes │ Registry │ Network │ Clipboard    │
└─────────────────────────────────────────────────────────────┘

# Run all tests
npm test

# Run specific test file
node test/test.js

pc_controller/
├── src/
│   ├── index.ts              # Entry point — server bootstrap & tool registration
│   ├── state.ts              # Shared state (sessions, usage stats, config)
│   ├── helpers.ts            # Shared utilities (execAsync, formatBytes, shell builder)
│   └── tools/
│       ├── shell.ts          # run_command, run_command_long, execute_code
│       ├── files.ts          # 14 file tools (read, write, edit, search, preview, ...)
│       ├── system.ts         # 12 system tools (screenshot, sys_info, processes, UI, ...)
│       ├── sessions.ts       # list_sessions, read_process_output, interact_with_process
│       └── admin.ts          # config_get/set, usage stats, recent calls, read_url
├── dist/                      # Compiled JavaScript
├── test/
│   └── test.js               # Test suite (25 tests)
├── skill/
│   ├── SKILL.md              # AI skill documentation
│   └── reference/
│       └── tools.md          # Detailed tool reference
├── config/                    # Configuration examples
│   ├── claude-desktop.json
│   ├── cursor.json
│   ├── windsurf.json
│   ├── openclaude.json
│   └── chatgpt-setup.md
├── images/
│   └── banner.png             # Project banner image
├── README.md                  # This file
├── package.json
├── tsconfig.json
└── .gitignore

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Development mode with hot reload
npm run dev

# Watch mode (auto-rebuild on changes)
npm run watch

# Run tests
npm test

# Start production server
npm start

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

# Rebuild the project
npm run build

# Check for errors
npm run dev  # Shows detailed error messages