penpot/mcp/packages/server/src/tools/dev/ReadTaigaIssueTool.ts
Dr. Dominik Jain c0f0b14540
🎉 Add direct MCP feedback channel via dedicated tool (#12551)
* ♻️ Move devenv-only tools to a separate folder

* 🎉 Add an MCP feedback channel

Add a user-approved feedback tool and an MCP-token-authenticated backend
endpoint that queues plain-text email. Enable the tool through the
configured backend URI in both local and multi-user mode.

Validate subject and feedback limits, enforce per-profile rate limits,
and document configuration. Cover authentication, queueing, tool
availability, and failure handling with backend and MCP tests.

Closes #12490

AI-assisted-by: gpt-6

* ♻️ Move MCP feedback submission into RPC

Use the standard RPC wrappers for feedback and remove the dedicated
HTTP endpoint, route wiring, and custom rate limiter.

Restrict MCP tokens to opted-in routes and commands. Add a shared RPC
call helper to the MCP backend client and adapt the existing tests.

AI-assisted-by: gpt-6

* 🐛 Harden MCP feedback auth, validation and messages

Accept MCP tokens when either the mcp or the access-tokens flag is on, so
instances that enable MCP without personal access tokens can send
feedback. Personal tokens still need access-tokens. Keep the issuer in one
constant, decode tokens without raising to reject unknown issuers, and
name the issuer and type checks.

Reject control characters in the subject, and in the feedback all but
tabs and line breaks, in both the command and the tool, so a NUL answers
400 instead of failing when the mail job is stored. Answer 403 with
profile-blocked or profile-not-active for unusable profiles, record only
who sent feedback in the audit event, and add doc metadata.

Replace on OAuth approval an MCP token issued before MCP tokens had their
own issuer, or one this instance cannot decrypt, since the backend rejects
both.

In the MCP server, mention disabled access tokens on 401, drop the unused
503 case, and say that delivery happens in the background. Document the
flags in the README.

AI-assisted-by: claude-opus-5-5

* 📚 Document the MCP feedback tool and MCP token rules

List submit_feedback among the MCP tools and add an MCP feedback section to
the configuration guide covering PENPOT_MCP_BACKEND_URI,
PENPOT_MCP_FEEDBACK_EMAIL, the flags and the email settings. Add commented
examples of both variables to the compose file.

In the agent memories, record when OAuth approval replaces an MCP token,
how the MCP server reaches the backend, and which flags, routes and
commands accept MCP tokens.

AI-assisted-by: claude-opus-5-5
2026-10-29 10:35:46 +01:00

164 lines
5.2 KiB
TypeScript

import { z } from "zod";
import { Tool } from "../../Tool";
import "reflect-metadata";
import type { ToolResponse } from "../../ToolResponse";
import { TextResponse } from "../../ToolResponse";
import { PenpotMcpServer } from "../../PenpotMcpServer";
/**
* Arguments for the {@link ReadTaigaIssueTool}.
*/
export class ReadTaigaIssueArgs {
static schema = {
issueNumber: z
.number()
.int()
.positive()
.describe(
"The Penpot issue number as it appears in Taiga URLs, " +
"e.g. 14177 for https://tree.taiga.io/project/penpot/issue/14177"
),
};
/**
* The Penpot issue number as it appears in Taiga issue URLs
* (e.g. 14177 for https://tree.taiga.io/project/penpot/issue/14177).
*/
issueNumber!: number;
}
/**
* Represents a file attachment on a Taiga issue.
*/
interface TaigaAttachment {
filename: string;
size: number;
url: string;
}
/**
* Represents a comment on a Taiga issue.
*/
interface TaigaComment {
username: string;
comment: string;
}
/**
* The resolved issue data returned by the tool.
*/
interface TaigaIssueData {
subject: string;
description: string;
status: string;
attachments: TaigaAttachment[];
comments: TaigaComment[];
}
/**
* Tool for reading Penpot issues from the Taiga project tracker.
*
* Resolves a Penpot issue number to its internal Taiga ID and retrieves the issue's
* subject, description, status, attachments, and comments via the Taiga REST API.
*/
export class ReadTaigaIssueTool extends Tool<ReadTaigaIssueArgs> {
private static readonly TAIGA_API_BASE = "https://api.taiga.io/api/v1";
constructor(mcpServer: PenpotMcpServer) {
super(mcpServer, ReadTaigaIssueArgs.schema);
}
public getToolName(): string {
return "read_taiga_issue";
}
public getToolDescription(): string {
return "Reads a Penpot issue from the Taiga project tracker, returning its subject, description, status, attachments, and comments.";
}
protected async executeCore(args: ReadTaigaIssueArgs): Promise<ToolResponse> {
const { projectId, issueId } = await this.resolveIssue(args.issueNumber);
const issueData = await this.fetchIssueData(projectId, issueId);
return new TextResponse(JSON.stringify(issueData, null, 2));
}
/**
* Resolves a Penpot issue number to the internal Taiga project and issue IDs.
*/
private async resolveIssue(issueNumber: number): Promise<{ projectId: number; issueId: number }> {
const url = `${ReadTaigaIssueTool.TAIGA_API_BASE}/resolver?project=penpot&issue=${issueNumber}`;
const data = await this.fetchJson(url);
return { projectId: data.project, issueId: data.issue };
}
/**
* Fetches the full issue data including details, attachments, and comments.
*/
private async fetchIssueData(projectId: number, issueId: number): Promise<TaigaIssueData> {
// fetch issue details, attachments, and history in parallel
const [details, attachments, comments] = await Promise.all([
this.fetchIssueDetails(issueId),
this.fetchAttachments(projectId, issueId),
this.fetchComments(issueId),
]);
return {
subject: details.subject,
description: details.description ?? "",
status: details.status_extra_info?.name ?? "Unknown",
attachments,
comments,
};
}
/**
* Fetches the core issue details from the Taiga API.
*/
private async fetchIssueDetails(issueId: number): Promise<any> {
const url = `${ReadTaigaIssueTool.TAIGA_API_BASE}/issues/${issueId}`;
return this.fetchJson(url);
}
/**
* Fetches the attachments for an issue.
*/
private async fetchAttachments(projectId: number, issueId: number): Promise<TaigaAttachment[]> {
const url = `${ReadTaigaIssueTool.TAIGA_API_BASE}/issues/attachments?project=${projectId}&object_id=${issueId}`;
const data: any[] = await this.fetchJson(url);
return data.map((a) => ({
filename: a.name,
size: a.size,
url: a.url,
}));
}
/**
* Fetches comments from the issue history.
*
* History entries that have a non-empty `comment` field are treated as comments.
*/
private async fetchComments(issueId: number): Promise<TaigaComment[]> {
const url = `${ReadTaigaIssueTool.TAIGA_API_BASE}/history/issue/${issueId}`;
const history: any[] = await this.fetchJson(url);
return history
.filter((entry) => entry.comment && entry.comment.trim().length > 0)
.map((entry) => ({
username: entry.user?.username ?? "unknown",
comment: entry.comment,
}));
}
/**
* Performs a GET request and returns the parsed JSON response.
*
* @throws Error if the HTTP response status is not OK
*/
private async fetchJson(url: string): Promise<any> {
const response = await fetch(url);
if (!response.ok) {
throw new Error(`Taiga API request failed: ${response.status} ${response.statusText} (${url})`);
}
return response.json();
}
}