msteams-channel: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Runtime is Bun (no Node, no bundler, no build step — TypeScript runs directly).

bun test                          # whole suite (394 tests, ~14s, no tenant/network)
bun test tests/gate.test.ts       # one file
bun test -t "outbound"            # one test by name
bun run typecheck                 # tsc --noEmit; must pass before committing
bun server.ts                     # run the MCP server standalone (stderr is the only log)
bun send.ts --list                # proactive-send CLI: list reachable conversations

Running the plugin for real needs two things beyond installing it — a managed-settings allowlist entry and claude --channels plugin:msteams@msteams-channel. See README.md "Two-step enablement"; without both, inbound events are dropped silently.

Architecture

One Bun process (server.ts) is simultaneously:

1. an MCP stdio server Claude Code spawns (tools + claude/channel capability), and
2. the Teams webhook listener (@microsoft/teams.apps App, served by our own src/bun-adapter.ts instead of the SDK's express adapter).

Same shape as the official telegram plugin, where the poller lives inside the MCP process. server.ts starts the listener and installs shutdown handlers on import — that is why pure logic (chunk.ts, env.ts, gate.ts) is extracted into src/, and why tests import modules rather than the server.

Inbound pipeline

webhook → queue.enqueue (persist before ack) → gate → conversations.upsert → permission-verdict intercept → attachment registration → normalize → notifications/claude/channel

• src/queue.ts — one file per activity, written before the webhook is acked; a throw becomes a 500 so Bot Framework retries. Dedup on activity.id; finished entries become tombstones. Unfinished entries replay on boot.
• src/gate.ts — the pure half of access control: tenant check, AAD-object-id match, channel opt-in, mention requirement. Also owns outboundAllowed(), extractThreadId(), mentionsBot(), and the Access type. Keep it free of I/O.
• src/access.ts — the stateful half: read/write access.json, pairing codes, approval dropfiles, static-mode snapshot. Imports from gate.ts, never the reverse.
• src/normalize.ts — activity → {content, meta}. Meta keys must match /^[A-Za-z0-9_]+$/ (hyphens are dropped silently by the harness) and every value must be a string. Paths go in meta, never in content — content is sender-forgeable.