aiwg/plugins/sdlc/commands/smith-mcpdef.md

Cognitive architecture for AI-augmented software development with structured memory, ensemble validation, and closed-loop correction. FAIR-aligned artifacts, 84% cost reduction via human-in-the-loop, standards adopted by 100+ organizations.

---
description: Generate MCP environment definition for MCPSmith with Docker and Node.js verification
category: smithing
argument-hint: [--output <path>] [--verify-only] [--update] [--create-network --interactive --guidance "text"]
allowed-tools: Bash, Read, Write, Glob
model: haiku
---

# 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:

```bash
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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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`:

```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/sdk@1.24.0

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

```bash
# 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: `@agentic/code/frameworks/sdlc-complete/agents/mcpsmith.md`
- MCP tool catalog: `.aiwg/smiths/mcpsmith/catalog.yaml`
- ToolSmith (sibling): `@agentic/code/frameworks/sdlc-complete/agents/toolsmith-dynamic.md`