system-health-mcp 1.0.0

package/README.md

@@ -0,0 +1,142 @@
+# System Health MCP Server
+
+A Model Context Protocol (MCP) server that provides real-time system health monitoring capabilities including CPU load, memory usage, and battery status.
+
+## Features
+
+- **Real-time CPU monitoring**: Get current CPU load percentage
+- **Memory statistics**: Track active and total memory usage
+- **Battery information**: Monitor battery level and charging status
+- **Hardware details**: GPU, network interfaces, disk usage, and Docker containers
+
+## Prerequisites
+
+- Node.js (v18 or higher recommended)
+- TypeScript
+- npm or yarn
+
+## Installation
+
+1. Clone this repository:
+
+```bash
+git clone <repository-url>
+cd system-health-mcp
+```
+
+2. Install dependencies:
+
+3. Build the TypeScript code:
+
+## Configuration
+
+To use this MCP server with an MCP-compatible client (like Claude Desktop), add the following configuration to your client's MCP settings file:
+
+```json
+{
+  "mcpServers": {
+    "system-health": {
+      "command": "node",
+      "args": ["/path/to/your/project/index.js"]
+    }
+  }
+}
+```
+
+**Important**: Replace `/path/to/your/project/index.js` with the absolute path to the built `index.js` file in your cloned repository.
+
+### Example Configuration Locations
+
+- **Claude Desktop (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Claude Desktop (Windows)**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Claude Desktop (Linux)**: `~/.config/Claude/claude_desktop_config.json`
+
+After updating the configuration, restart your MCP client for the changes to take effect.
+
+## Usage
+
+This MCP server exposes two tools for comprehensive system monitoring.
+
+### Running the Server
+
+```bash
+node index.js
+```
+
+The server communicates via stdio and is designed to be used with MCP-compatible clients.
+
+### Tool: get_system_stats
+
+Returns real-time system health information.
+
+**Response:**
+
+- `cpuLoadPercentage`: Current CPU load as a percentage
+- `memoryUsedGB`: Active memory in gigabytes
+- `memoryTotalGB`: Total system memory in gigabytes
+- `batteryLevel`: Battery percentage (or "No battery" if not applicable)
+- `isCharging`: Boolean indicating if the battery is currently charging
+
+**Example Response:**
+
+```json
+{
+  "cpuLoadPercentage": "23.45",
+  "memoryUsedGB": "8.42",
+  "memoryTotalGB": "16.00",
+  "batteryLevel": "85%",
+  "isCharging": false
+}
+```
+
+### Tool: get_hardware_details
+
+Returns detailed hardware information based on the specified category.
+
+**Parameters:**
+
+- `category` (required): One of `"graphics"`, `"network"`, `"disks"`, or `"docker"`
+
+**Categories:**
+
+- `graphics`: GPU and graphics card information
+- `network`: Network interface configurations
+- `disks`: Disk usage and filesystem information
+- `docker`: Docker container details
+
+**Example Request:**
+
+```json
+{
+  "category": "graphics"
+}
+```
+
+## Development
+
+### Project Structure
+
+- `index.ts`: Main server implementation
+- `package.json`: Project dependencies and configuration
+- `tsconfig.json`: TypeScript compiler configuration
+
+### Building
+
+```bash
+npx tsc
+```
+
+### Type Checking
+
+```bash
+npx tsc --noEmit
+```
+
+## Dependencies
+
+- `@modelcontextprotocol/sdk`: MCP SDK for building servers
+- `systeminformation`: Cross-platform system information library
+
+## License
+
+ISC

package/babel.config.mjs

@@ -0,0 +1,6 @@
+export default {
+  presets: [
+    ["@babel/preset-env", { targets: { node: "current" } }],
+    "@babel/preset-typescript",
+  ],
+};

package/index.ts

@@ -0,0 +1,213 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import si from 'systeminformation';
+import psList from 'ps-list';
+import pidusage from 'pidusage';
+import getFolderSize from 'get-folder-size';
+import fs from 'fs';
+import path from 'path';
+
+const server = new Server(
+  { name: "system-health-monitor", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+
+// Standalone handler for ListToolsRequest
+async function handleListToolsRequest() {
+  return {
+    tools: [
+      {
+        name: "get_system_stats",
+        description: "Get real-time CPU load, memory usage, and battery status",
+        inputSchema: { type: "object", properties: {} }
+      },
+      {
+        name: "get_hardware_details",
+        description: "Get detailed hardware info like GPU, Disk health, and Network config",
+        inputSchema: {
+          type: "object",
+          properties: {
+            category: {
+              type: "string",
+              enum: ["graphics", "network", "disks", "docker"]
+            }
+          }
+        }
+      },
+      {
+        name: "get_resource_hogs",
+        description: "Get top N resource hog processes by CPU usage",
+        inputSchema: {
+          type: "object",
+          properties: {
+            topN: { type: "number", default: 5 }
+          }
+        }
+      },
+      {
+        name: "get_largest_files_folders",
+        description: "Get top N largest files/folders in a directory",
+        inputSchema: {
+          type: "object",
+          properties: {
+            scanPath: { type: "string", default: "/" },
+            topN: { type: "number", default: 5 }
+          }
+        }
+      }
+    ]
+  };
+}
+
+server.setRequestHandler(ListToolsRequestSchema, handleListToolsRequest);
+
+// 2. Implement the logic
+// Standalone handler for CallToolRequest
+async function handleCallToolRequest(request: any) {
+    // Get top N resource hog processes
+    if (request.params.name === "get_resource_hogs") {
+      const { topN = 5 } = request.params.arguments || {};
+      const processes = await psList();
+      const usages = await Promise.all(
+        processes.map(async (proc) => {
+          try {
+            const stats: { cpu: number; memory: number } = await pidusage(proc.pid);
+            return {
+              ...proc,
+              cpu: stats.cpu,
+              memory: stats.memory,
+            };
+          } catch {
+            return null;
+          }
+        })
+      );
+      const validUsages = usages.filter((u): u is NonNullable<typeof u> => !!u);
+      validUsages.sort((a, b) => ((b && b.cpu) || 0) - ((a && a.cpu) || 0));
+      return {
+        content: [{ type: "text", text: JSON.stringify(validUsages.slice(0, Number(topN)), null, 2) }]
+      };
+    }
+
+    // Get top N largest files/folders in a directory
+    if (request.params.name === "get_largest_files_folders") {
+      const { scanPath = "/", topN = 5 } = request.params.arguments || {};
+      const items: { name: string; size: number; isDir: boolean }[] = [];
+      let dirents: fs.Dirent[];
+      try {
+        dirents = fs.readdirSync(scanPath as string, { withFileTypes: true });
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error reading directory: ${err}` }]
+        };
+      }
+      for (const dirent of dirents) {
+        const fullPath = path.join(scanPath as string, dirent.name);
+        try {
+          if (dirent.isDirectory()) {
+            const size = await getFolderSize(fullPath).then((result: { size: number }) => result.size);
+            items.push({ name: fullPath, size, isDir: true });
+          } else if (dirent.isFile()) {
+            const stats = fs.statSync(fullPath);
+            items.push({ name: fullPath, size: stats.size, isDir: false });
+          }
+        } catch {
+          // Ignore errors
+        }
+      }
+      items.sort((a, b) => b.size - a.size);
+      return {
+        content: [{ type: "text", text: JSON.stringify(items.slice(0, Number(topN)), null, 2) }]
+      };
+    }
+  if (request.params.name === "get_system_stats") {
+    const [cpu, mem, battery] = await Promise.all([
+      si.currentLoad(),
+      si.mem(),
+      si.battery()
+    ]);
+
+    const stats = {
+      cpuLoadPercentage: cpu.currentLoad.toFixed(2),
+      memoryUsedGB: (mem.active / 1024 / 1024 / 1024).toFixed(2),
+      memoryTotalGB: (mem.total / 1024 / 1024 / 1024).toFixed(2),
+      batteryLevel: battery.hasBattery ? `${battery.percent}%` : "No battery",
+      isCharging: battery.isCharging
+    };
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(stats, null, 2) }]
+    };
+  }
+
+  if (request.params.name === "get_hardware_details") {
+    const { category } = request.params.arguments as { category: string };
+    let data;
+
+    switch (category) {
+      case "graphics":
+        data = { graphics: await si.graphics() };
+        break;
+      case "network":
+        data = await si.networkInterfaces();
+        break;
+      case "disks":
+        data = await si.fsSize();
+        break;
+      case "docker":
+        data = await si.dockerContainers();
+        break;
+      default:
+        data = { error: "Invalid category" };
+    }
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+    };
+  }
+  throw new Error("Tool not found");
+}
+server.setRequestHandler(CallToolRequestSchema, handleCallToolRequest);
+
+
+// 3. Connect the transport
+
+
+// Single-request mode for testability
+if (process.env.TEST_MODE === '1') {
+  process.stdin.setEncoding('utf8');
+  let input = '';
+  process.stdin.on('data', (chunk) => {
+    input += chunk;
+    if (input.includes('\n')) {
+      process.stdin.pause();
+      handleInput(input.trim());
+    }
+  });
+
+  async function handleInput(line: string) {
+    try {
+      const req = JSON.parse(line);
+      let result;
+      if (req.schema === 'ListToolsRequest') {
+        result = await handleListToolsRequest();
+      } else if (req.schema === 'CallToolRequest') {
+        result = await handleCallToolRequest(req);
+      } else {
+        throw new Error('Unknown schema');
+      }
+      process.stdout.write(JSON.stringify(result) + '\n');
+      process.exit(0);
+    } catch (err: any) {
+      process.stderr.write((err && err.message ? err.message : String(err)) + '\n');
+      process.exit(1);
+    }
+  }
+} else {
+  (async () => {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+  })();
+}

package/jest.config.mjs

@@ -0,0 +1,8 @@
+export default {
+  testEnvironment: "node",
+  moduleFileExtensions: ["ts", "js", "json", "node"],
+  transform: {
+    "^.+\\.(ts|js)$": "babel-jest"
+  },
+  extensionsToTreatAsEsm: [".ts"],
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "system-health-mcp",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "mcp",
+    "system",
+    "debugging"
+  ],
+  "author": "John Van Wagenen",
+  "license": "ISC",
+  "type": "module",
+  "description": "A local MCP server to give your LLM access to hardware information.",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "get-folder-size": "^5.0.0",
+    "pidusage": "^4.0.1",
+    "ps-list": "^9.0.0",
+    "systeminformation": "^5.30.5"
+  },
+  "devDependencies": {
+    "repository": "https://github.com/jvdub/system-health-mcp",
+    "@types/node": "^25.0.10",
+    "@types/pidusage": "^2.0.5",
+    "@types/ps-list": "^6.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/test/index.edge.test.ts

@@ -0,0 +1,62 @@
+import { spawn } from 'child_process';
+import path from 'path';
+import { describe, expect, test } from '@jest/globals';
+
+describe('System Health MCP Server Edge Cases', () => {
+  const serverPath = path.resolve(__dirname, '../out/index.js');
+
+  function runServerWithInput(input: string): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const proc = spawn('node', [serverPath], { stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env, TEST_MODE: '1' } });
+      let output = '';
+      let error = '';
+      proc.stdout.on('data', (data: { toString: () => string; }) => {
+        output += data.toString();
+      });
+      proc.stderr.on('data', (data: { toString: () => string; }) => {
+        error += data.toString();
+      });
+      proc.on('close', () => {
+        if (error) reject(error);
+        else resolve(output);
+      });
+      proc.stdin.write(input);
+      proc.stdin.end();
+    });
+  }
+  it('should handle invalid tool name', async () => {
+    const request = JSON.stringify({
+      schema: 'CallToolRequest',
+      params: { name: 'nonexistent_tool', arguments: {} }
+    }) + '\n';
+    await expect(runServerWithInput(request)).rejects.toMatch(/Tool not found/);
+  });
+
+  it('should handle invalid hardware category', async () => {
+    const request = JSON.stringify({
+      schema: 'CallToolRequest',
+      params: { name: 'get_hardware_details', arguments: { category: 'invalid' } }
+    }) + '\n';
+    const output = await runServerWithInput(request);
+    expect(output).toMatch(/Invalid category/);
+  });
+
+  it('should handle unreadable directory in get_largest_files_folders', async () => {
+    const request = JSON.stringify({
+      schema: 'CallToolRequest',
+      params: { name: 'get_largest_files_folders', arguments: { scanPath: '/root/forbidden', topN: 1 } }
+    }) + '\n';
+    const output = await runServerWithInput(request);
+    expect(output).toMatch(/Error reading directory/);
+  });
+
+  it('should default to topN=5 if not provided', async () => {
+    const request = JSON.stringify({
+      schema: 'CallToolRequest',
+      params: { name: 'get_resource_hogs', arguments: {} }
+    }) + '\n';
+    const output = await runServerWithInput(request);
+    // Should return at least one process
+    expect(output).toMatch(/cpu/);
+  });
+});

package/test/index.test.ts

@@ -0,0 +1,80 @@
+import { spawn } from 'child_process';
+import path from 'path';
+import { describe, expect, test } from '@jest/globals';
+
+describe('System Health MCP Server', () => {
+  const serverPath = path.resolve(__dirname, '../out/index.js');
+
+  function runServerWithInput(input: string): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const proc = spawn('node', [serverPath], { stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env, TEST_MODE: '1' } });
+      let output = '';
+      let error = '';
+      proc.stdout.on('data', (data: { toString: () => string; }) => {
+        output += data.toString();
+      });
+      proc.stderr.on('data', (data: { toString: () => string; }) => {
+        error += data.toString();
+      });
+      proc.on('close', () => {
+        if (error) reject(error);
+        else resolve(output);
+      });
+      proc.stdin.write(input);
+      proc.stdin.end();
+    });
+  }
+  it('should list all tools', async () => {
+    const request = JSON.stringify({
+      schema: 'ListToolsRequest',
+      params: {}
+    }) + '\n';
+    const output = await runServerWithInput(request);
+    expect(output).toContain('get_system_stats');
+    expect(output).toContain('get_hardware_details');
+    expect(output).toContain('get_resource_hogs');
+    expect(output).toContain('get_largest_files_folders');
+  });
+
+  it('should return system stats', async () => {
+    const request = JSON.stringify({
+      schema: 'CallToolRequest',
+      params: { name: 'get_system_stats', arguments: {} }
+    }) + '\n';
+    const output = await runServerWithInput(request);
+    expect(output).toMatch(/cpuLoadPercentage/);
+    expect(output).toMatch(/memoryUsedGB/);
+    expect(output).toMatch(/memoryTotalGB/);
+    expect(output).toMatch(/batteryLevel/);
+    expect(output).toMatch(/isCharging/);
+  });
+
+  it('should return hardware details for graphics', async () => {
+    const request = JSON.stringify({
+      schema: 'CallToolRequest',
+      params: { name: 'get_hardware_details', arguments: { category: 'graphics' } }
+    }) + '\n';
+    const output = await runServerWithInput(request);
+    expect(output).toMatch(/graphics/);
+  });
+
+  it('should return resource hogs', async () => {
+    const request = JSON.stringify({
+      schema: 'CallToolRequest',
+      params: { name: 'get_resource_hogs', arguments: { topN: 2 } }
+    }) + '\n';
+    const output = await runServerWithInput(request);
+    expect(output).toMatch(/cpu/);
+    expect(output).toMatch(/memory/);
+  });
+
+  it('should return largest files/folders', async () => {
+    const request = JSON.stringify({
+      schema: 'CallToolRequest',
+      params: { name: 'get_largest_files_folders', arguments: { scanPath: '.', topN: 2 } }
+    }) + '\n';
+    const output = await runServerWithInput(request);
+    expect(output).toMatch(/name/);
+    expect(output).toMatch(/size/);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,46 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    // "rootDir": "./src",
+    "outDir": "./out",
+
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "nodenext",
+    "target": "esnext",
+    "types": ["node", "jest"],
+    // For nodejs:
+    // "lib": ["esnext"],
+    // "types": ["node"],
+    // and npm install -D @types/node
+
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+
+    // Style Options
+    // "noImplicitReturns": true,
+    // "noImplicitOverride": true,
+    // "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+
+    // Recommended Options
+    "strict": true,
+    "jsx": "react-jsx",
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+  }
+  ,
+  "include": ["index.ts"]
+}