mcp-proc/docs/API.md

API Usage Guide

Table of Contents

• Getting Started
• HTTP API
• JSON-RPC API
• SSE Events
• Examples

Getting Started

Start the HTTP server:

npm run start:sse

The server will be available at http://localhost:3000 with the following endpoints:

• /health - Health check
• /api/* - REST API endpoints
• /mcp/sse - Server-Sent Events endpoint
• /mcp/rpc - JSON-RPC endpoint
• /api-docs - Interactive Swagger documentation

HTTP API

System Information Endpoints

Get CPU Information

GET /api/cpu

Response:

{
  "success": true,
  "data": {
    "model": "Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz",
    "cores": 6,
    "processors": 12,
    "mhz": 2600.0
  }
}

Get Memory Information

GET /api/memory

Response:

{
  "success": true,
  "data": {
    "total": 16384000,
    "free": 4096000,
    "available": 8192000,
    "buffers": 512000,
    "cached": 2048000,
    "swapTotal": 4096000,
    "swapFree": 4096000
  }
}

Get Load Average

GET /api/load

Response:

{
  "success": true,
  "data": {
    "one": 1.5,
    "five": 1.2,
    "fifteen": 0.9,
    "runningProcesses": 2,
    "totalProcesses": 350
  }
}

Get Network Statistics

GET /api/network?interface=eth0

Response:

{
  "success": true,
  "data": [
    {
      "interface": "eth0",
      "rxBytes": 1048576000,
      "rxPackets": 1000000,
      "rxErrors": 0,
      "rxDropped": 0,
      "txBytes": 524288000,
      "txPackets": 500000,
      "txErrors": 0,
      "txDropped": 0
    }
  ]
}

ProcFS Operations

Read ProcFS File

GET /api/procfs?path=sys/kernel/hostname&format=raw

Response:

{
  "success": true,
  "data": "myserver\n"
}

Write ProcFS File

POST /api/procfs
Content-Type: application/json

{
  "path": "sys/kernel/hostname",
  "value": "newserver"
}

Sysctl Operations

Read Sysctl Parameter

GET /api/sysctl/net.ipv4.ip_forward

Response:

{
  "success": true,
  "data": {
    "key": "net.ipv4.ip_forward",
    "value": 0,
    "writable": true
  }
}

Write Sysctl Parameter

POST /api/sysctl
Content-Type: application/json

{
  "key": "net.ipv4.ip_forward",
  "value": 1
}

List All Sysctl Parameters

GET /api/sysctl

Process Management

List All Processes

GET /api/processes

Response:

{
  "success": true,
  "data": [1, 2, 3, 100, 101, ...]
}

Get Process Information

GET /api/processes/1

Response:

{
  "success": true,
  "data": {
    "pid": 1,
    "name": "systemd",
    "state": "S",
    "ppid": 0,
    "threads": 1,
    "vmSize": 168960,
    "vmRss": 13312
  }
}

Set Process Priority

POST /api/processes/12345/priority
Content-Type: application/json

{
  "priority": 10
}

JSON-RPC API

Send JSON-RPC requests to /mcp/rpc:

POST /mcp/rpc
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_cpu_info",
        "description": "Get CPU information"
      },
      ...
    ]
  }
}

Call a Tool

POST /mcp/rpc
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_cpu_info",
    "arguments": {}
  }
}

SSE Events

Connect to the SSE endpoint to receive real-time updates:

const eventSource = new EventSource('http://localhost:3000/mcp/sse');

eventSource.addEventListener('connected', (event) => {
  console.log('Connected:', JSON.parse(event.data));
});

eventSource.onerror = (error) => {
  console.error('Error:', error);
};

Examples

cURL Examples

# Health check
curl http://localhost:3000/health

# Get CPU info
curl http://localhost:3000/api/cpu

# Get memory info
curl http://localhost:3000/api/memory

# Read sysctl
curl http://localhost:3000/api/sysctl/kernel.hostname

# Write sysctl (requires permissions)
curl -X POST http://localhost:3000/api/sysctl \
  -H "Content-Type: application/json" \
  -d '{"key":"net.ipv4.ip_forward","value":1}'

# Get process info
curl http://localhost:3000/api/processes/1

JavaScript/Node.js Example

const fetch = require('node-fetch');

async function getCPUInfo() {
  const response = await fetch('http://localhost:3000/api/cpu');
  const data = await response.json();
  console.log(data);
}

getCPUInfo();

Python Example

import requests

response = requests.get('http://localhost:3000/api/cpu')
data = response.json()
print(data)

Using with MCP Client

Configure your MCP client (e.g., Claude Desktop):

{
  "mcpServers": {
    "procfs": {
      "command": "node",
      "args": ["/path/to/mcp-proc/dist/cli.js"]
    }
  }
}

Then use the tools in your MCP client:

Get CPU information using the procfs server

The client will automatically call the appropriate tool and format the response.

Error Handling

All endpoints return errors in a consistent format:

{
  "success": false,
  "error": "Error message here"
}

HTTP status codes:

• 200 - Success
• 400 - Bad Request (invalid parameters)
• 403 - Forbidden (insufficient permissions)
• 404 - Not Found
• 500 - Internal Server Error

Rate Limiting

Currently no rate limiting is implemented. For production use, consider adding rate limiting middleware.

Authentication

Currently no authentication is required. For production use, implement authentication using:

• API keys
• JWT tokens
• OAuth 2.0
• Basic Auth

Example with API key middleware:

app.use((req, res, next) => {
  const apiKey = req.headers['x-api-key'];
  if (apiKey !== process.env.API_KEY) {
    return res.status(403).json({ error: 'Invalid API key' });
  }
  next();
});