# noackjona-hash/system-media-control-mcp architecture

> Architecture diagram of the GitHub repository noackjona-hash/system-media-control-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/noackjona-hash/system-media-control-mcp
- Repository: https://github.com/noackjona-hash/system-media-control-mcp

## Overview

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.

Main entry points: [`client.js`](https://github.com/noackjona-hash/system-media-control-mcp/blob/main/client.js) (Client), [`server.js`](https://github.com/noackjona-hash/system-media-control-mcp/blob/main/server.js) (Server), [`README.md`](https://github.com/noackjona-hash/system-media-control-mcp/blob/main/README.md) (README), [`package.json`](https://github.com/noackjona-hash/system-media-control-mcp/blob/main/package.json) (Package)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Repo"]
  node_readme["README<br/>docs<br/>[README.md]"]
  node_pkg["Package<br/>npm metadata<br/>[package.json]"]
  node_mcp_wire(("MCP wire<br/>json-rpc"))
end

subgraph group_client["Client"]
  node_client_entry["Client<br/>node entrypoint<br/>[client.js]"]
  node_client_mode(("Chat mode<br/>cli flow"))
  node_prompt_loop(("Prompt loop<br/>orchestration"))
  node_ai_router["AI router<br/>model adapter"]
  node_tool_mediator["Tool mediator<br/>mcp bridge"]
  node_child_spawn(("Child process<br/>process control"))
end

subgraph group_server["Server"]
  node_server_entry["Server<br/>node entrypoint<br/>[server.js]"]
  node_mcp_tools["Tool host<br/>mcp server"]
  node_monitoring["Monitoring<br/>read-only tools"]
  node_control["Desktop control<br/>action tools"]
  node_power_proc["Power/process<br/>privileged tools"]
end

subgraph group_external["External"]
  node_win_api[("Windows APIs<br/>platform runtime")]
  node_ai_backends[("Model backends<br/>llm providers")]
end

node_readme -->|"documents"| node_client_entry
node_readme -->|"documents"| node_server_entry
node_pkg -->|"starts"| node_client_entry
node_client_entry -->|"runs"| node_client_mode
node_client_mode -->|"drives"| node_prompt_loop
node_prompt_loop -->|"sends prompt"| node_ai_router
node_ai_router -->|"calls"| node_ai_backends
node_ai_backends -->|"responses"| node_ai_router
node_ai_router -->|"tool request"| node_tool_mediator
node_tool_mediator -->|"spawns"| node_child_spawn
node_child_spawn -->|"connects"| node_mcp_wire
node_mcp_wire -->|"receives"| node_server_entry
node_server_entry -->|"hosts"| node_mcp_tools
node_mcp_tools -->|"queries"| node_monitoring
node_mcp_tools -->|"controls"| node_control
node_mcp_tools -->|"manages"| node_power_proc
node_monitoring -->|"uses"| node_win_api
node_control -->|"uses"| node_win_api
node_power_proc -->|"uses"| node_win_api
node_mcp_tools -->|"returns results"| node_mcp_wire
node_tool_mediator -->|"returns result"| node_ai_router

click node_readme "https://github.com/noackjona-hash/system-media-control-mcp/blob/main/README.md"
click node_pkg "https://github.com/noackjona-hash/system-media-control-mcp/blob/main/package.json"
click node_client_entry "https://github.com/noackjona-hash/system-media-control-mcp/blob/main/client.js"
click node_server_entry "https://github.com/noackjona-hash/system-media-control-mcp/blob/main/server.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_pkg,node_mcp_wire toneBlue
class node_client_entry,node_client_mode,node_prompt_loop,node_ai_router,node_tool_mediator,node_child_spawn toneAmber
class node_server_entry,node_mcp_tools,node_monitoring,node_control,node_power_proc toneMint
class node_win_api,node_ai_backends toneRose
```

## Components

### Repo

Node.js MCP automation system

- [README](https://github.com/noackjona-hash/system-media-control-mcp/blob/main/README.md): docs · Usage and architecture overview · `README.md`
- [Package](https://github.com/noackjona-hash/system-media-control-mcp/blob/main/package.json): npm metadata · Scripts and runtime entrypoints · `package.json`
- **MCP wire**: json-rpc · stdin/stdout transport between processes

### Client

User-facing orchestrator and AI broker

- [Client](https://github.com/noackjona-hash/system-media-control-mcp/blob/main/client.js): node entrypoint · Interactive CLI and conversation loop · `client.js`
- **Chat mode**: cli flow · Single-shot and continuous command handling
- **Prompt loop**: orchestration · Collects user input and drives turns
- **AI router**: model adapter · Selects backend and formats requests
- **Tool mediator**: mcp bridge · Translates model tool calls to MCP messages
- **Child process**: process control · Starts the server as a subprocess

### Server

Windows tool executor

- [Server](https://github.com/noackjona-hash/system-media-control-mcp/blob/main/server.js): node entrypoint · MCP tool host for Windows actions · `server.js`
- **Tool host**: mcp server · Receives tools/list and tools/call
- **Monitoring**: read-only tools · CPU, memory, disk, battery, GPU, network, uptime, audio info
- **Desktop control**: action tools · Volume, brightness, playback, browser, clipboard, windows, apps
- **Power/process**: privileged tools · Sleep, shutdown, restart, lock, abort, terminate process

### External

Model backends and Windows platform APIs

- **Windows APIs**: platform runtime · PowerShell, CIM, COM, clipboard, user32, on-the-fly C#
- **Model backends**: llm providers · Gemini, OpenAI, Anthropic, or compatible local endpoints

## Connections

- README → Client: documents · Explains CLI usage and orchestration
- README → Server: documents · Explains Windows tool host
- Package → Client: starts · npm start launches the client
- Client → Chat mode: runs · Interactive or one-off command mode
- Chat mode → Prompt loop: drives · Manages turn-by-turn conversation
- Prompt loop → AI router: sends prompt · Provides user input and tool schema
- AI router → Model backends: calls · Uses remote or local model provider
- Model backends → AI router: responses · Returns model text and tool requests
- AI router → Tool mediator: tool request · Hands off function-call style actions
- Tool mediator → Child process: spawns · Creates the server process
- Child process → MCP wire: connects · Wires stdin/stdout transport
- MCP wire → Server: receives · Server reads MCP messages
- Server → Tool host: hosts · Registers and dispatches tools
- Tool host → Monitoring: queries · Read-only system status tools
- Tool host → Desktop control: controls · Media, clipboard, window and app actions
- Tool host → Power/process: manages · Power state and process control
- Monitoring → Windows APIs: uses · Reads Windows system interfaces
- Desktop control → Windows APIs: uses · Calls Windows control surfaces
- Power/process → Windows APIs: uses · Executes privileged OS operations
- Tool host → MCP wire: returns results · Structured tool output back to client
- Tool mediator → AI router: returns result · Feeds tool output back for final answer