# KNEL-AIMiddleware

[![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://www.docker.com/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Compatible-orange.svg)](https://modelcontextprotocol.io/)
[![LSP](https://img.shields.io/badge/LSP-Compatible-purple.svg)](https://microsoft.github.io/language-server-protocol/)
[![Production](https://img.shields.io/badge/Production-31%2F42%20Ready-brightgreen.svg)](PRODUCTION-READY.md)

> MCP and LSP infrastructure for OpenWebUI and Crush to utilize

## Production Status

| Category | Production Ready | Total | Status |
|----------|-----------------|-------|--------|
| MCP Servers | 27 | 38 | 71% |
| LSP Servers | 4 | 4 | 100% |
| **Total** | **31** | **42** | **74%** |

**See [PRODUCTION-READY.md](PRODUCTION-READY.md) for the complete list of deployable servers.**

## 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.

### Use Cases

- **OpenWebUI Integration**: Provide MCP servers for enhanced AI context and tooling
- **Crush Integration**: LSP servers for intelligent code completion and analysis
- **Development**: Individual server isolation for easy debugging and updates
- **Production**: Scalable, containerized service deployment

### Features

- Modular architecture with each service in its own container
- Docker Compose orchestration and management
- Prebuilt images with minimal dependencies
- Crush-ready LSP server configuration
- Environment variables for secure configuration
- Built-in logging and container health checks

## Server Status

For detailed build and configuration status of all MCP/LSP servers, see [STATUS.md](STATUS.md).

**For production deployment, see [PRODUCTION-READY.md](PRODUCTION-READY.md).**

## Available Servers

Legend: ✅ Production Ready | ⚠️ Config Required | ❌ Not Production Ready

### MCP Servers

#### Design & Engineering (4 servers)
| Service | Status | Container Name | Description |
|---------|--------|---------------|-------------|
| kicad-mcp | ❌ | kneldevstack-aimiddleware-kicad-mcp | PCB design (host-only, requires KiCAD on host) |
| blender-mcp | ⚠️ | kneldevstack-aimiddleware-blender-mcp | 3D modeling (requires Blender with addon) |
| freecad-mcp | ⚠️ | kneldevstack-aimiddleware-freecad-mcp | CAD modeling (requires FreeCAD with addon) |
| gimp-mcp | ⚠️ | kneldevstack-aimiddleware-gimp-mcp | Image editing (requires GIMP server) |

#### Hosting & Infrastructure (5 servers)
| Service | Status | Container Name | Description |
|---------|--------|---------------|-------------|
| kubernetes-mcp | ⚠️ | kneldevstack-aimiddleware-kubernetes-mcp | K8s/OpenShift (requires kubeconfig) |
| docker-mcp | ⚠️ | kneldevstack-aimiddleware-docker-mcp | Container management (requires Docker socket) |
| proxmox-mcp | ⚠️ | kneldevstack-aimiddleware-proxmox-mcp | Hypervisor management (requires config) |
| terraform-mcp | ⚠️ | kneldevstack-aimiddleware-terraform-mcp | IaC automation (requires HCP credentials) |
| cloudron-mcp | ⚠️ | kneldevstack-aimiddleware-cloudron-mcp | Self-hosted apps (requires CLOUDRON_URL) |

#### Development Tools (1 server)
| Service | Status | Container Name | Description |
|---------|--------|---------------|-------------|
| context7-mcp | ⚠️ | kneldevstack-aimiddleware-context7-mcp | Documentation retrieval (requires Upstash Redis) |

#### Content Management (4 servers)
| Service | Status | Container Name | Description |
|---------|--------|---------------|-------------|
| nextcloud-mcp | ❌ | kneldevstack-aimiddleware-nextcloud-mcp | 90+ tools (crashes without live Nextcloud) |
| ghost-mcp | ⚠️ | kneldevstack-aimiddleware-ghost-mcp | CMS management (requires Ghost credentials) |
| docspace-mcp | ⚠️ | kneldevstack-aimiddleware-docspace-mcp | Collaboration (requires DOCSPACE credentials) |
| wordpress-mcp | ❌ | kneldevstack-aimiddleware-wordpress-mcp | WordPress (PHP plugin, not containerizable) |

#### Communication & Collaboration (3 servers)
| Service | Status | Container Name | Description |
|---------|--------|---------------|-------------|
| discourse-mcp | ❌ | kneldevstack-aimiddleware-discourse-mcp | Forum (upstream build error) |
| imap-mcp | ❌ | kneldevstack-aimiddleware-imap-mcp | Email (crashes without live IMAP) |
| postizz-mcp | ❌ | kneldevstack-aimiddleware-postizz-mcp | Social media (HTTP transport, not stdio) |

#### Analytics & Security (2 servers)
| Service | Status | Container Name | Description |
|---------|--------|---------------|-------------|
| matomo-mcp | ✅ | kneldevstack-aimiddleware-matomo-mcp | Analytics (hosted at openmost.io) |
| bitwarden-mcp | ⚠️ | kneldevstack-aimiddleware-bitwarden-mcp | Password vault (requires Bitwarden credentials) |

#### Financial & Budgeting (3 servers)
| Service | Status | Container Name | Description |
|---------|--------|---------------|-------------|
| firefly-iii-mcp | ⚠️ | kneldevstack-aimiddleware-firefly-iii-mcp | Finance (requires Firefly III URL + PAT) |
| actual-mcp | ⚠️ | kneldevstack-aimiddleware-actual-mcp | Budget (requires Actual server credentials) |
| paperless-mcp | ⚠️ | kneldevstack-aimiddleware-paperless-mcp | Documents (requires Paperless URL + token) |

#### Productivity & Automation (6 servers)
| Service | Status | Container Name | Description |
|---------|--------|---------------|-------------|
| audiobook-mcp | ⚠️ | kneldevstack-aimiddleware-audiobook-mcp | Audiobooks (requires AUDIOBOOK_ROOT) |
| snipeit-mcp | ❌ | kneldevstack-aimiddleware-snipeit-mcp | Assets (blocked: private PyPI package) |
| mcp-redmine | ⚠️ | kneldevstack-aimiddleware-mcp-redmine | Projects (requires REDMINE_URL) |
| mcp-ansible | ❌ | kneldevstack-aimiddleware-mcp-ansible | Automation (package not in PyPI) |
| elasticsearch-mcp | ✅ | kneldevstack-aimiddleware-elasticsearch-mcp | Search (bundled with Elasticsearch) |
| drawio-mcp | ⚠️ | kneldevstack-aimiddleware-drawio-mcp | Diagrams (requires DRAWIO_URL) |

#### Additional Tools (2 servers)
| Service | Status | Container Name | Description |
|---------|--------|---------------|-------------|
| penpot-mcp | ❌ | kneldevstack-aimiddleware-penpot-mcp | Design (HTTP/WebSocket transport, not stdio) |
| webserial-mcp | ❌ | kneldevstack-aimiddleware-webserial-mcp | ESP32 dev (requires bridge server + hardware) |

#### Reverse Engineering (2 servers)
| Service | Status | Container Name | Description |
|---------|--------|---------------|-------------|
| ghidra-mcp | ✅ | kneldevstack-aimiddleware-ghidra-mcp | Binary analysis (HTTP REST, not MCP protocol) |
| reverse-engineering-assistant | ❌ | kneldevstack-aimiddleware-reverse-engineering-assistant | ReVa (upstream build error: Ghidra 404) |

### LSP Servers (4 servers) - All Production Ready ✅
| Service | Status | 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, Bake |
| marksman | ✅ | kneldevstack-aimiddleware-marksman | LSP for Markdown |
| terraform-ls | ✅ | kneldevstack-aimiddleware-terraform-ls | LSP for Terraform |

### 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

- [Docker](https://docs.docker.com/get-docker/) 20.10+
- [Docker Compose](https://docs.docker.com/compose/install/) 2.0+
- (Optional) [Crush](https://github.com/charmbracelet/crush) for LSP integration

### Quick Start

1. **Clone the repository**
   ```bash
   git clone https://github.com/KNEL/KNEL-AIMiddleware.git
   cd KNEL-AIMiddleware
   ```

2. **Configure environment variables**
   ```bash
   cp .env.example .env
   # Edit .env with your API keys and configurations
   ```

3. **Build and start services**
   ```bash
   # Start all built services
   docker compose up -d

   # Or start specific service
   docker compose up -d <service-name>
   ```

### Setup Scripts

The repository includes helpful scripts in the `scripts/` directory:

#### scripts/CloneVendorRepos.sh
Clone all upstream vendor MCP/LSP repositories:
```bash
./scripts/CloneVendorRepos.sh
```

#### scripts/BuildAll.sh
Build all MCP/LSP services:
```bash
./scripts/BuildAll.sh
```

#### scripts/CleanVendor.sh
Remove all cloned vendor repositories:
```bash
./scripts/CleanVendor.sh
```

#### scripts/StatusCheck.sh
Check build status of all services:
```bash
./scripts/StatusCheck.sh
```

## Usage

### Docker Compose Commands

#### Build and Start
```bash
# Build specific service
docker compose build <service-name>

# Build without cache
docker compose build --no-cache <service-name>

# Start service (detached mode)
docker compose up -d <service-name>

# Start all services
docker compose up -d
```

#### View Logs
```bash
# Follow logs for service
docker compose logs -f <service-name>

# View last 100 lines
docker compose logs --tail 100 <service-name>
```

#### Stop and Clean
```bash
# Stop service
docker compose stop <service-name>

# Remove service (also deletes container)
docker compose rm -f <service-name>

# Stop all services
docker compose down

# Remove all volumes
docker compose down -v
```

### Service Profiles

Services are organized into profiles for selective startup:

```bash
# Development services (LSP + MCP)
docker compose --profile dev up

# Production services
docker compose --profile prod up

# Design tools (KiCAD, Blender, etc.)
docker compose --profile design up
```

## 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` |
| firefly-iii-mcp | `FIREFLY_III_BASE_URL`, `FIREFLY_III_PAT`, `FIREFLY_III_PRESET` (optional) |
| actual-mcp | `ACTUAL_SERVER_URL`, `ACTUAL_PASSWORD`, `ACTUAL_BUDGET_SYNC_ID` |
| paperless-mcp | `PAPERLESS_URL`, `PAPERLESS_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.

### crush.json Format

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

### Configuration Priority

Crush looks for configuration files in this order:
1. `.crush.json` (project-local)
2. `crush.json` (project-local)
3. `$HOME/.config/crush/crush.json` (global)

### Docker-based LSP Configuration

For Docker-based LSP instances, use this pattern:
```json
{
  "command": "docker",
  "args": [
    "run",
    "-i",           // Interactive mode (required for stdio)
    "--rm",         // Auto-cleanup after use
    "kneldevstack-aimiddleware-<service-name>",
    "<server-args>" // e.g., "start", "--stdio"
  ]
}
```

## Project Structure

```
KNEL-AIMiddleware/
├── docker-compose.yml          # Service orchestration
├── .env                        # Environment variables (not committed)
├── .env.example                # Environment template
├── dockerfiles/                # Custom Dockerfiles (tracked in git)
│   ├── bash-language-server/
│   ├── docker-language-server/
│   └── marksman/
├── vendor/                     # Cloned repositories (gitignored)
├── docs/                       # Documentation
│   └── SDLC.md                 # Software Development Lifecycle
├── AGENTS.md                   # AI agent guidelines and rules
├── STATUS.md                   # Server status and progress tracking
├── JOURNAL.md                  # Development journal (ADRs, insights)
└── README.md                   # This file
```

### Dockerfile Management

Custom Dockerfiles are created in `dockerfiles/` and referenced in `docker-compose.yml`:

```yaml
service-name:
  build:
    context: ./vendor/service-name
    dockerfile: ../../dockerfiles/service-name/Dockerfile
  container_name: kneldevstack-aimiddleware-service-name
  restart: unless-stopped
```

This approach:
- Keeps custom Dockerfiles under version control
- Uses vendor repository as build context
- Maintains clean separation of concerns

## Troubleshooting

### Container Not Starting

```bash
# Check container logs
docker compose logs <service-name>

# Inspect container state
docker inspect <container-name>
```

### MCP Server Not Connecting

1. Verify service is running: `docker ps`
2. Check logs for errors: `docker compose logs <service>`
3. Verify environment variables in `.env`
4. Test connectivity: `docker compose exec <service> curl localhost:8080`

### LSP Server Not Responding (Crush)

1. Verify Docker image exists: `docker images | grep knel`
2. Test container manually:
   ```bash
   echo '{"jsonrpc":"2.0","method":"initialize","params":{}}' | \
   docker run -i --rm kneldevstack-aimiddleware-<lsp-name>
   ```
3. Check `crush.json` configuration
4. Verify container runs with `-i` flag for stdio

### Port Conflicts

If ports are already in use, modify `docker-compose.yml`:

```yaml
ports:
  - "8081:8080"  # Change host port
```

## Contributing

Contributions are welcome! Please see [AGENTS.md](AGENTS.md) for development guidelines and [docs/SDLC.md](docs/SDLC.md) for the development workflow.

## References

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Language Server Protocol](https://microsoft.github.io/language-server-protocol/)
- [MCP SDK](https://github.com/modelcontextprotocol/sdk)
- [Docker](https://www.docker.com/)
- [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