From add39a2671009a0936cb31798ee2c8d105059cf2 Mon Sep 17 00:00:00 2001 From: Charles N Wyble Date: Wed, 21 Jan 2026 19:19:23 -0500 Subject: [PATCH] Enhance README.md with comprehensive documentation - Add project badges (Docker, License, MCP, LSP) - Add overview with use cases for OpenWebUI and Crush - Add features section - Add installation guide with prerequisites and quick start - Add Docker Compose usage documentation - Add Crush integration section with crush.json examples - Add project structure explanation with dockerfiles/ management - Add environment variables reference table - Add troubleshooting guide - Replace status table with link to STATUS.md (avoids duplication) - Add contributing section - Add acknowledgments section --- README.md | 291 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 290 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 1bba010..9a52bf3 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,292 @@ # KNEL-AIMiddleware -MCP and LSP infrastructure for OpenWebUI and Crush to utilize \ No newline at end of file +[![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/) + +> MCP and LSP infrastructure for OpenWebUI and Crush to utilize + +## 📖 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**: Each service runs in its own container +- ✅ **Docker Compose**: Easy orchestration and management +- ✅ **Prebuilt Images**: Optimized container images with minimal dependencies +- ✅ **Crush Ready**: Pre-configured LSP servers for `crush.json` +- ✅ **Environment Variables**: Secure configuration via `.env` file +- ✅ **Health Monitoring**: 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). + +## 📦 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 + ``` + +## 💻 Usage + +### Docker Compose Commands + +#### Build and Start +```bash +# Build specific service +docker compose build + +# Build without cache +docker compose build --no-cache + +# Start service (detached mode) +docker compose up -d + +# Start all services +docker compose up -d +``` + +#### View Logs +```bash +# Follow logs for service +docker compose logs -f + +# View last 100 lines +docker compose logs --tail 100 +``` + +#### Stop and Clean +```bash +# Stop service +docker compose stop + +# Remove service (also deletes container) +docker compose rm -f + +# 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 +``` + +## 🔧 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-", + "" // 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) +│ ├── bash-language-server/ +│ ├── docker-language-server/ +│ └── marksman/ +├── AGENTS.md # Development workflow and conventions +├── STATUS.md # Server status and progress tracking +└── 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 + +## 🌍 Environment Variables + +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 + +```bash +# Check container logs +docker compose logs + +# Inspect container state +docker inspect +``` + +### MCP Server Not Connecting + +1. Verify service is running: `docker ps` +2. Check logs for errors: `docker compose logs ` +3. Verify environment variables in `.env` +4. Test connectivity: `docker compose exec 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- + ``` +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. + +### Development Workflow + +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/) +- [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) +- [Docker](https://www.docker.com/) +- [Charmbracelet Crush](https://github.com/charmbracelet/crush) + +--- + +**Maintained by**: KNEL Development Team +**Last Updated**: 2024-01-21