Content
# jakub's mcp tools
MCP server + web dashboard for infrastructure discovery and remote management. Exposes tools to AI agents via the [Model Context Protocol](https://modelcontextprotocol.io) for SSH command execution, file transfer, log tailing, and machine/service inventory. A companion web UI provides a browser-based dashboard for the same data.
All components — the MCP server, REST API, and dashboard — share a single SQLite database. Machines and services registered in the web UI are immediately available to the MCP tools, and commands the agent executes appear in the dashboard's activity feed.
## Docker
```bash
docker compose up -d
# → Dashboard: http://localhost:8082
```
The database is persisted in `./data` on the host. Configure your MCP client:
```json
{
"mcpServers": {
"jakubs-mcp-tools": {
"command": "docker",
"args": ["compose", "run", "--rm", "mcp"]
}
}
}
```
## Running Without Docker
```bash
# Clone and install
git clone <repo-url>
cd mcp-tools
cp .env.example .env
npm install
# Build
npm run build
# Start the dashboard + API
npm run dev:all
# → UI: http://localhost:8081
# → API: http://localhost:8082
# Run the MCP server directly
npm run dev
```
## Configuration
| Variable | Default | Description |
|----------|---------|-------------|
| `DB_PATH` | `./infra.db` | Path to the SQLite database file |
| `SSH_TIMEOUT` | `10000` | SSH connection timeout in milliseconds |
| `ALLOWLIST_ENABLED` | `true` | Set to `false` to allow any SSH command without restriction |
| `ALLOWED_COMMANDS` | *(built-in list)* | Comma-separated allowed command prefixes (overrides defaults) |
## Features
### MCP Tools (for AI agents)
| Tool | Description |
|------|-------------|
| `get_all_machines` | List all machines and their microservices |
| `get_machine_by_id` | Look up a specific machine by ID |
| `add_machine` | Register a new machine (hostname, IP, SSH key) |
| `add_service` | Register a microservice on a machine |
| `execute_ssh` | Execute a command on a remote machine via SSH |
| `scp_file` | Upload/download files via SFTP |
| `tail_logs` | Tail the last N lines of a remote log file |
- **Command allowlisting** — SSH commands are validated against a configurable allowlist. Set `ALLOWLIST_ENABLED=false` in `.env` to allow any command without restriction.
- **Audit trail** — every SSH command and SCP transfer is logged with exit code, output, and timestamp.
- **Key-based auth** — all SSH connections use registered private keys (no passwords).
### Web Dashboard
- **Dashboard** — aggregate stats, recent activity feed, most-active machines
- **Machines** — table with search, pagination, CRUD modal (hostname, OS, IP, SSH user)
- **Services** — table with search, machine filter, pagination, CRUD modal (name, URL, port, type, notes)
- **Logs** — full audit trail with search, machine/status filters, detail view with command output
- Dark theme, responsive (mobile sidebar drawer)
## CLI Usage
Each module can be run standalone for testing:
```bash
# Query machines
node dist/get_machines.js --all
node dist/get_machines.js --id 1
# Execute a command
node dist/execute_ssh.js --id 1 --cmd "docker ps"
# Transfer a file
node dist/scp.js -i 1 -d to -r /tmp/out.txt -l ./local.txt
# Tail logs
node dist/tail_logs.js -i 1 -p /var/log/syslog -n 100
# Add a machine
node dist/add_entries.js add-machine --hostname web-01 --ip 10.0.0.1 --username root --key ~/.ssh/id_rsa
# Add a service
node dist/add_entries.js add-service --machine-id 1 --name nginx --port 80 --type "Web hosting"
```
## npm Scripts
| Script | Description |
|--------|-------------|
| `build` | Compile TypeScript (MCP server + API) |
| `start` | Run the MCP server |
| `dev` | Build + run MCP server |
| `dev:ui` | Vite dev server for the dashboard |
| `dev:api` | Node.js API server (port 8082) |
| `dev:all` | Run UI + API concurrently |
| `build:ui` | Production build of the dashboard |
| `preview:ui` | Preview production dashboard build |
## License
MIT
