msteams-mcp 0.29.2 → 0.30.0

package/dist/cli/resolve.js

@@ -0,0 +1,197 @@
+/**
+ * Command and argument resolution for the `msteams` CLI.
+ *
+ * Everything here is derived from the MCP tool definitions - their names and
+ * JSON input schemas - so a new tool is callable, documented and type-coerced
+ * without touching the CLI.
+ */
+import { parseArgs } from 'node:util';
+/** Thrown for anything the user can fix by retyping the command (exit code 2). */
+export class UsageError extends Error {
+}
+/** Flag aliases that read better than the raw parameter name. */
+export const FLAG_ALIASES = {
+    to: 'conversationId',
+    msg: 'messageId',
+    message: 'messageId',
+    reply: 'replyToMessageId',
+    replyTo: 'replyToMessageId',
+    user: 'userId',
+    force: 'forceNew',
+};
+/** Flags accepted for every command. */
+const GLOBAL_FLAGS = {
+    json: { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' },
+};
+export function schemaProps(tool) {
+    return (tool.inputSchema.properties ?? {});
+}
+export function requiredProps(tool) {
+    return (tool.inputSchema.required ?? []);
+}
+/** The parameter a bare value after the command maps to: the first required string. */
+export function positionalProp(tool) {
+    const props = schemaProps(tool);
+    return requiredProps(tool).find(name => (props[name]?.type ?? 'string') === 'string') ?? null;
+}
+const normalise = (name) => name.replace(/_/g, '').toLowerCase();
+/**
+ * Resolves a typed command to a tool name.
+ *
+ * Tries, in order: the exact name, `teams_<cmd>`, `teams_get_<cmd>`,
+ * `teams_search_<cmd>`, a unique `teams_<cmd>*` prefix, then a unique
+ * substring match ignoring underscores. So `search`, `get_thread`, `thread`,
+ * `send` and `markread` all land on the right tool.
+ */
+export function resolveToolName(names, command) {
+    const cmd = command.toLowerCase();
+    const exact = [cmd, `teams_${cmd}`, `teams_get_${cmd}`, `teams_search_${cmd}`]
+        .find(name => names.includes(name));
+    if (exact)
+        return exact;
+    const prefixed = names.filter(name => name.startsWith(`teams_${cmd}`));
+    if (prefixed.length === 1)
+        return prefixed[0];
+    const fuzzy = names.filter(name => normalise(name).includes(normalise(cmd)));
+    if (fuzzy.length === 1)
+        return fuzzy[0];
+    const candidates = prefixed.length ? prefixed : fuzzy;
+    throw new UsageError(candidates.length
+        ? `Ambiguous command '${command}' - matches ${candidates.join(', ')}.`
+        : `Unknown command '${command}'. Run 'msteams help' for the command list.`);
+}
+/** The shortest form that still resolves back to this tool - used in help output. */
+export function shortName(names, toolName) {
+    const candidates = [
+        toolName.replace(/^teams_(get_|search_|list_|find_)?/, ''),
+        toolName.replace(/^teams_/, ''),
+    ];
+    for (const candidate of candidates) {
+        if (!candidate)
+            continue;
+        try {
+            if (resolveToolName(names, candidate) === toolName)
+                return candidate;
+        }
+        catch {
+            // Ambiguous - fall through to the next candidate.
+        }
+    }
+    return toolName;
+}
+/** Coerces one raw flag value using the schema's declared type. */
+function coerce(prop, raw, flag) {
+    const type = prop?.type ?? 'string';
+    if (type === 'number' || type === 'integer') {
+        const value = Number(raw);
+        if (!Number.isFinite(value))
+            throw new UsageError(`--${flag} expects a number, got '${raw}'`);
+        return value;
+    }
+    if (type === 'array') {
+        const items = raw.trim().startsWith('[')
+            ? parseJson(raw, flag)
+            : raw.split(',').map(part => part.trim()).filter(Boolean);
+        return prop?.items?.type === 'number' ? items.map(Number) : items;
+    }
+    if (type === 'object')
+        return parseJson(raw, flag);
+    return raw;
+}
+function parseJson(raw, flag) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new UsageError(`--${flag} expects JSON, got '${raw}'`);
+    }
+}
+/** One-line reminder of a command's flags, used in every usage error. */
+function flagHint(props, label) {
+    const flags = Object.keys(props).map(name => `--${name}`).join(' ') || '(none)';
+    return `Flags for '${label}': ${flags}\nRun 'msteams help ${label}' for details.`;
+}
+/**
+ * Parses a command's arguments against its input schema.
+ *
+ * Flags are whatever the schema declares (plus the aliases above), values are
+ * coerced to the schema's types, and an unknown flag is a usage error rather
+ * than something the server has to reject.
+ */
+export function parseToolArgs(tool, argv, label = tool.name) {
+    const props = schemaProps(tool);
+    const options = { ...GLOBAL_FLAGS };
+    const optionType = (prop) => prop?.type === 'boolean' ? 'boolean' : 'string';
+    for (const [name, prop] of Object.entries(props)) {
+        options[name] = { type: optionType(prop) };
+    }
+    for (const [alias, target] of Object.entries(FLAG_ALIASES)) {
+        if (props[target] && !options[alias])
+            options[alias] = { type: optionType(props[target]) };
+    }
+    // `--flag true|false` stays supported for boolean flags (it is how the docs
+    // and the MCP skill spell them), so take the value here rather than letting
+    // parseArgs treat it as a positional.
+    const explicitBooleans = {};
+    const tokens = [];
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        const name = token.startsWith('--') ? token.slice(2) : '';
+        const next = argv[i + 1];
+        if (options[name]?.type === 'boolean' && (next === 'true' || next === 'false')) {
+            explicitBooleans[FLAG_ALIASES[name] ?? name] = next === 'true';
+            i++;
+            continue;
+        }
+        tokens.push(token);
+    }
+    let parsed;
+    try {
+        parsed = parseArgs({ args: tokens, options, allowPositionals: true, strict: true });
+    }
+    catch (error) {
+        // parseArgs messages carry a long tail about '--'; the first sentence is the useful part.
+        const reason = (error instanceof Error ? error.message : String(error)).split('. ')[0];
+        throw new UsageError(`${reason}.\n${flagHint(props, label)}`);
+    }
+    // `--help` only wants to read about the command, so skip validation.
+    if (parsed.values.help) {
+        return { args: {}, json: Boolean(parsed.values.json), help: true };
+    }
+    const args = {};
+    for (const [flag, raw] of Object.entries(parsed.values)) {
+        if (flag === 'json' || flag === 'help')
+            continue;
+        const key = FLAG_ALIASES[flag] ?? flag;
+        args[key] = typeof raw === 'boolean' ? raw : coerce(props[key], String(raw), flag);
+    }
+    Object.assign(args, explicitBooleans);
+    const missing = requiredProps(tool).filter(name => args[name] === undefined);
+    const positional = positionalProp(tool);
+    const [value, ...extra] = parsed.positionals;
+    if (extra.length) {
+        throw new UsageError(`Unexpected argument '${extra[0]}'. Run 'msteams help ${label}'.`);
+    }
+    if (value !== undefined) {
+        if (!positional) {
+            throw new UsageError(`'${label}' takes no value. Run 'msteams help ${label}' for its flags.`);
+        }
+        if (args[positional] === undefined) {
+            args[positional] = coerce(props[positional], value, positional);
+            missing.splice(missing.indexOf(positional), 1);
+        }
+    }
+    if (missing.length > 0) {
+        const positionalNote = positional && missing.includes(positional)
+            ? ` (${positional} can be given as the first value: msteams ${label} "...")`
+            : '';
+        throw new UsageError(`Missing required ${missing.map(name => `--${name}`).join(', ')}${positionalNote}.\n` +
+            flagHint(props, label));
+    }
+    return {
+        args,
+        json: Boolean(parsed.values.json),
+        help: Boolean(parsed.values.help),
+    };
+}

package/dist/cli/resolve.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * CLI resolution tests.
+ *
+ * These run against the real tool definitions, so they also guard the
+ * assumption the CLI rests on: that commands, flags and positional arguments
+ * can be derived from the schemas.
+ */
+export {};

package/dist/cli/resolve.test.js

@@ -0,0 +1,118 @@
+/**
+ * CLI resolution tests.
+ *
+ * These run against the real tool definitions, so they also guard the
+ * assumption the CLI rests on: that commands, flags and positional arguments
+ * can be derived from the schemas.
+ */
+import { describe, it, expect } from 'vitest';
+import { getToolDefinitions } from '../tools/registry.js';
+import { UsageError, parseToolArgs, positionalProp, resolveToolName, shortName, } from './resolve.js';
+import { firstSentence } from './help.js';
+const tools = getToolDefinitions();
+const names = tools.map(tool => tool.name);
+const tool = (name) => tools.find(t => t.name === name);
+describe('resolveToolName', () => {
+    it.each([
+        ['teams_search', 'teams_search'],
+        ['search', 'teams_search'],
+        ['thread', 'teams_get_thread'],
+        ['get_thread', 'teams_get_thread'],
+        ['people', 'teams_search_people'],
+        ['send', 'teams_send_message'],
+        ['send_message', 'teams_send_message'],
+        ['save', 'teams_save_message'],
+        ['unsave', 'teams_unsave_message'],
+        ['markread', 'teams_mark_read'],
+        ['channel', 'teams_find_channel'],
+        ['chat', 'teams_get_chat'],
+        ['chats', 'teams_list_chats'],
+        ['message', 'teams_get_message'],
+        ['assignment', 'teams_get_assignment'],
+        ['assignments', 'teams_list_assignments'],
+        ['SEARCH', 'teams_search'],
+    ])('resolves %s', (command, expected) => {
+        expect(resolveToolName(names, command)).toBe(expected);
+    });
+    it('rejects an unknown command', () => {
+        expect(() => resolveToolName(names, 'nope')).toThrow(UsageError);
+    });
+    it('rejects an ambiguous command and names the candidates', () => {
+        expect(() => resolveToolName(names, 'reaction')).toThrow(/teams_add_reaction/);
+    });
+});
+describe('shortName', () => {
+    it('gives every tool a label that resolves back to it', () => {
+        for (const name of names) {
+            expect(resolveToolName(names, shortName(names, name))).toBe(name);
+        }
+    });
+});
+describe('positionalProp', () => {
+    it('is the first required string', () => {
+        expect(positionalProp(tool('teams_search'))).toBe('query');
+        expect(positionalProp(tool('teams_send_message'))).toBe('content');
+    });
+    it('is absent when nothing is required', () => {
+        expect(positionalProp(tool('teams_get_favorites'))).toBeNull();
+    });
+});
+describe('parseToolArgs', () => {
+    const parse = (name, argv) => parseToolArgs(tool(name), argv);
+    it('maps a bare value to the positional parameter', () => {
+        expect(parse('teams_search', ['hello']).args).toEqual({ query: 'hello' });
+    });
+    it('coerces numbers from the schema type and leaves ids as strings', () => {
+        const { args } = parse('teams_get_thread', ['--conversationId', '19:abc', '--limit', '25']);
+        expect(args).toEqual({ conversationId: '19:abc', limit: 25 });
+    });
+    it('accepts booleans as a bare flag and as --flag true|false', () => {
+        expect(parse('teams_get_thread', ['--markRead']).args.markRead).toBe(true);
+        expect(parse('teams_get_thread', ['--markRead', 'true']).args.markRead).toBe(true);
+        expect(parse('teams_get_thread', ['--markRead', 'false']).args.markRead).toBe(false);
+    });
+    it('parses arrays as JSON or a comma-separated list', () => {
+        expect(parse('teams_create_group_chat', ['--userIds', '["a","b"]']).args.userIds).toEqual(['a', 'b']);
+        expect(parse('teams_create_group_chat', ['--userIds', 'a, b']).args.userIds).toEqual(['a', 'b']);
+    });
+    it('applies flag aliases', () => {
+        const { args } = parse('teams_send_message', ['hi', '--to', '19:abc']);
+        expect(args).toEqual({ content: 'hi', conversationId: '19:abc' });
+    });
+    it('prefers an explicit flag over the positional', () => {
+        expect(parse('teams_search', ['bare', '--query', 'flag']).args.query).toBe('flag');
+    });
+    it('extracts the global flags without passing them to the tool', () => {
+        const parsed = parse('teams_search', ['hi', '--json']);
+        expect(parsed.json).toBe(true);
+        expect(parsed.args).toEqual({ query: 'hi' });
+        expect(parse('teams_search', ['--help']).help).toBe(true);
+    });
+    it.each([
+        ['an unknown flag', 'teams_search', ['hi', '--nope', 'x']],
+        ['a non-numeric number', 'teams_search', ['hi', '--size', 'abc']],
+        ['a missing required parameter', 'teams_send_message', []],
+        ['a second bare value', 'teams_search', ['one', 'two']],
+        ['a value for a command that takes none', 'teams_get_favorites', ['oops']],
+    ])('rejects %s', (_label, name, argv) => {
+        expect(() => parse(name, argv)).toThrow(UsageError);
+    });
+    it('does not require parameters that --help only wants to read about', () => {
+        expect(parse('teams_send_message', ['--help']).help).toBe(true);
+    });
+});
+describe('firstSentence', () => {
+    it('stops at the end of the first sentence', () => {
+        expect(firstSentence('Find Teams channels by name. Searches both (1) channels...'))
+            .toBe('Find Teams channels by name');
+    });
+    it('does not treat an abbreviation as the end', () => {
+        expect(firstSentence('Get profiles by MRI (e.g. "8:orgid:uuid"). Returns display name.'))
+            .toBe('Get profiles by MRI (e.g. "8:orgid:uuid")');
+    });
+    it('gives every tool a non-empty summary', () => {
+        for (const t of tools) {
+            expect(firstSentence(t.description ?? '').length).toBeGreaterThan(5);
+        }
+    });
+});

package/dist/cli.d.ts

@@ -1,20 +1,20 @@
 #!/usr/bin/env node
 /**
- * Teams MCP CLI
+ * Teams CLI
  *
- * A standalone command-line interface with full parity to the MCP server.
- * It runs the same in-process server over an in-memory transport and speaks
- * to it through the real MCP protocol, so every registered tool is callable.
+ * A standalone command-line interface with full parity to the MCP server. It
+ * runs the same in-process server over an in-memory transport and speaks to it
+ * through the real MCP protocol, so every registered tool is callable.
  *
- * Usage (installed):
- *   msteams                               # List tools and check status
- *   msteams search "query"                # Search for messages (shortcut)
- *   msteams teams_search --query "q"      # Generic tool call
- *   msteams --json                        # Output as JSON
+ *   msteams                          # command list
+ *   msteams help search              # detail for one command
+ *   msteams search "query"           # call a tool
+ *   msteams get_thread --to "<id>"   # flags come from the tool's schema
+ *   msteams search "query" --json    # machine-readable output
  *
- * Usage (from the repo):
- *   npm run cli -- search "query"
+ * Commands, flags, type coercion and help are all derived from the tool
+ * definitions, so a new tool needs no changes here.
  *
- * Any unrecognised command is treated as a tool name. Use --key value for parameters.
+ * Exit codes: 0 success, 1 the tool failed, 2 the command was malformed.
  */
 export {};