feat(mcp): add MCP bridge + Cowork kit + business-user docs

Turn lark-cli into an MCP server so Claude Desktop (Cowork) and
claude.ai (web) can drive Lark/Feishu without Claude Code.

- cmd/mcp: `lark-cli mcp serve` (stdio + streamable-HTTP), 21 curated
  tools + `lark_api` passthrough; bearer-token gate via
  LARK_MCP_BEARER_TOKEN (constant-time), /health endpoint, audit log.
- shortcuts/im: port `+card-send` (YAML card spec -> Feishu card JSON).
- .claude: 23 Cowork workflow skills + /mcp-* slash commands.
- docs: business-user guide (desktop, web/tunnel, auth, skills, tools,
  security, troubleshooting) + 30-slide deck.
- examples/mcp-hosts, scripts/setup-mcp.sh, MCP_QUICKSTART.md.

Secrets (Lark token, bearer token) stay in OS keychain / env vars;
nothing sensitive committed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: transformgroup

.claude/commands/mcp-add.md

@@ -0,0 +1,69 @@
+---
+description: Walk through adding a new tool to the lark-cli MCP bridge
+argument-hint: <tool-name> [underlying shortcut, e.g. "im +messages-pin"]
+allowed-tools: Bash, Read, Edit, Write, Grep, Glob
+---
+
+You will add a new MCP tool to `cmd/mcp/tools.go`. Follow these
+steps exactly; do not skip the verification.
+
+## 1. Resolve the shortcut
+
+If the user supplied the underlying shortcut as the second argument,
+use it directly. Otherwise, ask the user OR delegate to the
+`shortcut-explorer` agent to find the right service/verb pair (conceptual `service +command`).
+
+Confirm the shortcut's exact flag names by reading
+`shortcuts/<domain>/<file>.go`. **Never guess flags.**
+
+## 2. Pick a tool name
+
+Format: `lark_<domain>_<verb>` — e.g. `lark_im_pin`, `lark_doc_export`.
+Stay consistent with the existing 20 tools.
+
+## 3. Edit `cmd/mcp/tools.go`
+
+1. Append a new `toolXxx()` factory near the bottom of the file.
+2. Register it in `allTools()`, grouped with siblings of the same
+   domain.
+3. Define the JSON Schema as a raw string literal. Required fields
+   go in the top-level `required` array.
+4. In the `Build` closure:
+   - Use `argString(args, "key")` for required strings.
+   - Use `appendFlag(argv, "flag-name", value)` for optional flags.
+   - Add `appendIdentity(argv, args)` at the end so callers can
+     pass `as: "bot"`.
+   - Map MCP arg names with `_` to CLI flag names with `-`.
+
+## 4. Verify
+
+```bash
+go build -o ~/bin/lark-cli .
+~/bin/lark-cli mcp tools | grep <tool-name>
+```
+
+Then run the smoke handshake (from `cmd/mcp/README.md` §Verify) and
+issue a real `tools/call` for the new tool with safe arguments
+(`--dry-run` flag if the shortcut supports it).
+
+## 5. Update docs
+
+- Append the tool to the catalogue table in `cmd/mcp/README.md`.
+
+## 6. Report
+
+Summarise:
+
+- Tool name + 1-line description.
+- Exact CLI invocation it generates.
+- Verification output (build status, mcp tools listing line, smoke
+  test result).
+- Any flag names you could not confirm from source.
+
+## Hard rules
+
+- No third-party MCP library imports.
+- No `fmt.Println` or any stdout write inside `cmd/mcp/`. Stdout
+  is JSON-RPC only.
+- One MCP tool wraps exactly one shortcut. Composite flows go to
+  `lark_api` or are left to the model to chain.

.claude/commands/mcp-call.md

@@ -0,0 +1,81 @@
+---
+description: Invoke one MCP tool end-to-end (handshake + tools/call) and print the result
+argument-hint: <tool-name> [json-args, default {}]
+allowed-tools: Bash, Read
+---
+
+One-shot wrapper around `lark-cli mcp serve` for fast dev iteration.
+Use after editing `cmd/mcp/tools.go` to confirm a tool actually
+works without launching Claude Desktop.
+
+## 1. Resolve inputs
+
+- Tool name: `$1`. Required. If empty, abort and tell the user the
+  usage: `/mcp-call <tool-name> '<json-args>'`.
+- Args: `$2`. Default `{}` if not supplied.
+- Validate `$2` parses as JSON before spending the handshake:
+
+```bash
+echo "$2" | python3 -c "import json,sys;json.loads(sys.stdin.read())" \
+  || { echo "Args is not valid JSON"; exit 1; }
+```
+
+## 2. Locate the binary
+
+Prefer `~/bin/lark-cli` (dev build). Fall back to `which lark-cli`.
+Print the absolute path you picked.
+
+## 3. Confirm the tool is in the catalogue
+
+```bash
+$BIN mcp tools 2>&1 | grep -F "$1" \
+  || { echo "Tool '$1' not in catalogue — rebuild via /mcp-rebuild"; exit 1; }
+```
+
+## 4. Send the call
+
+```bash
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"mcp-call","version":"0"}}}' \
+  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
+  "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"$1\",\"arguments\":$ARGS}}" \
+  | $BIN mcp serve 2>/tmp/mcp-call.stderr
+```
+
+Where `$ARGS` is `$2` (already validated JSON).
+
+## 5. Parse and present
+
+Three lines on stdout. Discard the first (init response) and
+focus on the third (the `tools/call` result):
+
+```bash
+... | python3 -c "
+import json, sys
+lines = [l for l in sys.stdin if l.strip()]
+resp = json.loads(lines[-1])
+result = resp.get('result', {})
+err = result.get('isError')
+print('isError:', bool(err))
+for block in result.get('content', []):
+    print(block.get('text', ''))
+"
+```
+
+## 6. Report
+
+- Tool called + args used.
+- `isError: true/false`.
+- Result content (truncated to ~40 lines).
+- If `isError: true`: tail `/tmp/mcp-call.stderr` for the stderr
+  the subprocess emitted — that's where the real error is.
+
+## Safety
+
+- **Refuse destructive args** unless the user explicitly types
+  "yes, run it for real". Specifically: `lark_im_send` with a real
+  `chat_id`, any `*-delete` tool, anything where the shortcut does
+  not advertise `--dry-run`. Default to `--dry-run` if the
+  underlying shortcut supports it (delegate to `shortcut-explorer`
+  to check).
+- Always `rm -f /tmp/mcp-call.stderr` after.

.claude/commands/mcp-doctor.md

@@ -0,0 +1,91 @@
+---
+description: One-page health report for the MCP bridge — build, handshake, sample call, host config, logs
+allowed-tools: Bash, Read, Grep
+---
+
+Aggregate every layer of the bridge into a single, scannable report.
+Run when the user says "is everything ok", "status check", "what's
+the state of MCP", or before a release.
+
+## Sections (run in order, stop only on hard failure)
+
+### 1. Binary
+
+```bash
+BIN=$(command -v lark-cli || echo "$HOME/bin/lark-cli")
+[ -x "$BIN" ] || { echo "no binary"; exit 1; }
+"$BIN" --version
+```
+
+### 2. Catalogue
+
+```bash
+"$BIN" mcp tools 2>&1 | tail -3
+```
+
+Count tools. Compare to the count of `func toolXxx() tool {`
+in `cmd/mcp/tools.go` — should match.
+
+### 3. Handshake
+
+Reuse the recipe from `/mcp-test`. Capture stdout line count
+(expect 2) and stderr length.
+
+### 4. Sample `tools/call`
+
+Pick the safest tool from the catalogue (read-only, no required
+arg): `lark_calendar_agenda` with `{}` (today is the default), or
+`lark_task_my` with `{}`. Both are safe. If neither exists, skip
+this step and note "no safe sample".
+
+### 5. Host config
+
+```bash
+HOST_CFG="$HOME/Library/Application Support/Claude/claude_desktop_config.json"
+if [ -f "$HOST_CFG" ]; then
+  python3 -c "
+import json
+c = json.load(open('$HOST_CFG'))
+servers = c.get('mcpServers', {})
+for name, s in servers.items():
+    if 'lark' in name.lower():
+        print(name, '→', s.get('command'), s.get('args'))
+"
+fi
+```
+
+### 6. Recent host log
+
+`tail -20` of the latest `~/Library/Logs/Claude/mcp*.log` if any.
+
+### 7. Auth
+
+`lark-cli auth status` first 3 lines + `lark-cli profile list` head.
+
+## Report shape
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MCP doctor — <timestamp>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Binary       <path> <version>                    ✅ / ❌
+Catalogue    <N> tools (source: <M>)              ✅ / ⚠ drift / ❌
+Handshake    initialize + tools/list              ✅ / ❌
+Sample call  <tool> → isError=<bool>              ✅ / ❌
+Host config  registered as "<name>" → <path>      ✅ / ❌ / not-installed
+Host log     last error: "<line or —>"
+Auth         profile=<name> identity=<u/b>        ✅ / ❌
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+VERDICT      HEALTHY / DEGRADED / BROKEN
+NEXT ACTION  <one sentence, only if not HEALTHY>
+```
+
+Then stop. Do not start work — the user might just be checking.
+
+## Hard rules
+
+- Pure observation. Do not mutate any state — no `auth login`, no
+  host config edits, no rebuilds.
+- If a step requires sudo or a destructive command to even read
+  (rare here), skip it and note "skipped, requires elevation".
+- Always clean up temp files: `rm -f /tmp/mcp-doctor.*`.

.claude/commands/mcp-rebuild.md

@@ -0,0 +1,58 @@
+---
+description: Rebuild lark-cli and reinstall the binary so Claude Desktop picks up changes
+argument-hint: [install-path, default ~/bin/lark-cli]
+allowed-tools: Bash, Read
+---
+
+Rebuild the local binary after MCP changes and (re)install it where
+the MCP host will find it.
+
+## 1. Pick the install path
+
+Use `$1` if supplied. Otherwise default to `~/bin/lark-cli`.
+If the user explicitly wants `/usr/local/bin/lark-cli`, warn that
+sudo will be required and ask for confirmation.
+
+## 2. Build
+
+```bash
+go build -o /tmp/lark-cli .
+ls -la /tmp/lark-cli
+```
+
+If `go build` fails, stop and surface the error.
+
+## 3. Smoke-check the build
+
+```bash
+/tmp/lark-cli --version
+/tmp/lark-cli mcp tools | tail -3
+```
+
+Both must succeed. The `mcp tools` output should show "20 tools total"
+(or however many are defined in `cmd/mcp/tools.go`).
+
+## 4. Install
+
+```bash
+cp /tmp/lark-cli <install-path>
+<install-path> --version
+```
+
+## 5. Remind to restart
+
+After installing, the MCP host (Claude Desktop, Claude Code) still
+holds a handle to the **old** binary process. Tell the user:
+
+- Claude Desktop: Cmd+Q (full quit) and reopen.
+- Claude Code: the next session picks up the new binary; no restart
+  needed for ad-hoc CLI use.
+
+## 6. Report
+
+- Install path.
+- Binary version string and modification time.
+- Tool count.
+- Whether a restart is needed for the active host.
+
+Do not edit any source. This command is build-and-install only.

.claude/commands/mcp-test.md

@@ -0,0 +1,51 @@
+---
+description: Smoke-test the lark-cli MCP server (initialize + tools/list + optional tools/call)
+argument-hint: [tool-name] [json-args]
+allowed-tools: Bash, Read
+---
+
+Verify the MCP bridge end-to-end without needing Claude Desktop.
+
+## 1. Locate the binary
+
+Prefer `~/bin/lark-cli` (development build). Fall back to
+`/usr/local/bin/lark-cli` if that's where the user installed it.
+Print the path you picked.
+
+## 2. Run the handshake
+
+```bash
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
+  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
+  | <binary-path> mcp serve 2>/tmp/mcp-smoke.log
+```
+
+Expected: two JSON-RPC response lines on stdout. The first must
+contain `"protocolVersion":"2024-11-05"`. The second must contain
+`"tools":[`.
+
+## 3. (Optional) Real tool call
+
+If the user supplied `$1` (tool name), build a third request:
+
+```bash
+printf '%s\n' \
+  <initialize line> \
+  <initialized notification> \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"<tool>","arguments":<args>}}' \
+  | <binary-path> mcp serve
+```
+
+Use `$2` (JSON object) for arguments, or `{}` if not provided.
+
+## 4. Report
+
+- Binary path used.
+- Did initialize succeed? (Y/N)
+- Tool count in `tools/list` response.
+- If `tools/call` run: did it return `isError: true` or success?
+- Tail of `/tmp/mcp-smoke.log` for the server's stderr logs.
+
+Stop after reporting. Do not modify any files.

.claude/commands/mcp-tools.md

@@ -0,0 +1,18 @@
+---
+description: List the MCP tools currently exposed by `lark-cli mcp serve`
+allowed-tools: Bash
+---
+
+Run `lark-cli mcp tools` against the active install and print the
+catalogue. This is a one-shot read; no edits.
+
+```bash
+lark-cli mcp tools 2>&1 || ~/bin/lark-cli mcp tools 2>&1
+```
+
+If neither works, surface the error verbatim — the binary is likely
+not on PATH yet. Suggest running `/mcp-rebuild` to (re)install.
+
+After printing the catalogue, summarise in one sentence which tool
+domains are covered (IM, Calendar, Docs, Base, Contact, Task, Drive,
+plus the generic `lark_api` passthrough — note any gaps).