feat(mcp): MCP server for AI clients, consuming the REST API
New app apps/mcp (NestJS + @nestjs-mcp/server 2): Streamable HTTP at POST /mcp, stateless. - 24 tools: projects (mine, public, details with settings, board, stats, analytics, activity), tickets (my work, search, details with comments and history, create, update, move, assign, release, comment, link), releases (list, upcoming, details with progress and burnup, create, publish) and users (whoami, search). Admin operations stay in the web. - No credentials of its own: each call's Authorization header (a Pireon token) is forwarded to the API; without it only public projects are read. - Typed REST client generated from apps/api/openapi.json (openapi-fetch + openapi-typescript via `nx run mcp:openapi-types`); API refusals become readable tool errors; parameters validated with zod. - Tests: the real MCP against a simulated API (token forwarding, errors, validation, writes). - Docker target `mcp` (Node 24) and an optional compose service under the `mcp` profile; zod declared as a root dependency. - Docs: chapter 9 «Servidor MCP», references in 01/06/07 and the index; Word/PDF regenerated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
402
apps/mcp/src/app/tools/issues.resolver.ts
Normal file
402
apps/mcp/src/app/tools/issues.resolver.ts
Normal file
@@ -0,0 +1,402 @@
|
||||
import { McpContext, Resolver, Tool } from '@nestjs-mcp/server';
|
||||
import { z } from 'zod';
|
||||
import { TaskStreamApi } from '../api/taskstream-api';
|
||||
import { issueRef, limit, projectRef } from './params';
|
||||
import { issueLine } from './summaries';
|
||||
import { toolResult } from './tool-result';
|
||||
|
||||
const READ = { readOnlyHint: true, openWorldHint: false } as const;
|
||||
const WRITE = {
|
||||
readOnlyHint: false,
|
||||
destructiveHint: false,
|
||||
openWorldHint: false,
|
||||
} as const;
|
||||
|
||||
const PRIORITY = z.enum(['LOWEST', 'LOW', 'MEDIUM', 'HIGH', 'CRITICAL']);
|
||||
const CATEGORY = z.enum(['TODO', 'IN_PROGRESS', 'QA', 'DONE', 'CANCELLED']);
|
||||
const LINK_TYPE = z.enum([
|
||||
'BLOCKS',
|
||||
'DEPENDS_ON',
|
||||
'TESTS',
|
||||
'DUPLICATES',
|
||||
'RELATES_TO',
|
||||
]);
|
||||
|
||||
const ids = (what: string) =>
|
||||
z
|
||||
.array(z.string())
|
||||
.optional()
|
||||
.describe(`${what} ids of the project's settings (see get_project)`);
|
||||
|
||||
const issueFields = {
|
||||
description: z.string().max(50000).optional(),
|
||||
area: z.string().optional().describe('Area id (see get_project)'),
|
||||
priority: PRIORITY.optional(),
|
||||
labels: z.array(z.string().max(40)).max(20).optional(),
|
||||
figmaUrl: z.string().url().optional().describe('Figma frame (https)'),
|
||||
storyPoints: z.number().int().min(0).max(100).optional(),
|
||||
dueDate: z.string().optional().describe('ISO date, e.g. 2026-11-14'),
|
||||
};
|
||||
|
||||
type IssueFields = {
|
||||
description?: string;
|
||||
area?: string;
|
||||
priority?: z.infer<typeof PRIORITY>;
|
||||
labels?: string[];
|
||||
figmaUrl?: string;
|
||||
storyPoints?: number;
|
||||
dueDate?: string;
|
||||
};
|
||||
|
||||
@Resolver()
|
||||
export class IssuesResolver {
|
||||
constructor(private readonly api: TaskStreamApi) {}
|
||||
|
||||
/* ---- Reading ---- */
|
||||
|
||||
@Tool({
|
||||
name: 'my_issues',
|
||||
description:
|
||||
"Tickets across all the user's projects: assigned to them (default) or anyone's, filtered by status category (e.g. QA to see what waits for testing).",
|
||||
paramsSchema: z.object({
|
||||
assignedToMe: z.boolean().default(true),
|
||||
categories: z
|
||||
.array(CATEGORY)
|
||||
.optional()
|
||||
.describe('Default: open ones (TODO, IN_PROGRESS, QA)'),
|
||||
limit: limit(200, 50),
|
||||
}),
|
||||
annotations: READ,
|
||||
})
|
||||
mine(
|
||||
params: {
|
||||
assignedToMe: boolean;
|
||||
categories?: z.infer<typeof CATEGORY>[];
|
||||
limit: number;
|
||||
},
|
||||
ctx: McpContext,
|
||||
) {
|
||||
return toolResult(async () => {
|
||||
const page = await this.api.data(
|
||||
this.api.as(ctx).GET('/api/me/issues', {
|
||||
params: {
|
||||
query: {
|
||||
assignedToMe: params.assignedToMe,
|
||||
category: params.categories ?? ['TODO', 'IN_PROGRESS', 'QA'],
|
||||
limit: params.limit,
|
||||
},
|
||||
},
|
||||
}),
|
||||
);
|
||||
return { total: page.total, items: page.items.map(issueLine) };
|
||||
});
|
||||
}
|
||||
|
||||
@Tool({
|
||||
name: 'search_issues',
|
||||
description:
|
||||
'Search the tickets of a project by text (key, title, description) and filters.',
|
||||
paramsSchema: z.object({
|
||||
project: projectRef,
|
||||
search: z.string().max(200).optional(),
|
||||
statuses: ids('Status'),
|
||||
categories: z.array(CATEGORY).optional(),
|
||||
types: ids('Ticket type'),
|
||||
areas: ids('Area'),
|
||||
priorities: z.array(PRIORITY).optional(),
|
||||
assigneeId: z.string().optional().describe('User id'),
|
||||
unassigned: z.boolean().optional(),
|
||||
releaseId: z.string().optional(),
|
||||
labels: z.array(z.string()).optional(),
|
||||
limit: limit(200, 30),
|
||||
offset: z.number().int().min(0).default(0),
|
||||
}),
|
||||
annotations: READ,
|
||||
})
|
||||
search(
|
||||
params: {
|
||||
project: string;
|
||||
search?: string;
|
||||
statuses?: string[];
|
||||
categories?: z.infer<typeof CATEGORY>[];
|
||||
types?: string[];
|
||||
areas?: string[];
|
||||
priorities?: z.infer<typeof PRIORITY>[];
|
||||
assigneeId?: string;
|
||||
unassigned?: boolean;
|
||||
releaseId?: string;
|
||||
labels?: string[];
|
||||
limit: number;
|
||||
offset: number;
|
||||
},
|
||||
ctx: McpContext,
|
||||
) {
|
||||
return toolResult(async () => {
|
||||
const page = await this.api.data(
|
||||
this.api.as(ctx).GET('/api/projects/{project}/issues', {
|
||||
params: {
|
||||
path: { project: params.project },
|
||||
query: {
|
||||
search: params.search,
|
||||
status: params.statuses,
|
||||
category: params.categories,
|
||||
type: params.types,
|
||||
area: params.areas,
|
||||
priority: params.priorities,
|
||||
assigneeId: params.assigneeId,
|
||||
unassigned: params.unassigned,
|
||||
releaseId: params.releaseId,
|
||||
label: params.labels,
|
||||
limit: params.limit,
|
||||
offset: params.offset,
|
||||
},
|
||||
},
|
||||
}),
|
||||
);
|
||||
return { total: page.total, items: page.items.map(issueLine) };
|
||||
});
|
||||
}
|
||||
|
||||
@Tool({
|
||||
name: 'get_issue',
|
||||
description:
|
||||
'A ticket in full: description, links, allowed next statuses, and optionally its comments and history.',
|
||||
paramsSchema: z.object({
|
||||
issue: issueRef,
|
||||
withComments: z.boolean().default(true),
|
||||
withHistory: z.boolean().default(false),
|
||||
}),
|
||||
annotations: READ,
|
||||
})
|
||||
getIssue(
|
||||
params: { issue: string; withComments: boolean; withHistory: boolean },
|
||||
ctx: McpContext,
|
||||
) {
|
||||
return toolResult(async () => {
|
||||
const client = this.api.as(ctx);
|
||||
const path = { issue: params.issue };
|
||||
const issue = await this.api.data(
|
||||
client.GET('/api/issues/{issue}', { params: { path } }),
|
||||
);
|
||||
const comments = params.withComments
|
||||
? (
|
||||
await this.api.data(
|
||||
client.GET('/api/issues/{issue}/comments', {
|
||||
params: { path, query: { limit: 100 } },
|
||||
}),
|
||||
)
|
||||
).items.map((c) => ({
|
||||
id: c.id,
|
||||
author: c.author.name,
|
||||
at: c.createdAt,
|
||||
body: c.body,
|
||||
}))
|
||||
: undefined;
|
||||
const history = params.withHistory
|
||||
? (
|
||||
await this.api.data(
|
||||
client.GET('/api/issues/{issue}/history', {
|
||||
params: { path, query: { limit: 100 } },
|
||||
}),
|
||||
)
|
||||
).map((a) => ({ at: a.occurredAt, summary: a.summary }))
|
||||
: undefined;
|
||||
return {
|
||||
...issueLine(issue),
|
||||
description: issue.description,
|
||||
reporter: issue.reporter.name,
|
||||
figmaUrl: issue.figmaUrl,
|
||||
storyPoints: issue.storyPoints,
|
||||
dueDate: issue.dueDate,
|
||||
allowedTransitions: issue.allowedTransitions,
|
||||
links: issue.links,
|
||||
createdAt: issue.createdAt,
|
||||
comments,
|
||||
history,
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
/* ---- Writing ---- */
|
||||
|
||||
@Tool({
|
||||
name: 'create_issue',
|
||||
description:
|
||||
'Create a ticket. Type and area are ids of the project settings (see get_project); it starts in the first pending status.',
|
||||
paramsSchema: z.object({
|
||||
project: projectRef,
|
||||
type: z.string().describe('Ticket type id, e.g. BUG'),
|
||||
title: z.string().min(1).max(255),
|
||||
assigneeId: z.string().optional().describe('User id (a project member)'),
|
||||
releaseId: z.string().optional(),
|
||||
...issueFields,
|
||||
}),
|
||||
annotations: WRITE,
|
||||
})
|
||||
create(
|
||||
params: IssueFields & {
|
||||
project: string;
|
||||
type: string;
|
||||
title: string;
|
||||
assigneeId?: string;
|
||||
releaseId?: string;
|
||||
},
|
||||
ctx: McpContext,
|
||||
) {
|
||||
const { project, ...body } = params;
|
||||
return toolResult(() =>
|
||||
this.api.data(
|
||||
this.api.as(ctx).POST('/api/projects/{project}/issues', {
|
||||
params: { path: { project } },
|
||||
body,
|
||||
}),
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
@Tool({
|
||||
name: 'update_issue',
|
||||
description: 'Change the title, description, type, area, priority, labels…',
|
||||
paramsSchema: z.object({
|
||||
issue: issueRef,
|
||||
title: z.string().min(1).max(255).optional(),
|
||||
type: z.string().optional().describe('Ticket type id'),
|
||||
...issueFields,
|
||||
}),
|
||||
annotations: { ...WRITE, idempotentHint: true },
|
||||
})
|
||||
update(
|
||||
params: IssueFields & { issue: string; title?: string; type?: string },
|
||||
ctx: McpContext,
|
||||
) {
|
||||
const { issue, ...body } = params;
|
||||
return toolResult(() =>
|
||||
this.api.data(
|
||||
this.api.as(ctx).PATCH('/api/issues/{issue}', {
|
||||
params: { path: { issue } },
|
||||
body,
|
||||
}),
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
@Tool({
|
||||
name: 'change_issue_status',
|
||||
description:
|
||||
"Move a ticket to another status. It must be one of the ticket's allowedTransitions (see get_issue); some statuses need a reason.",
|
||||
paramsSchema: z.object({
|
||||
issue: issueRef,
|
||||
status: z.string().describe('Status id, e.g. IN_PROGRESS'),
|
||||
reason: z.string().max(5000).optional(),
|
||||
}),
|
||||
annotations: WRITE,
|
||||
})
|
||||
changeStatus(
|
||||
{
|
||||
issue,
|
||||
status,
|
||||
reason,
|
||||
}: { issue: string; status: string; reason?: string },
|
||||
ctx: McpContext,
|
||||
) {
|
||||
return toolResult(() =>
|
||||
this.api.data(
|
||||
this.api.as(ctx).PUT('/api/issues/{issue}/status', {
|
||||
params: { path: { issue } },
|
||||
body: { status, reason },
|
||||
}),
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
@Tool({
|
||||
name: 'assign_issue',
|
||||
description: 'Assign a ticket to a project member, or unassign it (null).',
|
||||
paramsSchema: z.object({
|
||||
issue: issueRef,
|
||||
assigneeId: z.string().nullable().describe('User id, or null'),
|
||||
}),
|
||||
annotations: { ...WRITE, idempotentHint: true },
|
||||
})
|
||||
assign(
|
||||
{ issue, assigneeId }: { issue: string; assigneeId: string | null },
|
||||
ctx: McpContext,
|
||||
) {
|
||||
return toolResult(() =>
|
||||
this.api.data(
|
||||
this.api.as(ctx).PUT('/api/issues/{issue}/assignee', {
|
||||
params: { path: { issue } },
|
||||
body: { assigneeId },
|
||||
}),
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
@Tool({
|
||||
name: 'set_issue_release',
|
||||
description: 'Put a ticket in a planned release, or take it out (null).',
|
||||
paramsSchema: z.object({
|
||||
issue: issueRef,
|
||||
releaseId: z.string().nullable(),
|
||||
}),
|
||||
annotations: { ...WRITE, idempotentHint: true },
|
||||
})
|
||||
setRelease(
|
||||
{ issue, releaseId }: { issue: string; releaseId: string | null },
|
||||
ctx: McpContext,
|
||||
) {
|
||||
return toolResult(() =>
|
||||
this.api.data(
|
||||
this.api.as(ctx).PUT('/api/issues/{issue}/release', {
|
||||
params: { path: { issue } },
|
||||
body: { releaseId },
|
||||
}),
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
@Tool({
|
||||
name: 'add_comment',
|
||||
description: 'Comment on a ticket (decisions, explanations, steps).',
|
||||
paramsSchema: z.object({
|
||||
issue: issueRef,
|
||||
body: z.string().min(1).max(20000),
|
||||
}),
|
||||
annotations: WRITE,
|
||||
})
|
||||
comment({ issue, body }: { issue: string; body: string }, ctx: McpContext) {
|
||||
return toolResult(() =>
|
||||
this.api.data(
|
||||
this.api.as(ctx).POST('/api/issues/{issue}/comments', {
|
||||
params: { path: { issue } },
|
||||
body: { body },
|
||||
}),
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
@Tool({
|
||||
name: 'link_issues',
|
||||
description:
|
||||
'Relate two tickets, e.g. WEB-3 DEPENDS_ON API-7 (they may be in different projects).',
|
||||
paramsSchema: z.object({
|
||||
issue: issueRef,
|
||||
type: LINK_TYPE,
|
||||
target: issueRef,
|
||||
}),
|
||||
annotations: WRITE,
|
||||
})
|
||||
link(
|
||||
params: { issue: string; type: z.infer<typeof LINK_TYPE>; target: string },
|
||||
ctx: McpContext,
|
||||
) {
|
||||
return toolResult(() =>
|
||||
this.api.data(
|
||||
this.api.as(ctx).POST('/api/issues/{issue}/links', {
|
||||
params: { path: { issue: params.issue } },
|
||||
body: { type: params.type, targetIssue: params.target },
|
||||
}),
|
||||
),
|
||||
);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user