KNEL/KNEL-AIMiddleware
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cd5754e8a7af0426d06cea00ac400953028e3715
KNEL-AIMiddleware/AGENTS.md
Charles N Wyble 1c1b44c025 docs: refactor AGENTS.md to reference STATUS.md 
Removed Status column from all tables to eliminate duplication
Added prominent note about STATUS.md being single source of truth
Added comprehensive STATUS.md maintenance instructions
Emphasized that STATUS.md must be kept current at all times
Commit STATUS.md updates in separate atomic commits

💘 Generated with Crush

Co-Authored-By: Crush <crush@charm.land>
2026-01-21 17:45:48 -05:00

195 lines
7.8 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-AIMW-kicad-mcp | PCB design automation with 64 tools, JLCPCB integration (host-only) |
| blender-mcp | KNELDevStack-AIMW-blender-mcp | 3D modeling, materials, scenes, AI 3D model generation |
| freecad-mcp | KNELDevStack-AIMW-freecad-mcp | CAD modeling, Python execution, parts library |
#### Hosting & Infrastructure (5 servers)
| Service | Container Name | Description |
|---------|---------------|-------------|
| kubernetes-mcp | KNELDevStack-AIMW-kubernetes-mcp | K8s/OpenShift management (native Go implementation) |
| docker-mcp | KNELDevStack-AIMW-docker-mcp | Container and compose stack management |
| proxmox-mcp | KNELDevStack-AIMW-proxmox-mcp | Hypervisor VM/container management |
| terraform-mcp | KNELDevStack-AIMW-terraform-mcp | IaC automation, HCP Terraform, workspace management |
| cloudron-mcp | KNELDevStack-AIMW-cloudron-mcp | Self-hosted app management |
#### Development Tools (2 servers)
| Service | Container Name | Description |
|---------|---------------|-------------|
| bash-language-server | KNELDevStack-AIMW-bash-language-server | LSP for bash (diagnostics, completion, formatting) |
| context7-mcp | KNELDevStack-AIMW-context7-mcp | MCP server framework and SDK for documentation |
#### Content Management (4 servers)
| Service | Container Name | Description |
|---------|---------------|-------------|
| nextcloud-mcp | KNELDevStack-AIMW-nextcloud-mcp | 90+ tools across 8 apps (Notes, Calendar, Files, Deck, etc.) |
| ghost-mcp | KNELDevStack-AIMW-ghost-mcp | CMS post, member, newsletter management |
| docspace-mcp | KNELDevStack-AIMW-docspace-mcp | Room, file, collaboration management |
| wordpress-mcp | KNELDevStack-AIMW-wordpress-mcp | WordPress integration via Abilities API |
#### Communication & Collaboration (3 servers)
| Service | Container Name | Description |
|---------|---------------|-------------|
| discourse-mcp | KNELDevStack-AIMW-discourse-mcp | Forum search, posts, topics, categories (read/write modes) |
| imap-mcp | KNELDevStack-AIMW-imap-mcp | Email browsing, composition, Gmail OAuth2 support |
| postizz-mcp | KNELDevStack-AIMW-postizz-mcp | Social media management platform |
#### Analytics & Security (2 servers)
| Service | Container Name | Description |
|---------|---------------|-------------|
| matomo-mcp | KNELDevStack-AIMW-matomo-mcp | Analytics integration |
| bitwarden-mcp | KNELDevStack-AIMW-bitwarden-mcp | Official password vault management |
#### Productivity & Automation (6 servers)
| Service | Container Name | Description |
|---------|---------------|-------------|
| gimp-mcp | KNELDevStack-AIMW-gimp-mcp | Image editing with GIMP 3.0, OCR support |
| snipeit-mcp | KNELDevStack-AIMW-snipeit-mcp | Asset inventory, maintenance tracking |
| mcp-redmine | KNELDevStack-AIMW-mcp-redmine | Project management, issue tracking, file operations |
| mcp-ansible | KNELDevStack-AIMW-mcp-ansible | IT automation playbooks |
| elasticsearch-mcp | KNELDevStack-AIMW-elasticsearch-mcp | Search and index management (Rust) |
| audiobook-mcp | KNELDevStack-AIMW-audiobook-mcp | Audiobook management with AI-powered features |
#### Additional Tools (3 servers)
| Service | Container Name | Description |
|---------|---------------|-------------|
| drawio-mcp | KNELDevStack-AIMW-drawio-mcp | Draw.io diagram management |
| docker-language-server | KNELDevStack-AIMW-docker-language-server | Language server for Dockerfiles, Compose files, Bake files |
| penpot-mcp | KNELDevStack-AIMW-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-AIMW-` for easy identification
- Container names are in PascalCase for readability
- 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
- **KiCAD MCP** is host-only - requires KiCAD to be installed on host machine and connects via TCP
## 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