Slim CLAUDE.md from 65K to 21K by splitting app-specific docs
Move OpenClaw, Palmr, MinIO, JSX publishing, MCP configs, and migration candidates into dedicated docs/ files. Keep only DevOps-essential content inline (deployment rules, DNS, router, credentials, troubleshooting). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Alejandro Gutiérrez
180
docs/mcp-configs.md
Normal file
180
docs/mcp-configs.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# MCP Server Configurations
|
||||
|
||||
Detailed setup and configuration guides for MCP servers used with the NUC.
|
||||
|
||||
## Stalwart Mail MCP
|
||||
|
||||
**Location:** `~/mcp-servers/stalwart-mail/`
|
||||
|
||||
Manage the self-hosted Stalwart mail server via natural language.
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Category | Tools |
|
||||
|----------|-------|
|
||||
| **Users** | `list_users`, `get_user`, `create_user`, `update_user_password`, `delete_user`, `add_email_alias` |
|
||||
| **Domains** | `create_domain`, `generate_dkim` |
|
||||
| **Queue** | `list_queue`, `get_queue_status`, `delete_queued_message`, `retry_queued_message` |
|
||||
| **Monitoring** | `get_metrics`, `get_dmarc_reports`, `get_server_logs` |
|
||||
| **DNS** | `check_dns_records`, `troubleshoot_delivery` |
|
||||
| **Spam** | `train_spam`, `train_ham`, `update_spam_filter` |
|
||||
|
||||
### Usage Examples
|
||||
```
|
||||
"List all mail users"
|
||||
"Create user sales with email sales@whyrating.com and password Secret123"
|
||||
"Check the mail queue"
|
||||
"Verify DNS records for whyrating.com"
|
||||
"Show server metrics"
|
||||
"Delete user john"
|
||||
```
|
||||
|
||||
### Direct API Test (if MCP not responding)
|
||||
```bash
|
||||
curl -s -u "admin:QfKYjCJdxu" "http://192.168.1.3:8081/api/principal" | jq .
|
||||
```
|
||||
|
||||
### Reconfigure MCP
|
||||
```bash
|
||||
claude mcp remove stalwart-mail
|
||||
claude mcp add stalwart-mail \
|
||||
-e STALWART_URL=http://192.168.1.3:8081 \
|
||||
-e STALWART_USER=admin \
|
||||
-e STALWART_PASS=QfKYjCJdxu \
|
||||
--scope user \
|
||||
-- ~/mcp-servers/stalwart-mail/.venv/bin/python ~/mcp-servers/stalwart-mail/server.py
|
||||
```
|
||||
|
||||
### SMTP Authentication Requirements
|
||||
|
||||
1. **Password format:** Must be SHA-512 hashed (not plaintext). When creating users via API:
|
||||
```python
|
||||
import crypt
|
||||
hashed = crypt.crypt('password', crypt.mksalt(crypt.METHOD_SHA512))
|
||||
# Use hashed value in 'secrets' field
|
||||
```
|
||||
2. **SMTP login:** Use username only (e.g., `info`), NOT full email (`info@whyrating.com`)
|
||||
3. **Port 465 (SMTPS):** Supports PLAIN/LOGIN auth with implicit TLS
|
||||
4. **Port 587 (Submission):** Requires STARTTLS, only OAuth supported without TLS
|
||||
|
||||
### Send email via Python (from NUC)
|
||||
```python
|
||||
import smtplib, ssl
|
||||
from email.mime.text import MIMEText
|
||||
|
||||
context = ssl.create_default_context()
|
||||
context.check_hostname = False
|
||||
context.verify_mode = ssl.CERT_NONE
|
||||
|
||||
with smtplib.SMTP_SSL('localhost', 465, context=context) as server:
|
||||
server.login('info', 'whyrating2026') # Username only!
|
||||
server.sendmail('info@whyrating.com', 'recipient@example.com', msg.as_string())
|
||||
```
|
||||
|
||||
## Email Client MCP (Read/Send Emails)
|
||||
|
||||
**Package:** [mcp-email-server](https://github.com/ai-zerolab/mcp-email-server)
|
||||
|
||||
Read and send emails via IMAP/SMTP directly from Claude.
|
||||
|
||||
**Configured for:** `info@whyrating.com` on Stalwart
|
||||
|
||||
### Usage Examples
|
||||
```
|
||||
"Check my inbox"
|
||||
"Read the latest email"
|
||||
"Send an email to john@example.com with subject Hello"
|
||||
"Search emails from support@"
|
||||
"List email folders"
|
||||
```
|
||||
|
||||
### Reconfigure
|
||||
```bash
|
||||
claude mcp remove email-client
|
||||
claude mcp add email-client \
|
||||
-e MCP_EMAIL_SERVER_EMAIL_ADDRESS=info@whyrating.com \
|
||||
-e MCP_EMAIL_SERVER_PASSWORD=whyrating2026 \
|
||||
-e MCP_EMAIL_SERVER_IMAP_HOST=192.168.1.3 \
|
||||
-e MCP_EMAIL_SERVER_IMAP_PORT=143 \
|
||||
-e MCP_EMAIL_SERVER_SMTP_HOST=192.168.1.3 \
|
||||
-e MCP_EMAIL_SERVER_SMTP_PORT=587 \
|
||||
-e MCP_EMAIL_SERVER_SMTP_VERIFY_SSL=false \
|
||||
-e MCP_EMAIL_SERVER_ENABLE_ATTACHMENT_DOWNLOAD=true \
|
||||
--scope user \
|
||||
-- uvx mcp-email-server@latest stdio
|
||||
```
|
||||
|
||||
## Adding Remote MCP Servers (HTTP Transport)
|
||||
|
||||
**Use `claude mcp add --transport http` for remote MCP endpoints** - this is the recommended method for services with native MCP support.
|
||||
|
||||
```bash
|
||||
# Basic syntax
|
||||
claude mcp add --transport http <name> <url> --scope user --header "<header>"
|
||||
|
||||
# Example: NocoDB MCP (globally available)
|
||||
claude mcp add --transport http nocodb http://192.168.1.3:8084/mcp/ncnyir1cy6n9bf5p \
|
||||
--scope user \
|
||||
--header "xc-mcp-token: qjjAXRxuYzRtEn-cA4lbPFi5km_pojTX"
|
||||
```
|
||||
|
||||
**Scope options:**
|
||||
- `--scope user` - Available across all projects (stored in `~/.claude.json`)
|
||||
- `--scope local` - Current project only (default)
|
||||
- `--scope project` - Shared via `.mcp.json` (committed to repo)
|
||||
|
||||
**Why CLI over JSON config:**
|
||||
- JSON config with `mcp-remote` often fails to load tools
|
||||
- CLI `--transport http` handles HTTP endpoints natively
|
||||
- No need for `--allow-http` flag or other workarounds
|
||||
|
||||
**Managing MCP servers:**
|
||||
```bash
|
||||
claude mcp list # List all configured servers
|
||||
claude mcp get nocodb # Get details for specific server
|
||||
claude mcp remove nocodb # Remove a server
|
||||
/mcp # Check status in Claude Code
|
||||
```
|
||||
|
||||
## Playwriter as Fallback
|
||||
|
||||
When SSH, API endpoints, or other MCPs can't accomplish a task (e.g., no API available, UI-only settings), use **Playwriter MCP** to automate browser interactions:
|
||||
|
||||
```javascript
|
||||
// Navigate to service UI
|
||||
await page.goto('http://192.168.1.3:8000');
|
||||
// Get page state
|
||||
console.log(await accessibilitySnapshot({ page }));
|
||||
// Interact with elements
|
||||
await page.locator('aria-ref=e5').click();
|
||||
```
|
||||
|
||||
**Use cases:**
|
||||
- Configuring services that lack APIs (Coolify UI settings, etc.)
|
||||
- Creating OAuth apps, API keys through web interfaces
|
||||
- Debugging issues by inspecting service dashboards
|
||||
- Any task where clicking through a UI is the only option
|
||||
|
||||
## Remote Browser Container (NUC)
|
||||
|
||||
A dedicated browser container runs on the NUC for AI-controlled browsing without local resources:
|
||||
|
||||
**Access:**
|
||||
- noVNC Web: `http://192.168.1.3:6081/vnc.html`
|
||||
- Playwriter Relay: `ws://192.168.1.3:19988`
|
||||
- Chrome DevTools: `http://192.168.1.3:9222`
|
||||
|
||||
**MCP connects remotely via:**
|
||||
```json
|
||||
{
|
||||
"playwriter-nuc-01": {
|
||||
"_id": "nuc-01",
|
||||
"_host": "192.168.1.3",
|
||||
"args": ["playwriter", "--host", "ws://192.168.1.3:19988", "--token", "nuc-browser-token"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**First-time setup:** Access noVNC, install Playwriter extension, click to activate (turns green).
|
||||
|
||||
**Container location:** `~/playwriter-browser/` on NUC (deployed via docker compose)
|
||||
Reference in New Issue
Block a user