Watch

Jonathan Hefner 9acebd7f9f

Separate static and dynamic data in system-monitor-server tools

The two-tool architecture previously had both tools returning identical
`SystemStats` data. This refactors them to properly separate concerns:

- `get-system-info` (Model-visible): Returns static system configuration
  (hostname, platform, CPU model/count, total memory) sent once via
  `ontoolresult`

- `poll-system-stats` (App-only): Returns dynamic metrics (per-core CPU
  timing, memory usage, uptime) polled every 2 seconds

Moves `formatBytes()` and `formatUptime()` utilities to the client since
the server now returns raw values for client-side formatting.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-28 11:04:35 -06:00

3.4 KiB

Raw Blame History

Example: System Monitor App

A demo MCP App that displays real-time OS metrics with a stacked area chart for per-core CPU usage and a bar gauge for memory.

MCP Client Configuration

Add to your MCP client configuration (stdio transport):

{
  "mcpServers": {
    "system-monitor": {
      "command": "npx",
      "args": [
        "-y",
        "--silent",
        "--registry=https://registry.npmjs.org/",
        "@modelcontextprotocol/server-system-monitor",
        "--stdio"
      ]
    }
  }
}

Local Development

To test local modifications, use this configuration (replace ~/code/ext-apps with your clone path):

{
  "mcpServers": {
    "system-monitor": {
      "command": "bash",
      "args": [
        "-c",
        "cd ~/code/ext-apps/examples/system-monitor-server && npm run build >&2 && node dist/index.js --stdio"
      ]
    }
  }
}

Features

Per-Core CPU Monitoring: Stacked area chart showing individual CPU core utilization over a 1-minute sliding window
Memory Usage: Horizontal bar gauge with color-coded thresholds (green/yellow/red)
System Info: Hostname, platform, and uptime display
Auto-Polling: Automatically starts monitoring on load with 2-second refresh interval
Theme Support: Adapts to light/dark mode preferences

Running

Install dependencies:
```
npm install
```

Build and start the server:

npm run start:http  # for Streamable HTTP transport
# OR
npm run start:stdio  # for stdio transport

View using the basic-host example or another MCP Apps-compatible host.

Architecture

Server (`server.ts`)

Exposes two tools demonstrating a polling pattern:

get-system-info (Model-visible) — Returns static system configuration:
- Hostname, platform, architecture
- CPU model and core count
- Total memory
poll-system-stats (App-only, visibility: ["app"]) — Returns dynamic metrics:
- Per-core CPU timing data (idle/total counters)
- Memory usage (used/free/percentage)
- Uptime

The Model-visible tool is linked to a UI resource via _meta.ui.resourceUri.

App (`src/mcp-app.ts`)

Receives static system info via ontoolresult when the host sends the get-system-info result
Polls poll-system-stats every 2 seconds for dynamic metrics
Uses Chart.js for the stacked area chart visualization
Computes CPU usage percentages client-side from timing deltas
Maintains a 30-point history (1 minute at 2s intervals)

3.4 KiB Raw Blame History