noackjona-hash/system-media-control-mcp

1. Overall shape

- This repo is a two-process Node.js MCP automation system for Windows.

- client.js is the user-facing orchestrator and AI broker.

- server.js is the Windows tool executor that exposes MCP tools.

2. Primary boundary

- The key architectural boundary is between the AI-facing client and the OS-facing server.

- They communicate over MCP / JSON-RPC using stdin/stdout, with the client spawning the server as a child process.

3. Client subsystem

- The client manages the conversation loop, command-line interaction, and tool-call mediation.

- It sends the user prompt plus the available tool schema to an AI provider, then relays any tool requests to the MCP server.

- It also supports a continuous chat mode and single-shot CLI mode.

4. AI provider abstraction

- The client can talk to multiple model backends: Gemini, OpenAI, Anthropic, or an OpenAI-compatible local endpoint such as Ollama/LM Studio.

- If no API credentials are present, it falls back to a local mock mode for offline simulation.

- This means the LLM is not embedded in the server; it is an external decision-making layer controlled by the client.

5. Server subsystem

- The server is the system-control adapter that implements the MCP tools.

- It receives tool invocations from the client and returns structured results back through stdout.

- Its job is not conversation; it is deterministic execution of Windows actions and system queries.

6. Windows integration layer

- The server relies on Windows-specific mechanisms: PowerShell, CIM, COM audio objects, clipboard access, and user32 keyboard/window emulation.

- The README notes that it can compile C# on the fly to bypass PowerShell COM binding limitations.

- This makes the server strongly platform-bound to Windows.

7. Tool categories

- The 19 tools cluster into four functional groups: system monitoring, media/desktop control, clipboard/launching, and power/process management.

- Monitoring tools query CPU, memory, disk, uptime, battery, network, GPU, and audio devices.

- Control tools modify volume, brightness, playback, power state, windows, clipboard, browser, and applications.

8. Data flow for a tool call

- User input starts in the client.

- The client sends the prompt and tool list to the AI provider.

- If the AI chooses a tool, the client converts that request into an MCP tools/call message and sends it to the server.

- The server executes the Windows action, returns the result, and the client passes that result back to the AI for the final natural-language answer.

9. Power and process control

- Power-related actions are treated as privileged OS operations with explicit actions like lock, sleep, shutdown, restart, and abort shutdown.

- Process termination is also server-side and can target either a process name or PID.

- These are separated from simple read-only status tools, which is important for diagramming trust and risk boundaries.

10. User interface and runtime

- There is no browser or GUI app in this repo; the primary interface is the terminal.

- The runtime requirement is Node.js v18+ on Windows.

- npm start launches the interactive loop, while passing a command string triggers a one-off interaction.

11. Repository structure

- The repository is intentionally small: one client entrypoint, one server entrypoint, package metadata, and the README.

- That suggests a thin application wrapper around OS automation primitives rather than a larger multi-service system.

12. What to show in an architecture diagram

- Draw two Node.js processes with a parent-child relationship.

- Put the AI provider outside the repo boundary, connected only to the client.

- Put Windows APIs / PowerShell / COM / user32 outside the server boundary as the execution target.

- Emphasize the bidirectional MCP message path between client and server, and the client’s role as the mediator between human intent, model reasoning, and OS execution.