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>
Charles N Wyble