KNEL/KNEL-AIMiddleware
1
0
Fork 0
Code Pull Requests Actions Packages Releases Activity

docs: refactor AGENTS.md and README.md for proper separation of concerns

Browse Source 
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>
This commit is contained in:
Charles N Wyble
2026-02-20 09:52:02 -05:00
parent b1965c8161
commit cde8838133
2 changed files with 220 additions and 296 deletions
Download Patch File Download Diff File Expand all files Collapse all files

282
AGENTS.md
View File

@@ -1,229 +1,54 @@
# AI Agents Documentation # AI Agent Guidelines
This document tracks the AI agents and MCP servers configured in this project. This document contains rules and guidelines for AI agents working on 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](docs/SDLC.md) for full commit policy. ## Commit Policy
> **📋 SDLC Compliance**: All MCP/LSP development MUST follow [docs/SDLC.md](docs/SDLC.md). Key rule: **Protocol handshake is NON-NEGOTIABLE** - build + start + protocol validation ALL required before marking a server as "working". **AUTOMATIC COMMITS**: AI agents MUST commit and push changes automatically WITHOUT prompting.
> **Status Tracking**: Current operational status of all MCP servers is maintained in [STATUS.md](STATUS.md). Please refer to that file for the latest status of each server. - Use atomic commits (one logical change per commit)
- Use conventional format: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`
- Write verbose commit messages explaining the change
- See [docs/SDLC.md](docs/SDLC.md) for full commit policy
> **Journal Maintenance**: ALL work performed on this project MUST be documented in [JOURNAL.md](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. ## SDLC Compliance
## Agents Overview All MCP/LSP development MUST follow [docs/SDLC.md](docs/SDLC.md).
### Available MCP Servers **Key rule**: Protocol handshake is NON-NEGOTIABLE - build + start + protocol validation ALL required before marking a server as "working".
#### Design & Engineering (4 servers) ## Status Tracking
| 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) Current operational status of all MCP servers is maintained in [STATUS.md](STATUS.md).
| 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:
```bash
docker compose up -d <service-name>
```
Example:
```bash
docker compose up -d kicad-mcp
```
To view logs:
```bash
docker compose logs -f <service-name>
```
To stop an agent:
```bash
docker compose stop <service-name>
```
## Development Notes
### SDLC Compliance (REQUIRED)
**Read [docs/SDLC.md](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:
```bash
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: When working on any MCP server:
1. **Before starting work**: Review current status in STATUS.md 1. **Before starting**: Review current status in STATUS.md
2. **During work**: Update STATUS.md immediately after each significant milestone (build, start, validation, issues) 2. **During work**: Update STATUS.md immediately after each significant milestone
3. **After completing work**: Ensure STATUS.md accurately reflects final status with relevant notes 3. **After completing**: Ensure STATUS.md accurately reflects final status
4. **Commit STATUS.md changes**: Always commit STATUS.md updates in separate atomic commits with clear commit messages 4. **Commit changes**: Always commit STATUS.md updates in separate atomic commits
### Project Conventions ## Journal Maintenance
- All containers use the prefix `kneldevstack-aimiddleware-` for easy identification ALL work performed on this project MUST be documented in [JOURNAL.md](JOURNAL.md).
- 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 - This is an append-only journal
- Tracks Architecture Decision Records (ADRs), insights, patterns, and reasoning
- Never delete entries from the journal
- Each entry must be date/time stamped
All LSP and MCP instances must be configured in `crush.json` for Crush to use them. The configuration file uses the following format: ## Project Conventions
- Container prefix: `kneldevstack-aimiddleware-` for all containers
- Container names: lowercase for consistency
- Service names: lowercase for Docker Compose compatibility
- Each agent validated individually before moving to the next
- `vendor/` directory is gitignored (cloned repos not committed)
- Custom Dockerfiles saved in `dockerfiles/` with subdirectory structure
- KiCAD MCP is host-only - requires KiCAD installed on host machine
## Crush Configuration
LSP and MCP instances are configured in `crush.json`:
```json ```json
{ {
@@ -248,11 +73,11 @@ All LSP and MCP instances must be configured in `crush.json` for Crush to use th
2. `crush.json` (project-local) 2. `crush.json` (project-local)
3. `$HOME/.config/crush/crush.json` (global) 3. `$HOME/.config/crush/crush.json` (global)
**For Docker-based LSP/MCP instances:** **Docker-based instances:**
- Use `docker` as the command - Use `docker` as command
- Include container name as the main argument - Include container name as main argument
- Use `-i` for interactive mode (required for stdio communication) - Use `-i` for interactive mode (required for stdio)
- Use `--rm` to automatically clean up containers after use - Use `--rm` to auto-cleanup containers
## Validation Checklist ## Validation Checklist
@@ -261,15 +86,22 @@ For each agent, verify in order:
- [ ] Container starts without errors - [ ] Container starts without errors
- [ ] **Protocol handshake returns valid response** (MANDATORY - see SDLC) - [ ] **Protocol handshake returns valid response** (MANDATORY - see SDLC)
- [ ] Logs show proper initialization - [ ] Logs show proper initialization
- [ ] Environment variables are correctly set (if required) - [ ] Environment variables correctly set (if required)
- [ ] Tools are registered and available - [ ] Tools registered and available
- [ ] Resources are accessible (if applicable) - [ ] Resources accessible (if applicable)
> **⚠️ CRITICAL**: Items 1-3 are NON-NEGOTIABLE. Do not mark a server as "working" without protocol validation. **CRITICAL**: Items 1-3 are NON-NEGOTIABLE. Do not mark a server as "working" without protocol validation.
## References ## MCP Handshake Command
- [Model Context Protocol](https://modelcontextprotocol.io/) ```bash
- [MCP SDK](https://github.com/modelcontextprotocol/sdk) echo '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{},"protocolVersion":"2024-11-05","clientInfo":{"name":"test","version":"1.0.0"}},"id":1}' | \
- [AIWorkStack-dev](https://github.com/stars/ReachableCEO/lists/aiworkstack-dev) timeout 10 docker run --rm -i kneldevstack-aimiddleware-<service>
- [AIWorkStack-ops](https://github.com/stars/ReachableCEO/lists/aiworkstack-ops) ```
## Related Documentation
- [README.md](README.md) - Project overview, server inventory, installation, usage
- [STATUS.md](STATUS.md) - Server operational status and issues
- [docs/SDLC.md](docs/SDLC.md) - Software Development Lifecycle requirements
- [JOURNAL.md](JOURNAL.md) - Development journal and ADRs

222
README.md
View File

@@ -7,31 +7,134 @@
> MCP and LSP infrastructure for OpenWebUI and Crush to utilize > MCP and LSP infrastructure for OpenWebUI and Crush to utilize
## 📖 Overview ## Overview
KNEL-AIMiddleware is a comprehensive Docker-based infrastructure for running **Model Context Protocol (MCP)** servers and **Language Server Protocol (LSP)** providers. It enables AI assistants like OpenWebUI and Crush to seamlessly integrate with external tools, services, and code intelligence. KNEL-AIMiddleware is a comprehensive Docker-based infrastructure for running **Model Context Protocol (MCP)** servers and **Language Server Protocol (LSP)** providers. It enables AI assistants like OpenWebUI and Crush to seamlessly integrate with external tools, services, and code intelligence.
### 🎯 Use Cases ### Use Cases
- **OpenWebUI Integration**: Provide MCP servers for enhanced AI context and tooling - **OpenWebUI Integration**: Provide MCP servers for enhanced AI context and tooling
- **Crush Integration**: LSP servers for intelligent code completion and analysis - **Crush Integration**: LSP servers for intelligent code completion and analysis
- **Development**: Individual server isolation for easy debugging and updates - **Development**: Individual server isolation for easy debugging and updates
- **Production**: Scalable, containerized service deployment - **Production**: Scalable, containerized service deployment
## 🚀 Features ### Features
- ✅ **Modular Architecture**: Each service runs in its own container - Modular architecture with each service in its own container
- ✅ **Docker Compose**: Easy orchestration and management - Docker Compose orchestration and management
- ✅ **Prebuilt Images**: Optimized container images with minimal dependencies - Prebuilt images with minimal dependencies
- ✅ **Crush Ready**: Pre-configured LSP servers for `crush.json` - Crush-ready LSP server configuration
- ✅ **Environment Variables**: Secure configuration via `.env` file - Environment variables for secure configuration
- ✅ **Health Monitoring**: Built-in logging and container health checks - Built-in logging and container health checks
## 📊 Server Status ## Server Status
For detailed build and configuration status of all MCP/LSP servers, see [STATUS.md](STATUS.md). For detailed build and configuration status of all MCP/LSP servers, see [STATUS.md](STATUS.md).
## 📦 Installation ## Available Servers
### 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) |
### Server Technologies 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
#### Rust (1 server)
- Elasticsearch MCP
#### Prebuilt Binaries (4 servers)
- bash-language-server (npm prebuilt)
- docker-language-server (Go binary)
- marksman (prebuilt binary)
- terraform-ls (HashiCorp release binary)
## Installation
### Prerequisites ### Prerequisites
@@ -64,45 +167,33 @@ For detailed build and configuration status of all MCP/LSP servers, see [STATUS.
### Setup Scripts ### Setup Scripts
The repository includes helpful scripts in the `scripts/` directory to simplify setup and management: The repository includes helpful scripts in the `scripts/` directory:
#### scripts/CloneVendorRepos.sh #### scripts/CloneVendorRepos.sh
Clone all upstream vendor MCP/LSP repositories: Clone all upstream vendor MCP/LSP repositories:
```bash ```bash
./scripts/CloneVendorRepos.sh ./scripts/CloneVendorRepos.sh
``` ```
This script clones all 40+ vendor repositories into `vendor/` directory.
#### scripts/BuildAll.sh #### scripts/BuildAll.sh
Build all MCP/LSP services: Build all MCP/LSP services:
```bash ```bash
./scripts/BuildAll.sh ./scripts/BuildAll.sh
``` ```
This script iterates through all services in `docker-compose.yml` and builds each one.
#### scripts/CleanVendor.sh #### scripts/CleanVendor.sh
Remove all cloned vendor repositories: Remove all cloned vendor repositories:
```bash ```bash
./scripts/CleanVendor.sh ./scripts/CleanVendor.sh
``` ```
⚠️ **Warning**: This permanently deletes all cloned vendor repositories. You'll need to re-clone them.
#### scripts/StatusCheck.sh #### scripts/StatusCheck.sh
Check build status of all services: Check build status of all services:
```bash ```bash
./scripts/StatusCheck.sh ./scripts/StatusCheck.sh
``` ```
This script checks which Docker images exist and compares with `STATUS.md`. ## Usage
## 💻 Usage
### Docker Compose Commands ### Docker Compose Commands
@@ -160,7 +251,33 @@ docker compose --profile prod up
docker compose --profile design up docker compose --profile design up
``` ```
## 🔧 Crush Integration ## Environment Variables
Required variables for MCP servers (see `.env.example`):
| 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` |
**Security Note**: Never commit `.env` file to version control.
## Crush Integration
All LSP and MCP instances must be configured in `crush.json` for Crush to use them. All LSP and MCP instances must be configured in `crush.json` for Crush to use them.
@@ -209,7 +326,7 @@ For Docker-based LSP instances, use this pattern:
} }
``` ```
## 🏗️ Project Structure ## Project Structure
``` ```
KNEL-AIMiddleware/ KNEL-AIMiddleware/
@@ -221,11 +338,11 @@ KNEL-AIMiddleware/
│ ├── docker-language-server/ │ ├── docker-language-server/
│ └── marksman/ │ └── marksman/
├── vendor/ # Cloned repositories (gitignored) ├── vendor/ # Cloned repositories (gitignored)
│ ├── bash-language-server/ ├── docs/ # Documentation
│ ├── docker-language-server/ │ └── SDLC.md # Software Development Lifecycle
│ └── marksman/ ├── AGENTS.md # AI agent guidelines and rules
├── AGENTS.md # Development workflow and conventions
├── STATUS.md # Server status and progress tracking ├── STATUS.md # Server status and progress tracking
├── JOURNAL.md # Development journal (ADRs, insights)
└── README.md # This file └── README.md # This file
``` ```
@@ -247,22 +364,7 @@ This approach:
- Uses vendor repository as build context - Uses vendor repository as build context
- Maintains clean separation of concerns - Maintains clean separation of concerns
## 🌍 Environment Variables ## Troubleshooting
Required variables (see `.env.example`):
| Variable | Description | Required |
|----------|-------------|-----------|
| `OPENAI_API_KEY` | OpenAI API key for LLM services | Yes (for OpenAI) |
| `KICAD_HOST` | KiCAD server host | Yes (for KiCAD MCP) |
| `KICAD_PORT` | KiCAD server port | Yes (for KiCAD MCP) |
| `BITWARDEN_*` | Bitwarden credentials | Yes (for Bitwarden MCP) |
| `MATOMO_*` | Matomo API credentials | Yes (for Matomo MCP) |
| `*_API_KEY` | Service-specific API keys | Varies |
**⚠️ Security Note**: Never commit `.env` file to version control.
## 🔍 Troubleshooting
### Container Not Starting ### Container Not Starting
@@ -301,32 +403,22 @@ ports:
- "8081:8080" # Change host port - "8081:8080" # Change host port
``` ```
## 🤝 Contributing ## Contributing
Contributions are welcome! Please see [AGENTS.md](AGENTS.md) for development guidelines. Contributions are welcome! Please see [AGENTS.md](AGENTS.md) for development guidelines and [docs/SDLC.md](docs/SDLC.md) for the development workflow.
### Development Workflow ## References
1. Review [AGENTS.md](AGENTS.md) for conventions
2. Check [STATUS.md](STATUS.md) for current project status
3. Create feature branch
4. Add service following existing patterns
5. Update `docker-compose.yml`, `STATUS.md`, and `crush.json`
6. Test thoroughly
7. Submit pull request
## 📄 License
This project is licensed under the MIT License - see [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [Model Context Protocol](https://modelcontextprotocol.io/) - [Model Context Protocol](https://modelcontextprotocol.io/)
- [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) - [Language Server Protocol](https://microsoft.github.io/language-server-protocol/)
- [MCP SDK](https://github.com/modelcontextprotocol/sdk)
- [Docker](https://www.docker.com/) - [Docker](https://www.docker.com/)
- [Charmbracelet Crush](https://github.com/charmbracelet/crush) - [Charmbracelet Crush](https://github.com/charmbracelet/crush)
## License
This project is licensed under the MIT License - see [LICENSE](LICENSE) file for details.
--- ---
**Maintained by**: KNEL Development Team **Maintained by**: KNEL Development Team
**Last Updated**: 2026-02-19