333 líneas
8.4 KiB
Markdown
333 líneas
8.4 KiB
Markdown
# MCP ProcFS Server
|
|
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](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
|