@plosson/agentio 0.5.13 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plosson/agentio",
-  "version": "0.5.13",
+  "version": "0.6.0",
   "description": "CLI for LLM agents to interact with communication and tracking services",
   "type": "module",
   "license": "MIT",
@@ -35,7 +35,8 @@
     "dev": "bun run src/index.ts",
     "build": "bun build src/index.ts --outdir dist --target node",
     "build:native": "bun build src/index.ts --compile --minify --sourcemap --bytecode --define BUILD_VERSION=\"\\\"$(bun -e 'console.log(require(\"./package.json\").version)')\\\"\" --outfile dist/agentio",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
   },
   "engines": {
     "node": ">=18"
@@ -53,6 +54,7 @@
     "@googleapis/sheets": "^13.0.1",
     "@googleapis/tasks": "^12.0.0",
     "@inquirer/prompts": "^8.2.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@whiskeysockets/baileys": "^7.0.0-rc.9",
     "commander": "^14.0.2",
     "google-auth-library": "^10.0.0",

package/src/auth/oauth.ts

@@ -15,6 +15,7 @@ const GCHAT_SCOPES = [
   'https://www.googleapis.com/auth/chat.messages.readonly',   // read messages (get operations)
   'https://www.googleapis.com/auth/chat.spaces.readonly',     // read space info and list
   'https://www.googleapis.com/auth/chat.memberships.readonly', // read space members
+  'https://www.googleapis.com/auth/directory.readonly',        // resolve user IDs to names/emails via People API
   'https://www.googleapis.com/auth/userinfo.email',           // get user email for profile naming
 ];
 

package/src/commands/gchat.ts

@@ -96,6 +96,11 @@ export function registerGChatCommands(program: Command): void {
           }
         }
 
+        // Unescape shell-escaped characters (e.g. zsh history expansion: \! → !)
+        if (text) {
+          text = text.replace(/\\!/g, '!');
+        }
+
         const { client, profile } = await getGChatClient(options.profile);
         await enforceWriteAccess('gchat', profile, 'send message');
         const result = await client.send({

package/src/commands/mcp.ts

@@ -0,0 +1,147 @@
+import { Command } from 'commander';
+import { readFile, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { listProfiles } from '../config/config-manager';
+import { interactiveCheckbox } from '../utils/interactive';
+import { CliError, handleError } from '../utils/errors';
+import {
+  parseServiceProfiles,
+  startMcpServer,
+  type ServiceProfilePair,
+} from '../mcp/server';
+
+const MCP_JSON = '.mcp.json';
+
+/**
+ * Load existing .mcp.json or return empty structure.
+ */
+async function loadMcpJson(
+  dir: string
+): Promise<Record<string, unknown>> {
+  const filePath = join(dir, MCP_JSON);
+  if (!existsSync(filePath)) {
+    return {};
+  }
+  const content = await readFile(filePath, 'utf-8');
+  return JSON.parse(content) as Record<string, unknown>;
+}
+
+/**
+ * Write .mcp.json, merging with existing content.
+ */
+async function writeMcpJson(
+  dir: string,
+  pairs: ServiceProfilePair[]
+): Promise<string> {
+  const filePath = join(dir, MCP_JSON);
+  const existing = await loadMcpJson(dir);
+
+  const mcpServers = (existing.mcpServers as Record<string, unknown>) || {};
+
+  // Build the args list
+  const serveArgs = pairs.map((p) =>
+    p.profile ? `${p.service}:${p.profile}` : p.service
+  );
+
+  mcpServers['agentio'] = {
+    command: 'agentio',
+    args: ['mcp', 'serve', ...serveArgs],
+  };
+
+  existing.mcpServers = mcpServers;
+
+  await writeFile(filePath, JSON.stringify(existing, null, 2) + '\n');
+  return filePath;
+}
+
+/**
+ * Interactive mode: let user pick from configured profiles.
+ */
+async function interactiveInstall(): Promise<ServiceProfilePair[]> {
+  const allProfiles = await listProfiles();
+  const choices: Array<{
+    name: string;
+    value: ServiceProfilePair;
+    checked?: boolean;
+  }> = [];
+
+  for (const { service, profiles } of allProfiles) {
+    if (profiles.length === 0) continue;
+    for (const profile of profiles) {
+      choices.push({
+        name: `${service}:${profile.name}`,
+        value: { service, profile: profile.name },
+      });
+    }
+  }
+
+  if (choices.length === 0) {
+    throw new CliError(
+      'CONFIG_ERROR',
+      'No profiles configured',
+      'Add profiles first with: agentio <service> profile add'
+    );
+  }
+
+  const selected = await interactiveCheckbox<ServiceProfilePair>({
+    message: 'Select services to expose via MCP',
+    choices,
+    required: true,
+  });
+
+  return selected;
+}
+
+export function registerMcpCommands(program: Command): void {
+  const mcp = program
+    .command('mcp')
+    .description('MCP server operations');
+
+  // serve subcommand
+  mcp
+    .command('serve')
+    .description('Start stdio MCP server exposing CLI commands as tools')
+    .argument('<pairs...>', 'Service:profile pairs (e.g., gmail:work slack:team rss)')
+    .action(async (pairArgs: string[]) => {
+      try {
+        const pairs = parseServiceProfiles(pairArgs);
+        await startMcpServer(pairs);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  // install subcommand
+  mcp
+    .command('install')
+    .description('Install MCP server config into .mcp.json')
+    .argument('[pairs...]', 'Service:profile pairs (interactive if omitted)')
+    .action(async (pairArgs: string[]) => {
+      try {
+        let pairs: ServiceProfilePair[];
+
+        if (pairArgs && pairArgs.length > 0) {
+          pairs = parseServiceProfiles(pairArgs);
+        } else {
+          pairs = await interactiveInstall();
+        }
+
+        if (pairs.length === 0) {
+          console.log('No services selected.');
+          return;
+        }
+
+        const filePath = await writeMcpJson(process.cwd(), pairs);
+
+        const serveArgs = pairs
+          .map((p) => (p.profile ? `${p.service}:${p.profile}` : p.service))
+          .join(' ');
+
+        console.log(`Wrote ${filePath}`);
+        console.log(`\nMCP server command: agentio mcp serve ${serveArgs}`);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+}

package/src/index.ts

@@ -22,6 +22,7 @@ import { registerWhatsAppCommands } from './commands/whatsapp';
 // Agentio utilities
 import { registerClaudeCommands } from './commands/claude';
 import { registerConfigCommands } from './commands/config';
+import { registerMcpCommands } from './commands/mcp';
 import { registerDocsCommand } from './commands/docs';
 import { registerGatewayCommands } from './commands/gateway';
 import { registerReauthCommand } from './commands/reauth';
@@ -65,10 +66,16 @@ registerWhatsAppCommands(program);
 // Agentio utilities
 registerClaudeCommands(program);
 registerConfigCommands(program);
+registerMcpCommands(program);
 registerDocsCommand(program);
 registerGatewayCommands(program);
 registerReauthCommand(program);
 registerStatusCommand(program);
 registerUpdateCommand(program);
 
+// Show help (exit 0) when no command is provided
+program.action(() => {
+  program.help();
+});
+
 program.parse();

package/src/mcp/__tests__/install.test.ts

@@ -0,0 +1,136 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { mkdtemp, writeFile, readFile, rm } from 'fs/promises';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { existsSync } from 'fs';
+
+// Re-implement the core install logic here for unit testing
+// (the actual command uses process.cwd() and commander, so we test the JSON generation)
+
+interface ServiceProfilePair {
+  service: string;
+  profile?: string;
+}
+
+async function loadMcpJson(dir: string): Promise<Record<string, unknown>> {
+  const filePath = join(dir, '.mcp.json');
+  if (!existsSync(filePath)) {
+    return {};
+  }
+  const content = await readFile(filePath, 'utf-8');
+  return JSON.parse(content) as Record<string, unknown>;
+}
+
+async function writeMcpJson(
+  dir: string,
+  pairs: ServiceProfilePair[]
+): Promise<string> {
+  const filePath = join(dir, '.mcp.json');
+  const existing = await loadMcpJson(dir);
+  const mcpServers = (existing.mcpServers as Record<string, unknown>) || {};
+
+  const serveArgs = pairs.map((p) =>
+    p.profile ? `${p.service}:${p.profile}` : p.service
+  );
+
+  mcpServers['agentio'] = {
+    command: 'agentio',
+    args: ['mcp', 'serve', ...serveArgs],
+  };
+
+  existing.mcpServers = mcpServers;
+  await writeFile(filePath, JSON.stringify(existing, null, 2) + '\n');
+  return filePath;
+}
+
+describe('MCP install (.mcp.json generation)', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'agentio-mcp-test-'));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  test('creates .mcp.json with correct structure', async () => {
+    await writeMcpJson(tmpDir, [
+      { service: 'gmail', profile: 'work' },
+      { service: 'rss' },
+    ]);
+
+    const content = JSON.parse(
+      await readFile(join(tmpDir, '.mcp.json'), 'utf-8')
+    );
+
+    expect(content).toEqual({
+      mcpServers: {
+        agentio: {
+          command: 'agentio',
+          args: ['mcp', 'serve', 'gmail:work', 'rss'],
+        },
+      },
+    });
+  });
+
+  test('preserves other servers in existing .mcp.json', async () => {
+    // Write an existing .mcp.json with another server
+    await writeFile(
+      join(tmpDir, '.mcp.json'),
+      JSON.stringify({
+        mcpServers: {
+          'other-server': {
+            command: 'other',
+            args: ['serve'],
+          },
+        },
+      })
+    );
+
+    await writeMcpJson(tmpDir, [{ service: 'gmail', profile: 'work' }]);
+
+    const content = JSON.parse(
+      await readFile(join(tmpDir, '.mcp.json'), 'utf-8')
+    );
+
+    // Both servers should be present
+    expect(content.mcpServers['other-server']).toEqual({
+      command: 'other',
+      args: ['serve'],
+    });
+    expect(content.mcpServers['agentio']).toEqual({
+      command: 'agentio',
+      args: ['mcp', 'serve', 'gmail:work'],
+    });
+  });
+
+  test('updates existing agentio entry in .mcp.json', async () => {
+    // First install
+    await writeMcpJson(tmpDir, [{ service: 'gmail', profile: 'work' }]);
+
+    // Second install with different services
+    await writeMcpJson(tmpDir, [
+      { service: 'slack', profile: 'team' },
+      { service: 'rss' },
+    ]);
+
+    const content = JSON.parse(
+      await readFile(join(tmpDir, '.mcp.json'), 'utf-8')
+    );
+
+    // Should be updated, not duplicated
+    expect(content.mcpServers['agentio']).toEqual({
+      command: 'agentio',
+      args: ['mcp', 'serve', 'slack:team', 'rss'],
+    });
+  });
+
+  test('creates .mcp.json when it does not exist', async () => {
+    expect(existsSync(join(tmpDir, '.mcp.json'))).toBe(false);
+
+    await writeMcpJson(tmpDir, [{ service: 'rss' }]);
+
+    expect(existsSync(join(tmpDir, '.mcp.json'))).toBe(true);
+  });
+});

package/src/mcp/__tests__/server.test.ts

@@ -0,0 +1,39 @@
+import { describe, test, expect } from 'bun:test';
+import { parseServiceProfiles } from '../server';
+
+describe('parseServiceProfiles', () => {
+  test('parses service:profile pairs', () => {
+    const pairs = parseServiceProfiles(['gmail:work', 'slack:team']);
+    expect(pairs).toEqual([
+      { service: 'gmail', profile: 'work' },
+      { service: 'slack', profile: 'team' },
+    ]);
+  });
+
+  test('parses service without profile', () => {
+    const pairs = parseServiceProfiles(['rss']);
+    expect(pairs).toEqual([{ service: 'rss' }]);
+  });
+
+  test('handles mixed services with and without profiles', () => {
+    const pairs = parseServiceProfiles(['gmail:work', 'rss', 'jira:myteam']);
+    expect(pairs).toEqual([
+      { service: 'gmail', profile: 'work' },
+      { service: 'rss' },
+      { service: 'jira', profile: 'myteam' },
+    ]);
+  });
+
+  test('handles empty array', () => {
+    const pairs = parseServiceProfiles([]);
+    expect(pairs).toEqual([]);
+  });
+
+  test('handles profile with colons in name', () => {
+    // Edge case: profile name itself contains a colon
+    const pairs = parseServiceProfiles(['gmail:work:extra']);
+    expect(pairs).toEqual([
+      { service: 'gmail', profile: 'work:extra' },
+    ]);
+  });
+});

package/src/mcp/__tests__/tools.test.ts

@@ -0,0 +1,136 @@
+import { describe, test, expect } from 'bun:test';
+import { Command } from 'commander';
+import { collectMcpTools } from '../tools';
+import { registerRssCommands } from '../../commands/rss';
+import { registerGmailCommands } from '../../commands/gmail';
+import { registerSlackCommands } from '../../commands/slack';
+import { registerWhatsAppCommands } from '../../commands/whatsapp';
+
+function buildProgram(...registers: ((p: Command) => void)[]): Command {
+  const program = new Command();
+  program.name('agentio');
+  for (const reg of registers) {
+    reg(program);
+  }
+  return program;
+}
+
+describe('collectMcpTools', () => {
+  test('collects leaf commands for a simple service (rss)', () => {
+    const program = buildProgram(registerRssCommands);
+    const tools = collectMcpTools(program, 'rss');
+
+    const names = tools.map((t) => t.name);
+    expect(names).toContain('rss_articles');
+    expect(names).toContain('rss_get');
+    expect(names).toContain('rss_info');
+    expect(names).toHaveLength(3);
+  });
+
+  test('excludes profile subcommands', () => {
+    const program = buildProgram(registerGmailCommands);
+    const tools = collectMcpTools(program, 'gmail');
+
+    const names = tools.map((t) => t.name);
+    // Should not contain profile-related tools
+    expect(names.some((n) => n.includes('profile'))).toBe(false);
+  });
+
+  test('excludes --profile from options', () => {
+    const program = buildProgram(registerGmailCommands);
+    const tools = collectMcpTools(program, 'gmail');
+
+    for (const tool of tools) {
+      const optLongs = tool.options.map((o) => o.long);
+      expect(optLongs).not.toContain('profile');
+      expect(Object.keys(tool.inputSchema.properties)).not.toContain('profile');
+    }
+  });
+
+  test('returns empty array for unknown service', () => {
+    const program = buildProgram(registerRssCommands);
+    const tools = collectMcpTools(program, 'nonexistent');
+    expect(tools).toHaveLength(0);
+  });
+
+  test('marks required positional arguments as required in schema', () => {
+    const program = buildProgram(registerRssCommands);
+    const tools = collectMcpTools(program, 'rss');
+
+    const getTool = tools.find((t) => t.name === 'rss_get')!;
+    expect(getTool.inputSchema.required).toContain('url');
+    expect(getTool.inputSchema.required).toContain('article_id');
+  });
+
+  test('does not mark options as required in schema', () => {
+    const program = buildProgram(registerRssCommands);
+    const tools = collectMcpTools(program, 'rss');
+
+    const articlesTool = tools.find((t) => t.name === 'rss_articles')!;
+    // --limit and --since should NOT be in required
+    expect(articlesTool.inputSchema.required).not.toContain('limit');
+    expect(articlesTool.inputSchema.required).not.toContain('since');
+  });
+
+  test('identifies boolean options correctly', () => {
+    const program = buildProgram(registerGmailCommands);
+    const tools = collectMcpTools(program, 'gmail');
+
+    const sendTool = tools.find((t) => t.name === 'gmail_send')!;
+    const htmlProp = sendTool.inputSchema.properties['html'];
+    expect(htmlProp).toBeDefined();
+    expect(htmlProp.type).toBe('boolean');
+  });
+
+  test('handles nested commands (whatsapp inbox/outbox/group)', () => {
+    const program = buildProgram(registerWhatsAppCommands);
+    const tools = collectMcpTools(program, 'whatsapp');
+
+    const names = tools.map((t) => t.name);
+    expect(names).toContain('whatsapp_inbox_pull');
+    expect(names).toContain('whatsapp_inbox_get');
+    expect(names).toContain('whatsapp_inbox_ack');
+    expect(names).toContain('whatsapp_inbox_reply');
+    expect(names).toContain('whatsapp_outbox_send');
+    expect(names).toContain('whatsapp_group_list');
+  });
+
+  test('tool has correct commandPath', () => {
+    const program = buildProgram(registerWhatsAppCommands);
+    const tools = collectMcpTools(program, 'whatsapp');
+
+    const pullTool = tools.find((t) => t.name === 'whatsapp_inbox_pull')!;
+    expect(pullTool.commandPath).toEqual(['whatsapp', 'inbox', 'pull']);
+  });
+
+  test('tool inputSchema has valid JSON Schema structure', () => {
+    const program = buildProgram(registerRssCommands);
+    const tools = collectMcpTools(program, 'rss');
+
+    for (const tool of tools) {
+      expect(tool.inputSchema.type).toBe('object');
+      expect(tool.inputSchema.properties).toBeDefined();
+      expect(typeof tool.inputSchema.properties).toBe('object');
+
+      // All property values should have a type
+      for (const [, prop] of Object.entries(tool.inputSchema.properties)) {
+        expect(prop.type).toBeDefined();
+        expect(['string', 'boolean']).toContain(prop.type);
+      }
+    }
+  });
+
+  test('collects tools from multiple services independently', () => {
+    const program = buildProgram(registerRssCommands, registerSlackCommands);
+
+    const rssTools = collectMcpTools(program, 'rss');
+    const slackTools = collectMcpTools(program, 'slack');
+
+    expect(rssTools.length).toBeGreaterThan(0);
+    expect(slackTools.length).toBeGreaterThan(0);
+
+    // No cross-contamination
+    expect(rssTools.every((t) => t.name.startsWith('rss_'))).toBe(true);
+    expect(slackTools.every((t) => t.name.startsWith('slack_'))).toBe(true);
+  });
+});

package/src/mcp/server.ts

@@ -0,0 +1,259 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { Command } from 'commander';
+import { collectMcpTools, type McpToolDefinition } from './tools.js';
+
+// Import all service registrations
+import { registerDiscourseCommands } from '../commands/discourse';
+import { registerGCalCommands } from '../commands/gcal';
+import { registerGChatCommands } from '../commands/gchat';
+import { registerGDocsCommands } from '../commands/gdocs';
+import { registerGDriveCommands } from '../commands/gdrive';
+import { registerGitHubCommands } from '../commands/github';
+import { registerGmailCommands } from '../commands/gmail';
+import { registerGSheetsCommands } from '../commands/gsheets';
+import { registerGTasksCommands } from '../commands/gtasks';
+import { registerJiraCommands } from '../commands/jira';
+import { registerRssCommands } from '../commands/rss';
+import { registerSlackCommands } from '../commands/slack';
+import { registerSqlCommands } from '../commands/sql';
+import { registerTelegramCommands } from '../commands/telegram';
+import { registerWhatsAppCommands } from '../commands/whatsapp';
+
+const SERVICE_REGISTRATIONS: Record<string, (program: Command) => void> = {
+  discourse: registerDiscourseCommands,
+  gcal: registerGCalCommands,
+  gchat: registerGChatCommands,
+  gdocs: registerGDocsCommands,
+  gdrive: registerGDriveCommands,
+  github: registerGitHubCommands,
+  gmail: registerGmailCommands,
+  gsheets: registerGSheetsCommands,
+  gtasks: registerGTasksCommands,
+  jira: registerJiraCommands,
+  rss: registerRssCommands,
+  slack: registerSlackCommands,
+  sql: registerSqlCommands,
+  telegram: registerTelegramCommands,
+  whatsapp: registerWhatsAppCommands,
+};
+
+export interface ServiceProfilePair {
+  service: string;
+  profile?: string;
+}
+
+/**
+ * Parse "service:profile" pairs from argv.
+ */
+export function parseServiceProfiles(args: string[]): ServiceProfilePair[] {
+  return args.map((arg) => {
+    const colonIndex = arg.indexOf(':');
+    if (colonIndex === -1) {
+      return { service: arg };
+    }
+    return {
+      service: arg.substring(0, colonIndex),
+      profile: arg.substring(colonIndex + 1),
+    };
+  });
+}
+
+/**
+ * Build a commander program with only the requested services registered.
+ */
+function buildProgram(services: string[]): Command {
+  const program = new Command();
+  program.name('agentio').exitOverride();
+
+  for (const service of services) {
+    const register = SERVICE_REGISTRATIONS[service];
+    if (register) {
+      register(program);
+    }
+  }
+
+  return program;
+}
+
+/**
+ * Execute a command by capturing stdout output.
+ * Builds argv from the tool definition + input arguments, injects --profile.
+ */
+async function executeCommand(
+  program: Command,
+  tool: McpToolDefinition,
+  input: Record<string, unknown>,
+  profile?: string
+): Promise<string> {
+  const argv = ['node', 'agentio', ...tool.commandPath];
+
+  // Add positional arguments in order
+  for (const argDef of tool.args) {
+    const value = input[argDef.name];
+    if (value !== undefined && value !== null) {
+      if (argDef.variadic && Array.isArray(value)) {
+        for (const v of value) {
+          argv.push(String(v));
+        }
+      } else {
+        argv.push(String(value));
+      }
+    }
+  }
+
+  // Add options
+  for (const optDef of tool.options) {
+    const paramName = optDef.long.replace(/-([a-z])/g, (_, c: string) =>
+      c.toUpperCase()
+    );
+    const value = input[paramName];
+    if (value !== undefined && value !== null) {
+      if (typeof value === 'boolean') {
+        if (value) {
+          argv.push(`--${optDef.long}`);
+        }
+      } else if (Array.isArray(value)) {
+        for (const v of value) {
+          argv.push(`--${optDef.long}`, String(v));
+        }
+      } else {
+        argv.push(`--${optDef.long}`, String(value));
+      }
+    }
+  }
+
+  // Inject --profile if provided
+  if (profile) {
+    argv.push('--profile', profile);
+  }
+
+  // Capture stdout
+  const chunks: string[] = [];
+  const originalLog = console.log;
+  const originalWrite = process.stdout.write;
+
+  console.log = (...args: unknown[]) => {
+    chunks.push(args.map(String).join(' '));
+  };
+
+  process.stdout.write = ((
+    chunk: string | Uint8Array,
+    ...rest: unknown[]
+  ): boolean => {
+    if (typeof chunk === 'string') {
+      chunks.push(chunk);
+    } else {
+      chunks.push(Buffer.from(chunk).toString());
+    }
+    return true;
+  }) as typeof process.stdout.write;
+
+  try {
+    await program.parseAsync(argv);
+  } finally {
+    console.log = originalLog;
+    process.stdout.write = originalWrite;
+  }
+
+  return chunks.join('\n');
+}
+
+/**
+ * Start the MCP stdio server with the given service:profile pairs.
+ */
+export async function startMcpServer(
+  pairs: ServiceProfilePair[]
+): Promise<void> {
+  const services = [...new Set(pairs.map((p) => p.service))];
+
+  // Validate services
+  for (const service of services) {
+    if (!SERVICE_REGISTRATIONS[service]) {
+      console.error(`Unknown service: ${service}`);
+      process.exit(1);
+    }
+  }
+
+  // Build a profile lookup: service → profile
+  const profileMap = new Map<string, string | undefined>();
+  for (const pair of pairs) {
+    profileMap.set(pair.service, pair.profile);
+  }
+
+  // Build commander program and collect tools
+  const program = buildProgram(services);
+  const allTools: McpToolDefinition[] = [];
+  for (const service of services) {
+    allTools.push(...collectMcpTools(program, service));
+  }
+
+  if (allTools.length === 0) {
+    console.error('No tools found for the specified services');
+    process.exit(1);
+  }
+
+  // Create MCP server
+  const server = new Server(
+    { name: 'agentio', version: '1.0.0' },
+    { capabilities: { tools: {} } }
+  );
+
+  // Handle list tools
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: allTools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      })),
+    };
+  });
+
+  // Handle call tool
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const tool = allTools.find((t) => t.name === name);
+
+    if (!tool) {
+      return {
+        content: [{ type: 'text' as const, text: `Unknown tool: ${name}` }],
+        isError: true,
+      };
+    }
+
+    // Determine the service from the tool name to look up the profile
+    const service = tool.commandPath[0];
+    const profile = profileMap.get(service);
+
+    // Build a fresh program for each call to avoid state leaks
+    const execProgram = buildProgram(services);
+
+    try {
+      const output = await executeCommand(
+        execProgram,
+        tool,
+        (args as Record<string, unknown>) || {},
+        profile
+      );
+      return {
+        content: [{ type: 'text' as const, text: output || '(no output)' }],
+      };
+    } catch (error: unknown) {
+      const message =
+        error instanceof Error ? error.message : String(error);
+      return {
+        content: [{ type: 'text' as const, text: `Error: ${message}` }],
+        isError: true,
+      };
+    }
+  });
+
+  // Start stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/mcp/tools.ts

@@ -0,0 +1,153 @@
+import { Command } from 'commander';
+
+export interface McpToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, { type: string; description?: string }>;
+    required?: string[];
+  };
+  /** The full commander path segments, e.g. ['gmail', 'search'] */
+  commandPath: string[];
+  /** Arguments in order, with metadata */
+  args: Array<{ name: string; required: boolean; variadic: boolean }>;
+  /** Options (long flag name → flag string for commander) */
+  options: Array<{ long: string; flags: string; required: boolean }>;
+}
+
+/**
+ * Walk the commander tree for a given service and produce MCP tool definitions.
+ * Excludes profile subcommands and strips --profile from options.
+ */
+export function collectMcpTools(
+  program: Command,
+  service: string
+): McpToolDefinition[] {
+  const help = program.createHelp();
+  const serviceCmd = help
+    .visibleCommands(program)
+    .find((c) => c.name() === service);
+
+  if (!serviceCmd) {
+    return [];
+  }
+
+  const results: McpToolDefinition[] = [];
+  walkCommand(serviceCmd, [service], results);
+  return results;
+}
+
+function walkCommand(
+  cmd: Command,
+  path: string[],
+  results: McpToolDefinition[]
+): void {
+  const help = cmd.createHelp();
+  const subcommands = help
+    .visibleCommands(cmd)
+    .filter((c) => c.name() !== 'help');
+
+  // Skip profile subcommand tree entirely
+  const nonProfileSubs = subcommands.filter((c) => c.name() !== 'profile');
+
+  if (nonProfileSubs.length === 0) {
+    // Leaf command — create a tool definition
+    const tool = buildToolDefinition(cmd, path);
+    if (tool) {
+      results.push(tool);
+    }
+    return;
+  }
+
+  // If this command itself has arguments or meaningful options, also expose it
+  const args = help.visibleArguments(cmd);
+  const opts = help
+    .visibleOptions(cmd)
+    .filter(
+      (o) => !o.long?.includes('help') && o.long !== '--profile'
+    );
+  if (args.length > 0 || opts.length > 0) {
+    const tool = buildToolDefinition(cmd, path);
+    if (tool) {
+      results.push(tool);
+    }
+  }
+
+  // Recurse into non-profile subcommands
+  for (const sub of nonProfileSubs) {
+    walkCommand(sub, [...path, sub.name()], results);
+  }
+}
+
+function buildToolDefinition(
+  cmd: Command,
+  path: string[]
+): McpToolDefinition | null {
+  const help = cmd.createHelp();
+  const toolName = path.join('_');
+  const description = cmd.description() || toolName;
+
+  const properties: Record<string, { type: string; description?: string }> = {};
+  const required: string[] = [];
+
+  // Arguments
+  const argDefs: McpToolDefinition['args'] = [];
+  for (const arg of help.visibleArguments(cmd)) {
+    const paramName = arg.name().replace(/[^a-zA-Z0-9_]/g, '_');
+    properties[paramName] = {
+      type: 'string',
+      ...(arg.description ? { description: arg.description } : {}),
+    };
+    if (arg.required) {
+      required.push(paramName);
+    }
+    argDefs.push({
+      name: paramName,
+      required: arg.required,
+      variadic: arg.variadic,
+    });
+  }
+
+  // Options (skip --help, --profile)
+  const optDefs: McpToolDefinition['options'] = [];
+  for (const opt of help.visibleOptions(cmd)) {
+    if (opt.long?.includes('help')) continue;
+    if (opt.long === '--profile') continue;
+
+    const longName = opt.long?.replace(/^--/, '') || '';
+    if (!longName) continue;
+
+    // Convert kebab-case to camelCase for the property name
+    const paramName = longName.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+
+    // Determine type: boolean flags vs value options
+    const isBoolean = opt.flags && !opt.flags.includes('<') && !opt.flags.includes('[');
+
+    properties[paramName] = {
+      type: isBoolean ? 'boolean' : 'string',
+      ...(opt.description ? { description: opt.description } : {}),
+    };
+
+    // Note: Commander's opt.required means "value required when flag is used",
+    // not "flag must be provided". Options are always optional in the MCP schema.
+    optDefs.push({
+      long: longName,
+      flags: opt.flags,
+      required: false,
+    });
+  }
+
+  return {
+    name: toolName,
+    description,
+    inputSchema: {
+      type: 'object',
+      properties,
+      ...(required.length > 0 ? { required } : {}),
+    },
+    commandPath: path,
+    args: argDefs,
+    options: optDefs,
+  };
+}

package/src/services/gchat/client.ts

@@ -15,8 +15,14 @@ import type {
   GChatSpace,
 } from '../../types/gchat';
 
+interface ResolvedUser {
+  displayName: string;
+  email?: string;
+}
+
 export class GChatClient implements ServiceClient {
   private credentials: GChatCredentials;
+  private userCache = new Map<string, ResolvedUser>();
 
   constructor(credentials: GChatCredentials) {
     this.credentials = credentials;
@@ -223,6 +229,11 @@ export class GChatClient implements ServiceClient {
       });
 
       const messages = response.data.messages || [];
+
+      // Resolve unique sender IDs to display names via People API
+      const senderIds = [...new Set(messages.map(m => m.sender?.name).filter(Boolean))] as string[];
+      await this.resolveUsers(senderIds, auth);
+
       return messages.map((msg: chat_v1.Schema$Message) => {
         const gchatMsg: GChatMessage = {
           name: msg.name || '',
@@ -231,12 +242,7 @@ export class GChatClient implements ServiceClient {
           updateTime: (msg as Record<string, unknown>).lastUpdateTime as string || new Date().toISOString(),
         };
         if (msg.text) gchatMsg.text = msg.text;
-        if (msg.sender?.name) {
-          gchatMsg.sender = {
-            name: msg.sender.name,
-            displayName: msg.sender.displayName || msg.sender.name,
-          };
-        }
+        gchatMsg.sender = this.enrichSender(msg);
         if (msg.thread?.name) {
           gchatMsg.thread = {
             name: msg.thread.name,
@@ -270,6 +276,12 @@ export class GChatClient implements ServiceClient {
       }
 
       const msg = response.data as chat_v1.Schema$Message;
+
+      // Resolve sender
+      if (msg.sender?.name) {
+        await this.resolveUsers([msg.sender.name], auth);
+      }
+
       const gchatMsg: GChatMessage = {
         name: msg.name || '',
         createTime: msg.createTime || new Date().toISOString(),
@@ -277,12 +289,7 @@ export class GChatClient implements ServiceClient {
         updateTime: (msg as Record<string, unknown>).lastUpdateTime as string || new Date().toISOString(),
       };
       if (msg.text) gchatMsg.text = msg.text;
-      if (msg.sender?.name) {
-        gchatMsg.sender = {
-          name: msg.sender.name,
-          displayName: msg.sender.displayName || msg.sender.name,
-        };
-      }
+      gchatMsg.sender = this.enrichSender(msg);
       if (msg.thread?.name) {
         gchatMsg.thread = {
           name: msg.thread.name,
@@ -306,15 +313,29 @@ export class GChatClient implements ServiceClient {
     const chat = gchat({ version: 'v1', auth: auth as any });
 
     try {
-      const response = await chat.spaces.list({});
-
-      const spaces = response.data.spaces || [];
-      return spaces.map((space: chat_v1.Schema$Space) => ({
-        name: space.name || '',
-        displayName: space.displayName || 'Unnamed',
-        type: (space.type as 'ROOM' | 'DM') || 'ROOM',
-        description: space.spaceDetails?.description || undefined,
-      }));
+      const allSpaces: GChatSpace[] = [];
+      let pageToken: string | undefined;
+
+      do {
+        const response = await chat.spaces.list({
+          pageSize: 100,
+          pageToken,
+        });
+
+        const spaces = response.data.spaces || [];
+        for (const space of spaces) {
+          allSpaces.push({
+            name: space.name || '',
+            displayName: space.displayName || 'Unnamed',
+            type: (space.type as 'ROOM' | 'DM') || 'ROOM',
+            description: space.spaceDetails?.description || undefined,
+          });
+        }
+
+        pageToken = response.data.nextPageToken || undefined;
+      } while (pageToken);
+
+      return allSpaces;
     } catch (err) {
       const code = this.getErrorCode(err);
       const message = this.getErrorMessage(err);
@@ -326,6 +347,45 @@ export class GChatClient implements ServiceClient {
     }
   }
 
+  private async resolveUsers(userIds: string[], auth: OAuth2Client): Promise<void> {
+    const unknown = userIds.filter(id => !this.userCache.has(id));
+    if (unknown.length === 0) return;
+
+    const token = await auth.getAccessToken();
+    if (!token.token) return;
+
+    // Resolve users in parallel via People API
+    await Promise.all(unknown.map(async (userId) => {
+      try {
+        // userId is like "users/123456", extract the numeric part
+        const personId = userId.replace('users/', '');
+        const res = await fetch(
+          `https://people.googleapis.com/v1/people/${personId}?personFields=names,emailAddresses`,
+          { headers: { Authorization: `Bearer ${token.token}` } }
+        );
+        if (!res.ok) return;
+        const data = await res.json() as Record<string, any>;
+        const name = data.names?.[0]?.displayName;
+        const email = data.emailAddresses?.[0]?.value;
+        if (name) {
+          this.userCache.set(userId, { displayName: name, email });
+        }
+      } catch {
+        // Silently skip unresolvable users
+      }
+    }));
+  }
+
+  private enrichSender(msg: chat_v1.Schema$Message): GChatMessage['sender'] {
+    if (!msg.sender?.name) return undefined;
+    const cached = this.userCache.get(msg.sender.name);
+    return {
+      name: msg.sender.name,
+      displayName: cached?.displayName || msg.sender.displayName || msg.sender.name,
+      email: cached?.email,
+    };
+  }
+
   private getErrorCode(err: unknown): ErrorCode {
     if (err && typeof err === 'object') {
       const error = err as Record<string, unknown>;

package/src/types/gchat.ts

@@ -1,6 +1,7 @@
 export interface GChatSender {
   name: string;
   displayName: string;
+  email?: string;
   avatarUrl?: string;
 }
 

package/src/utils/output.ts

@@ -132,7 +132,10 @@ export function printGChatMessageList(messages: GChatMessage[]): void {
     const msg = messages[i];
     console.log(`[${i + 1}] ${msg.name}`);
     if (msg.sender) {
-      console.log(`    From: ${msg.sender.displayName || 'Unknown'}`);
+      const from = msg.sender.email
+        ? `${msg.sender.displayName} <${msg.sender.email}>`
+        : msg.sender.displayName || 'Unknown';
+      console.log(`    From: ${from}`);
     }
     if (msg.text) {
       const snippet = msg.text.length > 100 ? msg.text.substring(0, 100) + '...' : msg.text;
@@ -146,7 +149,10 @@ export function printGChatMessageList(messages: GChatMessage[]): void {
 export function printGChatMessage(msg: GChatMessage): void {
   console.log(`ID: ${msg.name}`);
   if (msg.sender) {
-    console.log(`From: ${msg.sender.displayName || 'Unknown'}`);
+    const from = msg.sender.email
+      ? `${msg.sender.displayName} <${msg.sender.email}>`
+      : msg.sender.displayName || 'Unknown';
+    console.log(`From: ${from}`);
   }
   console.log(`Date: ${msg.createTime}`);
   if (msg.thread) {