diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3486b53 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,176 @@ +# AI Agents Documentation + +This document tracks the AI agents and MCP servers configured in this project. + +## Agents Overview + +### Available MCP Servers + +#### Design & Engineering (3 servers) +| Service | Container Name | Status | Description | +|---------|---------------|--------|-------------| +| kicad-mcp | KNELDevStack-AIMW-kicad-mcp | In Progress | PCB design automation with 64 tools, JLCPCB integration | +| blender-mcp | KNELDevStack-AIMW-blender-mcp | Pending | 3D modeling, materials, scenes, AI 3D model generation | +| freecad-mcp | KNELDevStack-AIMW-freecad-mcp | Pending | CAD modeling, Python execution, parts library | + +#### Hosting & Infrastructure (5 servers) +| Service | Container Name | Status | Description | +|---------|---------------|--------|-------------| +| kubernetes-mcp | KNELDevStack-AIMW-kubernetes-mcp | Pending | K8s/OpenShift management (native Go implementation) | +| docker-mcp | KNELDevStack-AIMW-docker-mcp | Pending | Container and compose stack management | +| proxmox-mcp | KNELDevStack-AIMW-proxmox-mcp | Pending | Hypervisor VM/container management | +| terraform-mcp | KNELDevStack-AIMW-terraform-mcp | Pending | IaC automation, HCP Terraform, workspace management | +| cloudron-mcp | KNELDevStack-AIMW-cloudron-mcp | Pending | Self-hosted app management | + +#### Development Tools (2 servers) +| Service | Container Name | Status | Description | +|---------|---------------|--------|-------------| +| bash-language-server | KNELDevStack-AIMW-bash-language-server | Pending | LSP for bash (diagnostics, completion, formatting) | +| context7-mcp | KNELDevStack-AIMW-context7-mcp | Pending | MCP server framework and SDK for documentation | + +#### Content Management (4 servers) +| Service | Container Name | Status | Description | +|---------|---------------|--------|-------------| +| nextcloud-mcp | KNELDevStack-AIMW-nextcloud-mcp | Pending | 90+ tools across 8 apps (Notes, Calendar, Files, Deck, etc.) | +| ghost-mcp | KNELDevStack-AIMW-ghost-mcp | Pending | CMS post, member, newsletter management | +| docspace-mcp | KNELDevStack-AIMW-docspace-mcp | Pending | Room, file, collaboration management | +| wordpress-mcp | KNELDevStack-AIMW-wordpress-mcp | Pending | WordPress integration via Abilities API | + +#### Communication & Collaboration (3 servers) +| Service | Container Name | Status | Description | +|---------|---------------|--------|-------------| +| discourse-mcp | KNELDevStack-AIMW-discourse-mcp | Pending | Forum search, posts, topics, categories (read/write modes) | +| imap-mcp | KNELDevStack-AIMW-imap-mcp | Pending | Email browsing, composition, Gmail OAuth2 support | +| postizz-mcp | KNELDevStack-AIMW-postizz-mcp | Pending | Social media management platform | + +#### Analytics & Security (2 servers) +| Service | Container Name | Status | Description | +|---------|---------------|--------|-------------| +| matomo-mcp | KNELDevStack-AIMW-matomo-mcp | Pending | Analytics integration | +| bitwarden-mcp | KNELDevStack-AIMW-bitwarden-mcp | Pending | Official password vault management | + +#### Productivity & Automation (6 servers) +| Service | Container Name | Status | Description | +|---------|---------------|--------|-------------| +| gimp-mcp | KNELDevStack-AIMW-gimp-mcp | Pending | Image editing with GIMP 3.0, OCR support | +| snipeit-mcp | KNELDevStack-AIMW-snipeit-mcp | Pending | Asset inventory, maintenance tracking | +| mcp-redmine | KNELDevStack-AIMW-mcp-redmine | Pending | Project management, issue tracking, file operations | +| mcp-ansible | KNELDevStack-AIMW-mcp-ansible | Pending | IT automation playbooks | +| elasticsearch-mcp | KNELDevStack-AIMW-elasticsearch-mcp | Pending | Search and index management (Rust) | +| audiobook-mcp | KNELDevStack-AIMW-audiobook-mcp | Pending | Audiobook management with AI-powered features | + +#### Additional Tools (3 servers) +| Service | Container Name | Status | Description | +|---------|---------------|--------|-------------| +| drawio-mcp | KNELDevStack-AIMW-drawio-mcp | Pending | Draw.io diagram management | +| docker-language-server | KNELDevStack-AIMW-docker-language-server | Pending | Language server for Dockerfiles, Compose files, Bake files | + +## 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` | +| context7-mcp | `UPSTASH_REDIS_REST_URL`, `UPSTASH_REDIS_REST_TOKEN` | + +## Quick Start + +To start an agent: +```bash +docker compose up -d +``` + +Example: +```bash +docker compose up -d kicad-mcp +``` + +To view logs: +```bash +docker compose logs -f +``` + +To stop an agent: +```bash +docker compose stop +``` + +## Development Notes + +- 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 + +## 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)