Infrastructure MCP Architecture

MCP-compatible server exposing 20 infrastructure management and knowledge tools for the Sanchez Family network. Provides Docker, Traefik, DNS, network, service, documentation, and diagnostic capabilities to any AI agent or MCP client on the network.

The server acts as the single programmatic interface between AI agents (Claude Code, n8n workflows) and the production infrastructure running on rod-server (10.0.1.6). It bridges the gap between natural language tool calls and low-level Docker/Traefik/DNS APIs.

Component Classification

Component	Classification	Role
`src/index.js`	Primary	Express HTTP server, tool dispatcher, MCP JSON-RPC endpoints
`src/tools/docker.js`	Primary	Docker container management (list, logs, stats, compose status)
`src/tools/traefik.js`	Primary	Traefik reverse proxy introspection (routers, services, overview)
`src/tools/dns.js`	Primary	Pi-hole DNS record and statistics queries
`src/tools/network.js`	Secondary	Network inventory, port checks, connectivity tests
`src/tools/services.js`	Secondary	Service catalog and HTTP health checks
`src/tools/docs.js`	Secondary	Architecture docs, service info, troubleshooting guides
`src/tools/diagnose.js`	Secondary	Multi-step service and DNS diagnostics
`src/data/infrastructure.json`	Auxiliary	Static knowledge base (hosts, services, topology, troubleshooting)
Docker Socket	External	Docker Engine API via `/var/run/docker.sock`
Traefik API	External	Traefik dashboard API at `http://traefik:8080/api`
Pi-hole	External	DNS config files (read-only mounts) + HTTP API
MCP Proxy	External	Upstream proxy at `mcp.home:3100` (API key auth)

Tools

Tool Categories

Runtime

Node.js 20

Port

3200

Source Files

Network

hosting_web

2. Runtime Architecture

Diagram A: Runtime Request Flow

Request Flow

Claude Code (or any MCP client) sends an HTTP POST to /call with a tool name and parameters -- either directly to infra-mcp.home:3200 or via the MCP Proxy at mcp.home:3100 (which adds API key authentication).
The Express server (index.js) dispatches the request to the appropriate tool module based on the tool name prefix (docker, traefik, dns, network, service, docs, diagnose).
Each tool module queries its backend: Docker tools use the dockerode library over the Unix socket, Traefik tools query the HTTP dashboard API, DNS tools read mounted config files or the Pi-hole HTTP API, and knowledge tools read from the static infrastructure.json.
Results are returned as MCP-compatible content blocks ({"content": [{"type": "text", "text": "..."}]}), ready for consumption by any MCP client.

3. Public Interfaces

HTTP Endpoints

Method	Path	Auth	Description
`GET`	`/health`	None	Server status, tool count, uptime
`GET`	`/tools`	None	List all 20 tools with MCP schemas
`GET`	`/docs`	None	Auto-generated API documentation
`POST`	`/call`	None (direct) / API key (proxy)	Execute a tool: `{"tool":"name","params":{}}`
`POST`	`/tools/list`	None	MCP JSON-RPC 2.0 tool listing
`POST`	`/tools/call`	None	MCP JSON-RPC 2.0 tool execution

Access URLs

Method	URL	Auth
Direct (LAN)	`https://infra-mcp.home`	None
Direct (public)	`https://infra-mcp.sanchezfamily.ca`	None
Via MCP Proxy	`https://mcp.home/mcp/infra/...`	`X-API-Key` header

MCP Tools (20)

Docker Tools (4)

Tool Name	Description	Parameters
`docker_list_containers`	List all Docker containers with status, ports, networks, and image info	`all` (boolean, optional)
`docker_container_logs`	Get recent logs from a Docker container	`name` (string, required), `lines` (number, optional)
`docker_container_stats`	Get CPU, memory, and network stats for a container	`name` (string, required)
`docker_compose_status`	Get status of all Docker Compose projects and containers	None

Traefik Tools (3)

Tool Name	Description	Parameters
`traefik_list_routers`	List all HTTP routers with rules, entrypoints, and TLS config	None
`traefik_list_services`	List all services with backend URLs and health status	None
`traefik_overview`	Dashboard overview with router, service, middleware counts	None

DNS Tools (3)

Tool Name	Description	Parameters
`dns_list_records`	List all Pi-hole custom DNS records (IP-to-domain)	None
`dns_list_local_domains`	List all local `.home` domain mappings from dnsmasq	None
`dns_query_stats`	Pi-hole DNS query statistics and blocking status	None

Network Tools (3)

Tool Name	Description	Parameters
`network_inventory`	Full network inventory: hosts, IPs, topology, firewall rules	None
`network_check_port`	Check if a port is open on a host (TCP connect, 3s timeout)	`host` (string, required), `port` (number, required)
`network_test_connectivity`	Test connectivity via ping or HTTP request	`host` (string, required), `method` (string, optional)

Service Tools (2)

Tool Name	Description	Parameters
`service_catalog`	Complete service catalog with names, types, URLs, ports	`filter` (string, optional)
`service_health_check`	HTTP health check on any URL with status code and timing	`url` (string, required)

Documentation Tools (3)

Tool Name	Description	Parameters
`docs_architecture`	Full architecture docs: topology, request flow, TLS, firewall	None
`docs_service_info`	Detailed info about a specific service (config, URLs, management commands)	`service` (string, required)
`docs_troubleshooting`	Troubleshooting guides for common infrastructure issues	`topic` (string, optional)

Diagnostic Tools (2)

Tool Name	Description	Parameters
`diagnose_service`	Comprehensive diagnostics: container status, port, HTTP, Traefik routing	`service` (string, required)
`diagnose_dns_resolution`	Test full DNS resolution chain: Pi-hole, registration, external DNS, HTTPS	`domain` (string, required)

4. Repository Structure

_infra_mcp/
  CLAUDE.md               # Comprehensive API docs and usage guide
  Dockerfile              # Node.js 20 Alpine, production build
  package.json            # 3 dependencies (express, axios, dockerode)
  docs/
    ARCHITECTURE.html     # Previous architecture doc
  src/
    index.js              # Express server, tool dispatcher, MCP endpoints
    data/
      infrastructure.json # Static knowledge base (hosts, services, topology)
    tools/
      docker.js           # 4 tools: list, logs, stats, compose status
      traefik.js          # 3 tools: routers, services, overview
      dns.js              # 3 tools: records, local domains, query stats
      network.js          # 3 tools: inventory, port check, connectivity
      services.js         # 2 tools: catalog, health check
      docs.js             # 3 tools: architecture, service info, troubleshooting
      diagnose.js         # 2 tools: service diagnostics, DNS resolution

Module Architecture

Each tool module exports a uniform interface:

tools -- Array of MCP tool definitions with name, description, and inputSchema
call(name, params) -- Async function that dispatches to the correct handler by tool name

The main index.js aggregates all modules into a flat registry, mapping each tool name to its module's call function. This keeps tool modules fully independent with no cross-dependencies.

5. Deployment

Docker Container

Property	Value
Image base	`node:20-alpine`
Container name	`infra-mcp`
Port	3200 (internal)
Network	`hosting_web`
Compose file	`/home/rod/_rod/_hosting/docker-compose.agent-system.yml`
Source directory	`/home/rod/_rod/_infra_mcp`
MCP Proxy backend	Registered as `infra` in `MCP_SERVERS` env var

Volume Mounts

Host Path	Container Path	Mode	Purpose
`/var/run/docker.sock`	`/var/run/docker.sock`	Read-only	Docker Engine API access
Pi-hole `custom.list`	`/pihole-config/custom.list`	Read-only	DNS record listing
Pi-hole `02-local-domains.conf`	`/pihole-config/02-local-domains.conf`	Read-only	Local domain listing
`CLAUDE.md`	`/docs/CLAUDE.md`	Read-only	Architecture documentation source

Environment Variables

Variable	Default	Description
`PORT`	`3200`	HTTP server listen port
`TRAEFIK_API_URL`	`http://traefik:8080/api`	Traefik dashboard API base URL
`PIHOLE_CUSTOM_LIST`	`/pihole-config/custom.list`	Path to Pi-hole custom DNS records
`PIHOLE_DNSMASQ_CONF`	`/pihole-config/02-local-domains.conf`	Path to dnsmasq local domain config
`DOCS_DIR`	`/docs`	Directory containing CLAUDE.md

Management Commands

# Build
cd /home/rod/_rod/_hosting
docker compose -f docker-compose.agent-system.yml --env-file /home/rod/_rod/.env build infra-mcp

# Start / Restart
docker compose -f docker-compose.agent-system.yml --env-file /home/rod/_rod/.env up -d infra-mcp

# Logs
docker logs -f infra-mcp

# Health check
curl -sk https://infra-mcp.home/health

# Local development
cd /home/rod/_rod/_infra_mcp
npm install && PORT=3200 node src/index.js

Traefik Routing

Three routers are defined in dynamic.yml:

infra-mcp-http -- HTTP redirect for both domains
infra-mcp -- HTTPS public (infra-mcp.sanchezfamily.ca, Let's Encrypt)
infra-mcp-local -- HTTPS local (infra-mcp.home, local CA wildcard)

Middleware: lan-only (admin access restricted to LAN IPs) + security-headers

6. Dependencies

NPM Packages (Production)

Package	Version	Purpose	Used By
`express`	^4.18.0	HTTP server and routing framework	`index.js`
`axios`	^1.6.0	HTTP client for Traefik API, Pi-hole API, health checks	`traefik.js`, `dns.js`, `services.js`, `diagnose.js`, `network.js`
`dockerode`	^4.0.0	Docker Engine API client via Unix socket	`docker.js`, `diagnose.js`

Node.js Built-in Modules

Module	Used By	Purpose
`fs`	`dns.js`, `docs.js`	Read Pi-hole config files and CLAUDE.md
`path`	`dns.js`, `docs.js`	File path resolution
`net`	`network.js`, `diagnose.js`	TCP socket connections for port checks
`child_process`	`network.js`, `diagnose.js`	Exec `ping` and `dig` commands
`https`	`services.js`, `diagnose.js`, `network.js`	TLS agent with `rejectUnauthorized: false` for self-signed certs

External Services

Service	Connection	Required	Failure Impact
Docker Engine	`/var/run/docker.sock`	Yes	All `docker_*` tools and container diagnostics fail
Traefik Dashboard API	`http://traefik:8080/api`	Yes	All `traefik_*` tools and routing diagnostics fail
Pi-hole Config Files	Mounted at `/pihole-config/`	Partial	`dns_list_records` and `dns_list_local_domains` return errors; other tools unaffected
Pi-hole HTTP API	`http://pihole:80/admin/api.php`	Partial	`dns_query_stats` fails; may require auth token
Network (ping/dig)	System commands	Optional	`network_test_connectivity` and `diagnose_dns_resolution` may degrade

7. Data Sources

Source	Type	Mount / Connection	Tools Using It
Docker Socket	Unix socket	`/var/run/docker.sock` (read-only)	`docker_*`, `diagnose_service`
Traefik API	HTTP	`http://traefik:8080/api` (Docker network)	`traefik_`, `diagnose_`
Pi-hole custom.list	File	`/pihole-config/custom.list` (read-only)	`dns_list_records`
Pi-hole dnsmasq conf	File	`/pihole-config/02-local-domains.conf` (read-only)	`dns_list_local_domains`
Pi-hole HTTP API	HTTP	`http://pihole:80/admin/api.php` (Docker network)	`dns_query_stats`
infrastructure.json	Static JSON	Built into image at `src/data/`	`network_`, `service_`, `docs_`, `diagnose_`
CLAUDE.md	File	`/docs/CLAUDE.md` (read-only mount)	`docs_architecture`

Updating the knowledge base: The static infrastructure.json is baked into the Docker image at build time. After adding new hosts, services, or changing network configuration, edit src/data/infrastructure.json, rebuild the image, and restart the container.

8. Constraints and Risks

Item	Severity	Description
Docker socket access	Medium	Read-only mount of `/var/run/docker.sock` allows container inspection but not management. The socket is still a privileged resource -- container compromise could read container metadata.
No authentication on direct access	Medium	Direct access to `infra-mcp.home` has no API key requirement. Mitigated by Traefik `lan-only` middleware restricting access to 10.0.1.0/24 and Docker subnets.
Static knowledge base	Low	`infrastructure.json` is baked into the image. Adding new services requires a rebuild. Network/service changes are not reflected until the image is rebuilt.
Pi-hole API auth	Low	`dns_query_stats` may fail if Pi-hole requires an authentication token. The tool gracefully returns an error message.
Shell command injection	Low	`network_test_connectivity` and `diagnose_dns_resolution` pass user input to `exec()` for ping/dig. Input validation is minimal -- currently relies on LAN-only access restriction.
No tests	Low	No unit or integration tests. The server is validated through manual health checks and end-to-end tool calls.

Generated by /repo-architecture v2.0.0 on 2026-03-22. This document is auto-generated -- regenerate after significant changes.