413
docs/API.md
Archivo normal
413
docs/API.md
Archivo normal
@@ -0,0 +1,413 @@
|
||||
# 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();
|
||||
});
|
||||
```
|
||||
512
docs/DEPLOYMENT.md
Archivo normal
512
docs/DEPLOYMENT.md
Archivo normal
@@ -0,0 +1,512 @@
|
||||
# Deployment Guide
|
||||
|
||||
This guide covers deploying MCP ProcFS Server in production environments.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Linux server (Ubuntu 20.04+, Debian 11+, or similar)
|
||||
- Node.js 18 or higher
|
||||
- sudo/root access for system operations
|
||||
- systemd (for service management)
|
||||
|
||||
## Installation on Server
|
||||
|
||||
### Option 1: From npm (recommended)
|
||||
|
||||
```bash
|
||||
# Install globally
|
||||
sudo npm install -g @mcp/procfs-server
|
||||
|
||||
# Verify installation
|
||||
mcp-procfs --version
|
||||
```
|
||||
|
||||
### Option 2: From source
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/cameronrye/activitypub-mcp.git
|
||||
cd activitypub-mcp/mcp-proc
|
||||
|
||||
# Install and build
|
||||
npm install
|
||||
npm run build
|
||||
|
||||
# Link globally (optional)
|
||||
sudo npm link
|
||||
```
|
||||
|
||||
## Running as a Service
|
||||
|
||||
### systemd Service File
|
||||
|
||||
Create `/etc/systemd/system/mcp-procfs.service`:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=MCP ProcFS Server
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=mcp-procfs
|
||||
Group=mcp-procfs
|
||||
WorkingDirectory=/opt/mcp-procfs
|
||||
Environment="NODE_ENV=production"
|
||||
Environment="PORT=3000"
|
||||
ExecStart=/usr/bin/node /usr/local/lib/node_modules/@mcp/procfs-server/dist/cli-sse.js
|
||||
Restart=on-failure
|
||||
RestartSec=10
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
SyslogIdentifier=mcp-procfs
|
||||
|
||||
# Security settings
|
||||
NoNewPrivileges=true
|
||||
PrivateTmp=true
|
||||
ProtectSystem=strict
|
||||
ProtectHome=true
|
||||
ReadWritePaths=/var/log/mcp-procfs
|
||||
|
||||
# Required capabilities
|
||||
CapabilityBoundingSet=CAP_SYS_NICE CAP_SYS_ADMIN CAP_DAC_OVERRIDE
|
||||
AmbientCapabilities=CAP_SYS_NICE CAP_SYS_ADMIN CAP_DAC_OVERRIDE
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
### Setup Service
|
||||
|
||||
```bash
|
||||
# Create user
|
||||
sudo useradd -r -s /bin/false mcp-procfs
|
||||
|
||||
# Create working directory
|
||||
sudo mkdir -p /opt/mcp-procfs
|
||||
sudo chown mcp-procfs:mcp-procfs /opt/mcp-procfs
|
||||
|
||||
# Create log directory
|
||||
sudo mkdir -p /var/log/mcp-procfs
|
||||
sudo chown mcp-procfs:mcp-procfs /var/log/mcp-procfs
|
||||
|
||||
# Reload systemd
|
||||
sudo systemctl daemon-reload
|
||||
|
||||
# Enable and start service
|
||||
sudo systemctl enable mcp-procfs
|
||||
sudo systemctl start mcp-procfs
|
||||
|
||||
# Check status
|
||||
sudo systemctl status mcp-procfs
|
||||
|
||||
# View logs
|
||||
sudo journalctl -u mcp-procfs -f
|
||||
```
|
||||
|
||||
## Nginx Reverse Proxy
|
||||
|
||||
### Install Nginx
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install nginx
|
||||
```
|
||||
|
||||
### Configure Nginx
|
||||
|
||||
Create `/etc/nginx/sites-available/mcp-procfs`:
|
||||
|
||||
```nginx
|
||||
upstream mcp_procfs {
|
||||
server 127.0.0.1:3000;
|
||||
keepalive 64;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 80;
|
||||
server_name procfs.example.com;
|
||||
|
||||
# Redirect to HTTPS
|
||||
return 301 https://$server_name$request_uri;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name procfs.example.com;
|
||||
|
||||
# SSL certificates (use Let's Encrypt)
|
||||
ssl_certificate /etc/letsencrypt/live/procfs.example.com/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/procfs.example.com/privkey.pem;
|
||||
|
||||
# SSL configuration
|
||||
ssl_protocols TLSv1.2 TLSv1.3;
|
||||
ssl_ciphers HIGH:!aNULL:!MD5;
|
||||
ssl_prefer_server_ciphers on;
|
||||
|
||||
# Security headers
|
||||
add_header Strict-Transport-Security "max-age=31536000" always;
|
||||
add_header X-Frame-Options "SAMEORIGIN" always;
|
||||
add_header X-Content-Type-Options "nosniff" always;
|
||||
|
||||
# Rate limiting
|
||||
limit_req_zone $binary_remote_addr zone=mcp_limit:10m rate=10r/s;
|
||||
limit_req zone=mcp_limit burst=20 nodelay;
|
||||
|
||||
# Proxy settings
|
||||
location / {
|
||||
proxy_pass http://mcp_procfs;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection 'upgrade';
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_cache_bypass $http_upgrade;
|
||||
|
||||
# SSE configuration
|
||||
proxy_buffering off;
|
||||
proxy_cache off;
|
||||
proxy_read_timeout 86400;
|
||||
}
|
||||
|
||||
# API documentation
|
||||
location /api-docs {
|
||||
proxy_pass http://mcp_procfs/api-docs;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
}
|
||||
|
||||
# Health check
|
||||
location /health {
|
||||
proxy_pass http://mcp_procfs/health;
|
||||
access_log off;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Enable Site
|
||||
|
||||
```bash
|
||||
# Create symlink
|
||||
sudo ln -s /etc/nginx/sites-available/mcp-procfs /etc/nginx/sites-enabled/
|
||||
|
||||
# Test configuration
|
||||
sudo nginx -t
|
||||
|
||||
# Reload Nginx
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
## SSL/TLS with Let's Encrypt
|
||||
|
||||
```bash
|
||||
# Install certbot
|
||||
sudo apt install certbot python3-certbot-nginx
|
||||
|
||||
# Obtain certificate
|
||||
sudo certbot --nginx -d procfs.example.com
|
||||
|
||||
# Auto-renewal is set up automatically
|
||||
# Test renewal
|
||||
sudo certbot renew --dry-run
|
||||
```
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
Create `/opt/mcp-procfs/.env`:
|
||||
|
||||
```bash
|
||||
NODE_ENV=production
|
||||
PORT=3000
|
||||
LOG_LEVEL=info
|
||||
```
|
||||
|
||||
Update systemd service to use env file:
|
||||
|
||||
```ini
|
||||
[Service]
|
||||
EnvironmentFile=/opt/mcp-procfs/.env
|
||||
```
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Prometheus Metrics (future enhancement)
|
||||
|
||||
The server can be extended to expose metrics:
|
||||
|
||||
```typescript
|
||||
// Add to server-sse.ts
|
||||
import promClient from 'prom-client';
|
||||
|
||||
const register = new promClient.Registry();
|
||||
const httpRequestDuration = new promClient.Histogram({
|
||||
name: 'http_request_duration_seconds',
|
||||
help: 'Duration of HTTP requests in seconds',
|
||||
labelNames: ['method', 'route', 'status'],
|
||||
});
|
||||
register.registerMetric(httpRequestDuration);
|
||||
|
||||
app.get('/metrics', async (req, res) => {
|
||||
res.set('Content-Type', register.contentType);
|
||||
res.end(await register.metrics());
|
||||
});
|
||||
```
|
||||
|
||||
### Log Rotation
|
||||
|
||||
Create `/etc/logrotate.d/mcp-procfs`:
|
||||
|
||||
```
|
||||
/var/log/mcp-procfs/*.log {
|
||||
daily
|
||||
missingok
|
||||
rotate 14
|
||||
compress
|
||||
delaycompress
|
||||
notifempty
|
||||
create 0640 mcp-procfs mcp-procfs
|
||||
sharedscripts
|
||||
postrotate
|
||||
systemctl reload mcp-procfs > /dev/null 2>&1 || true
|
||||
endscript
|
||||
}
|
||||
```
|
||||
|
||||
## Security Hardening
|
||||
|
||||
### Firewall (UFW)
|
||||
|
||||
```bash
|
||||
# Allow SSH
|
||||
sudo ufw allow ssh
|
||||
|
||||
# Allow HTTP and HTTPS
|
||||
sudo ufw allow 80/tcp
|
||||
sudo ufw allow 443/tcp
|
||||
|
||||
# Enable firewall
|
||||
sudo ufw enable
|
||||
|
||||
# Check status
|
||||
sudo ufw status
|
||||
```
|
||||
|
||||
### Fail2ban (optional)
|
||||
|
||||
Create `/etc/fail2ban/filter.d/mcp-procfs.conf`:
|
||||
|
||||
```ini
|
||||
[Definition]
|
||||
failregex = ^<HOST> .* "POST /api/.*" 401
|
||||
^<HOST> .* "POST /api/.*" 403
|
||||
ignoreregex =
|
||||
```
|
||||
|
||||
Create `/etc/fail2ban/jail.d/mcp-procfs.conf`:
|
||||
|
||||
```ini
|
||||
[mcp-procfs]
|
||||
enabled = true
|
||||
port = http,https
|
||||
filter = mcp-procfs
|
||||
logpath = /var/log/nginx/access.log
|
||||
maxretry = 5
|
||||
bantime = 3600
|
||||
```
|
||||
|
||||
## Backup
|
||||
|
||||
### Configuration Backup
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# /opt/mcp-procfs/backup.sh
|
||||
|
||||
BACKUP_DIR="/var/backups/mcp-procfs"
|
||||
DATE=$(date +%Y%m%d_%H%M%S)
|
||||
|
||||
mkdir -p $BACKUP_DIR
|
||||
|
||||
# Backup configuration
|
||||
tar -czf $BACKUP_DIR/config_$DATE.tar.gz \
|
||||
/etc/systemd/system/mcp-procfs.service \
|
||||
/etc/nginx/sites-available/mcp-procfs \
|
||||
/opt/mcp-procfs/.env
|
||||
|
||||
# Keep only last 7 days
|
||||
find $BACKUP_DIR -name "config_*.tar.gz" -mtime +7 -delete
|
||||
```
|
||||
|
||||
Add to crontab:
|
||||
|
||||
```bash
|
||||
0 2 * * * /opt/mcp-procfs/backup.sh
|
||||
```
|
||||
|
||||
## Health Checks
|
||||
|
||||
### External Monitoring
|
||||
|
||||
Use services like UptimeRobot, Pingdom, or custom scripts:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# health-check.sh
|
||||
|
||||
ENDPOINT="https://procfs.example.com/health"
|
||||
RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" $ENDPOINT)
|
||||
|
||||
if [ $RESPONSE -eq 200 ]; then
|
||||
echo "OK: Server is healthy"
|
||||
exit 0
|
||||
else
|
||||
echo "ERROR: Server returned $RESPONSE"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
## Performance Tuning
|
||||
|
||||
### Node.js Options
|
||||
|
||||
Update systemd service:
|
||||
|
||||
```ini
|
||||
[Service]
|
||||
Environment="NODE_OPTIONS=--max-old-space-size=2048"
|
||||
```
|
||||
|
||||
### Nginx Tuning
|
||||
|
||||
Add to nginx.conf:
|
||||
|
||||
```nginx
|
||||
worker_processes auto;
|
||||
worker_rlimit_nofile 65535;
|
||||
|
||||
events {
|
||||
worker_connections 4096;
|
||||
use epoll;
|
||||
}
|
||||
```
|
||||
|
||||
## Scaling
|
||||
|
||||
### Horizontal Scaling with PM2
|
||||
|
||||
```bash
|
||||
# Install PM2
|
||||
npm install -g pm2
|
||||
|
||||
# Start with cluster mode
|
||||
pm2 start dist/cli-sse.js -i max --name mcp-procfs
|
||||
|
||||
# Save configuration
|
||||
pm2 save
|
||||
|
||||
# Setup startup script
|
||||
pm2 startup
|
||||
```
|
||||
|
||||
### Load Balancing
|
||||
|
||||
Update Nginx upstream:
|
||||
|
||||
```nginx
|
||||
upstream mcp_procfs {
|
||||
least_conn;
|
||||
server 127.0.0.1:3000;
|
||||
server 127.0.0.1:3001;
|
||||
server 127.0.0.1:3002;
|
||||
server 127.0.0.1:3003;
|
||||
keepalive 64;
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Service won't start
|
||||
|
||||
```bash
|
||||
# Check logs
|
||||
sudo journalctl -u mcp-procfs -n 50
|
||||
|
||||
# Check permissions
|
||||
sudo -u mcp-procfs /usr/bin/node --version
|
||||
|
||||
# Verify installation
|
||||
which node
|
||||
node --version
|
||||
```
|
||||
|
||||
### Permission errors
|
||||
|
||||
```bash
|
||||
# Grant capabilities
|
||||
sudo setcap cap_sys_nice,cap_sys_admin+ep /usr/bin/node
|
||||
|
||||
# Or run as root (not recommended)
|
||||
sudo systemctl edit mcp-procfs
|
||||
# Add: User=root
|
||||
```
|
||||
|
||||
### High memory usage
|
||||
|
||||
```bash
|
||||
# Monitor with htop
|
||||
htop
|
||||
|
||||
# Check Node.js heap
|
||||
node --expose-gc --max-old-space-size=512 dist/cli-sse.js
|
||||
```
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Updates
|
||||
|
||||
```bash
|
||||
# Stop service
|
||||
sudo systemctl stop mcp-procfs
|
||||
|
||||
# Update package
|
||||
sudo npm update -g @mcp/procfs-server
|
||||
|
||||
# Start service
|
||||
sudo systemctl start mcp-procfs
|
||||
|
||||
# Verify
|
||||
curl http://localhost:3000/health
|
||||
```
|
||||
|
||||
### Rolling Restart
|
||||
|
||||
```bash
|
||||
# With PM2
|
||||
pm2 reload mcp-procfs
|
||||
|
||||
# With systemd
|
||||
sudo systemctl restart mcp-procfs
|
||||
```
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] Server provisioned
|
||||
- [ ] Node.js installed
|
||||
- [ ] MCP ProcFS Server installed
|
||||
- [ ] systemd service configured
|
||||
- [ ] Service running and enabled
|
||||
- [ ] Nginx installed and configured
|
||||
- [ ] SSL certificates obtained
|
||||
- [ ] Firewall configured
|
||||
- [ ] Monitoring set up
|
||||
- [ ] Backups configured
|
||||
- [ ] Documentation updated
|
||||
- [ ] Team trained
|
||||
|
||||
## Support
|
||||
|
||||
For production support:
|
||||
- GitHub Issues: https://github.com/cameronrye/activitypub-mcp/issues
|
||||
- Documentation: https://github.com/cameronrye/activitypub-mcp/tree/master/mcp-proc
|
||||
319
docs/DEVELOPMENT.md
Archivo normal
319
docs/DEVELOPMENT.md
Archivo normal
@@ -0,0 +1,319 @@
|
||||
# Development Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 18 or higher
|
||||
- Linux operating system (for full functionality)
|
||||
- Basic understanding of procfs and Linux system internals
|
||||
- TypeScript knowledge
|
||||
|
||||
## Setup Development Environment
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/cameronrye/activitypub-mcp.git
|
||||
cd activitypub-mcp/mcp-proc
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Build the project
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
mcp-proc/
|
||||
├── src/
|
||||
│ ├── lib/ # Core library code
|
||||
│ │ ├── procfs-reader.ts # ProcFS reading logic
|
||||
│ │ └── procfs-writer.ts # ProcFS writing logic
|
||||
│ ├── types/ # Type definitions
|
||||
│ │ ├── procfs.ts # ProcFS types
|
||||
│ │ ├── mcp.ts # MCP protocol types
|
||||
│ │ └── schemas.ts # Zod validation schemas
|
||||
│ ├── server.ts # MCP JSON-RPC server
|
||||
│ ├── server-sse.ts # HTTP/SSE server
|
||||
│ ├── cli.ts # CLI for JSON-RPC server
|
||||
│ ├── cli-sse.ts # CLI for HTTP server
|
||||
│ └── index.ts # Main exports
|
||||
├── examples/ # Usage examples
|
||||
├── scripts/ # Build and setup scripts
|
||||
├── tests/ # Test files
|
||||
└── docs/ # Documentation
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Running in Development Mode
|
||||
|
||||
```bash
|
||||
# Watch mode with hot reload
|
||||
npm run dev
|
||||
|
||||
# For HTTP/SSE server
|
||||
npm run start:sse
|
||||
```
|
||||
|
||||
### Building
|
||||
|
||||
```bash
|
||||
# Compile TypeScript
|
||||
npm run build
|
||||
|
||||
# Clean build
|
||||
rm -rf dist/ && npm run build
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
npm test
|
||||
|
||||
# Watch mode
|
||||
npm run test:watch
|
||||
|
||||
# Coverage report
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
### Linting and Formatting
|
||||
|
||||
```bash
|
||||
# Check code style
|
||||
npm run lint
|
||||
|
||||
# Format code
|
||||
npm run format
|
||||
```
|
||||
|
||||
## Adding New Features
|
||||
|
||||
### Adding a New ProcFS Reader
|
||||
|
||||
1. Add the method to `src/lib/procfs-reader.ts`:
|
||||
|
||||
```typescript
|
||||
async getNewMetric(): Promise<NewMetricType> {
|
||||
const content = await this.readRaw('path/to/file');
|
||||
// Parse content
|
||||
return parsedData;
|
||||
}
|
||||
```
|
||||
|
||||
2. Add the type definition in `src/types/procfs.ts`:
|
||||
|
||||
```typescript
|
||||
export interface NewMetricType {
|
||||
field1: string;
|
||||
field2: number;
|
||||
}
|
||||
```
|
||||
|
||||
3. Add validation schema in `src/types/schemas.ts`:
|
||||
|
||||
```typescript
|
||||
export const NewMetricRequestSchema = z.object({
|
||||
param: z.string(),
|
||||
});
|
||||
```
|
||||
|
||||
4. Add tool definition in `src/server.ts`:
|
||||
|
||||
```typescript
|
||||
{
|
||||
name: 'get_new_metric',
|
||||
description: 'Get new metric',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
param: { type: 'string' }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
5. Add HTTP endpoint in `src/server-sse.ts`:
|
||||
|
||||
```typescript
|
||||
this.app.get('/api/new-metric', async (req, res) => {
|
||||
try {
|
||||
const data = await this.reader.getNewMetric();
|
||||
res.json({ success: true, data });
|
||||
} catch (error) {
|
||||
res.status(500).json({
|
||||
success: false,
|
||||
error: (error as Error).message
|
||||
});
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Adding Tests
|
||||
|
||||
Create test file in `tests/`:
|
||||
|
||||
```typescript
|
||||
import { ProcFSReader } from '../src/lib/procfs-reader';
|
||||
|
||||
describe('ProcFSReader', () => {
|
||||
let reader: ProcFSReader;
|
||||
|
||||
beforeEach(() => {
|
||||
reader = new ProcFSReader();
|
||||
});
|
||||
|
||||
test('should read CPU info', async () => {
|
||||
const info = await reader.getCPUInfo();
|
||||
expect(info).toHaveProperty('model');
|
||||
expect(info).toHaveProperty('cores');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Code Style Guidelines
|
||||
|
||||
- Use TypeScript strict mode
|
||||
- Follow ESLint rules
|
||||
- Use Prettier for formatting
|
||||
- Add JSDoc comments for public APIs
|
||||
- Use async/await for asynchronous code
|
||||
- Handle errors gracefully
|
||||
- Validate inputs with Zod schemas
|
||||
|
||||
## Debugging
|
||||
|
||||
### Debug MCP Server
|
||||
|
||||
```bash
|
||||
# With debug output
|
||||
DEBUG=* npm start
|
||||
```
|
||||
|
||||
### Debug HTTP Server
|
||||
|
||||
```bash
|
||||
# Check server logs
|
||||
npm run start:sse
|
||||
|
||||
# Test endpoints
|
||||
curl http://localhost:3000/health
|
||||
```
|
||||
|
||||
### Using VS Code Debugger
|
||||
|
||||
Create `.vscode/launch.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"type": "node",
|
||||
"request": "launch",
|
||||
"name": "Debug Server",
|
||||
"program": "${workspaceFolder}/src/cli.ts",
|
||||
"preLaunchTask": "npm: build",
|
||||
"outFiles": ["${workspaceFolder}/dist/**/*.js"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Permission Errors
|
||||
|
||||
Some operations require elevated permissions:
|
||||
|
||||
```bash
|
||||
# Run with sudo (not recommended for development)
|
||||
sudo npm start
|
||||
|
||||
# Better: Use capabilities
|
||||
sudo setcap cap_sys_nice,cap_sys_admin+ep $(which node)
|
||||
```
|
||||
|
||||
### TypeScript Errors
|
||||
|
||||
```bash
|
||||
# Clean and rebuild
|
||||
rm -rf dist/ node_modules/
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
```bash
|
||||
# Change port
|
||||
PORT=8080 npm run start:sse
|
||||
|
||||
# Kill process using port 3000
|
||||
lsof -ti:3000 | xargs kill -9
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Add tests
|
||||
5. Run linting and tests
|
||||
6. Submit a pull request
|
||||
|
||||
### Commit Message Format
|
||||
|
||||
```
|
||||
type(scope): subject
|
||||
|
||||
body
|
||||
|
||||
footer
|
||||
```
|
||||
|
||||
Types:
|
||||
- `feat`: New feature
|
||||
- `fix`: Bug fix
|
||||
- `docs`: Documentation
|
||||
- `style`: Formatting
|
||||
- `refactor`: Code restructuring
|
||||
- `test`: Adding tests
|
||||
- `chore`: Maintenance
|
||||
|
||||
Example:
|
||||
```
|
||||
feat(procfs): add disk temperature reading
|
||||
|
||||
Add support for reading disk temperature from /sys/class/hwmon.
|
||||
Includes new getDiskTemperature() method in ProcFSReader.
|
||||
|
||||
Closes #123
|
||||
```
|
||||
|
||||
## Release Process
|
||||
|
||||
1. Update version in `package.json`
|
||||
2. Update `CHANGELOG.md`
|
||||
3. Run tests: `npm test`
|
||||
4. Build: `npm run build`
|
||||
5. Commit changes
|
||||
6. Create git tag: `git tag v1.0.0`
|
||||
7. Push: `git push --follow-tags`
|
||||
8. Publish: `npm publish`
|
||||
|
||||
Or use the release script:
|
||||
|
||||
```bash
|
||||
./scripts/release.sh 1.0.0
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [MCP Specification](https://modelcontextprotocol.io)
|
||||
- [TypeScript Documentation](https://www.typescriptlang.org/docs/)
|
||||
- [Express.js Guide](https://expressjs.com/en/guide/routing.html)
|
||||
- [Zod Documentation](https://zod.dev/)
|
||||
- [Jest Testing Framework](https://jestjs.io/)
|
||||
204
docs/QUICKSTART.md
Archivo normal
204
docs/QUICKSTART.md
Archivo normal
@@ -0,0 +1,204 @@
|
||||
# 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` |
|
||||
Referencia en una nueva incidencia
Block a user