205 líneas
3.9 KiB
Markdown
205 líneas
3.9 KiB
Markdown
# 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` |
|