# MCP ProcFS Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)

A powerful [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for reading and modifying Linux `/proc` filesystem values. Provides both JSON-RPC (stdio) and Server-Sent Events (SSE) interfaces with full Swagger API documentation.

## Features

- 🔍 **Comprehensive ProcFS Access**: Read and write to `/proc` filesystem
- 🎛️ **System Monitoring**: CPU, memory, load, network, and disk statistics
- ⚙️ **Sysctl Management**: Read and modify kernel parameters
- 🔧 **Process Control**: Monitor and manage processes (priority, affinity, signals)
- 📡 **Dual Protocols**: JSON-RPC over stdio and HTTP with SSE
- 📚 **Full API Documentation**: Interactive Swagger UI
- 🔐 **Type-Safe**: Written in TypeScript with comprehensive type definitions
- ✅ **Validated**: Zod schemas for request/response validation

## Installation

### From npm

```bash
npm install -g @mcp/procfs-server
```

### From source

```bash
git clone https://github.com/user/mcp-proc.git
cd mcp-proc
npm install
npm run build
```

## Quick Start

### JSON-RPC Server (stdio)

```bash
# Start the MCP server on stdio
mcp-procfs

# Or with npm
npm start
```

### HTTP Server with SSE

```bash
# Start HTTP server on port 3000
npm run start:sse

# Custom port
PORT=8080 npm run start:sse
```

Then open your browser to:
- **API Documentation**: http://localhost:3000/api-docs
- **SSE Endpoint**: http://localhost:3000/mcp/sse
- **RPC Endpoint**: http://localhost:3000/mcp/rpc

## Usage

### As MCP Tool

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

```json
{
  "mcpServers": {
    "procfs": {
      "command": "mcp-procfs"
    }
  }
}
```

### Available Tools

#### System Information

- **get_cpu_info**: Get detailed CPU information
- **get_memory_info**: Get memory statistics
- **get_load_average**: Get system load average
- **get_network_stats**: Get network interface statistics
- **get_disk_stats**: Get disk I/O statistics

#### ProcFS Operations

- **read_procfs**: Read any file from `/proc`
- **write_procfs**: Write to writable `/proc` files

#### Process Management

- **get_process_info**: Get detailed process information
- **list_processes**: List all process IDs
- **set_process_priority**: Change process nice value
- **set_process_affinity**: Set CPU affinity

#### Sysctl Management

- **read_sysctl**: Read kernel parameter
- **write_sysctl**: Modify kernel parameter
- **list_sysctl**: List all parameters

### Example: Using HTTP API

```bash
# Get CPU information
curl http://localhost:3000/api/cpu

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

# Read a sysctl parameter
curl http://localhost:3000/api/sysctl/net.ipv4.ip_forward

# Write a sysctl parameter (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 information
curl http://localhost:3000/api/processes/1

# Read custom procfs file
curl "http://localhost:3000/api/procfs?path=sys/kernel/hostname"
```

### Example: Using JSON-RPC

```typescript
import { MCPProcFSServer } from '@mcp/procfs-server';

const server = new MCPProcFSServer();
await server.run();
```

### Example: Direct Library Usage

```typescript
import { ProcFSReader, ProcFSWriter } from '@mcp/procfs-server';

const reader = new ProcFSReader();
const writer = new ProcFSWriter();

// Get CPU info
const cpuInfo = await reader.getCPUInfo();
console.log(cpuInfo);

// Get memory info
const memInfo = await reader.getMemInfo();
console.log(memInfo);

// Read sysctl
const param = await writer.readSysctl('net.ipv4.ip_forward');
console.log(param);

// Write sysctl (requires root)
await writer.writeSysctl('net.ipv4.ip_forward', 1);
```

## API Documentation

When running the HTTP server, full interactive API documentation is available at:

**http://localhost:3000/api-docs**

The documentation includes:
- All endpoints with request/response schemas
- Try-it-out functionality
- Example requests and responses
- Authentication requirements

### API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/health` | Health check |
| GET | `/api/cpu` | CPU information |
| GET | `/api/memory` | Memory information |
| GET | `/api/load` | Load average |
| GET | `/api/network` | Network statistics |
| GET | `/api/disk` | Disk statistics |
| GET | `/api/procfs` | Read procfs file |
| POST | `/api/procfs` | Write procfs file |
| GET | `/api/sysctl` | List sysctl parameters |
| GET | `/api/sysctl/:key` | Read sysctl parameter |
| POST | `/api/sysctl` | Write sysctl parameter |
| GET | `/api/processes` | List all processes |
| GET | `/api/processes/:pid` | Get process info |
| POST | `/api/processes/:pid/priority` | Set process priority |
| GET | `/mcp/sse` | SSE endpoint |
| POST | `/mcp/rpc` | JSON-RPC endpoint |

## MCP Resources

The server exposes the following MCP resources:

- `procfs://cpuinfo` - CPU information
- `procfs://meminfo` - Memory information
- `procfs://loadavg` - Load average
- `procfs://net/dev` - Network statistics
- `procfs://diskstats` - Disk statistics

## Permissions

Some operations require elevated permissions:

- **Read-only operations**: Most read operations work without special permissions
- **Write operations**: Require appropriate permissions (usually root)
- **Process management**: Some operations require CAP_SYS_NICE or root
- **Sysctl writes**: Usually require root or specific capabilities

### Running with elevated permissions

```bash
# Run with sudo (not recommended for production)
sudo mcp-procfs

# Better: Use capabilities
sudo setcap cap_sys_nice,cap_sys_admin+ep $(which node)
mcp-procfs
```

## Development

### Setup

```bash
npm install
npm run build
```

### Development Mode

```bash
npm run dev  # Watch mode with hot reload
```

### Testing

```bash
npm test              # Run tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report
```

### Linting

```bash
npm run lint          # Check code
npm run format        # Format code
```

## Architecture

```
mcp-proc/
├── src/
│   ├── lib/
│   │   ├── procfs-reader.ts    # ProcFS reading logic
│   │   └── procfs-writer.ts    # ProcFS writing logic
│   ├── types/
│   │   ├── procfs.ts           # ProcFS type definitions
│   │   ├── mcp.ts              # MCP protocol types
│   │   └── schemas.ts          # Zod validation schemas
│   ├── server.ts               # MCP JSON-RPC server
│   ├── server-sse.ts           # HTTP/SSE server
│   ├── cli.ts                  # JSON-RPC CLI entry
│   ├── cli-sse.ts              # HTTP/SSE CLI entry
│   └── index.ts                # Main exports
├── scripts/
│   ├── setup.sh                # Setup script
│   ├── build.sh                # Build script
│   └── release.sh              # Release script
└── tests/                      # Test files
```

## Technology Stack

- **Runtime**: Node.js 18+
- **Language**: TypeScript
- **Validation**: Zod
- **Web Framework**: Express
- **Documentation**: Swagger/OpenAPI
- **MCP SDK**: @modelcontextprotocol/sdk
- **Testing**: Jest

## Security Considerations

⚠️ **Important Security Notes**:

1. This server provides direct access to system resources
2. Write operations can affect system behavior
3. Always run with minimum required permissions
4. Consider using read-only mode for untrusted clients
5. Implement authentication for production deployments
6. Monitor and log all write operations

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) file for details

## Resources

- [Model Context Protocol Specification](https://modelcontextprotocol.io)
- [Linux /proc Documentation](https://www.kernel.org/doc/Documentation/filesystems/proc.txt)
- [sysctl Documentation](https://www.kernel.org/doc/Documentation/sysctl/)

## Support

- **Issues**: [GitHub Issues](https://github.com/cameronrye/activitypub-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/cameronrye/activitypub-mcp/discussions)

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.

---

Made with ❤️ for the MCP community