@mizyoel/mercury-mesh 0.9.4

package/.mesh/templates/machine-capabilities.md

@@ -0,0 +1,77 @@
+# Machine Capability Discovery & Label-Based Routing
+
+> Enable Ralph to skip issues requiring capabilities the current machine lacks.
+
+## Overview
+
+When running Mercury Mesh across multiple machines (laptops, DevBoxes, GPU servers, Kubernetes nodes), each machine has different tooling. The capability system lets you declare what each machine can do, and Ralph automatically routes work accordingly.
+
+## Setup
+
+### 1. Create a Capabilities Manifest
+
+Create `~/.mesh/machine-capabilities.json` (user-wide) or `.mesh/machine-capabilities.json` (project-local):
+
+```json
+{
+  "machine": "MY-LAPTOP",
+  "capabilities": ["browser", "personal-gh", "onedrive"],
+  "missing": ["gpu", "docker", "azure-speech"],
+  "lastUpdated": "2026-03-22T00:00:00Z"
+}
+```
+
+### 2. Label Issues with Requirements
+
+Add `needs:*` labels to issues that require specific capabilities:
+
+| Label | Meaning |
+|-------|---------|
+| `needs:browser` | Requires Playwright / browser automation |
+| `needs:gpu` | Requires NVIDIA GPU |
+| `needs:personal-gh` | Requires personal GitHub account |
+| `needs:emu-gh` | Requires Enterprise Managed User account |
+| `needs:azure-cli` | Requires authenticated Azure CLI |
+| `needs:docker` | Requires Docker daemon |
+| `needs:onedrive` | Requires OneDrive sync |
+| `needs:teams-mcp` | Requires Teams MCP tools |
+
+Custom capabilities are supported — any `needs:X` label works if `X` is in the machine's `capabilities` array.
+
+### 3. Run Ralph
+
+```bash
+Mercury Mesh watch --interval 5
+```
+
+The CLI command is still legacy-named during the compatibility phase.
+
+Ralph will log skipped issues:
+```
+⏭️ Skipping #42 "Train ML model" — missing: gpu
+✓ Triaged #43 "Fix CSS layout" → Picard (routing-rule)
+```
+
+## How It Works
+
+1. Ralph loads `machine-capabilities.json` at startup
+2. For each open issue, Ralph extracts `needs:*` labels
+3. If any required capability is missing, the issue is skipped
+4. Issues without `needs:*` labels are always processed (opt-in system)
+
+## Kubernetes Integration
+
+On Kubernetes, machine capabilities map to node labels:
+
+```yaml
+# Node labels (set by capability DaemonSet or manually)
+node.mesh.dev/gpu: "true"
+node.mesh.dev/browser: "true"
+
+# Pod spec uses nodeSelector
+spec:
+  nodeSelector:
+    node.mesh.dev/gpu: "true"
+```
+
+A DaemonSet can run capability discovery on each node and maintain labels automatically. See the [Mercury Mesh on AKS (legacy repo name: Mercury Mesh-on-aks)](https://github.com/tamirdresher/Mercury Mesh-on-aks) project for a complete Kubernetes deployment example.

package/.mesh/templates/mcp-config.md

@@ -0,0 +1,90 @@
+# MCP Integration — Configuration and Samples
+
+MCP (Model Context Protocol) servers extend Mercury Mesh with tools for external services — Trello, Aspire dashboards, Azure, Notion, and more. The user configures MCP servers in their environment; Mercury Mesh discovers and uses them.
+
+> **Full patterns:** Read `.mesh/skills/mcp-tool-discovery/SKILL.md` for discovery patterns, domain-specific usage, and graceful degradation.
+
+## Config File Locations
+
+Users configure MCP servers at these locations (checked in priority order):
+1. **Repository-level:** `.copilot/mcp-config.json` (team-shared, committed to repo)
+2. **Workspace-level:** `.vscode/mcp.json` (VS Code workspaces)
+3. **User-level:** `~/.copilot/mcp-config.json` (personal)
+4. **CLI override:** `--additional-mcp-config` flag (session-specific)
+
+## Sample Config — Trello
+
+```json
+{
+  "mcpServers": {
+    "trello": {
+      "command": "npx",
+      "args": ["-y", "@trello/mcp-server"],
+      "env": {
+        "TRELLO_API_KEY": "${TRELLO_API_KEY}",
+        "TRELLO_TOKEN": "${TRELLO_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Sample Config — GitHub
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Sample Config — Azure
+
+```json
+{
+  "mcpServers": {
+    "azure": {
+      "command": "npx",
+      "args": ["-y", "@azure/mcp-server"],
+      "env": {
+        "AZURE_SUBSCRIPTION_ID": "${AZURE_SUBSCRIPTION_ID}",
+        "AZURE_CLIENT_ID": "${AZURE_CLIENT_ID}",
+        "AZURE_CLIENT_SECRET": "${AZURE_CLIENT_SECRET}",
+        "AZURE_TENANT_ID": "${AZURE_TENANT_ID}"
+      }
+    }
+  }
+}
+```
+
+## Sample Config — Aspire
+
+```json
+{
+  "mcpServers": {
+    "aspire": {
+      "command": "npx",
+      "args": ["-y", "@aspire/mcp-server"],
+      "env": {
+        "ASPIRE_DASHBOARD_URL": "${ASPIRE_DASHBOARD_URL}"
+      }
+    }
+  }
+}
+```
+
+## Authentication Notes
+
+- **GitHub MCP requires a separate token** from the `gh` CLI auth. Generate at https://github.com/settings/tokens
+- **Trello requires API key + token** from https://trello.com/power-ups/admin
+- **Azure requires service principal credentials** — see Azure docs for setup
+- **Aspire uses the dashboard URL** — typically `http://localhost:18888` during local dev
+
+Auth is a real blocker for some MCP servers. Users need separate tokens for GitHub MCP, Azure MCP, Trello MCP, etc. This is a documentation problem, not a code problem.