feat: v1.3 advanced features + WebSocket transport + batch command

.github/workflows/claude-code-review.yml

@@ -19,9 +19,9 @@ jobs:
     env:
       ANTHROPIC_BASE_URL: http://10.71.20.53:4000
       ANTHROPIC_API_KEY: ${{ secrets.LITELLM_API_KEY }}
-      ANTHROPIC_MODEL: sonnet
-      ANTHROPIC_DEFAULT_SONNET_MODEL: sonnet
-      ANTHROPIC_DEFAULT_OPUS_MODEL: opus
+      ANTHROPIC_MODEL: sonnet4.6
+      ANTHROPIC_DEFAULT_SONNET_MODEL: sonnet4.6
+      ANTHROPIC_DEFAULT_OPUS_MODEL: opus4.6
       ANTHROPIC_DEFAULT_HAIKU_MODEL: haiku
     steps:
       - name: Checkout
@@ -34,7 +34,7 @@ jobs:
         with:
           anthropic_api_key: ${{ secrets.LITELLM_API_KEY }}
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          model: "sonnet"
+          model: "sonnet4.6"
           direct_prompt: |
             Review this PR for the mcp2cli project (CLI bridge for MCP servers). Focus on:
             1. Bugs and logic errors

README.md

@@ -51,6 +51,7 @@ mcp2cli discovers MCP servers from `~/.config/mcp2cli/services.json`:
 {
   "services": {
     "n8n": {
+      "description": "n8n workflow automation",
       "backend": "stdio",
       "command": "npx",
       "args": ["-y", "@anthropic-ai/n8n-mcp"],
@@ -60,6 +61,7 @@ mcp2cli discovers MCP servers from `~/.config/mcp2cli/services.json`:
       }
     },
     "homekit": {
+      "description": "HomeKit smart home control",
       "backend": "stdio",
       "command": "node",
       "args": ["/path/to/homekit-mcp/dist/index.js"],
@@ -249,6 +251,177 @@ mcp2cli n8n n8n_get_workflow --params '{"id": "abc123"}'
 
 This pattern keeps MCP tool definitions out of the agent's system prompt entirely. The agent only pays context cost when it actually needs to call a tool, and even then only for the specific tool's schema -- not all tools from all servers.
 
+## v1.3 Advanced Features
+
+### Schema Caching
+
+Schemas are cached locally to avoid re-fetching on every invocation. Cached schemas live at `~/.cache/mcp2cli/schemas/` with a 24-hour TTL. Cache drift is detected via SHA-256 hashing -- if the upstream schema changes, the cache is automatically invalidated.
+
+```bash
+# Check cache status (age, TTL, drift)
+mcp2cli cache status
+
+# Clear all cached schemas
+mcp2cli cache clear
+
+# Clear cache for a specific service
+mcp2cli cache clear n8n
+
+# Bypass cache for a single schema lookup
+mcp2cli schema n8n.n8n_list_workflows --fresh
+```
+
+Override the cache directory with `MCP2CLI_CACHE_DIR`.
+
+### Access Control
+
+Restrict which tools are exposed per service using `allowTools` and `blockTools` in `services.json`. Both accept glob patterns.
+
+```json
+{
+  "services": {
+    "n8n": {
+      "description": "n8n workflow automation",
+      "backend": "stdio",
+      "command": "npx",
+      "args": ["-y", "@anthropic/n8n-mcp"],
+      "allowTools": ["n8n_list_*", "n8n_get_*"],
+      "blockTools": ["n8n_delete_*"]
+    }
+  }
+}
+```
+
+When both are present, `allowTools` is evaluated first (whitelist), then `blockTools` removes matches from the allowed set.
+
+#### Cross-Service Tool Search
+
+Search for tools across all services using cached schemas:
+
+```bash
+# Find all tools matching a pattern
+mcp2cli grep "workflow"
+
+# Regex patterns work
+mcp2cli grep "delete|remove"
+```
+
+This searches cached schemas only -- no MCP connections are made.
+
+### WebSocket Transport
+
+Connect to MCP servers over WebSocket. Supports optional stdio fallback and access control, same as HTTP.
+
+```json
+{
+  "services": {
+    "remote-mcp": {
+      "description": "Remote MCP server via WebSocket",
+      "backend": "websocket",
+      "url": "ws://mcp-gateway.local:3000/mcp",
+      "fallback": {
+        "command": "npx",
+        "args": ["-y", "@anthropic/n8n-mcp"]
+      }
+    }
+  }
+}
+```
+
+WebSocket services benefit from the same circuit breaker and fallback behavior as HTTP services.
+
+### Batch Tool Calls
+
+Execute multiple tool calls in a single invocation by piping NDJSON to `mcp2cli batch`. Each line is a JSON object with `service`, `tool`, and `params` fields:
+
+```bash
+# Sequential execution (default)
+cat <<EOF | mcp2cli batch
+{"service": "n8n", "tool": "n8n_list_workflows", "params": {}}
+{"service": "n8n", "tool": "n8n_get_workflow", "params": {"id": "1"}}
+EOF
+
+# Parallel execution
+cat <<EOF | mcp2cli batch --parallel
+{"service": "n8n", "tool": "n8n_list_workflows", "params": {}}
+{"service": "n8n", "tool": "n8n_get_workflow", "params": {"id": "1"}}
+EOF
+```
+
+Output is NDJSON -- one result per line with the original service/tool for correlation:
+
+```json
+{"service":"n8n","tool":"n8n_list_workflows","success":true,"result":{...}}
+{"service":"n8n","tool":"n8n_get_workflow","success":true,"result":{...}}
+```
+
+Errors for individual calls are reported inline without aborting the batch.
+
+### Gateway Resilience
+
+HTTP/SSE services can define a `fallback` stdio config. If the remote gateway is unreachable, mcp2cli transparently falls back to a local MCP server process.
+
+```json
+{
+  "services": {
+    "n8n": {
+      "description": "n8n via HTTP gateway with stdio fallback",
+      "backend": "http",
+      "url": "http://mcp-gateway:3000/n8n",
+      "fallback": {
+        "command": "npx",
+        "args": ["-y", "@anthropic/n8n-mcp"]
+      }
+    }
+  }
+}
+```
+
+A circuit breaker protects against repeated failures: after 5 consecutive failures the circuit opens and routes directly to fallback for 60 seconds before re-probing the primary. Circuit state is persisted to `~/.cache/mcp2cli/circuit-breaker/` so it survives process restarts.
+
+### Output Formats
+
+Control output format with the `--format` flag:
+
+```bash
+mcp2cli n8n n8n_list_workflows --params '{}' --format table
+mcp2cli n8n n8n_list_workflows --params '{}' --format yaml
+mcp2cli n8n n8n_list_workflows --params '{}' --format csv
+mcp2cli n8n n8n_list_workflows --params '{}' --format ndjson
+```
+
+| Format | Description |
+|--------|-------------|
+| `json` | Default. Structured JSON (unchanged from v1.0) |
+| `table` | Aligned columns -- human-readable terminal output |
+| `yaml` | YAML output |
+| `csv` | RFC 4180 CSV -- pipe to spreadsheets or `csvtool` |
+| `ndjson` | One JSON object per line -- for streaming pipelines |
+
+Error responses are always JSON regardless of the `--format` flag.
+
+### Skill Auto-Regeneration
+
+Generated skill files can be previewed and kept in sync with upstream schema changes:
+
+```bash
+# Preview what would change without writing
+mcp2cli generate-skills --diff n8n
+
+# Regenerate (preserves manual sections)
+mcp2cli generate-skills n8n
+```
+
+Manual edits inside `MANUAL:START` / `MANUAL:END` markers are preserved across regeneration. When schema drift is detected (via the caching layer), skill regeneration can be triggered automatically.
+
+## v1.3 Environment Variables
+
+In addition to the variables listed above, v1.3 adds:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MCP2CLI_CACHE_DIR` | `~/.cache/mcp2cli` | Base directory for schema cache and circuit breaker state |
+
 ## Development
 
 ```bash

examples/services-basic.json

@@ -0,0 +1,10 @@
+{
+  "services": {
+    "n8n": {
+      "description": "n8n workflow automation",
+      "backend": "stdio",
+      "command": "npx",
+      "args": ["-y", "@anthropic/n8n-mcp"]
+    }
+  }
+}

examples/services-http-fallback.json

@@ -0,0 +1,13 @@
+{
+  "services": {
+    "n8n": {
+      "description": "n8n via HTTP gateway with stdio fallback",
+      "backend": "http",
+      "url": "http://mcp-gateway.local:3000/n8n",
+      "fallback": {
+        "command": "npx",
+        "args": ["-y", "@anthropic/n8n-mcp"]
+      }
+    }
+  }
+}

examples/services-multi.json

@@ -0,0 +1,18 @@
+{
+  "services": {
+    "n8n": {
+      "description": "n8n workflow automation",
+      "backend": "stdio",
+      "command": "npx",
+      "args": ["-y", "@anthropic/n8n-mcp"],
+      "allowTools": ["n8n_list_*", "n8n_get_*", "n8n_search_*"],
+      "blockTools": ["n8n_delete_*"]
+    },
+    "qmd": {
+      "description": "QMD document search and retrieval",
+      "backend": "stdio",
+      "command": "qmd",
+      "args": ["mcp"]
+    }
+  }
+}

examples/services-websocket.json

@@ -0,0 +1,13 @@
+{
+  "services": {
+    "remote-mcp": {
+      "description": "Remote MCP server via WebSocket",
+      "backend": "websocket",
+      "url": "ws://mcp-gateway.local:3000/mcp",
+      "fallback": {
+        "command": "npx",
+        "args": ["-y", "@anthropic/n8n-mcp"]
+      }
+    }
+  }
+}

examples/skills/n8n/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: n8n
+description: MCP tools for n8n
+triggers:
+  - n8n
+  - workflow
+  - node
+  - detail
+  - levels
+  - multiple
+  - modes
+  - template
+---
+
+# n8n
+
+MCP tools for n8n
+
+<!-- AUTO-GENERATED:START -->
+
+## Quick Reference
+
+| Tool | Description |
+|------|-------------|
+| get_node | Get node info with progressive detail levels and multiple modes. |
+| get_template | Get template by ID. |
+| n8n_autofix_workflow | Automatically fix common workflow validation errors. |
+| n8n_create_workflow | Create workflow. |
+| n8n_delete_workflow | Permanently delete a workflow. |
+| n8n_deploy_template | Deploy a workflow template from n8n. |
+| n8n_executions | Manage workflow executions: get details, list, or delete. |
+| n8n_get_workflow | Get workflow by ID with different detail levels. |
+| n8n_health_check | Check n8n instance health and API connectivity. |
+| n8n_list_workflows | List workflows (minimal metadata only). |
+| n8n_test_workflow | Test/trigger workflow execution. |
+| n8n_update_full_workflow | Full workflow update. |
+| n8n_update_partial_workflow | Update workflow incrementally with diff operations. |
+| n8n_validate_workflow | Validate workflow by ID. |
+| n8n_workflow_versions | Manage workflow version history, rollback, and cleanup. |
+| search_nodes | Search n8n nodes by keyword with optional real-world examples. |
+| search_templates | Search templates with multiple modes. |
+| tools_documentation | Get documentation for n8n MCP tools. |
+| validate_node | Validate n8n node configuration. |
+| validate_workflow | Full workflow validation: structure, connections, expressions, AI tools. |
+
+## Usage
+
+```bash
+mcp2cli n8n <tool> --params '{...}'
+```
+
+See `references/` for detailed parameter docs per tool.
+
+<!-- AUTO-GENERATED:END -->
+
+## Notes
+
+<!-- MANUAL:START -->
+<!-- Add your custom notes, examples, or overrides here -->
+<!-- MANUAL:END -->