jmagly/smith-mcpdef

MCP Environment Definition Generator

Generate an MCP environment definition file that catalogs Docker and Node.js capabilities for the MCPSmith agent. This file describes the local environment's ability to build and run containerized MCP servers.

Arguments

• --output <path> - Output file path (default: .aiwg/smiths/mcp-definition.yaml)
• --verify-only - Verify existing definition without regenerating
• --update - Update existing definition with any changes
• --create-network - Create the Docker network if it doesn't exist

Workflow

Step 1: Ensure Directory Structure

Create the mcpsmith directory if it doesn't exist:

mkdir -p .aiwg/smiths/mcpsmith/tools
mkdir -p .aiwg/smiths/mcpsmith/implementations
mkdir -p .aiwg/smiths/mcpsmith/templates
mkdir -p .aiwg/smiths/mcpsmith/images

Step 2: Check Docker Availability

Verify Docker is installed and running:

# Check Docker CLI
docker --version

# Check Docker daemon is running
docker info 2>/dev/null | head -20

# Check Docker Compose
docker compose version 2>/dev/null || docker-compose --version 2>/dev/null

Required: Docker must be available and running for MCPSmith to function.

Step 3: Check Node.js Environment

Verify Node.js is available:

# Node.js version
node --version

# npm version
npm --version

# Check for MCP SDK (in project or global)
npm list @modelcontextprotocol/sdk 2>/dev/null || npm list -g @modelcontextprotocol/sdk 2>/dev/null

Step 4: Check Docker Images

Verify base images are accessible:

# Check if base images exist locally or can be pulled
docker image inspect node:20-alpine 2>/dev/null || echo "node:20-alpine not cached"
docker image inspect node:20-slim 2>/dev/null || echo "node:20-slim not cached"

Step 5: Check/Create Docker Network

Verify or create the MCP network for container communication:

# Check if network exists
docker network ls | grep aiwg-mcp-network

# Create if missing (only with --create-network flag)
docker network create aiwg-mcp-network 2>/dev/null || true

Step 6: Determine Available Port Range

Find available ports in the configured range:

# Check ports 9100-9199 for availability
for port in $(seq 9100 9110); do
  nc -z localhost $port 2>/dev/null || echo "$port available"
done

Step 7: Generate YAML Output

Create .aiwg/smiths/mcp-definition.yaml:

# MCP Environment Definition for MCPSmith
# Generated: <timestamp>
# Platform: <os> <version>

docker:
  available: true|false
  version: "<docker version>"
  compose_version: "<compose version>"
  runtime: "<containerd|runc>"
  daemon_running: true|false

node:
  available: true|false
  version: "<node version>"
  npm_version: "<npm version>"

mcp:
  sdk_available: true|false
  sdk_version: "<version or null>"
  spec_version: "2025-11-25"
  transports:
    - stdio
    # - http  # if supported

base_images:
  node_alpine:
    image: "node:20-alpine"
    cached: true|false
  node_slim:
    image: "node:20-slim"
    cached: true|false

network:
  name: "aiwg-mcp-network"
  exists: true|false
  driver: "bridge"

ports:
  range_start: 9100
  range_end: 9199
  available: [9100, 9101, ...]  # First 10 available ports

capabilities:
  can_build_images: true|false
  can_run_containers: true|false
  can_create_networks: true|false
  stdio_transport: true|false
  http_transport: true|false

Step 8: Report Summary

Output a summary of the MCP environment:

MCP Environment Definition Generated
=====================================
Docker: Available (v24.0.7)
  - Daemon: Running
  - Compose: v2.23.0
  - Runtime: containerd

Node.js: Available (v20.10.0)
  - npm: v10.2.0
  - MCP SDK: @modelcontextprotocol/[email protected]

Base Images:
  - node:20-alpine: Cached
  - node:20-slim: Not cached (will pull on first use)

Network:
  - aiwg-mcp-network: Exists

Port Range: 9100-9199
  - Available ports: 9100, 9101, 9102, ... (10 shown)

Capabilities:
  ✓ Can build images
  ✓ Can run containers
  ✓ Can create networks
  ✓ Stdio transport
  ✗ HTTP transport (not configured)

Output: .aiwg/smiths/mcp-definition.yaml

Error Conditions

Docker Not Available

Error: Docker is not available.

MCPSmith requires Docker to build and run MCP tool containers.

Please install Docker:
  - Linux: https://docs.docker.com/engine/install/
  - macOS: https://docs.docker.com/desktop/mac/install/
  - Windows: https://docs.docker.com/desktop/windows/install/

After installation, ensure Docker daemon is running:
  sudo systemctl start docker  # Linux
  open -a Docker               # macOS

Docker Daemon Not Running

Error: Docker daemon is not running.

Start Docker:
  - Linux: sudo systemctl start docker
  - macOS: Open Docker Desktop
  - Windows: Start Docker Desktop

Then re-run: /smith-mcpdef

Node.js Not Available

Warning: Node.js is not available on the host.

MCPSmith can still build containers (Node.js included in image),
but local testing may be limited.

For full functionality, install Node.js:
  https://nodejs.org/

Verify-Only Mode

When --verify-only is specified:

1. Read existing .aiwg/smiths/mcp-definition.yaml
2. Re-check all capabilities
3. Report any changes
4. Do NOT modify the file

Verifying MCP environment definition...

Docker:
  ✓ Version matches (24.0.7)
  ✓ Daemon running
  ✓ Compose available

Node.js:
  ✓ Version matches (20.10.0)
  ✗ MCP SDK version changed: 1.23.0 → 1.24.0

Network:
  ✓ aiwg-mcp-network exists

Verification complete. 1 change detected.
Run with --update to refresh definition.

Update Mode

When --update is specified:

1. Read existing definition
2. Re-check all capabilities
3. Update changed values
4. Preserve user customizations (port_range, etc.)
5. Update timestamp

Usage Examples

# Generate full MCP definition
/smith-mcpdef

# Custom output location
/smith-mcpdef --output ./custom-mcp-def.yaml

# Verify existing definition
/smith-mcpdef --verify-only

# Update definition and create network
/smith-mcpdef --update --create-network

Prerequisites Check

Before MCPSmith can operate, verify:

| Requirement | Status | Notes | |-------------|--------|-------| | Docker CLI | Required | docker --version | | Docker Daemon | Required | Must be running | | Docker Compose | Recommended | For multi-container tools | | Node.js | Recommended | For local testing | | MCP SDK | Optional | Can be installed in container |

Success Criteria

• [ ] Docker availability verified
• [ ] Docker daemon running confirmed
• [ ] Node.js version detected (if available)
• [ ] Base images checked
• [ ] Network status determined
• [ ] Port range scanned
• [ ] Capabilities assessed
• [ ] mcp-definition.yaml generated with correct format

References

• MCPSmith agent: @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/agents/mcpsmith.md
• MCP tool catalog: .aiwg/smiths/mcpsmith/catalog.yaml
• ToolSmith (sibling): @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/agents/toolsmith-dynamic.md