mcp-proc/docs/API.md

# API Usage Guide

## Table of Contents

- [Getting Started](#getting-started)
- [HTTP API](#http-api)
- [JSON-RPC API](#json-rpc-api)
- [SSE Events](#sse-events)
- [Examples](#examples)

## Getting Started

Start the HTTP server:

```bash
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

```bash
GET /api/cpu
```

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

#### Get Memory Information

```bash
GET /api/memory
```

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

#### Get Load Average

```bash
GET /api/load
```

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

#### Get Network Statistics

```bash
GET /api/network?interface=eth0
```

Response:
```json
{
  "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

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

Response:
```json
{
  "success": true,
  "data": "myserver\n"
}
```

#### Write ProcFS File

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

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

### Sysctl Operations

#### Read Sysctl Parameter

```bash
GET /api/sysctl/net.ipv4.ip_forward
```

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

#### Write Sysctl Parameter

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

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

#### List All Sysctl Parameters

```bash
GET /api/sysctl
```

### Process Management

#### List All Processes

```bash
GET /api/processes
```

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

#### Get Process Information

```bash
GET /api/processes/1
```

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

#### Set Process Priority

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

{
  "priority": 10
}
```

## JSON-RPC API

Send JSON-RPC requests to `/mcp/rpc`:

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

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

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

### Call a Tool

```bash
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:

```javascript
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

```bash
# 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

```javascript
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

```python
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):

```json
{
  "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:

```json
{
  "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:

```typescript
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();
});
```