Root cause fix for AI agent failing to commit/push automatically:
1. Added Task Completion Checklist to AGENTS.md with mandatory items:
- All requested work implemented
- Changes staged (git add)
- Changes committed (conventional format)
- Changes pushed (git push)
- STATUS.md updated (if applicable)
- JOURNAL.md updated (if applicable)
2. Added pre-push hook in .githooks/ (tracked, not .git/hooks/):
- Blocks push if uncommitted changes exist
- Safety net if checklist is skipped
3. Fixed .gitignore: changed "vendor/" to "vendor" to also ignore symlink
After cloning, run: git config core.hooksPath .githooks
💘 Generated with Crush
Assisted-by: GLM-5 via Crush <crush@charm.land>
Root cause fix for AI agent failing to commit/push automatically:
- Added explicit Task Completion Checklist section to AGENTS.md
- Added pre-push git hook to block push if uncommitted changes exist
The checklist forces verification of commit/push before declaring work done.
The git hook provides safety net if checklist is skipped.
Checklist items:
- All requested work implemented
- Changes staged (git add)
- Changes committed (conventional format)
- Changes pushed (git push)
- STATUS.md updated (if applicable)
- JOURNAL.md updated (if applicable)
DO NOT STOP until all applicable items complete.
💘 Generated with Crush
Assisted-by: GLM-5 via Crush <crush@charm.land>
- proxmox-mcp: Fixed by patching pyproject.toml to use fastmcp from PyPI
and updating imports from mcp.server.fastmcp to fastmcp. Container now
builds and runs (requires PROXMOX_MCP_CONFIG env var).
- snipeit-mcp: Created stub Dockerfile that exits with error message.
Upstream depends on private snipeit-api package never published to PyPI.
- STATUS.md: Updated to reflect 25 working MCP servers including proxmox-mcp.
- .env: Added template with placeholders for required credentials.
💘 Generated with Crush
Assisted-by: GLM-5 via Crush <crush@charm.land>
Add actual-mcp, beszel-mcp, gitea-mcp, ha-mcp, limesurvey-mcp,
linkwarden-mcp, mcp-grafana, and superset-mcp with full validation.
Key fixes applied:
- linkwarden-mcp: Added 'stdio' subcommand to ENTRYPOINT
- mcp-grafana: Fixed build path (./cmd/mcp-grafana) and added '--transport stdio' flag
All 8 servers validated with MCP protocol handshake.
Working MCP server count: 24 (up from 16)
💘 Generated with Crush
Assisted-by: GLM-5 via Crush <crush@charm.land>
AGENTS.md now contains only AI agent rules/guidelines:
- Commit Policy, SDLC Compliance, Status Tracking, Journal Maintenance
- Project Conventions, Crush Configuration, Validation Checklist
- MCP Handshake Command example
- References to other documentation files instead of duplicating content
README.md now contains comprehensive project documentation:
- Full MCP/LSP server inventory tables (30+ servers organized by category)
- Server technologies by language (TypeScript, Python, Go, Rust, Prebuilt)
- Environment variables reference table for all services
- Installation, usage, troubleshooting guides
- Crush integration configuration examples
This refactoring ensures:
- AGENTS.md is a concise reference for AI agent behavior (~107 lines)
- README.md is the comprehensive project documentation (~424 lines)
- No duplication between files
- Each file has a single responsibility
💔 Generated with Crush
Assisted-by: GLM-5 via Crush <crush@charm.land>
Changes:
- Updated all script references to use scripts/ prefix
- Updated vendor repository count from 32+ to 40+
- Removed Makefile targets section (Makefile no longer primary interface)
This aligns documentation with current project structure where all
utility scripts are organized under the scripts/ directory.
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.
