teams-api-mcp 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Maxim Mazurok
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,406 @@
1
+ # teams-api
2
+
3
+ AI-native Microsoft Teams integration — read conversations, send messages, and manage members via the Teams Chat Service REST API.
4
+
5
+ Designed for autonomous AI agents that need to interact with Teams: read messages, reply to people, monitor conversations, and participate in team workflows.
6
+
7
+ > [!NOTE]
8
+ > This project was AI-generated using Claude Opus 4.6 with human guidance and review.
9
+
10
+ ## Getting Started
11
+
12
+ `teams-api` can be used in three ways:
13
+
14
+ 1. As an MCP server for editors and AI tools. This is the recommended path for most users.
15
+ 2. As a CLI for direct terminal use.
16
+ 3. As a programmatic Node.js library. This is the advanced path and is documented near the end.
17
+
18
+ ### Recommended: MCP via `npx @latest`
19
+
20
+ Prefer running from `npx` so you always pick up the latest published version while the project is evolving quickly.
21
+
22
+ If you are on macOS and already use a platform authenticator / FIDO2 passkey, start with auto-login:
23
+
24
+ ```json
25
+ {
26
+ "mcpServers": {
27
+ "teams": {
28
+ "command": "npx",
29
+ "args": ["-y", "teams-api-mcp@latest"],
30
+ "env": {
31
+ "TEAMS_AUTO": "true",
32
+ "TEAMS_EMAIL": "you@example.com"
33
+ }
34
+ }
35
+ }
36
+ }
37
+ ```
38
+
39
+ If you are on Windows or Linux, or you want a visible browser login flow, use interactive login instead:
40
+
41
+ ```json
42
+ {
43
+ "mcpServers": {
44
+ "teams": {
45
+ "command": "npx",
46
+ "args": ["-y", "teams-api-mcp@latest"],
47
+ "env": {
48
+ "TEAMS_LOGIN": "true",
49
+ "TEAMS_EMAIL": "you@example.com",
50
+ "TEAMS_REGION": "emea"
51
+ }
52
+ }
53
+ }
54
+ }
55
+ ```
56
+
57
+ > [!TIP]
58
+ > In both recommended setups, `teams-api` captures the full token bundle automatically during login. Most users never need to copy tokens manually.
59
+
60
+ ### CLI
61
+
62
+ You can also use the CLI directly without installing anything:
63
+
64
+ ```bash
65
+ npx -y -p teams-api-mcp@latest teams-api auth --login --region emea
66
+ npx -y -p teams-api-mcp@latest teams-api list-conversations --login --region emea --limit 20
67
+ ```
68
+
69
+ If you use the CLI often, a global install is optional:
70
+
71
+ ```bash
72
+ npm install -g teams-api-mcp
73
+ teams-api auth --login --region emea
74
+ ```
75
+
76
+ ### Advanced Topics
77
+
78
+ Manual token usage, debug-session auth, and programmatic Node.js usage are covered later in this README.
79
+
80
+ ## Platform support
81
+
82
+ | Feature | macOS | Windows / Linux |
83
+ | ---------------------- | -------------- | --------------- |
84
+ | **Interactive login** | Full support | Full support |
85
+ | **Auto-login (FIDO2)** | Full support | Not supported |
86
+ | **Debug session** | Full support | Full support |
87
+ | **Direct token** | Full support | Full support |
88
+ | **Token caching** | macOS Keychain | Not available |
89
+ | **CLI & MCP server** | Full support | Full support |
90
+ | **Programmatic API** | Full support | Full support |
91
+
92
+ ## Authentication
93
+
94
+ Most users do not need to manage tokens manually.
95
+
96
+ If you use interactive login, auto-login, or a Chrome debug session, `teams-api` captures the full token bundle automatically from Teams web traffic. That includes the base `skypeToken` plus the extra bearer tokens used for profile resolution and reliable people/chat/channel search.
97
+
98
+ On macOS, prefer auto-login when you have a platform authenticator / FIDO2 passkey set up. On other platforms, use interactive login.
99
+
100
+ Direct token usage is the advanced/manual path.
101
+
102
+ | Method | Description | Automation | Platform |
103
+ | --------------------- | ---------------------------------------------------------------------------- | ---------------- | -------- |
104
+ | **Auto-login** | Playwright launches system Chrome and captures the full token bundle | Fully unattended | macOS |
105
+ | **Interactive login** | Opens a browser window and captures skype, middle-tier, and Substrate tokens | One-time manual | All |
106
+ | **Debug session** | Connects to a running Chrome instance and captures the full token bundle | Semi-manual | All |
107
+ | **Direct token** | Provide a previously captured token or token bundle explicitly | Manual | All |
108
+
109
+ ### Auto-login (macOS only)
110
+
111
+ Requires macOS with a platform authenticator (e.g. Intune Company Portal) and a FIDO2 passkey enrolled. Fully unattended — no browser window appears.
112
+
113
+ ### Interactive login (recommended for Windows / Linux)
114
+
115
+ The easiest cross-platform option. A browser window opens, you log in with any method your organization supports (password, MFA, passkey, etc.), and the token is captured automatically:
116
+
117
+ ```bash
118
+ teams-api auth --login --region emea
119
+ ```
120
+
121
+ Optionally pre-fill your email:
122
+
123
+ ```bash
124
+ teams-api auth --login --email you@example.com --region emea
125
+ ```
126
+
127
+ > [!NOTE]
128
+ > Interactive login uses Playwright's bundled Chromium. No system Chrome installation is required.
129
+
130
+ ### Advanced / manual methods
131
+
132
+ **Debug session** — start Chrome with `--remote-debugging-port=9222`, navigate to Teams and log in, then run:
133
+
134
+ ```bash
135
+ teams-api auth --debug-port 9222 --region emea
136
+ ```
137
+
138
+ **Direct token** — advanced/manual only. Extract `x-skypetoken` from browser DevTools (Network tab) and pass it directly:
139
+
140
+ ```bash
141
+ teams-api list-conversations --token "<paste-token-here>" --region emea
142
+ ```
143
+
144
+ If you want reliable people/chat/channel lookup and profile resolution on the direct-token path, also pass the extra bearer tokens captured from Teams requests:
145
+
146
+ ```bash
147
+ teams-api find-people \
148
+ --token "<paste-skype-token-here>" \
149
+ --bearer-token "<paste-api-spaces-skype-bearer-token-here>" \
150
+ --substrate-token "<paste-substrate-bearer-token-here>" \
151
+ --region emea \
152
+ --query "Jane Doe"
153
+ ```
154
+
155
+ > [!TIP]
156
+ > Skip this section if you are using `--login`, `--auto`, `TEAMS_LOGIN`, or `TEAMS_AUTO`. Those modes capture the full token bundle automatically.
157
+
158
+ > [!TIP]
159
+ > Replace `emea` with your region (`apac`, `emea`, or `amer`). See [API regions](#api-regions) below.
160
+
161
+ ## CLI
162
+
163
+ Preferred without install:
164
+
165
+ ```bash
166
+ npx -y -p teams-api-mcp@latest teams-api <command> [options]
167
+ ```
168
+
169
+ Optional global install for frequent use:
170
+
171
+ ```bash
172
+ npm install -g teams-api-mcp
173
+ teams-api <command> [options]
174
+ ```
175
+
176
+ The examples below use `teams-api` for readability. If you are not installing globally, replace it with `npx -y -p teams-api-mcp@latest teams-api`.
177
+
178
+ ### Auth flags (available on all commands)
179
+
180
+ | Flag | Description |
181
+ | --------------------------- | ------------------------------------------------------------ |
182
+ | `--login` | Interactive browser login (all platforms) |
183
+ | `--auto` | Auto-acquire token via FIDO2 passkey (macOS) |
184
+ | `--email <email>` | Corporate email (required with `--auto`, optional otherwise) |
185
+ | `--token <token>` | Use an existing skype token (advanced/manual) |
186
+ | `--bearer-token <token>` | Optional middle-tier bearer token (advanced/manual) |
187
+ | `--substrate-token <token>` | Optional Substrate bearer token (advanced/manual) |
188
+ | `--debug-port <port>` | Chrome debug port (default: 9222) |
189
+ | `--region <region>` | API region (default: apac) |
190
+ | `--format <format>` | Output format: json, text, md, toon |
191
+ | `--output <file>` | Export output to file (default format: md) |
192
+
193
+ ### Examples
194
+
195
+ ```bash
196
+ # Acquire a token (interactive — all platforms)
197
+ teams-api auth --login --region emea
198
+
199
+ # Acquire a token (auto — macOS with FIDO2)
200
+ teams-api auth --auto --email you@example.com
201
+
202
+ # List conversations
203
+ teams-api list-conversations --login --region emea --limit 20 --format json
204
+
205
+ # Find a conversation by topic
206
+ teams-api find-conversation --auto --email you@example.com --query "Design Review"
207
+
208
+ # Find a 1:1 chat by person name
209
+ teams-api find-one-on-one --auto --email you@example.com --person-name "Jane Doe"
210
+
211
+ # Read messages (by topic name, person name, or direct ID)
212
+ teams-api get-messages --auto --email you@example.com --chat "Design Review"
213
+ teams-api get-messages --auto --email you@example.com --to "Jane Doe" --max-pages 5
214
+ teams-api get-messages --auto --email you@example.com --conversation-id "19:abc@thread.v2" --format json
215
+
216
+ # Newest-first order (API returns newest-first; default is oldest-first/chronological)
217
+ teams-api get-messages --auto --email you@example.com --chat "General" --order newest-first
218
+
219
+ # Send a message
220
+ teams-api send-message --auto --email you@example.com --to "Jane Doe" --content "Hello!"
221
+ teams-api send-message --auto --email you@example.com --chat "Design Review" --content "Status update"
222
+
223
+ # List members
224
+ teams-api get-members --auto --email you@example.com --chat "Design Review" --format md
225
+
226
+ # Get current user info
227
+ teams-api whoami --auto --email you@example.com
228
+
229
+ # Export messages to a file (default format: md)
230
+ teams-api get-messages --auto --email you@example.com --chat "General" --output exports/general.md
231
+
232
+ # Export as JSON to a file
233
+ teams-api get-messages --auto --email you@example.com --chat "General" --format json --output exports/general.json
234
+
235
+ # Toon format (fun ASCII art output)
236
+ teams-api list-conversations --auto --email you@example.com --format toon
237
+ ```
238
+
239
+ ## MCP server
240
+
241
+ The MCP server exposes Teams operations as tools for AI agents via stdio transport.
242
+
243
+ ### Recommended setup
244
+
245
+ For most users, use one of these login-based configs. No manual token extraction is required.
246
+
247
+ **macOS (auto-login with FIDO2):**
248
+
249
+ ```json
250
+ {
251
+ "mcpServers": {
252
+ "teams": {
253
+ "command": "npx",
254
+ "args": ["-y", "teams-api-mcp@latest"],
255
+ "env": {
256
+ "TEAMS_AUTO": "true",
257
+ "TEAMS_EMAIL": "you@example.com"
258
+ }
259
+ }
260
+ }
261
+ }
262
+ ```
263
+
264
+ **All platforms (interactive login):**
265
+
266
+ ```json
267
+ {
268
+ "mcpServers": {
269
+ "teams": {
270
+ "command": "npx",
271
+ "args": ["-y", "teams-api-mcp@latest"],
272
+ "env": {
273
+ "TEAMS_LOGIN": "true",
274
+ "TEAMS_EMAIL": "you@example.com",
275
+ "TEAMS_REGION": "emea"
276
+ }
277
+ }
278
+ }
279
+ }
280
+ ```
281
+
282
+ > [!TIP]
283
+ > In the recommended configs above, `teams-api` captures the full token bundle automatically during login. You do not need to copy `skypeToken`, `bearerToken`, or `substrateToken` into the MCP config.
284
+
285
+ ### Advanced: direct token configuration
286
+
287
+ Use this only if you already have tokens from another flow or need to avoid browser-based auth entirely.
288
+
289
+ **All platforms (direct token):**
290
+
291
+ ```json
292
+ {
293
+ "mcpServers": {
294
+ "teams": {
295
+ "command": "npx",
296
+ "args": ["-y", "teams-api-mcp@latest"],
297
+ "env": {
298
+ "TEAMS_TOKEN": "<paste-skype-token-here>",
299
+ "TEAMS_BEARER_TOKEN": "<optional-api-spaces-skype-bearer-token>",
300
+ "TEAMS_SUBSTRATE_TOKEN": "<optional-substrate-bearer-token>",
301
+ "TEAMS_REGION": "emea"
302
+ }
303
+ }
304
+ }
305
+ }
306
+ ```
307
+
308
+ > [!TIP]
309
+ > If you do use direct tokens, `teams-api auth --login --region emea` prints the full token object as JSON. For basic chat operations, `skypeToken` is enough. For reliable people/chat/channel search and profile resolution, also pass `bearerToken` and `substrateToken`.
310
+
311
+ ### Environment variables
312
+
313
+ | Variable | Description |
314
+ | ----------------------- | --------------------------------------------------- |
315
+ | `TEAMS_TOKEN` | Pre-existing skype token |
316
+ | `TEAMS_BEARER_TOKEN` | Optional middle-tier bearer token |
317
+ | `TEAMS_SUBSTRATE_TOKEN` | Optional Substrate bearer token |
318
+ | `TEAMS_REGION` | API region (default: apac) |
319
+ | `TEAMS_EMAIL` | Corporate email for auto-login or interactive login |
320
+ | `TEAMS_AUTO` | Set to `true` to enable auto-login (macOS + FIDO2) |
321
+ | `TEAMS_LOGIN` | Set to `true` to enable interactive browser login |
322
+ | `TEAMS_DEBUG_PORT` | Chrome debug port (default: 9222) |
323
+
324
+ ### Available tools
325
+
326
+ All MCP tools accept an optional `format` parameter (`json`, `text`, `md`, or `toon`). Default format is `toon`.
327
+
328
+ | Tool | Description |
329
+ | -------------------------- | ----------------------------------------------------- |
330
+ | `teams_list_conversations` | List available conversations |
331
+ | `teams_find_conversation` | Find a conversation by topic or member name |
332
+ | `teams_find_one_on_one` | Find a 1:1 chat with a person |
333
+ | `teams_find_people` | Search the organization directory |
334
+ | `teams_find_chats` | Search chats by name or member |
335
+ | `teams_get_messages` | Get messages from a conversation |
336
+ | `teams_send_message` | Send a message to a conversation |
337
+ | `teams_get_members` | List members of a conversation |
338
+ | `teams_get_transcript` | Get a meeting transcript from a recorded conversation |
339
+ | `teams_whoami` | Get the authenticated user's display name |
340
+
341
+ See [SKILL.md](SKILL.md) for detailed tool descriptions and typical agent workflows.
342
+
343
+ ## API regions
344
+
345
+ The Teams Chat Service URL varies by region. Use the `region` parameter or `TEAMS_REGION` env var:
346
+
347
+ | Region | Base URL |
348
+ | ------ | -------------------------------------------- |
349
+ | `apac` | `https://apac.ng.msg.teams.microsoft.com/v1` |
350
+ | `emea` | `https://emea.ng.msg.teams.microsoft.com/v1` |
351
+ | `amer` | `https://amer.ng.msg.teams.microsoft.com/v1` |
352
+
353
+ ## Known limitations
354
+
355
+ - Token lifetime is ~24 hours. After expiry, you must re-acquire.
356
+ - The Teams Chat Service REST API is undocumented and may change without notice.
357
+ - Auto-login requires macOS, system Chrome, a platform authenticator, and a FIDO2 passkey. On other platforms, use interactive login (`--login`) instead.
358
+ - Token caching (macOS Keychain) is only available on macOS. On other platforms, pass the token directly or re-run interactive login each time.
359
+ - The members API returns empty display names for 1:1 chat participants. Use `findOneOnOneConversation()` to resolve names from message history.
360
+ - Reaction actor identities come from the `emotions` field in message payloads. Parsing handles both JSON-string and array formats.
361
+
362
+ ## Programmatic API
363
+
364
+ This is the advanced integration path. Most users should start with MCP or CLI instead.
365
+
366
+ Install the package in your project:
367
+
368
+ ```bash
369
+ npm install teams-api-mcp
370
+ ```
371
+
372
+ Example:
373
+
374
+ ```typescript
375
+ import { TeamsClient } from "teams-api-mcp";
376
+
377
+ // Interactive login — opens a browser, you log in manually (all platforms)
378
+ const client = await TeamsClient.fromInteractiveLogin({ region: "emea" });
379
+
380
+ // Or auto-login via platform authenticator (macOS + FIDO2 passkey)
381
+ const autoClient = await TeamsClient.fromAutoLogin({
382
+ email: "you@example.com",
383
+ });
384
+
385
+ // Advanced/manual: create a client from previously captured tokens
386
+ const manualClient = TeamsClient.fromToken("skype-token-here", "apac");
387
+
388
+ const conversations = await client.listConversations();
389
+ const messages = await client.getMessages(conversations[0].id, {
390
+ maxPages: 5,
391
+ onProgress: (count) => console.log(`Fetched ${count} messages`),
392
+ });
393
+
394
+ await client.sendMessage(conversations[0].id, "Hello from the API!");
395
+
396
+ const oneOnOne = await client.findOneOnOneConversation("Jane Doe");
397
+ const members = await client.getMembers(conversations[0].id);
398
+ ```
399
+
400
+ ## Contributing
401
+
402
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, architecture, and implementation notes.
403
+
404
+ ## License
405
+
406
+ MIT
package/SKILL.md ADDED
@@ -0,0 +1,130 @@
1
+ # teams-api MCP Skill
2
+
3
+ Use this skill when you need to interact with Microsoft Teams — reading messages, sending replies, listing conversations, or looking up team members.
4
+
5
+ All tools share a unified interface with the CLI and programmatic API. Tool definitions, parameters, and descriptions are generated from a single source (`src/actions.ts`).\n\nAll tools accept an optional `format` parameter (`json`, `text`, `md`, or `toon`). Default format is `toon`.
6
+
7
+ ## When to use
8
+
9
+ - Reading unread messages from Teams chats
10
+ - Sending messages or replies to conversations
11
+ - Finding a specific conversation or 1:1 chat
12
+ - Looking up who is in a conversation
13
+ - Monitoring conversations for updates
14
+ - Acting on behalf of the user in Teams workflows
15
+
16
+ ## Available MCP tools
17
+
18
+ ### teams_list_conversations
19
+
20
+ List conversations (chats, group chats, meetings, channels). Returns conversation ID, topic, type, member count, and last message time.
21
+
22
+ Parameters:
23
+
24
+ - `limit` (optional, number): Maximum number of conversations to return. Default: 50.
25
+
26
+ ### teams_find_conversation
27
+
28
+ Find a conversation by topic name (case-insensitive partial match). For 1:1 chats (which have no topic), use `teams_find_one_on_one` instead.
29
+
30
+ Parameters:
31
+
32
+ - `query` (required, string): Partial topic name to search for.
33
+
34
+ ### teams_find_one_on_one
35
+
36
+ Find a 1:1 conversation with a person by name. Searches untitled chats by scanning recent message sender names. Also finds the self-chat if the name matches the current user.
37
+
38
+ Parameters:
39
+
40
+ - `personName` (required, string): Name of the person to find (case-insensitive partial match).
41
+
42
+ ### teams_get_messages
43
+
44
+ Get messages from a conversation. Identify the conversation by topic name, person name for 1:1 chats, or direct ID. At least one identifier is required.
45
+
46
+ Parameters:
47
+
48
+ - `chat` (optional, string): Find conversation by topic name (partial match).
49
+ - `to` (optional, string): Find 1:1 conversation by person name.
50
+ - `conversationId` (optional, string): Direct conversation thread ID.
51
+ - `maxPages` (optional, number): Maximum pagination pages to fetch. Default: 100.
52
+ - `pageSize` (optional, number): Messages per page. Default: 200.
53
+ - `textOnly` (optional, boolean): Only return text messages, excluding system events. Default: true.
54
+ - `order` (optional, string): Message order — `oldest-first` (chronological, default) or `newest-first`.
55
+
56
+ ### teams_send_message
57
+
58
+ Send a plain-text message to a conversation. Identify the conversation by topic name, person name for 1:1 chats, or direct ID. At least one identifier is required.
59
+
60
+ Parameters:
61
+
62
+ - `chat` (optional, string): Find conversation by topic name (partial match).
63
+ - `to` (optional, string): Find 1:1 conversation by person name.
64
+ - `conversationId` (optional, string): Direct conversation thread ID.
65
+ - `content` (required, string): Message text to send.
66
+
67
+ ### teams_get_members
68
+
69
+ List members of a conversation. Identify the conversation by topic name, person name for 1:1 chats, or direct ID. At least one identifier is required. Note: 1:1 chat members may have empty display names.
70
+
71
+ Parameters:
72
+
73
+ - `chat` (optional, string): Find conversation by topic name (partial match).
74
+ - `to` (optional, string): Find 1:1 conversation by person name.
75
+ - `conversationId` (optional, string): Direct conversation thread ID.
76
+
77
+ ### teams_whoami
78
+
79
+ Get the display name and region of the currently authenticated user.
80
+
81
+ No parameters.
82
+
83
+ ## Typical workflows
84
+
85
+ ### Read and summarize a conversation
86
+
87
+ 1. Call `teams_get_messages` with `chat: "Chat Name"` — conversation resolution happens automatically
88
+ 2. Summarize the messages
89
+
90
+ Or for 1:1 chats:
91
+
92
+ 1. Call `teams_get_messages` with `to: "Person Name"`
93
+ 2. Summarize the messages
94
+
95
+ ### Reply to someone
96
+
97
+ 1. Call `teams_send_message` with `to: "Person Name"` and `content: "Your reply"`
98
+
99
+ Or for group chats:
100
+
101
+ 1. Call `teams_send_message` with `chat: "Chat Name"` and `content: "Your message"`
102
+
103
+ ### Monitor a conversation
104
+
105
+ 1. Call `teams_get_messages` with `chat: "Chat Name"` and `maxPages: 1` to check for new messages
106
+
107
+ ### Find out who is in a chat
108
+
109
+ 1. Call `teams_get_members` with `chat: "Chat Name"`
110
+
111
+ ### Look up a conversation ID
112
+
113
+ 1. Call `teams_find_conversation` with the topic name
114
+ 2. Use the returned conversation ID for subsequent operations
115
+
116
+ ## Authentication
117
+
118
+ The MCP server handles authentication automatically via environment variables. Common configurations:
119
+
120
+ - `TEAMS_TOKEN=<token>` — pre-acquired skype token (all platforms)
121
+ - `TEAMS_AUTO=true` and `TEAMS_EMAIL=user@company.com` — unattended FIDO2 login (macOS only)
122
+ - `TEAMS_LOGIN=true` — interactive browser login (all platforms, opens a visible browser window)
123
+
124
+ ## Important notes
125
+
126
+ - Conversation IDs look like `19:abc123@thread.v2` for group chats or `48:notes` for self-chat
127
+ - 1:1 chats have no topic name — use `teams_find_one_on_one` or the `to` parameter to find them by person name
128
+ - Messages include reactions, mentions, and quoted message references
129
+ - Token lifetime is ~24 hours — the server re-authenticates automatically with auto-login
130
+ - All tools share the same parameters and behavior as the CLI commands and programmatic API
@@ -0,0 +1,49 @@
1
+ /**
2
+ * Unified action definitions for the Teams API.
3
+ *
4
+ * This is the single source of truth for all operations. CLI commands,
5
+ * MCP tools, and programmatic usage all derive from these definitions.
6
+ *
7
+ * Each action declares:
8
+ * - name, title, description — shared help text and documentation
9
+ * - parameters — typed parameter definitions with descriptions and defaults
10
+ * - execute — the implementation, calling TeamsClient methods
11
+ * - formatResult — human-readable output formatter (CLI without --json)
12
+ */
13
+ import type { TeamsClient } from "./teams-client.js";
14
+ export interface ActionParameter {
15
+ /** Parameter name in camelCase (CLI flags auto-converted to kebab-case). */
16
+ name: string;
17
+ /** Parameter type. Determines CLI flag syntax and MCP Zod schema. */
18
+ type: "string" | "number" | "boolean";
19
+ /** Description for CLI help, MCP tool description, and documentation. */
20
+ description: string;
21
+ /** Whether the parameter must be provided. */
22
+ required: boolean;
23
+ /** Default value when parameter is omitted. */
24
+ default?: string | number | boolean;
25
+ }
26
+ export interface ActionDefinition {
27
+ /** Kebab-case name. CLI command name; MCP tool name is `teams_` + snake_case. */
28
+ name: string;
29
+ /** Human-readable title (MCP tool title). */
30
+ title: string;
31
+ /** Full description shared across CLI help, MCP, and documentation. */
32
+ description: string;
33
+ /** Typed parameter definitions. */
34
+ parameters: ActionParameter[];
35
+ /** Execute the action against a TeamsClient. */
36
+ execute: (client: TeamsClient, parameters: Record<string, unknown>) => Promise<unknown>;
37
+ /** Format result as human-readable text (CLI output without --json). */
38
+ formatResult: (result: unknown) => string;
39
+ /** Format result as Markdown. */
40
+ formatMarkdown: (result: unknown) => string;
41
+ /** Format result as fun ASCII art with emojis. */
42
+ formatToon: (result: unknown) => string;
43
+ }
44
+ export type OutputFormat = "json" | "text" | "md" | "toon";
45
+ export type MessageOrder = "newest-first" | "oldest-first";
46
+ /** Format an action result in the specified output format. */
47
+ export declare function formatOutput(action: ActionDefinition, result: unknown, format?: OutputFormat): string;
48
+ export declare const actions: ActionDefinition[];
49
+ //# sourceMappingURL=actions.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAerD,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IACtC,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,QAAQ,EAAE,OAAO,CAAC;IAClB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,gDAAgD;IAChD,OAAO,EAAE,CACP,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAChC,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,wEAAwE;IACxE,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC;IAC1C,iCAAiC;IACjC,cAAc,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC;IAC5C,kDAAkD;IAClD,UAAU,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC;CACzC;AAID,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC;AAC3D,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG,cAAc,CAAC;AAE3D,8DAA8D;AAC9D,wBAAgB,YAAY,CAC1B,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,OAAO,EACf,MAAM,GAAE,YAAqB,GAC5B,MAAM,CAWR;AAs6BD,eAAO,MAAM,OAAO,EAAE,gBAAgB,EAWrC,CAAC"}