teams-api 0.6.0 → 0.8.0

package/README.md

@@ -25,19 +25,6 @@ Designed for autonomous AI agents that need to interact with Teams: read message
 
 The quickest way to get started is to click one of the install badges above, or follow the instructions for your editor below.
 
-#### Install as an agent skill
-
-The [SKILL.md](SKILL.md) teaches AI agents _how_ to use the MCP tools (when to call which tool, typical workflows, parameter guidance). Install it with the [`skills` CLI](https://github.com/vercel-labs/skills):
-
-```bash
-npx -y skills add Maxim-Mazurok/teams-api
-```
-
-This copies the skill into your agent's skills directory (Claude Code, Cursor, GitHub Copilot, Codex, and [many more](https://www.npmjs.com/package/skills#supported-agents)).
-
-> [!NOTE]
-> The skill is optional — the MCP tools work without it. The skill just gives agents extra context about when and how to use each tool.
-
 #### Editor-specific instructions
 
 <details>
@@ -393,7 +380,7 @@ All MCP tools accept an optional `format` parameter (`json`, `text`, `md`, or `t
 | `teams_get_transcript`     | Get a meeting transcript from a recorded conversation |
 | `teams_whoami`             | Get the authenticated user's display name             |
 
-See [SKILL.md](SKILL.md) for detailed tool descriptions and typical agent workflows.
+Workflow guidance, tips, and important notes are served automatically via the MCP server's `instructions` field — no separate skill file needed. For the same content on the CLI, run `teams-api guide`.
 
 ## API regions
 

package/dist/actions/conversation-actions.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Conversation-related action definitions.
+ *
+ * Actions: list-conversations, find-conversation, find-one-on-one.
+ */
+import { type ActionDefinition } from "./formatters.js";
+export declare const listConversations: ActionDefinition;
+export declare const findConversation: ActionDefinition;
+export declare const findOneOnOne: ActionDefinition;
+//# sourceMappingURL=conversation-actions.d.ts.map

package/dist/actions/conversation-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-actions.d.ts","sourceRoot":"","sources":["../../src/actions/conversation-actions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,KAAK,gBAAgB,EAAc,MAAM,iBAAiB,CAAC;AAEpE,eAAO,MAAM,iBAAiB,EAAE,gBAmE/B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,gBAqD9B,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,gBA2C1B,CAAC"}

package/dist/actions/conversation-actions.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * Conversation-related action definitions.
+ *
+ * Actions: list-conversations, find-conversation, find-one-on-one.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findOneOnOne = exports.findConversation = exports.listConversations = void 0;
+const formatters_js_1 = require("./formatters.js");
+exports.listConversations = {
+    name: "list-conversations",
+    title: "List Teams Conversations",
+    description: "List conversations (chats, group chats, meetings, channels). " +
+        "Returns conversation ID, topic, type, member count, and last message time.",
+    parameters: [
+        {
+            name: "limit",
+            type: "number",
+            description: "Maximum number of conversations to return",
+            required: false,
+            default: 50,
+        },
+    ],
+    execute: async (client, parameters) => {
+        const limit = parameters.limit ?? 50;
+        return client.listConversations({ pageSize: limit });
+    },
+    formatResult: (result) => {
+        const conversations = result;
+        const lines = [`\n${conversations.length} conversations:\n`];
+        for (let i = 0; i < conversations.length; i++) {
+            const conversation = conversations[i];
+            const lastMessage = conversation.lastMessageTime?.slice(0, 10) ?? "unknown";
+            const topic = conversation.topic || "(untitled 1:1 chat)";
+            lines.push(`  [${i}] ${conversation.threadType}: "${topic}" ` +
+                `(members: ${conversation.memberCount ?? "?"}, last: ${lastMessage})`);
+        }
+        return lines.join("\n");
+    },
+    formatMarkdown: (result) => {
+        const conversations = result;
+        const lines = [`## Conversations (${conversations.length})`, ""];
+        if (conversations.length === 0)
+            return lines.join("\n");
+        lines.push("| # | Topic | Type | Members | Last Message |");
+        lines.push("|---|-------|------|---------|--------------|");
+        for (let i = 0; i < conversations.length; i++) {
+            const conversation = conversations[i];
+            const lastMessage = conversation.lastMessageTime?.slice(0, 10) ?? "unknown";
+            const topic = conversation.topic || "(untitled 1:1 chat)";
+            lines.push(`| ${i} | ${topic} | ${conversation.threadType} | ${conversation.memberCount ?? "?"} | ${lastMessage} |`);
+        }
+        return lines.join("\n");
+    },
+    formatToon: (result) => {
+        const conversations = result;
+        const lines = [(0, formatters_js_1.toonHeader)("📋", `${conversations.length} Conversations`)];
+        for (let i = 0; i < conversations.length; i++) {
+            const conversation = conversations[i];
+            const lastMessage = conversation.lastMessageTime?.slice(0, 10) ?? "unknown";
+            const topic = conversation.topic || "(untitled 1:1 chat)";
+            lines.push("");
+            lines.push(`  💬 [${i}] "${topic}"`);
+            lines.push(`      ${conversation.threadType} · ${conversation.memberCount ?? "?"} members · last: ${lastMessage}`);
+        }
+        return lines.join("\n");
+    },
+};
+exports.findConversation = {
+    name: "find-conversation",
+    title: "Find Teams Conversation",
+    description: "Find a conversation by topic name (case-insensitive partial match). " +
+        "When Substrate search is available, also matches by member names. " +
+        "For 1:1 chats (which have no topic), use find-one-on-one instead. " +
+        "Use the returned conversation ID for subsequent operations like get-messages or send-message.",
+    parameters: [
+        {
+            name: "query",
+            type: "string",
+            description: "Partial topic name to search for",
+            required: true,
+        },
+    ],
+    execute: async (client, parameters) => {
+        const query = parameters.query;
+        return client.findConversation(query);
+    },
+    formatResult: (result) => {
+        if (!result)
+            return "No conversation found.";
+        const conversation = result;
+        const lastMessage = conversation.lastMessageTime?.slice(0, 10) ?? "unknown";
+        return (`Found: "${conversation.topic}" ` +
+            `(${conversation.id}, ${conversation.threadType}, ` +
+            `members: ${conversation.memberCount ?? "?"}, last: ${lastMessage})`);
+    },
+    formatMarkdown: (result) => {
+        if (!result)
+            return "No conversation found.";
+        const conversation = result;
+        const lastMessage = conversation.lastMessageTime?.slice(0, 10) ?? "unknown";
+        return [
+            `## Found: "${conversation.topic}"`,
+            "",
+            `- **ID:** ${conversation.id}`,
+            `- **Type:** ${conversation.threadType}`,
+            `- **Members:** ${conversation.memberCount ?? "?"}`,
+            `- **Last message:** ${lastMessage}`,
+        ].join("\n");
+    },
+    formatToon: (result) => {
+        if (!result)
+            return "\n  🔍 No conversation found.";
+        const conversation = result;
+        const lastMessage = conversation.lastMessageTime?.slice(0, 10) ?? "unknown";
+        return [
+            (0, formatters_js_1.toonHeader)("🔍", `Found: "${conversation.topic}"`),
+            `  🆔 ${conversation.id}`,
+            `  📁 ${conversation.threadType} · ${conversation.memberCount ?? "?"} members · last: ${lastMessage}`,
+        ].join("\n");
+    },
+};
+exports.findOneOnOne = {
+    name: "find-one-on-one",
+    title: "Find 1:1 Conversation",
+    description: "Find a 1:1 conversation with a person by name. " +
+        "Uses Substrate people/chat search when available, " +
+        "falls back to scanning message senders. " +
+        "Also finds the self-chat if the name matches the current user.",
+    parameters: [
+        {
+            name: "personName",
+            type: "string",
+            description: "Name of the person to find (case-insensitive partial match)",
+            required: true,
+        },
+    ],
+    execute: async (client, parameters) => {
+        const personName = parameters.personName;
+        return client.findOneOnOneConversation(personName);
+    },
+    formatResult: (result) => {
+        if (!result)
+            return "No 1:1 conversation found.";
+        const searchResult = result;
+        return `Found 1:1 with ${searchResult.memberDisplayName} (${searchResult.conversationId})`;
+    },
+    formatMarkdown: (result) => {
+        if (!result)
+            return "No 1:1 conversation found.";
+        const searchResult = result;
+        return [
+            `## Found 1:1 with ${searchResult.memberDisplayName}`,
+            "",
+            `- **Conversation ID:** ${searchResult.conversationId}`,
+        ].join("\n");
+    },
+    formatToon: (result) => {
+        if (!result)
+            return "\n  🔍 No 1:1 conversation found.";
+        const searchResult = result;
+        return [
+            (0, formatters_js_1.toonHeader)("🔍", `Found 1:1 with ${searchResult.memberDisplayName}`),
+            `  🆔 ${searchResult.conversationId}`,
+        ].join("\n");
+    },
+};
+//# sourceMappingURL=conversation-actions.js.map

package/dist/actions/conversation-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-actions.js","sourceRoot":"","sources":["../../src/actions/conversation-actions.ts"],"names":[],"mappings":"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"}

package/dist/actions/definitions.d.ts

@@ -1,16 +1,11 @@
 /**
- * All action definitions for the Teams API.
+ * Action registry — the single source of truth for all Teams API operations.
  *
- * This is the single source of truth for all operations. CLI commands,
- * MCP tools, and programmatic usage all derive from these definitions.
- *
- * Each action declares:
- *   - name, title, description — shared help text and documentation
- *   - parameters — typed parameter definitions with descriptions and defaults
- *   - execute — the implementation, calling TeamsClient methods
- *   - formatResult — human-readable output formatter (CLI without --json)
+ * CLI commands, MCP tools, and programmatic usage all derive from these
+ * definitions. Individual action definitions live in domain-specific files;
+ * this module assembles them into the canonical registry.
  */
-import { type ActionDefinition } from "./formatters.js";
+import type { ActionDefinition } from "./formatters.js";
 /** All registered actions, derived from the registry map. */
 export declare const actions: ActionDefinition[];
 //# sourceMappingURL=definitions.d.ts.map

package/dist/actions/definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/actions/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAcH,OAAO,EACL,KAAK,gBAAgB,EAMtB,MAAM,iBAAiB,CAAC;AAw7BzB,6DAA6D;AAC7D,eAAO,MAAM,OAAO,EAAE,gBAAgB,EAAwC,CAAC"}
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/actions/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAqCxD,6DAA6D;AAC7D,eAAO,MAAM,OAAO,EAAE,gBAAgB,EAAwC,CAAC"}