MailUI4Agents/plugins/zcode-mail-bridge/test/generic-mcp.test.mjs

/**
 * 通用化（去 ZCode 影子）的看守判据。
 *
 * ★ 2026-10-02 新增。这三条改动的判别力此前**无人看守**：
 * 变异验证时「把 action-tools 挂回 server.mjs」与「platform 硬编码回 zcode」
 * 都能通过全套测试 —— 因为没有一条判据看 server.mjs 实际挂了什么、
 * 也没有一条看注册时上报的 platform。改动本身是对的，但没有判据就等于
 * 下次谁都能悄悄改回去。
 *
 * 这里验的都是**结构**（源码 + 模块行为），不联网。
 */

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { readFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';
import { GatewayClient } from '../lib/gateway.mjs';
import { buildTools, indexTools } from '../lib/tools.mjs';

const HERE = dirname(fileURLToPath(import.meta.url));
const ROOT = join(HERE, '..');

/**
 * server.mjs 真实挂载的工具清单。
 *
 * 走真实模块（main 会挂 stdio，但工具集合只依赖 client/agentName），
 * 复刻它那段装配逻辑 —— 直接 import 会启动服务器。
 */
function mountedToolNames() {
  const client = new GatewayClient({
    AGENTMAIL_AGENT_NAME: 'probe',
    AGENTMAIL_AGENT_KEY: 'k'
  });
  return [...indexTools(buildTools({ client, agentName: client.agentName })).keys()];
}

test('★ MCP 面**不含**会动机器的工具（run_command / write_file 已移除）', () => {
  const names = mountedToolNames();
  // 这两个是「会动机器」的。它们的门禁为 ZCode headless 双进程审批设计，
  // 脱离该宿主后语义不成立 —— 挂在通用 MCP 服务上等于给人一个没门禁的旁路。
  assert.ok(!names.includes('run_command'), 'run_command 不得回到通用 MCP 面');
  assert.ok(!names.includes('write_file'), 'write_file 不得回到通用 MCP 面');
  // 工具清单就这些 —— 挂进来的每个工具都是产品决策，不是实现细节
  assert.deepEqual(names.sort(), [
    'connect_to_server',
    'download_attachment',
    'forward_mail',
    'list_contacts',
    'read_inbox',
    'read_mail',
    'read_thread',
    'send_mail',
    'session_participants',
    'suggest_address',
    'upload_attachment'
  ]);
});

test('★ server.mjs 源码不 import action-tools / grants-file（结构层钉死，不只验运行结果）', async () => {
  const src = await readFile(join(ROOT, 'mcp', 'server.mjs'), 'utf8');
  assert.doesNotMatch(src, /action-tools/, 'server.mjs 不该再 import 执行类工具');
  assert.doesNotMatch(src, /grants-file/, '授权表是 ZCode 钩子的东西，不属通用 MCP 面');
  // 反向对照：它必须真的挂上了邮件工具，否则「没挂 action-tools」可能只是空文件
  assert.match(src, /buildTools/, 'server.mjs 必须装配邮件工具');
});

test('★ platform 可配置且默认 mcp（通用服务不冒充任何宿主）', () => {
  // 默认
  const dflt = new GatewayClient({ AGENTMAIL_AGENT_NAME: 'a', AGENTMAIL_AGENT_KEY: 'k' });
  assert.equal(dflt.platform, 'mcp');

  // 可配置：宿主可自报平台名（如 codex / claude-code），便于服务端统计
  const custom = new GatewayClient({
    AGENTMAIL_AGENT_NAME: 'a',
    AGENTMAIL_AGENT_KEY: 'k',
    AGENTMAIL_MCP_PLATFORM: 'my-host'
  });
  assert.equal(custom.platform, 'my-host');

  // 空白值不得变成空字符串（会让服务端统计出一个空平台）
  const blank = new GatewayClient({
    AGENTMAIL_AGENT_NAME: 'a',
    AGENTMAIL_AGENT_KEY: 'k',
    AGENTMAIL_MCP_PLATFORM: '   '
  });
  assert.equal(blank.platform, 'mcp', '空白 platform 必须回落默认值，不能是空串');
});

test('★ 注册载荷带可配置 platform，且源码里不残留 zcode 字面量', async () => {
  const gw = await readFile(join(ROOT, 'lib', 'gateway.mjs'), 'utf8');
  // 注册时上报的是 client.platform，不是硬编码
  assert.match(gw, /platform: this\.platform/, 'register 必须用可配置的 platform');
  assert.doesNotMatch(gw, /platform: 'zcode'/, 'register 不得硬编码 zcode');

  // 面向用户的文案不得把宿主名写死 —— 通用服务提着 ZCode 说「请在 ZCode 的
  // 插件设置里填写」，会让人去一个不存在的界面找配置。
  const tools = await readFile(join(ROOT, 'lib', 'tools.mjs'), 'utf8');
  assert.doesNotMatch(tools, /请在 ZCode 的插件设置里/, '错误文案不得指向 ZCode 插件设置');
});

test('★ connect_to_server 对 secret-only 的 Agent 也能注册（实测 400 过）', async () => {
  // 根因：`/agent/register` 只认 `Authorization: Bearer` 或 **body 里的 secret**，
  // 不认 `X-Agent-Secret` 头。而 connect_to_server 早前只发了那个头 ⇒
  // dsh / pi 这类 secret-only 的 Agent 调它必得 400，且模型看不出该改什么。
  //
  // 这条是**行为**判据：真起一个 fetch 替身，按 secret-only 装配调用该工具，
  // 检查请求体里确实带了 secret。
  const src = await readFile(join(ROOT, 'lib', 'tools.mjs'), 'utf8');
  assert.match(
    src,
    /secret:\s*client\.agentSecret/,
    'connect_to_server 在没有 Bearer 时必须把 secret 放进请求体'
  );

  // 端到端：真调一次工具，拦截 fetch 看它发出去什么。
  let captured = null;
  const fakeFetch = async (url, init) => {
    captured = { url, init };
    return {
      ok: true,
      status: 200,
      text: async () => JSON.stringify({ status: 'registered' })
    };
  };
  const realFetch = globalThis.fetch;
  globalThis.fetch = fakeFetch;
  try {
    const tools = buildTools({
      client: {
        baseURL: 'http://fake',
        agentName: 'dsh',
        agentKey: '',
        agentSecret: 'sekrit',
        platform: 'mcp',
        checkConfig: () => [],
        get: async () => ({}),
        post: async () => ({}),
        uploadFile: async () => ({}),
        downloadFile: async () => Buffer.alloc(0)
      },
      agentName: 'dsh'
    });
    const byName = indexTools(tools);
    await byName.get('connect_to_server').run({});
    assert.ok(captured, 'connect_to_server 应当真的发出请求');
    const body = JSON.parse(captured.init.body);
    assert.equal(body.secret, 'sekrit', 'secret-only 装配时 body 必须带 secret');
    assert.equal(body.platform, 'mcp', 'platform 仍应是可配置值');
    // 反向对照：没有 secret 时不能硬塞空串（那是另一种错）
    const tools2 = buildTools({
      client: {
        baseURL: 'http://fake', agentName: 'a', agentKey: 'key', agentSecret: '',
        platform: 'mcp', checkConfig: () => [], get: async () => ({}), post: async () => ({}),
        uploadFile: async () => ({}), downloadFile: async () => Buffer.alloc(0)
      },
      agentName: 'a'
    });
    captured = null;
    await indexTools(tools2).get('connect_to_server').run({});
    assert.equal(
      JSON.parse(captured.init.body).secret,
      undefined,
      '有 Bearer 时 body 不该塞 secret'
    );
  } finally {
    globalThis.fetch = realFetch;
  }
});