KNEL-AIMiddleware/AGENTS.md

AI Agents Documentation

This document tracks the AI agents and MCP servers configured in this project.

🔴 AUTOMATIC COMMITS: AI agents MUST commit and push changes automatically WITHOUT prompting. Use atomic commits (one logical change per commit), conventional format (feat:, fix:, docs:), and verbose messages. See docs/SDLC.md for full commit policy.

📋 SDLC Compliance: All MCP/LSP development MUST follow docs/SDLC.md. Key rule: Protocol handshake is NON-NEGOTIABLE - build + start + protocol validation ALL required before marking a server as "working".

Status Tracking: Current operational status of all MCP servers is maintained in STATUS.md. Please refer to that file for the latest status of each server.

Journal Maintenance: ALL work performed on this project MUST be documented in JOURNAL.md. This is an append-only journal that tracks Architecture Decision Records (ADRs), insights, patterns, and the reasoning behind all work done. Never delete entries from the journal. Each entry must be date/time stamped.

Agents Overview

Available MCP Servers

Design & Engineering (4 servers)

Service	Container Name	Description
kicad-mcp	kneldevstack-aimiddleware-kicad-mcp	PCB design automation with 64 tools, JLCPCB integration (host-only)
blender-mcp	kneldevstack-aimiddleware-blender-mcp	3D modeling, materials, scenes, AI 3D model generation
freecad-mcp	kneldevstack-aimiddleware-freecad-mcp	CAD modeling, Python execution, parts library
gimp-mcp	kneldevstack-aimiddleware-gimp-mcp	Image editing with GIMP 3.0, OCR support

Hosting & Infrastructure (5 servers)

Service	Container Name	Description
kubernetes-mcp	kneldevstack-aimiddleware-kubernetes-mcp	K8s/OpenShift management (native Go implementation)
docker-mcp	kneldevstack-aimiddleware-docker-mcp	Container and compose stack management
proxmox-mcp	kneldevstack-aimiddleware-proxmox-mcp	Hypervisor VM/container management
terraform-mcp	kneldevstack-aimiddleware-terraform-mcp	IaC automation, HCP Terraform, workspace management
cloudron-mcp	kneldevstack-aimiddleware-cloudron-mcp	Self-hosted app management

Development Tools (1 server)

Service	Container Name	Description
context7-mcp	kneldevstack-aimiddleware-context7-mcp	MCP server framework and SDK for documentation

Content Management (4 servers)

Service	Container Name	Description
nextcloud-mcp	kneldevstack-aimiddleware-nextcloud-mcp	90+ tools across 8 apps (Notes, Calendar, Files, Deck, etc.)
ghost-mcp	kneldevstack-aimiddleware-ghost-mcp	CMS post, member, newsletter management
docspace-mcp	kneldevstack-aimiddleware-docspace-mcp	Room, file, collaboration management
wordpress-mcp	kneldevstack-aimiddleware-wordpress-mcp	WordPress integration via Abilities API

Communication & Collaboration (3 servers)

Service	Container Name	Description
discourse-mcp	kneldevstack-aimiddleware-discourse-mcp	Forum search, posts, topics, categories (read/write modes)
imap-mcp	kneldevstack-aimiddleware-imap-mcp	Email browsing, composition, Gmail OAuth2 support
postizz-mcp	kneldevstack-aimiddleware-postizz-mcp	Social media management platform

Analytics & Security (2 servers)

Service	Container Name	Description
matomo-mcp	kneldevstack-aimiddleware-matomo-mcp	Analytics integration
bitwarden-mcp	kneldevstack-aimiddleware-bitwarden-mcp	Official password vault management

Productivity & Automation (6 servers)

Service	Container Name	Description
audiobook-mcp	kneldevstack-aimiddleware-audiobook-mcp	Audiobook management with AI-powered features
snipeit-mcp	kneldevstack-aimiddleware-snipeit-mcp	Asset inventory, maintenance tracking
mcp-redmine	kneldevstack-aimiddleware-mcp-redmine	Project management, issue tracking, file operations
mcp-ansible	kneldevstack-aimiddleware-mcp-ansible	IT automation playbooks
elasticsearch-mcp	kneldevstack-aimiddleware-elasticsearch-mcp	Search and index management (Rust)
drawio-mcp	kneldevstack-aimiddleware-drawio-mcp	Draw.io diagram management

Additional Tools (2 servers)

Service	Container Name	Description
penpot-mcp	kneldevstack-aimiddleware-penpot-mcp	Design collaboration platform integration
webserial-mcp	kneldevstack-aimiddleware-webserial-mcp	ESP32 MicroPython development via WebSerial (requires bridge server)

Reverse Engineering (2 servers)

Service	Container Name	Description
ghidra-mcp	kneldevstack-aimiddleware-ghidra-mcp	Binary analysis and reverse engineering (HTTP REST, not MCP)
reverse-engineering-assistant	kneldevstack-aimiddleware-reverse-engineering-assistant	ReVa - AI-assisted reverse engineering via MCP

LSP Servers (4 servers)

Service	Container Name	Description
bash-language-server	kneldevstack-aimiddleware-bash-language-server	LSP for bash (diagnostics, completion, formatting)
docker-language-server	kneldevstack-aimiddleware-docker-language-server	LSP for Dockerfiles, Compose files, Bake files
marksman	kneldevstack-aimiddleware-marksman	LSP for Markdown (diagnostics, completion, navigation)
terraform-ls	kneldevstack-aimiddleware-terraform-ls	LSP for Terraform (diagnostics, completion, navigation)

Agent Capabilities

By Language

TypeScript/Node.js (13 servers)

Most use npx for installation:

• KiCAD MCP
• Bitwarden MCP
• Discourse MCP
• Ghost MCP
• Cloudron MCP
• Kubernetes MCP
• Draw.io MCP
• Matomo MCP
• Postiz MCP
• WordPress MCP
• Audiobook MCP
• Context7 MCP
• Bash Language Server

Python (11 servers)

Most use uvx for installation:

• Blender MCP
• FreeCAD MCP
• GIMP MCP
• Docker MCP
• Proxmox MCP
• Snipe-IT MCP
• Redmine MCP
• IMAP MCP
• Ansible MCP
• Nextcloud MCP (hybrid)
• WebSerial MCP

Go (2 servers)

• Kubernetes MCP (also available via npx)
• Terraform MCP

No Language/Prebuilt (3 servers)

• bash-language-server (npm prebuilt)
• docker-language-server (Go binary)
• marksman (prebuilt binary)

Rust (1 server)

• Elasticsearch MCP

HashiCorp Binary (1 server)

• terraform-ls (HashiCorp release binary)

Environment Variables Reference

Common environment variables required for MCP servers:

Service	Required Variables
bitwarden-mcp	BITWARDEN_CLIENT_ID, BITWARDEN_CLIENT_SECRET, BITWARDEN_PASSWORD, BITWARDEN_SERVER_URL
discourse-mcp	DISCOURSE_URL, DISCOURSE_API_KEY, DISCOURSE_API_USERNAME
ghost-mcp	GHOST_API_URL, GHOST_ADMIN_API_KEY
cloudron-mcp	CLOUDRON_URL, CLOUDRON_TOKEN
nextcloud-mcp	NEXTCLOUD_HOST, NEXTCLOUD_USERNAME, NEXTCLOUD_APP_PASSWORD
proxmox-mcp	PROXMOX_HOST, PROXMOX_USER, PROXMOX_TOKEN, PROXMOX_NODE
snipeit-mcp	SNIPEIT_URL, SNIPEIT_TOKEN
redmine-mcp	REDMINE_URL, REDMINE_API_KEY
wordpress-mcp	WORDPRESS_URL, WORDPRESS_USERNAME, WORDPRESS_APPLICATION_PASSWORD
docspace-mcp	DOCSPACE_HOST, DOCSPACE_TOKEN
imap-mcp	IMAP_SERVER, IMAP_PORT, IMAP_USERNAME, IMAP_PASSWORD
postizz-mcp	POSTIZ_API_KEY, POSTIZ_URL
matomo-mcp	MATOMO_URL, MATOMO_TOKEN
elasticsearch-mcp	ELASTICSEARCH_URL, ELASTICSEARCH_USERNAME, ELASTICSEARCH_PASSWORD
kicad-mcp	KICAD_HOST (default: host.docker.internal), KICAD_PORT (default: 5555)
context7-mcp	UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN
penpot-mcp	PENPOT_URL (default: https://design.penpot.app), PENPOT_TOKEN

Quick Start

To start an agent:

docker compose up -d <service-name>

Example:

docker compose up -d kicad-mcp

To view logs:

docker compose logs -f <service-name>

To stop an agent:

docker compose stop <service-name>

Development Notes

SDLC Compliance (REQUIRED)

Read docs/SDLC.md before working on any MCP/LSP server.

The SDLC defines the mandatory validation workflow:

1. BUILD: Container must build without errors
2. START: Container must start without immediate crash
3. PROTOCOL: Must receive valid JSON-RPC response to handshake

Without ALL THREE, a server is NOT "working".

MCP handshake command:

echo '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{},"protocolVersion":"2024-11-05","clientInfo":{"name":"test","version":"1.0.0"}},"id":1}' | \
  timeout 10 docker run --rm -i kneldevstack-aimiddleware-<service>

Critical: STATUS.md Maintenance

STATUS.md MUST always be kept fully up to date as it is the single source of truth for operational status of all MCP servers in this project.

When working on any MCP server:

1. Before starting work: Review current status in STATUS.md
2. During work: Update STATUS.md immediately after each significant milestone (build, start, validation, issues)
3. After completing work: Ensure STATUS.md accurately reflects final status with relevant notes
4. Commit STATUS.md changes: Always commit STATUS.md updates in separate atomic commits with clear commit messages

Project Conventions

• All containers use the prefix kneldevstack-aimiddleware- for easy identification
• Container names are lowercase for consistency
• Service names are lowercase for Docker Compose compatibility
• Each agent is validated individually before moving to the next
• Vendor directory is gitignored to avoid committing cloned repositories
• Dockerfile Management: Custom Dockerfiles created for vendors must be saved in the dockerfiles/ directory with a corresponding subdirectory structure (e.g., dockerfiles/bash-language-server/Dockerfile). These are tracked in git, while vendor/* is not.
• KiCAD MCP is host-only - requires KiCAD to be installed on host machine and connects via TCP

Crush Integration

All LSP and MCP instances must be configured in crush.json for Crush to use them. The configuration file uses the following format:

{
  "$schema": "https://charm.land/crush.json",
  "lsp": {
    "bash": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "kneldevstack-aimiddleware-bash-language-server"]
    }
  },
  "mcp": {
    "docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "kneldevstack-aimiddleware-docker-mcp"]
    }
  }
}

Configuration Priority:

1. .crush.json (project-local)
2. crush.json (project-local)
3. $HOME/.config/crush/crush.json (global)

For Docker-based LSP/MCP instances:

• Use docker as the command
• Include container name as the main argument
• Use -i for interactive mode (required for stdio communication)
• Use --rm to automatically clean up containers after use

Validation Checklist

For each agent, verify in order:

• Container builds successfully
• Container starts without errors
• Protocol handshake returns valid response (MANDATORY - see SDLC)
• Logs show proper initialization
• Environment variables are correctly set (if required)
• Tools are registered and available
• Resources are accessible (if applicable)

⚠️ CRITICAL: Items 1-3 are NON-NEGOTIABLE. Do not mark a server as "working" without protocol validation.

References

• Model Context Protocol
• MCP SDK
• AIWorkStack-dev
• AIWorkStack-ops