⭐️⭐️⭐️ 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.
TypeScript agenticagileai-agentsbug-reportingbug-trackerganttissue-trackerjirajira-alternativekanbanlinearlinear-alternativeopen-sourceproduct-managementproject-managementroadmapself-hostedsprint-planningteam-collaborationtrello-alternative
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 },
});
});
});