Created scripts/validate-all.sh to validate ALL servers with actual
protocol handshake messages:
Coverage:
- 29 MCP servers (Design, Infrastructure, Content, Communication,
Analytics, Productivity, Reverse Engineering)
- 4 LSP servers (bash, docker, marksman, terraform-ls)
Features:
- Sends actual MCP initialize handshake to each container
- Sends actual LSP initialize handshake to LSP containers
- Categorizes results: PASSED, FAILED, SKIPPED, NEEDS_ENV,
NEEDS_SERVICE, TRANSPORT_MISMATCH
- Provides detailed summary with server names and versions
- Color-coded output for easy scanning
Usage:
./scripts/validate-all.sh # Test all servers
./scripts/validate-all.sh mcp # MCP servers only
./scripts/validate-all.sh lsp # LSP servers only
./scripts/validate-all.sh <service> # Specific service
This script implements the SDLC requirement for protocol validation.
Every server must pass build + start + protocol handshake to be
considered "working".
Added mandatory callout at top of AGENTS.md:
- AI agents MUST commit and push changes automatically WITHOUT prompting
- Use atomic commits (one logical change per commit)
- Use conventional format (feat:, fix:, docs:, build:, refactor:, test:)
- Verbose commit messages required
Updated Development Notes section:
- Added "SDLC Compliance (REQUIRED)" section with link to docs/SDLC.md
- Documented mandatory MCP handshake command
- Updated Validation Checklist to emphasize protocol handshake is MANDATORY
This ensures AI agents understand that committing is automatic,
not something to ask permission for.
Defines the software development lifecycle for KNEL-AIMiddleware:
- Protocol validation is NON-NEGOTIABLE: build + start + protocol handshake
ALL required before marking a server as "working"
- MCP initialize handshake: {"jsonrpc":"2.0","method":"initialize"...}
- STATUS.md is the single source of truth for server status
- Status categories: Working, Runtime Connection Required, Host-Only,
Transport Mismatch, Build Failed, Runtime Issue
- Step-by-step process for adding new MCP/LSP servers
- Common Dockerfile patterns for Python/uv, Node/npx, Go
- Wrapper script pattern for Crush integration
Commit Policy (MANDATORY):
- AI agents MUST commit automatically WITHOUT prompting
- Atomic commits: one logical change per commit
- Conventional format: feat:, fix:, docs:, build:, refactor:, test:
- Verbose messages explaining what, why, and how validated
- Automatic push after each commit
Version: 1.0
Recorded the completion of pushing all 32 container images to
git.knownelement.com/knel/knel-aimiddleware/ registry.
Assisted-by: GLM-5 via Crush <crush@charm.land>
- Fixed incorrect path /KNEL/KNEL-AIMiddleware/ to /KNEL-AIMiddleware/
- Added discourse and penpot MCP configurations to crush.json
- Tracked 10 new wrapper scripts for pending MCP servers
- Added paperless-mcp and postizz-mcp Dockerfiles
- Updated JOURNAL.md with today's work entry
💘 Generated with Crush
Assisted-by: GLM-5 via Crush <crush@charm.land>
- Add Dockerfiles for bitwarden-mcp, mcp-ansible, reverse-engineering-assistant
- Update CloneVendorRepos.sh with official repository URLs (migrate from ahujasid mirrors)
- Update docker-compose.yml with new services and reorganization
- Update STATUS.md with current operational status of all MCP servers
- Update AGENTS.md with webserial-mcp and terraform-ls documentation
- Add journal entries for recent work (ADRs, insights, patterns)
💔 Generated with Crush
Assisted-by: GLM-5 via Crush <crush@charm.land>
- Add terraform-ls Dockerfile (Alpine-based, v0.38.4)
- Add terraform-ls service to docker-compose.yml
- Create LSP wrapper script for Crush integration
- Add terraform entry to crush.json under lsp section
- Update STATUS.md with terraform-ls working status
🧡 Generated with Crush
Assisted-by: GLM-5 via Crush <crush@charm.land>
- Add webserial-mcp service to docker-compose.yml
- Create wrapper script and add to crush.json
- Update STATUS.md with build status and requirements
- Note: requires bridge server + browser + ESP32 hardware
deps: generated with Crush
Assisted-by: GLM-5 via Crush <crush@charm.land>
- Switch from empty ahujasid/kubernetes-mcp-server to silenceper/mcp-k8s
- Build multi-stage Go container (golang:1.24.1 -> alpine:3.18.4)
- Add wrapper script with kubeconfig mount
- Configure in crush.json for Crush integration
- Update STATUS.md with working status
Supports K8s resources (get/list/create/update/delete) and Helm operations.
💔 Generated with Crush
Assisted-by: GLM-5 via Crush <crush@charm.land>
Investigation revealed that 9 additional ahujasid MCP repositories are
empty (contain only .git folder, no actual code):
- kubernetes-mcp-server
- ProxmoxMCP
- terraform-mcp-server
- nextcloud-mcp-server
- snipeit-mcp
- mcp-redmine
- mcp-ansible
- penpot-mcp
- postizz-MCP
These cannot be used to build MCP containers. Added detailed entries to:
- Missing/Empty Vendor Repositories section
- Detailed Status table
- Known Issues section with alternative for kubernetes-mcp (silenceper/mcp-k8s)
This brings the total blocked MCPs to 11:
- 1 missing repo (matomo-mcp - 404)
- 10 empty repos (discourse + 9 documented here)
Related: ADR-007 Sequential MCP validation
- Updated CloneVendorRepos.sh to use official ONLYOFFICE/docspace-mcp
repository instead of ahujasid/docspace-mcp (which was outdated)
- Successfully built and validated docspace-mcp Docker container (236MB)
- Created wrapper script mcp-docspace-wrapper.sh with environment
variables for DOCSPACE_HOST and DOCSPACE_TOKEN
- Added docspace MCP configuration to crush.json
- Updated STATUS.md with working status for docspace-mcp
MCP handshake test confirmed server responds correctly:
- Protocol version: 2024-11-05
- Server: @onlyoffice/docspace-mcp v3.1.0
- Capabilities: tools
Also documented blocked MCPs in STATUS.md:
- matomo-mcp: vendor repo does not exist (404)
- discourse-mcp: vendor repo exists but is empty (no commits)
Related: ADR-007 Sequential MCP validation
discourse-mcp repository at https://github.com/ahujasid/discourse-mcp.git
exists but contains no commits - completely empty repository.
Added to:
- Missing Vendor Repositories section
- Known Issues section
- Detailed Status table (status: Blocked)
💘 Generated with Crush
Assisted-by: GLM-5 via Crush <crush@charm.land>
matomo-mcp-client repository referenced in CloneVendorRepos.sh
does not exist on GitHub (404). Verified via GitHub API that
ahujasid has 46 repos but none named matomo-mcp-client.
Unable to build this MCP until a valid source repository is identified.
Added to:
- Missing Vendor Repositories section
- Known Issues section
- Detailed Status table (status: Blocked)
💘 Generated with Crush
Assisted-by: GLM-5 via Crush <crush@charm.land>
kicad-mcp requires the pcbnew Python module which is only
available with a KiCAD installation. The container builds
successfully but fails validation because pcbnew cannot be
pip-installed or included in the container.
- Added "Host-Only MCP Servers" section to STATUS.md
- Updated detailed status table with kicad-mcp entry
- Added JOURNAL.md entry documenting the finding
- Updated docker-compose.yml to use custom Dockerfile
This MCP can only be used on a host machine with KiCAD
installed. It cannot be integrated into Crush via Docker.
Build details:
- Container size: 463MB
- Base: node:22-alpine with Python 3 + pip
- Dependencies: kicad-skip, Pillow, cairosvg, colorlog, pydantic
Validation error:
[ERROR] pcbnew validation failed: ModuleNotFoundError: No module named 'pcbnew'
Root cause:
- KiCAD's pcbnew is a C++ Python binding bundled with KiCAD
- Cannot be installed via pip or any package manager
- Server validates pcbnew at startup and exits if missing
Pattern identified:
Some MCPs integrate with desktop applications and cannot
be containerized. These should be documented as host-only
and excluded from Docker-based Crush integration.
Next MCP to process: matomo-mcp
💘 Generated with Crush
Assisted-by: GLM-5 via Crush <crush@charm.land>
Build and integrate IMAP MCP Server.
Changes:
- mcp-imap-wrapper.sh: Created wrapper script with container cleanup
- crush.json: Added imap-mcp entry with type: stdio and timeout: 60
- STATUS.md: Updated to mark imap-mcp as having configuration issues
- JOURNAL.md: Documented integration with full analysis of known issue
Known Issue:
- Server crashes on startup if IMAP connection fails
- Server does not respond to JSON-RPC initialize before crashing
- Requires working IMAP server to function in Crush
- Root cause: server attempts IMAP connection during lifespan context entry
- If connection fails, exception propagates and causes server exit
- Bug in imap-mcp: should handle connection gracefully
Validation:
- Container builds successfully (317MB, Python + uv)
- Wrapper script tested and working
- MCP protocol handshake: FAILED (server crashes before initialize)
- Cannot test protocol version or server capabilities due to crash
Environment Variables Required:
- PYTHONUNBUFFERED=1
- IMAP_HOST: IMAP server hostname
- IMAP_PORT: IMAP server port (default: 993)
- IMAP_USER: IMAP username
- IMAP_PASSWORD: IMAP password
Workaround:
User must have a working IMAP server running for imap-mcp
to initialize in Crush. If IMAP is unavailable, MCP will fail.
This is fifth MCP added in alphabetical order after filtering
out already working MCPs (audiobook, bitwarden, blender, cloudron,
context7, docker, drawio, elasticsearch, freecad, ghost, gimp).
Following ADR-007: Sequential Server Validation - one MCP at a time,
noting issues as they are encountered.
Build and validate GIMP MCP Server (GimpMCP v1.10.1).
Changes:
- dockerfiles/gimp-mcp/Dockerfile: Fixed ENTRYPOINT to use python -m instead of uvx
- mcp-gimp-wrapper.sh: Created wrapper script with container cleanup
- crush.json: Added gimp-mcp entry with type: stdio and timeout: 180
- STATUS.md: Updated working MCP list and detailed status table
- JOURNAL.md: Documented integration with full validation results
Validation:
- Container builds successfully (418MB, Python + uv)
- Dockerfile fix: Changed from uvx (slow, rebuilds packages) to python -m (fast, uses .venv)
- MCP protocol handshake verified with initialize request
- Protocol version 2024-11-05 confirmed
- Server name: GimpMCP, version 1.10.1
- Wrapper script tested and working
- Environment variable: PYTHONUNBUFFERED=1
- External dependency: GIMP 3.0 with server
Dockerfile Fix:
- Before: ENTRYPOINT ["uvx", "gimp-mcp-server"] (slow, rebuilds on every run)
- After: ENTRYPOINT ["python", "-m", "gimp_mcp_server"] (fast, uses built .venv)
- Entry point: gimp-mcp-server = "gimp_mcp_server:main" (from pyproject.toml)
This is fourth MCP added in alphabetical order after filtering
out already working MCPs (audiobook, bitwarden, blender, cloudron,
context7, docker, drawio, elasticsearch, freecad, ghost).
Following ADR-007: Sequential Server Validation - one MCP at a time.
Build and validate Ghost CMS MCP Server (ghost-mcp-ts v1.0.0).
Changes:
- mcp-ghost-wrapper.sh: Created wrapper script with container cleanup
- crush.json: Added ghost-mcp entry with type: stdio and timeout: 60
- STATUS.md: Updated working MCP list and detailed status table
- JOURNAL.md: Documented integration with full validation results
Validation:
- Container builds successfully (284MB, Node.js + TypeScript)
- MCP protocol handshake verified with initialize request
- Protocol version 2024-11-05 confirmed
- Server name: ghost-mcp-ts, version 1.0.0
- Wrapper script tested and working
- Environment variables: GHOST_API_URL, GHOST_ADMIN_API_KEY
- Capabilities: resources, tools, prompts (all listChanged: true)
This is third MCP added in alphabetical order after filtering
out already working MCPs (audiobook, bitwarden, blender, cloudron,
context7, docker, drawio, elasticsearch, freecad).
Following ADR-007: Sequential Server Validation - one MCP at a time,
awaiting user validation before proceeding to next MCP.
Build and validate FreeCAD MCP Server (v1.25.0).
Changes:
- mcp-freecad-wrapper.sh: Created wrapper script with container cleanup
- crush.json: Added freecad-mcp entry with type: stdio and timeout: 180
- STATUS.md: Updated working MCP list and detailed status table
- JOURNAL.md: Documented integration with full validation results
Validation:
- Container builds successfully (317MB, Python + uv)
- MCP protocol handshake verified with initialize request
- Protocol version 2024-11-05 confirmed
- Server name: FreeCADMCP, version 1.25.0
- Wrapper script tested and working
- Environment variable: PYTHONUNBUFFERED=1
- External dependency: FreeCAD with MCP addon (warning if not running)
Similar to blender-mcp:
- Both Python-based with uv package manager
- Both require CAD application with addon running
- Both show warning on startup when CAD app not connected
- Both still initialize properly for MCP protocol handshake
This is second MCP added in alphabetical order after filtering
out already working MCPs (audiobook, bitwarden, blender, cloudron,
context7, docker, drawio, elasticsearch).
Following ADR-007: Sequential Server Validation - one MCP at a time,
awaiting user validation before proceeding to next MCP.
Add MCP wrapper scripts that were created during earlier troubleshooting
but were not committed yet. All wrappers follow same pattern:
- Container cleanup before starting new instance
- Explicit naming with -crush suffix
- Environment variable passing from host .env file
- Special cases handled (docker-mcp socket mount)
Scripts added:
- mcp-audiobook-wrapper.sh
- mcp-bitwarden-wrapper.sh
- mcp-blender-wrapper.sh
- mcp-cloudron-wrapper.sh
- mcp-docker-wrapper.sh (with Docker socket mount)
- mcp-drawio-wrapper.sh
- mcp-elasticsearch-wrapper.sh
All scripts are executable and tested.
Build and validate Context7 Documentation MCP Server (v2.1.0).
Changes:
- mcp-context7-wrapper.sh: Created wrapper script with container cleanup
- crush.json: Added context7-mcp entry with type: stdio and timeout: 60
- STATUS.md: Updated working MCP list and detailed status table
- JOURNAL.md: Documented integration with full validation results
Validation:
- Container builds successfully (224MB, Node.js + TypeScript)
- MCP protocol handshake verified with initialize request
- Protocol version 2024-11-05 confirmed
- Server name: Context7, version 2.1.0
- Wrapper script tested and working
- Environment variables: UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN
This is the first MCP added in alphabetical order after filtering
out already working MCPs (audiobook, bitwarden, blender, cloudron,
docker, drawio, elasticsearch).
Following ADR-007: Sequential Server Validation - one MCP at a time,
awaiting user validation before proceeding to next MCP.
Build and validate Elasticsearch MCP server for search/indexing.
Changes:
- docker-compose.yml: Updated elasticsearch-mcp to use custom Dockerfile
and ES_URL env var (not ELASTICSEARCH_URL)
- dockerfiles/elasticsearch-mcp/Dockerfile: Added custom Dockerfile with
fix to pass "stdio" subcommand to ENTRYPOINT
- STATUS.md: Added elasticsearch-mcp as validated MCP (v0.2.1, 22MB)
Validation:
- Container builds successfully from Rust source (22MB)
- Fixed Dockerfile to pass "stdio" subcommand to entry point
- MCP protocol handshake verified with initialize request
- Protocol version 2024-11-05 confirmed
- Server name: rmcp, version 0.2.1
- Requires ES_URL environment variable (not ELASTICSEARCH_URL)
- NOTE: Server is deprecated, superseded by Elastic Agent Builder
- Tested with proper --name flag for container
Build and validate Draw.io MCP server for diagram management.
Changes:
- STATUS.md: Added drawio-mcp as validated MCP (v1.4.0, 302MB)
- STATUS.md: Updated counts and status sections
Validation:
- Container builds successfully from TypeScript source (302MB)
- Uses pnpm package manager for fast dependency installation
- MCP protocol handshake verified with initialize request
- Protocol version 2024-11-05 confirmed
- Server name: drawio-mcp-server, version 1.4.0
- Requires DRAWIO_URL environment variable
- WebSocket extension runs on port 3333
- Tested with proper --name flag for container
Build and validate Docker MCP server for container management.
Changes:
- STATUS.md: Added docker-mcp as validated MCP (v0.1.0, 188MB)
- STATUS.md: Updated counts and status sections
Validation:
- Container builds successfully from Python source (188MB)
- Uses uv package manager for fast dependency installation
- MCP protocol handshake verified with initialize request
- Protocol version 2024-11-05 confirmed
- Server name: docker-mcp, version 0.1.0
- Requires Docker socket mount (/var/run/docker.sock)
- Tested with proper --name flag for container
Build and validate Cloudron MCP server for self-hosted app management.
Changes:
- docker-compose.yml: Updated to use custom Dockerfile for cloudron-mcp
- dockerfiles/cloudron-mcp/Dockerfile: Added custom Dockerfile with fix
for CMD entry point (dist/server.js instead of dist/index.js)
- STATUS.md: Added cloudron-mcp as validated MCP (v0.1.0, 374MB)
Validation:
- Container builds successfully from TypeScript source (374MB)
- Fixed Dockerfile CMD to use correct entry point (dist/server.js)
- MCP protocol handshake verified with initialize request
- Protocol version 2024-11-05 confirmed
- Server name: cloudron-mcp, version 0.1.0
- Requires CLOUDRON_URL environment variable
- Tested with proper --name flag for container
Build and validate Blender MCP server for 3D modeling.
Changes:
- STATUS.md: Added blender-mcp as validated MCP (v1.25.0, 321MB)
- STATUS.md: Updated counts and status sections
Validation:
- Container builds successfully from Python source (321MB)
- Uses uv package manager for fast dependency installation
- MCP protocol handshake verified with initialize request
- Protocol version 2024-11-05 confirmed
- Server name: BlenderMCP, version 1.25.0
- Requires Blender application running with addon for full functionality
- Tested with proper --name flag for container
Build and validate Bitwarden MCP server for password management.
Changes:
- STATUS.md: Added bitwarden-mcp as validated MCP (v2026.1.0, 377MB)
- STATUS.md: Updated counts and status sections
Validation:
- Container builds successfully from source (multi-stage distroless build)
- MCP protocol handshake verified with initialize request
- Protocol version 2024-11-05 confirmed
- Server name: Bitwarden MCP Server, version 2026.1.0
- Requires BITWARDEN_CLIENT_ID, BITWARDEN_CLIENT_SECRET,
BITWARDEN_PASSWORD, BITWARDEN_SERVER_URL env vars
- Tested with proper --name flag for container
Document marksman Markdown LSP build and validation success.
Changes:
- STATUS.md: Added marksman as validated LSP (2025-12-13, 144MB)
- AGENTS.md: Added marksman to Development Tools section
- AGENTS.md: Updated server counts (Development Tools: 3→4)
Validation:
- Container builds successfully from custom Dockerfile
- Version 2025-12-13 verified with --version flag
- Crush wrapper script functional
- All three LSP servers (bash, docker, marksman) now working
Reset STATUS.md to clean slate and document bash-language-server LSP
build and validation success.
Changes:
- Cleaned all previous MCP/LSP server status entries
- Added bash-language-server as validated LSP (v5.6.0, 190MB)
- Updated crush.json configuration reference
- Cleared all known issues and build progress sections
Validation:
- Container builds successfully from custom Dockerfile
- Version 5.6.0 verified with --version flag
- Crush wrapper script functional
- User acceptance testing completed
- Mark 6 services as Built (cloudron, docspace, freecad, gimp, kicad, blender)
- Update 5 services as Building (elasticsearch, kubernetes, matomo, postizz, wordpress)
- Document 3 build failures with action items (ansible, snipeit, terraform)
- Update detailed status table with latest build information
Add the following built MCP servers to crush.json configuration:
- blender-mcp
- cloudron-mcp
- docspace-mcp
- freecad-mcp
- gimp-mcp
- kicad-mcp
All servers configured with appropriate environment variables.
Remove Makefile in favor of more flexible shell-based maintenance script.
The new maintenance.sh provides all the same functionality with
easier maintenance and better shell script integration.
Update crush.json LSP configurations to use newly created
wrapper scripts instead of direct Docker commands. This ensures
LSP server containers have consistent names matching their
images, allowing multiple Crush sessions to share containers
and enabling clean restart capability.
Add wrapper scripts for bash, docker, and marksman LSP servers
to ensure containers use explicit names matching image names.
Enables multiple Crush sessions to share LSP server containers
with clean restart capability.
- lsp-bash-wrapper.sh: Wrapper for bash-language-server
- lsp-docker-wrapper.sh: Wrapper for docker-language-server
- lsp-marksman-wrapper.sh: Wrapper for marksman markdown LSP
Each wrapper cleans up existing containers and starts new container
with --name flag to ensure consistent naming.
- Add validation summary section with working MCP servers list
- Document ProxmoxMCP config incompatibility with Crush
- Note slow initialization for context7, drawio, redmine
- Update bitwarden-mcp and audiobook-mcp status to Working
- Add known issues section for documentation
- Document validation script fixes and Docker config warning
- Fix bash script to use 'echo |' instead of '<<<' for Docker stdin
- Increase default timeout from 5s to 10s
- Add explicit timeout parameter to all test function calls
- Fix Ghost MCP env variables to use correct names and format
- Script was giving false negatives due to incorrect bash syntax
- Remove context7 from LSP section in crush.json (it's an MCP server)
- Add GHOST_API_URL and GHOST_ADMIN_API_KEY to ghost-mcp config
- Context7 was incorrectly configured as both LSP and MCP
