KNEL/KNEL-AIMiddleware
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c3f216e6bd27b31e4caf43b81a418c8fd08db662
KNEL-AIMiddleware/AGENTS.md
Charles N Wyble ab21749a16 docs: update container name references to lowercase kneldevstack-aimiddleware-* 
- AGENTS.md: Update all 29 container names in tables and Crush integration examples
- README.md: Update container names in Crush integration, troubleshooting, and project structure examples
- STATUS.md: Update container prefix note to reflect new naming convention

Aligns documentation with docker-compose.yml changes for consistency.
2026-01-22 10:05:43 -05:00

229 lines
9.2 KiB
Markdown
Raw Blame History

# AI Agents Documentation
This document tracks the AI agents and MCP servers configured in this project.
> **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.
## Agents Overview
### Available MCP Servers
#### Design & Engineering (3 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 |
#### 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 (2 servers)
| Service | Container Name | Description |
|---------|---------------|-------------|
| bash-language-server | kneldevstack-aimiddleware-bash-language-server | LSP for bash (diagnostics, completion, formatting) |
| 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 |
|---------|---------------|-------------|
| gimp-mcp | kneldevstack-aimiddleware-gimp-mcp | Image editing with GIMP 3.0, OCR support |
| 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) |
| audiobook-mcp | kneldevstack-aimiddleware-audiobook-mcp | Audiobook management with AI-powered features |
#### Additional Tools (3 servers)
| Service | Container Name | Description |
|---------|---------------|-------------|
| drawio-mcp | kneldevstack-aimiddleware-drawio-mcp | Draw.io diagram management |
| docker-language-server | kneldevstack-aimiddleware-docker-language-server | Language server for Dockerfiles, Compose files, Bake files |
| penpot-mcp | kneldevstack-aimiddleware-penpot-mcp | Design collaboration platform integration |
## 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 (10 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)
#### Go (2 servers)
- Kubernetes MCP (also available via npx)
- Terraform MCP
#### Rust (1 server)
- Elasticsearch MCP
## 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
### 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:
```json
{
"$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:
- [ ] Container builds successfully
- [ ] Container starts without errors
- [ ] Logs show proper initialization
- [ ] Environment variables are correctly set (if required)
- [ ] MCP protocol handshake completes
- [ ] Tools are registered and available
- [ ] Resources are accessible (if applicable)
## References
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP SDK](https://github.com/modelcontextprotocol/sdk)
- [AIWorkStack-dev](https://github.com/stars/ReachableCEO/lists/aiworkstack-dev)
- [AIWorkStack-ops](https://github.com/stars/ReachableCEO/lists/aiworkstack-ops)
Reference in New Issue View Git Blame Copy Permalink