fedd591b75
- Created PRODUCTION-READY.md with 31 deployable servers - Updated README.md with production status badges and markers - ✅ Production Ready (no config needed) - ⚠️ Config Required (works with backend) - ❌ Not Production Ready (blocked) - Updated STATUS.md with production summary table - Added legend for status indicators Production status: 31/42 servers (74%) ready for deployment 💘 Generated with Crush Assisted-by: GLM-5 via Crush <crush@charm.land>
450 lines
16 KiB
Markdown
450 lines
16 KiB
Markdown
# KNEL-AIMiddleware
|
|
|
|
[](https://www.docker.com/)
|
|
[](LICENSE)
|
|
[](https://modelcontextprotocol.io/)
|
|
[](https://microsoft.github.io/language-server-protocol/)
|
|
[](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
|