Maintenance MCP

Read-only Model Context Protocol server for collecting maintenance signals from an Ubuntu/Debian VPS and explicitly configured Node.js projects.

The server is designed to be launched on demand over SSH and stdio. It reports system, APT, Docker, Git, npm, framework, Caddy, and PostgreSQL state. It cannot install updates, edit files, restart containers, migrate databases, write Git state, or deploy software.

MCP contract

Version 0.1.0 exposes exactly eight read-only tools: system_status, os_updates, docker_status, list_projects, project_status, dependency_updates, security_audit, and maintenance_report. Callers select projects only by configured ID; no tool accepts a path or command. All results use schema version 1.0 and contain generatedAt, status, findings, errors, and tool-specific data. A failed project lookup returns an error envelope and MCP isError: true.

Findings keep update urgency, change risk, and security severity separate. SemVer patch, minor, and major changes map to green, yellow, and red; values that cannot be compared are unknown. Individual command, network, authentication, and parsing failures remain explicit and make an otherwise usable result partial.

Build and run

Node.js 24 LTS or newer is required.

npm ci
npm run lint
npm run typecheck
npm test
npm run build

Copy config/example.yaml to the root-owned /etc/maintenance-mcp/config.yaml and replace only the example project IDs and paths. Every project is canonicalized at startup and revalidated immediately before collection; relative paths, paths outside an allowlisted root, duplicate IDs, and symlink escapes are rejected. The npm registry must use HTTPS and its host must be allowlisted. Optional pull-only npm credentials may only be placed in the fixed, root-owned /etc/maintenance-mcp/npmrc.

Run locally with stdio using MAINTENANCE_MCP_CONFIG only for controlled testing. Production uses the root-owned forced-command wrapper described in deploy/README.md:

ssh maintenance-host /opt/maintenance-mcp/bin/maintenance-mcp

stdout is exclusively MCP JSON-RPC. Startup and transport diagnostics go to stderr after redaction. Commands use absolute executables, fixed argument arrays, shell: false, a minimal environment, shared concurrency limiting, and bounded time/output. apt list --upgradable reads the existing package cache and never refreshes or changes packages.

Security model

• The dedicated account has no interactive shell, forwarding, PTY, Docker-group membership, or writable application/config/project files.
• Docker access is isolated behind a root-owned, no-argument helper and one exact sudoers command. The helper pins the Docker socket, scrubs inherited environment state, bounds every subprocess, allowlists registry hosts, and emits only the public Docker snapshot schema.
• npm runs with scripts disabled, an explicit HTTPS registry, a fixed root-owned user config, and no global config. Raw command output and environment data are never returned as errors.
• The server contains no package installation, update application, file editing, container lifecycle, database migration, Git write, deployment, HTTP, or arbitrary-command capability.

See deploy/README.md for ownership, SSH, sudoers, credentials, and rollback requirements. A VPS smoke test remains mandatory before production use: run all eight tools as the dedicated account, compare the report to the underlying read-only commands, provoke one network/auth failure, and verify packages, containers, Git trees, manifests, and lockfiles remain unchanged.

Repository layout

• src/: server, contracts, configuration, collectors, and reporting logic
• test/: unit, integration, security, and stdio end-to-end tests
• config/: non-secret example configuration
• deploy/: SSH, sudoers, and fixed Docker snapshot helper examples
• reports/: implementation and quality-gate evidence

Release policy

The package version in package.json is authoritative and follows Semantic Versioning. Public MCP tool names and structured output schemas are API contracts. The initial implementation is version 0.1.0.