Skip to content

⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.

8.2 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
import { CallToolResultSchema, type CallToolRequest } from '@modelcontextprotocol/sdk/types.js';
import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv';
import type { JsonSchemaType } from '@modelcontextprotocol/sdk/validation/types.js';
import { auth } from '@repo/auth';
import { app, authedApi, ownWorkspaceId, createProject } from '#tests/helpers/app';
import { signUpTestUser } from '#tests/helpers/auth';
import { resetDb } from '#tests/helpers/db';
import { buildMcpServer } from '../../server';

const clients: Client[] = [];

async function callTool(client: Client, params: CallToolRequest['params']) {
  return CallToolResultSchema.parse(await client.callTool(params));
}

async function connect(userId: string) {
  const { key } = await auth.api.createApiKey({ body: { userId, name: 'structured-results' } });
  const server = await buildMcpServer(app, { kind: 'api-key', apiKey: key }, userId);
  const client = new Client({ name: 'structured-results-test', version: '1.0.0' });
  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
  await server.connect(serverTransport);
  await client.connect(clientTransport);
  clients.push(client);
  return client;
}

describe('MCP structured results through the SDK client', () => {
  beforeEach(resetDb);
  afterEach(async () => {
    await Promise.all(clients.splice(0).map((client) => client.close()));
  });

  it('compiles every advertised output schema and validates object, array, and empty results', async () => {
    const user = await signUpTestUser();
    const client = await connect(user.userId);
    const listed = await client.listTools();
    expect(listed.tools.length).toBeGreaterThan(0);
    const withoutSchema = listed.tools.filter((tool) => tool.outputSchema === undefined);
    expect(withoutSchema.map((tool) => tool.name).sort()).toEqual([
      'view_attachment',
      'view_document_asset',
      'view_initiative_images',
      'view_issue_images',
    ]);
    expect(
      listed.tools.every((tool) => !tool.outputSchema || tool.outputSchema.type === 'object'),
    ).toBe(true);

    const created = await callTool(client, {
      name: 'create_project',
      arguments: { key: 'RESULT', name: 'Structured results' },
    });
    expect(created.isError).toBe(false);
    expect(created.structuredContent).toMatchObject({
      ok: true,
      status: 201,
      data: { key: 'RESULT', name: 'Structured results' },
    });
    const text = created.content[0];
    expect(text.type).toBe('text');
    if (text.type === 'text')
      expect(JSON.parse(text.text)).toEqual(created.structuredContent?.data);

    const projects = await callTool(client, { name: 'list_projects' });
    expect(projects.structuredContent).toMatchObject({
      ok: true,
      status: 200,
      data: [{ key: 'RESULT' }],
    });

    const deleted = await callTool(client, {
      name: 'delete_project',
      arguments: { projectKey: 'RESULT' },
    });
    expect(deleted.isError).toBe(false);
    expect(deleted.content).toEqual([{ type: 'text', text: '' }]);
    expect(deleted.structuredContent).toEqual({ ok: true, status: 204, data: null });
  });

  // A client that checks arguments with Ajv refuses a tool whose schema it cannot compile,
  // even for a call with no arguments (#805).
  it('compiles every advertised input schema in the SDK validator', async () => {
    const user = await signUpTestUser();
    const client = await connect(user.userId);
    const validator = new AjvJsonSchemaValidator();
    const refused: string[] = [];
    for (const tool of (await client.listTools()).tools) {
      try {
        validator.getValidator(tool.inputSchema as JsonSchemaType);
      } catch {
        refused.push(tool.name);
      }
    }
    expect(refused).toEqual([]);
  });

  it('creates a checklist batch through the SDK and returns a validated array result', async () => {
    const owner = await signUpTestUser();
    const api = authedApi(owner.cookie);
    await createProject(api, { key: 'MKT', name: 'Marketing' });
    const view = await api.projects({ projectKey: 'MKT' }).get();
    const issue = await api.projects({ projectKey: 'MKT' }).issues.post({
      columnId: view.data!.columns[0].id,
      title: 'Release',
    });
    const checklist = await api
      .issues({ issueId: issue.data!.id })
      .checklists.post({ title: 'Steps' });
    const client = await connect(owner.userId);
    const listed = await client.listTools();
    const tool = listed.tools.find((entry) => entry.name === 'create_checklist_items');
    expect(tool?.inputSchema.properties?.items).toMatchObject({
      type: 'array',
      minItems: 1,
      maxItems: 100,
    });
    const items = [{ content: 'Tag release' }, { content: 'Publish notes' }];
    const result = await callTool(client, {
      name: 'create_checklist_items',
      arguments: { checklistId: checklist.data!.id, items },
    });
    expect(result.isError).toBe(false);
    expect(result.structuredContent).toMatchObject({ ok: true, status: 201, data: items });
    const invalid = await callTool(client, {
      name: 'create_checklist_items',
      arguments: { checklistId: checklist.data!.id, items: [] },
    });
    expect(invalid.isError).toBe(true);
    expect(invalid.structuredContent).toMatchObject({ ok: false, status: 400 });
    const read = await api.issues({ issueId: issue.data!.id }).get();
    expect(read.data!.checklists[0].items).toMatchObject(items);
    expect(read.data!.checklists[0].items).toHaveLength(2);
  });

  it('validates structured validation, conflict, and permission errors without changing their text', async () => {
    const owner = await signUpTestUser();
    const api = authedApi(owner.cookie);
    await createProject(api, { key: 'PRIVATE', name: 'Private project' });
    const client = await connect(owner.userId);
    await client.listTools();
    for (const [args, status] of [
      [{ key: 'MISSING' }, 400],
      [{ key: 'PRIVATE', name: 'Duplicate' }, 409],
    ] as const) {
      const result = await callTool(client, { name: 'create_project', arguments: args });
      expect(result.isError).toBe(true);
      expect(result.structuredContent).toMatchObject({
        ok: false,
        status,
        error: { code: `HTTP_${status}`, retryable: false, retryAfterSeconds: null },
      });
      const content = result.content[0];
      if (content.type === 'text') {
        expect(JSON.parse(content.text).error).toBe(
          (result.structuredContent?.error as { message: string }).message,
        );
      }
    }

    const outsider = await signUpTestUser();
    const otherClient = await connect(outsider.userId);
    await otherClient.listTools();
    const forbidden = await callTool(otherClient, {
      name: 'get_project',
      arguments: { projectKey: 'PRIVATE' },
    });
    expect(forbidden.isError).toBe(true);
    expect(forbidden.structuredContent).toMatchObject({
      ok: false,
      status: 403,
      error: { code: 'HTTP_403', retryable: false },
    });
  });

  it('returns the same error envelope for missing team arguments and unknown tools', async () => {
    const user = await signUpTestUser();
    await authedApi(user.cookie).teams.post({
      name: 'Another team',
      slug: 'another-team',
      workspaceId: await ownWorkspaceId(authedApi(user.cookie)),
    });
    const client = await connect(user.userId);
    await client.listTools();
    const missing = await callTool(client, { name: 'list_ai_agents' });
    expect(missing.isError).toBe(true);
    expect(missing.structuredContent).toMatchObject({
      ok: false,
      status: 400,
      error: { code: 'HTTP_400', retryable: false },
    });
    expect(missing.content[0]).toMatchObject({
      type: 'text',
      text: expect.stringContaining('teamId'),
    });

    const unknown = await callTool(client, { name: 'unknown_tool' });
    expect(unknown.isError).toBe(true);
    expect(unknown.content).toEqual([{ type: 'text', text: 'Unknown tool: unknown_tool' }]);
    expect(unknown.structuredContent).toMatchObject({
      ok: false,
      status: 404,
      error: { code: 'HTTP_404', retryable: false },
    });
  });
});