⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";
import { encodeCustomFieldValue } from "../kaneo/custom-field-value.js";
import { buildFullTaskUpdateBody } from "../kaneo/task-helpers.js";
import { errorResult, textResult } from "../utils/mcp-result.js";
import { getCurrentUser } from "./get-current-user.js";
export type ToolClient = {
readonly usingApiKey?: boolean;
json<T = unknown>(path: string, init?: RequestInit): Promise<T>;
};
export type ToolRegistrar = {
registerTool(
name: string,
config: { description: string; inputSchema: z.ZodObject },
callback: (args: unknown) => Promise<CallToolResult>,
): unknown;
};
const prioritySchema = z.enum([
"no-priority",
"low",
"medium",
"high",
"urgent",
]);
const nonEmptyString = z.string().trim().min(1);
const optionalNonEmptyString = nonEmptyString.optional();
const nullableOptionalNonEmptyString = nonEmptyString.nullable().optional();
const isoDateTimeSchema = z.string().datetime({ offset: true });
const optionalIsoDateTimeSchema = isoDateTimeSchema.optional();
const nullableOptionalIsoDateTimeSchema = isoDateTimeSchema
.nullable()
.optional();
const hexColorSchema = z
.string()
.regex(
/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/,
"Expected a hex color like #FF6600",
);
function run(fn: () => Promise<unknown>): Promise<CallToolResult> {
return fn()
.then((data) => textResult(data))
.catch((e: unknown) =>
errorResult(e instanceof Error ? e.message : String(e)),
);
}
export function registerTools(
server: ToolRegistrar,
ctx: { client: ToolClient },
): void {
const { client } = ctx;
const registerTool = <S extends z.ZodObject>(
name: string,
config: { description: string; inputSchema: S },
callback: (args: z.output<S>) => Promise<CallToolResult>,
) =>
server.registerTool(name, config, async (args) => {
const parsed = config.inputSchema.safeParse(args);
if (!parsed.success) return errorResult(z.prettifyError(parsed.error));
return callback(parsed.data);
});
registerTool(
"whoami",
{
description:
"Return the current Kaneo user for the configured authentication method.",
inputSchema: z.object({}),
},
async () => run(() => getCurrentUser(client)),
);
registerTool(
"list_workspaces",
{
description:
"List workspaces (Better Auth organizations) the signed-in user can access.",
inputSchema: z.object({}),
},
async () =>
run(() => client.json("/api/auth/organization/list", { method: "GET" })),
);
registerTool(
"list_projects",
{
description: "List projects in a workspace.",
inputSchema: z.object({
workspaceId: nonEmptyString.describe("Workspace ID"),
includeArchived: z
.boolean()
.optional()
.describe("Include archived projects"),
}),
},
async (args) => {
const { workspaceId, includeArchived } = args;
const qs = new URLSearchParams({ workspaceId });
if (includeArchived === true) {
qs.set("includeArchived", "true");
}
return run(() =>
client.json(`/api/project?${qs.toString()}`, { method: "GET" }),
);
},
);
registerTool(
"get_project",
{
description: "Get a single project by ID.",
inputSchema: z.object({ id: nonEmptyString }),
},
async (args) =>
run(() => client.json(`/api/project/${encodeURIComponent(args.id)}`)),
);
registerTool(
"create_project",
{
description: "Create a project in a workspace.",
inputSchema: z.object({
name: nonEmptyString,
workspaceId: nonEmptyString,
icon: nonEmptyString,
slug: nonEmptyString,
}),
},
async (args) =>
run(() =>
client.json("/api/project", {
method: "POST",
body: JSON.stringify({
name: args.name,
workspaceId: args.workspaceId,
icon: args.icon,
slug: args.slug,
}),
}),
),
);
registerTool(
"update_project",
{
description:
"Update project metadata (PATCH-style: only provided fields are changed).",
inputSchema: z.object({
id: nonEmptyString,
name: optionalNonEmptyString,
icon: z.string().optional(),
slug: optionalNonEmptyString,
description: z.string().optional(),
isPublic: z.boolean().optional(),
}),
},
async (args) => {
const { id, ...patch } = args;
return run(async () => {
const existing = (await client.json(
`/api/project/${encodeURIComponent(id)}`,
{ method: "GET" },
)) as Record<string, unknown>;
const name =
patch.name ??
(typeof existing.name === "string" ? existing.name : "");
if (!name) {
throw new Error("Cannot update project: missing name.");
}
const icon =
patch.icon !== undefined
? patch.icon
: typeof existing.icon === "string"
? existing.icon
: "Layout";
const slug =
patch.slug ??
(typeof existing.slug === "string" ? existing.slug : "");
if (!slug) {
throw new Error("Cannot update project: missing slug.");
}
const description =
patch.description !== undefined
? patch.description
: typeof existing.description === "string"
? existing.description
: "";
const isPublic =
patch.isPublic !== undefined
? patch.isPublic
: typeof existing.isPublic === "boolean"
? existing.isPublic
: false;
const body = { name, icon, slug, description, isPublic };
return client.json(`/api/project/${encodeURIComponent(id)}`, {
method: "PUT",
body: JSON.stringify(body),
});
});
},
);
const listTasksSchema = z.object({
projectId: nonEmptyString,
status: optionalNonEmptyString,
priority: prioritySchema.optional(),
assigneeId: optionalNonEmptyString,
page: z.number().int().min(1).max(1_000_000).optional(),
relatedPage: z.number().int().min(1).max(1_000_000).optional(),
limit: z.number().int().min(1).max(100).optional(),
sortBy: z
.enum(["createdAt", "priority", "dueDate", "position", "title", "number"])
.optional(),
sortOrder: z.enum(["asc", "desc"]).optional(),
dueBefore: optionalIsoDateTimeSchema,
dueAfter: optionalIsoDateTimeSchema,
});
registerTool(
"list_tasks",
{
description:
"List a bounded page of tasks for a project (50 by default, maximum 100). Use pagination.totalPages and page to retrieve the rest; filters and sorting apply before pagination. For every task page, also follow relatedPage through pagination.relatedTotalPages for complete labels, links and column metadata. Custom field values are not included; use get_task_custom_field_values.",
inputSchema: listTasksSchema,
},
async (args) => {
const { projectId, ...rest } = args;
const qs = new URLSearchParams();
for (const [k, v] of Object.entries(rest)) {
if (v === undefined || v === null) {
continue;
}
qs.set(k, String(v));
}
const q = qs.toString();
const path = `/api/task/tasks/${encodeURIComponent(projectId)}${q ? `?${q}` : ""}`;
return run(() => client.json(path, { method: "GET" }));
},
);
registerTool(
"get_task",
{
description:
"Get a task by ID. Custom field values are not included; use get_task_custom_field_values.",
inputSchema: z.object({ taskId: nonEmptyString }),
},
async (args) =>
run(() =>
client.json(`/api/task/${encodeURIComponent(args.taskId)}`, {
method: "GET",
}),
),
);
registerTool(
"get_task_by_ticket_id",
{
description:
"Get one task by its ticket ID (project key and number, e.g. KAN-12). If multiple accessible tasks share the ID, provide workspaceId or projectId.",
inputSchema: z.object({
ticketId: nonEmptyString,
workspaceId: optionalNonEmptyString,
projectId: optionalNonEmptyString,
}),
},
async ({ ticketId, workspaceId, projectId }) => {
const query = new URLSearchParams();
if (workspaceId) query.set("workspaceId", workspaceId);
if (projectId) query.set("projectId", projectId);
const suffix = query.toString();
return run(() =>
client.json(
`/api/task/by-ticket-id/${encodeURIComponent(ticketId)}${suffix ? `?${suffix}` : ""}`,
{ method: "GET" },
),
);
},
);
registerTool(
"create_task",
{
description: "Create a task in a project.",
inputSchema: z.object({
projectId: nonEmptyString,
title: nonEmptyString,
description: z.string(),
priority: prioritySchema,
status: nonEmptyString,
startDate: optionalIsoDateTimeSchema,
dueDate: optionalIsoDateTimeSchema,
userId: optionalNonEmptyString,
}),
},
async (args) => {
const body: Record<string, string | undefined> = {
title: args.title,
description: args.description,
priority: args.priority,
status: args.status,
};
if (args.startDate !== undefined) {
body.startDate = args.startDate;
}
if (args.dueDate !== undefined) {
body.dueDate = args.dueDate;
}
if (args.userId !== undefined) {
body.userId = args.userId;
}
return run(() =>
client.json(`/api/task/${encodeURIComponent(args.projectId)}`, {
method: "POST",
body: JSON.stringify(body),
}),
);
},
);
registerTool(
"duplicate_task",
{
description:
"Duplicate a task in the same project, copying its fields and labels. Pass title to rename the copy.",
inputSchema: z.object({
taskId: nonEmptyString,
title: optionalNonEmptyString,
}),
},
async (args) => {
const body: Record<string, string> = {};
if (args.title !== undefined) {
body.title = args.title;
}
return run(() =>
client.json(`/api/task/duplicate/${encodeURIComponent(args.taskId)}`, {
method: "POST",
body: JSON.stringify(body),
}),
);
},
);
const updateTaskSchema = z.object({
taskId: nonEmptyString,
title: optionalNonEmptyString,
description: z.string().nullable().optional(),
status: optionalNonEmptyString,
priority: prioritySchema.optional(),
projectId: optionalNonEmptyString,
position: z.number().optional(),
startDate: nullableOptionalIsoDateTimeSchema,
dueDate: nullableOptionalIsoDateTimeSchema,
userId: nullableOptionalNonEmptyString,
});
registerTool(
"update_task",
{
description:
"Update a task (fetches current task, merges fields, then full update).",
inputSchema: updateTaskSchema,
},
async (args) => {
const { taskId, ...patch } = args;
return run(async () => {
const existing = (await client.json(
`/api/task/${encodeURIComponent(taskId)}`,
{ method: "GET" },
)) as Record<string, unknown>;
const body = buildFullTaskUpdateBody(existing, patch);
return client.json(`/api/task/${encodeURIComponent(taskId)}`, {
method: "PUT",
body: JSON.stringify(body),
});
});
},
);
registerTool(
"move_task",
{
description:
"Move a task to another project (and optional column status).",
inputSchema: z.object({
taskId: nonEmptyString,
destinationProjectId: nonEmptyString,
destinationStatus: optionalNonEmptyString,
}),
},
async (args) =>
run(() =>
client.json(`/api/task/move/${encodeURIComponent(args.taskId)}`, {
method: "PUT",
body: JSON.stringify({
destinationProjectId: args.destinationProjectId,
...(args.destinationStatus !== undefined
? { destinationStatus: args.destinationStatus }
: {}),
}),
}),
),
);
registerTool(
"update_task_status",
{
description: "Update only the status (column) of a task.",
inputSchema: z.object({
taskId: nonEmptyString,
status: nonEmptyString,
}),
},
async (args) =>
run(() =>
client.json(`/api/task/status/${encodeURIComponent(args.taskId)}`, {
method: "PUT",
body: JSON.stringify({ status: args.status }),
}),
),
);
registerTool(
"list_task_comments",
{
description: "List comments on a task.",
inputSchema: z.object({ taskId: nonEmptyString }),
},
async (args) =>
run(() =>
client.json(`/api/comment/${encodeURIComponent(args.taskId)}`, {
method: "GET",
}),
),
);
registerTool(
"create_task_comment",
{
description: "Add a comment to a task.",
inputSchema: z.object({
taskId: nonEmptyString,
content: nonEmptyString,
}),
},
async (args) =>
run(() =>
client.json(`/api/comment/${encodeURIComponent(args.taskId)}`, {
method: "POST",
body: JSON.stringify({ content: args.content }),
}),
),
);
registerTool(
"update_task_comment",
{
description: "Update one of your comments on a task.",
inputSchema: z.object({
commentId: nonEmptyString,
content: nonEmptyString,
}),
},
async (args) =>
run(() =>
client.json(`/api/comment/${encodeURIComponent(args.commentId)}`, {
method: "PUT",
body: JSON.stringify({ content: args.content }),
}),
),
);
registerTool(
"delete_task_comment",
{
description: "Delete one of your comments from a task.",
inputSchema: z.object({ commentId: nonEmptyString }),
},
async (args) =>
run(() =>
client.json(`/api/comment/${encodeURIComponent(args.commentId)}`, {
method: "DELETE",
}),
),
);
registerTool(
"list_workspace_labels",
{
description: "List labels defined in a workspace.",
inputSchema: z.object({ workspaceId: nonEmptyString }),
},
async (args) =>
run(() =>
client.json(
`/api/label/workspace/${encodeURIComponent(args.workspaceId)}`,
{ method: "GET" },
),
),
);
registerTool(
"create_label",
{
description:
"Create a label in a workspace (optionally attach to a task).",
inputSchema: z.object({
name: nonEmptyString,
color: hexColorSchema,
workspaceId: nonEmptyString,
taskId: optionalNonEmptyString,
}),
},
async (args) =>
run(() =>
client.json("/api/label", {
method: "POST",
body: JSON.stringify({
name: args.name,
color: args.color,
workspaceId: args.workspaceId,
...(args.taskId !== undefined ? { taskId: args.taskId } : {}),
}),
}),
),
);
registerTool(
"attach_label_to_task",
{
description: "Attach an existing label to a task.",
inputSchema: z.object({
labelId: nonEmptyString,
taskId: nonEmptyString,
}),
},
async (args) =>
run(() =>
client.json(`/api/label/${encodeURIComponent(args.labelId)}/task`, {
method: "PUT",
body: JSON.stringify({ taskId: args.taskId }),
}),
),
);
registerTool(
"detach_label_from_task",
{
description: "Detach a label from its current task.",
inputSchema: z.object({ labelId: nonEmptyString }),
},
async (args) =>
run(() =>
client.json(`/api/label/${encodeURIComponent(args.labelId)}/task`, {
method: "DELETE",
}),
),
);
registerTool(
"create_task_relation",
{
description:
"Create a relation between two tasks. relationType: 'subtask' (sourceTaskId is the parent, targetTaskId the child), 'blocks' (sourceTaskId blocks targetTaskId), or 'related' (bidirectional).",
inputSchema: z.object({
sourceTaskId: nonEmptyString,
targetTaskId: nonEmptyString,
relationType: z.enum(["subtask", "blocks", "related"]),
}),
},
async (args) =>
run(() =>
client.json("/api/task-relation", {
method: "POST",
body: JSON.stringify({
sourceTaskId: args.sourceTaskId,
targetTaskId: args.targetTaskId,
relationType: args.relationType,
}),
}),
),
);
registerTool(
"get_task_relations",
{
description:
"List all relations (subtask/blocks/related) involving a task.",
inputSchema: z.object({ taskId: nonEmptyString }),
},
async (args) =>
run(() =>
client.json(`/api/task-relation/${encodeURIComponent(args.taskId)}`, {
method: "GET",
}),
),
);
registerTool(
"delete_task_relation",
{
description: "Delete a task relation by its relation ID.",
inputSchema: z.object({ id: nonEmptyString }),
},
async (args) =>
run(() =>
client.json(`/api/task-relation/${encodeURIComponent(args.id)}`, {
method: "DELETE",
}),
),
);
registerTool(
"delete_label",
{
description:
"Delete a task or workspace label by ID. Workspace-label cascades resume automatically; repeat the tool if pendingDeletion remains true.",
inputSchema: z.object({ id: nonEmptyString }),
},
async (args) =>
run(async () => {
let result: unknown;
const signal = AbortSignal.timeout(10_000);
// Bound work per tool call. The API persists the continuation boundary.
for (let page = 0; page < 100; page++) {
if (page > 0 && signal.aborted) break;
try {
result = await client.json(
`/api/label/${encodeURIComponent(args.id)}`,
{ method: "DELETE", signal },
);
} catch (error) {
if (signal.aborted && result) break;
throw error;
}
if (
!result ||
typeof result !== "object" ||
!("pendingDeletion" in result) ||
!result.pendingDeletion
)
break;
}
return result;
}),
);
registerTool(
"list_workspace_members",
{
description:
"List the members of a workspace. Use this to resolve the user ID an assignee tool expects.",
inputSchema: z.object({ workspaceId: nonEmptyString }),
},
async (args) =>
run(() =>
client.json(
`/api/workspace/${encodeURIComponent(args.workspaceId)}/members`,
),
),
);
registerTool(
"search",
{
description:
"Search across tasks, projects, workspaces, comments, and activities.",
inputSchema: z.object({
q: nonEmptyString.describe("Search query"),
type: z
.enum([
"all",
"tasks",
"projects",
"workspaces",
"comments",
"activities",
])
.optional()
.describe("Restrict results to one kind. Defaults to all."),
workspaceId: optionalNonEmptyString.describe("Limit to one workspace"),
projectId: optionalNonEmptyString.describe("Limit to one project"),
limit: z
.number()
.int()
.min(1)
.max(50)
.optional()
.describe("Maximum results, 1 to 50. Defaults to 20."),
}),
},
async (args) => {
const qs = new URLSearchParams({ q: args.q });
if (args.type) qs.set("type", args.type);
if (args.workspaceId) qs.set("workspaceId", args.workspaceId);
if (args.projectId) qs.set("projectId", args.projectId);
if (args.limit !== undefined) qs.set("limit", String(args.limit));
return run(() => client.json(`/api/search?${qs.toString()}`));
},
);
registerTool(
"list_project_columns",
{
description:
"List a project's columns. Their slugs are the values update_task_status and create_task accept as a status.",
inputSchema: z.object({ projectId: nonEmptyString }),
},
async (args) =>
run(() =>
client.json(`/api/column/${encodeURIComponent(args.projectId)}`),
),
);
registerTool(
"list_project_custom_fields",
{
description:
"List a project's custom field definitions: id, name, type (text, number, date, dropdown, boolean, multiselect), required, options, and defaultValue.",
inputSchema: z.object({ projectId: nonEmptyString }),
},
async (args) =>
run(() =>
client.json(
`/api/custom-field/project/${encodeURIComponent(args.projectId)}`,
),
),
);
registerTool(
"get_task_custom_field_values",
{
description:
"List a task's custom field values with each field's name, type, and options. Fields without a value are omitted. Multiselect values are JSON array strings.",
inputSchema: z.object({ taskId: nonEmptyString }),
},
async (args) =>
run(() =>
client.json(
`/api/custom-field/task/${encodeURIComponent(args.taskId)}`,
),
),
);
registerTool(
"set_task_custom_field_value",
{
description:
"Set or clear one custom field value on a task. Get fieldId from list_project_custom_fields. Pass dates as YYYY-MM-DD, a dropdown value as one of its options, multiselect values as an array of options, and null to clear the value (required fields can't be cleared).",
inputSchema: z.object({
taskId: nonEmptyString,
fieldId: nonEmptyString,
value: z
.union([z.string(), z.number(), z.boolean(), z.array(z.string())])
.nullable()
.describe("New value, or null to clear it"),
}),
},
async (args) =>
run(() =>
client.json("/api/custom-field/value", {
method: "PUT",
body: JSON.stringify({
taskId: args.taskId,
fieldId: args.fieldId,
value: encodeCustomFieldValue(args.value),
}),
}),
),
);
registerTool(
"delete_task",
{
description: "Delete a task by ID.",
inputSchema: z.object({ taskId: nonEmptyString }),
},
async (args) =>
run(() =>
client.json(`/api/task/${encodeURIComponent(args.taskId)}`, {
method: "DELETE",
}),
),
);
registerTool(
"update_task_assignee",
{
description:
"Assign a task to a workspace member, or pass a null userId to unassign it.",
inputSchema: z.object({
taskId: nonEmptyString,
userId: nonEmptyString
.nullable()
.describe("Member user ID, or null to unassign"),
}),
},
async (args) =>
run(() =>
client.json(`/api/task/assignee/${encodeURIComponent(args.taskId)}`, {
method: "PUT",
body: JSON.stringify({ userId: args.userId }),
}),
),
);
registerTool(
"update_task_due_date",
{
description: "Set a task's due date. Omit dueDate to clear it.",
inputSchema: z.object({
taskId: nonEmptyString,
dueDate: optionalIsoDateTimeSchema,
}),
},
async (args) =>
run(() =>
client.json(`/api/task/due-date/${encodeURIComponent(args.taskId)}`, {
method: "PUT",
body: JSON.stringify(
args.dueDate === undefined ? {} : { dueDate: args.dueDate },
),
}),
),
);
registerTool(
"update_task_recurrence",
{
description:
"Make a task repeat, or omit frequency to stop it repeating. When a repeating task moves into a final column, the next task is created in the first open column, due one step after the completed task's due date.",
inputSchema: z.object({
taskId: nonEmptyString,
frequency: z.enum(["daily", "weekly", "monthly", "yearly"]).optional(),
interval: z.number().int().min(1).max(99).default(1),
weekdays: z
.array(z.number().int().min(0).max(6))
.min(1)
.max(7)
.optional()
.describe(
"Weekly only: days to repeat on, 0 for Sunday to 6 for Saturday.",
),
timeZone: nonEmptyString
.optional()
.describe(
"Required with frequency: the user's IANA time zone, such as Europe/Madrid. Weekdays and month ends are matched in this zone, so a wrong one moves the next task to another local day.",
),
}),
},
async (args) => {
if (args.frequency && !args.timeZone)
return errorResult("timeZone is required with frequency");
return run(() =>
client.json(`/api/task/recurrence/${encodeURIComponent(args.taskId)}`, {
method: "PUT",
body: JSON.stringify({
recurrence: args.frequency
? {
frequency: args.frequency,
interval: args.interval,
...(args.weekdays ? { weekdays: args.weekdays } : {}),
timeZone: args.timeZone,
}
: null,
}),
}),
);
},
);
registerTool(
"list_task_time_entries",
{
description: "List the time entries logged against a task.",
inputSchema: z.object({ taskId: nonEmptyString }),
},
async (args) =>
run(() =>
client.json(`/api/time-entry/task/${encodeURIComponent(args.taskId)}`),
),
);
registerTool(
"get_time_entry",
{
description: "Get a single time entry by ID.",
inputSchema: z.object({ id: nonEmptyString }),
},
async (args) =>
run(() => client.json(`/api/time-entry/${encodeURIComponent(args.id)}`)),
);
registerTool(
"create_time_entry",
{
description:
"Log time against a task. Omit endTime to leave the entry running.",
inputSchema: z.object({
taskId: nonEmptyString,
startTime: isoDateTimeSchema,
endTime: optionalIsoDateTimeSchema,
description: optionalNonEmptyString,
}),
},
async (args) =>
run(() =>
client.json("/api/time-entry", {
method: "POST",
body: JSON.stringify({
taskId: args.taskId,
startTime: args.startTime,
...(args.endTime ? { endTime: args.endTime } : {}),
...(args.description ? { description: args.description } : {}),
}),
}),
),
);
registerTool(
"update_time_entry",
{
description:
"Update a time entry. startTime is required; omitting endTime keeps the stored one. startTime cannot be later than the end time.",
inputSchema: z.object({
id: nonEmptyString,
startTime: isoDateTimeSchema,
endTime: optionalIsoDateTimeSchema,
description: optionalNonEmptyString,
}),
},
async (args) =>
run(() =>
client.json(`/api/time-entry/${encodeURIComponent(args.id)}`, {
method: "PUT",
body: JSON.stringify({
startTime: args.startTime,
...(args.endTime ? { endTime: args.endTime } : {}),
...(args.description ? { description: args.description } : {}),
}),
}),
),
);
registerTool(
"list_task_activity",
{
description: "List a task's activity history.",
inputSchema: z.object({ taskId: nonEmptyString }),
},
async (args) =>
run(() =>
client.json(`/api/activity/${encodeURIComponent(args.taskId)}`),
),
);
registerTool(
"list_notifications",
{
description: "List the signed-in user's notifications.",
inputSchema: z.object({}),
},
async () => run(() => client.json("/api/notification")),
);
}