# Quick Start Guide

## Installation

### Option 1: From npm (when published)

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

### Option 2: From source

```bash
git clone https://github.com/cameronrye/activitypub-mcp.git
cd activitypub-mcp/mcp-proc
./scripts/setup.sh
```

## First Run

### JSON-RPC Server (stdio)

```bash
# Using global install
mcp-procfs

# Or from source
npm start
```

### HTTP Server with SSE

```bash
# Default port 3000
npm run start:sse

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

Open browser to http://localhost:3000/api-docs to explore the API.

## Basic Usage Examples

### Get System Information

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

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

# Load average
curl http://localhost:3000/api/load

# Network statistics
curl http://localhost:3000/api/network
```

### Process Management

```bash
# List all processes
curl http://localhost:3000/api/processes

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

# Set process priority (requires permissions)
curl -X POST http://localhost:3000/api/processes/1234/priority \
  -H "Content-Type: application/json" \
  -d '{"priority": 10}'
```

### Sysctl Operations

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

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

## Using with MCP Client

### Claude Desktop Configuration

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

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

Then restart Claude Desktop and use natural language:

```
"What's the current CPU usage?"
"Show me memory statistics"
"List all running processes"
"What's the system load average?"
```

## Common Tasks

### Monitor System Resources

```bash
# Real-time monitoring
node examples/monitoring-dashboard.js
```

### Read Custom ProcFS Files

```bash
curl "http://localhost:3000/api/procfs?path=sys/kernel/hostname&format=raw"
```

### Adjust System Parameters

```bash
# Check current value
curl http://localhost:3000/api/sysctl/vm.swappiness

# Change value (requires root)
sudo curl -X POST http://localhost:3000/api/sysctl \
  -H "Content-Type: application/json" \
  -d '{"key": "vm.swappiness", "value": 10}'
```

## Troubleshooting

### Permission Denied

Some operations require elevated permissions:

```bash
# Option 1: Run with sudo (not recommended)
sudo npm run start:sse

# Option 2: Use capabilities
sudo setcap cap_sys_nice,cap_sys_admin+ep $(which node)
npm run start:sse
```

### Port Already in Use

```bash
# Use different port
PORT=8080 npm run start:sse

# Or kill existing process
lsof -ti:3000 | xargs kill -9
```

### Cannot Read /proc Files

Ensure you're running on Linux:

```bash
uname -s  # Should output: Linux
```

Check file permissions:

```bash
ls -la /proc/cpuinfo
cat /proc/cpuinfo
```

## Next Steps

- Read the full [API Documentation](docs/API.md)
- Check out [Examples](examples/)
- Learn about [Development](docs/DEVELOPMENT.md)
- Review [Security Considerations](README.md#security-considerations)

## Getting Help

- Issues: https://github.com/cameronrye/activitypub-mcp/issues
- Discussions: https://github.com/cameronrye/activitypub-mcp/discussions
- Documentation: https://github.com/cameronrye/activitypub-mcp/tree/master/mcp-proc

## Quick Reference

| Task | Command |
|------|---------|
| Start JSON-RPC server | `mcp-procfs` or `npm start` |
| Start HTTP server | `npm run start:sse` |
| View API docs | http://localhost:3000/api-docs |
| Get CPU info | `curl localhost:3000/api/cpu` |
| Get memory info | `curl localhost:3000/api/memory` |
| List processes | `curl localhost:3000/api/processes` |
| Read sysctl | `curl localhost:3000/api/sysctl/KEY` |
| Health check | `curl localhost:3000/health` |