backlog-mcp-server 0.4.0

package/build/types/zod/backlogOutputDefinition.js

@@ -0,0 +1,468 @@
+import { z } from 'zod';
+export const TextFormattingRuleSchema = z.enum(['backlog', 'markdown']);
+export const RoleTypeSchema = z.union([
+    z.nativeEnum({
+        Admin: 1,
+        User: 2,
+        Reporter: 3,
+        Viewer: 4,
+        GuestReporter: 5,
+        GuestViewer: 6,
+    }),
+    z.nativeEnum({
+        Admin: 1,
+        MemberOrGuest: 2,
+        MemberOrGuestForAddIssues: 3,
+        MemberOrGuestForViewIssues: 4,
+    }),
+]);
+export const LanguageSchema = z.union([
+    z.literal('en'),
+    z.literal('ja'),
+    z.null(),
+]);
+export const ActivityTypeSchema = z.nativeEnum({
+    Undefined: -1,
+    IssueCreated: 1,
+    IssueUpdated: 2,
+    IssueCommented: 3,
+    IssueDeleted: 4,
+    WikiCreated: 5,
+    WikiUpdated: 6,
+    WikiDeleted: 7,
+    FileAdded: 8,
+    FileUpdated: 9,
+    FileDeleted: 10,
+    SvnCommitted: 11,
+    GitPushed: 12,
+    GitRepositoryCreated: 13,
+    IssueMultiUpdated: 14,
+    ProjectUserAdded: 15,
+    ProjectUserRemoved: 16,
+    NotifyAdded: 17,
+    PullRequestAdded: 18,
+    PullRequestUpdated: 19,
+    PullRequestCommented: 20,
+    PullRequestMerged: 21,
+    MilestoneCreated: 22,
+    MilestoneUpdated: 23,
+    MilestoneDeleted: 24,
+    ProjectGroupAdded: 25,
+    ProjectGroupDeleted: 26,
+});
+export const IssueTypeColorSchema = z.enum([
+    '#e30000',
+    '#990000',
+    '#934981',
+    '#814fbc',
+    '#2779ca',
+    '#007e9a',
+    '#7ea800',
+    '#ff9200',
+    '#ff3265',
+    '#666665',
+]);
+export const ProjectStatusColorSchema = z.enum([
+    '#ea2c00',
+    '#e87758',
+    '#e07b9a',
+    '#868cb7',
+    '#3b9dbd',
+    '#4caf93',
+    '#b0be3c',
+    '#eda62a',
+    '#f42858',
+    '#393939',
+]);
+export const CustomFieldTypeSchema = z.nativeEnum({
+    Text: 1,
+    TextArea: 2,
+    Numeric: 3,
+    Date: 4,
+    SingleList: 5,
+    MultipleList: 6,
+    CheckBox: 7,
+    Radio: 8,
+});
+export const WebhookActivityIdSchema = z.number();
+export const UserSchema = z.object({
+    id: z.number(),
+    userId: z.string(),
+    name: z.string(),
+    roleType: RoleTypeSchema,
+    lang: LanguageSchema,
+    mailAddress: z.string(),
+    lastLoginTime: z.string(),
+});
+export const ProjectStatusSchema = z.object({
+    id: z.number(),
+    projectId: z.number(),
+    name: z.string(),
+    color: ProjectStatusColorSchema,
+    displayOrder: z.number(),
+});
+export const CategorySchema = z.object({
+    id: z.number(),
+    projectId: z.number(),
+    name: z.string(),
+    displayOrder: z.number(),
+});
+export const IssueFileInfoSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+    size: z.number(),
+    createdUser: UserSchema,
+    created: z.string(),
+});
+export const StarSchema = z.object({
+    id: z.number(),
+    comment: z.string().optional(),
+    url: z.string(),
+    title: z.string(),
+    presenter: UserSchema,
+    created: z.string(),
+});
+export const IssueTypeSchema = z.object({
+    id: z.number(),
+    projectId: z.number(),
+    name: z.string(),
+    color: IssueTypeColorSchema,
+    displayOrder: z.number(),
+    templateSummary: z.string().optional(),
+    templateDescription: z.string().optional(),
+});
+export const ResolutionSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+});
+export const PrioritySchema = z.object({
+    id: z.number(),
+    name: z.string(),
+});
+export const VersionSchema = z.object({
+    id: z.number(),
+    projectId: z.number(),
+    name: z.string(),
+    description: z.string().optional(),
+    startDate: z.string().optional(),
+    releaseDueDate: z.string().optional(),
+    archived: z.boolean(),
+    displayOrder: z.number(),
+});
+export const CustomFieldSchema = z.object({
+    id: z.number(),
+    projectId: z.number(),
+    typeId: CustomFieldTypeSchema,
+    name: z.string(),
+    description: z.string(),
+    required: z.boolean(),
+    applicableIssueTypes: z.array(z.number()),
+});
+export const SharedFileSchema = z.object({
+    id: z.number(),
+    projectId: z.number(),
+    type: z.string(),
+    dir: z.string(),
+    name: z.string(),
+    size: z.number(),
+    createdUser: UserSchema,
+    created: z.string(),
+    updatedUser: UserSchema,
+    updated: z.string(),
+});
+export const IssueSchema = z.object({
+    id: z.number(),
+    projectId: z.number(),
+    issueKey: z.string(),
+    keyId: z.number(),
+    issueType: IssueTypeSchema,
+    summary: z.string(),
+    description: z.string(),
+    resolution: ResolutionSchema.optional(),
+    priority: PrioritySchema,
+    status: ProjectStatusSchema,
+    assignee: UserSchema.optional(),
+    category: z.array(CategorySchema),
+    versions: z.array(VersionSchema),
+    milestone: z.array(VersionSchema),
+    startDate: z.string().optional(),
+    dueDate: z.string().optional(),
+    estimatedHours: z.number().optional(),
+    actualHours: z.number().optional(),
+    parentIssueId: z.number().optional(),
+    createdUser: UserSchema,
+    created: z.string(),
+    updatedUser: UserSchema,
+    updated: z.string(),
+    customFields: z.array(CustomFieldSchema),
+    attachments: z.array(IssueFileInfoSchema),
+    sharedFiles: z.array(SharedFileSchema),
+    stars: z.array(StarSchema),
+});
+export const ProjectSchema = z.object({
+    id: z.number(),
+    projectKey: z.string(),
+    name: z.string(),
+    chartEnabled: z.boolean(),
+    useResolvedForChart: z.boolean(),
+    subtaskingEnabled: z.boolean(),
+    projectLeaderCanEditProjectLeader: z.boolean(),
+    useWiki: z.boolean(),
+    useFileSharing: z.boolean(),
+    useWikiTreeView: z.boolean(),
+    useOriginalImageSizeAtWiki: z.boolean(),
+    useSubversion: z.boolean(),
+    useGit: z.boolean(),
+    textFormattingRule: TextFormattingRuleSchema,
+    archived: z.boolean(),
+    displayOrder: z.number(),
+    useDevAttributes: z.boolean(),
+});
+export const AttachmentInfoSchema = z.object({
+    id: z.number(),
+    type: z.string(),
+});
+export const AttributeInfoSchema = z.object({
+    id: z.number(),
+    typeId: z.number(),
+});
+export const NotificationInfoSchema = z.object({
+    type: z.string(),
+});
+export const IssueChangeLogSchema = z.object({
+    field: z.string(),
+    newValue: z.string(),
+    originalValue: z.string(),
+    attachmentInfo: AttachmentInfoSchema,
+    attributeInfo: AttributeInfoSchema,
+    notificationInfo: NotificationInfoSchema,
+});
+export const CommentNotificationSchema = z.object({
+    id: z.number(),
+    alreadyRead: z.boolean(),
+    reason: z.number(),
+    user: UserSchema,
+    resourceAlreadyRead: z.boolean(),
+});
+export const IssueCommentSchema = z.object({
+    id: z.number(),
+    projectId: z.number(),
+    issueId: z.number(),
+    content: z.string(),
+    changeLog: z.array(IssueChangeLogSchema),
+    createdUser: UserSchema,
+    created: z.string(),
+    updated: z.string(),
+    stars: z.array(StarSchema),
+    notifications: z.array(CommentNotificationSchema),
+});
+export const PullRequestStatusSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+});
+export const PullRequestFileInfoSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+    size: z.number(),
+    createdUser: UserSchema,
+    created: z.string(),
+});
+export const ChangeLogSchema = z.object({
+    field: z.string(),
+    newValue: z.string(),
+    originalValue: z.string(),
+});
+export const PullRequestChangeLogSchema = ChangeLogSchema;
+export const PullRequestSchema = z.object({
+    id: z.number(),
+    projectId: z.number(),
+    repositoryId: z.number(),
+    number: z.number(),
+    summary: z.string(),
+    description: z.string(),
+    base: z.string(),
+    branch: z.string(),
+    status: PullRequestStatusSchema,
+    assignee: UserSchema.optional(),
+    issue: IssueSchema,
+    baseCommit: z.string().optional(),
+    branchCommit: z.string().optional(),
+    mergeCommit: z.string().optional(),
+    closeAt: z.string().optional(),
+    mergeAt: z.string().optional(),
+    createdUser: UserSchema,
+    created: z.string(),
+    updatedUser: UserSchema,
+    updated: z.string(),
+    attachments: z.array(PullRequestFileInfoSchema),
+    stars: z.array(StarSchema),
+});
+export const PullRequestCommentSchema = z.object({
+    id: z.number(),
+    content: z.string(),
+    changeLog: z.array(PullRequestChangeLogSchema),
+    createdUser: UserSchema,
+    created: z.string(),
+    updated: z.string(),
+    stars: z.array(StarSchema),
+    notifications: z.array(CommentNotificationSchema),
+});
+export const WikiFileInfoSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+    size: z.number(),
+    createdUser: UserSchema,
+    created: z.string(),
+});
+export const TagSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+});
+export const WikiSchema = z.object({
+    id: z.number(),
+    projectId: z.number(),
+    name: z.string(),
+    content: z.string(),
+    tags: z.array(TagSchema),
+    attachments: z.array(WikiFileInfoSchema),
+    sharedFiles: z.array(SharedFileSchema),
+    stars: z.array(StarSchema),
+    createdUser: UserSchema,
+    created: z.string(),
+    updatedUser: UserSchema,
+    updated: z.string(),
+});
+export const IssueCountSchema = z.object({
+    count: z.number(),
+});
+export const WatchingListItemSchema = z.object({
+    id: z.number(),
+    resourceAlreadyRead: z.boolean(),
+    note: z.string(),
+    type: z.string(),
+    issue: IssueSchema,
+    lastContentUpdated: z.string(),
+    created: z.string(),
+    updated: z.string(),
+});
+export const GitRepositorySchema = z.object({
+    id: z.number(),
+    projectId: z.number(),
+    name: z.string(),
+    description: z.string(),
+    hookUrl: z.string().optional(),
+    httpUrl: z.string(),
+    sshUrl: z.string(),
+    displayOrder: z.number(),
+    pushedAt: z.string().optional(),
+    createdUser: UserSchema,
+    created: z.string(),
+    updatedUser: UserSchema,
+    updated: z.string(),
+});
+export const NotificationSchema = z.object({
+    id: z.number(),
+    alreadyRead: z.boolean(),
+    reason: z.number(),
+    resourceAlreadyRead: z.boolean(),
+    project: ProjectSchema.optional(),
+    issue: IssueSchema.optional(),
+    comment: IssueCommentSchema.optional(),
+    pullRequest: PullRequestSchema.optional(),
+    pullRequestComment: PullRequestCommentSchema.optional(),
+    sender: UserSchema,
+    created: z.string(),
+});
+export const NotificationCountSchema = z.object({
+    count: z.number(),
+});
+export const PullRequestCountSchema = z.object({
+    count: z.number(),
+});
+export const SpaceSchema = z.object({
+    spaceKey: z.string(),
+    name: z.string(),
+    ownerId: z.number(),
+    lang: z.string(),
+    timezone: z.string(),
+    reportSendTime: z.string(),
+    textFormattingRule: TextFormattingRuleSchema,
+    created: z.string(),
+    updated: z.string(),
+});
+export const WatchingListCountSchema = z.object({
+    count: z.number(),
+});
+export const WikiListItemSchema = z.object({
+    id: z.number(),
+    projectId: z.number(),
+    name: z.string(),
+    tags: z.array(TagSchema),
+    createdUser: UserSchema,
+    created: z.string(),
+    updatedUser: UserSchema,
+    updated: z.string(),
+});
+export const WikiCountSchema = z.object({
+    count: z.number(),
+});
+export const DocumentSchema = z.object({
+    id: z.number(),
+    projectId: z.number(),
+    name: z.string(),
+    content: z.string(),
+    createdUser: UserSchema,
+    created: z.string(),
+    updatedUser: UserSchema,
+    updated: z.string(),
+});
+export const DocumentAttachmentSchema = z.object({
+    filename: z.string(),
+    body: z.any(),
+    url: z.string(),
+});
+export const DocumentTagSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+});
+export const DocumentFileInfoSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+    size: z.number(),
+    createdUser: UserSchema,
+    created: z.string(),
+});
+export const DocumentItemSchema = z.object({
+    id: z.string(),
+    projectId: z.number(),
+    title: z.string(),
+    plain: z.string(),
+    json: z.string(),
+    statusId: z.number(),
+    emoji: z.string().nullable(),
+    attachments: z.array(DocumentFileInfoSchema),
+    tags: z.array(DocumentTagSchema),
+    createdUser: UserSchema,
+    created: z.string(),
+    updatedUser: UserSchema,
+    updated: z.string(),
+});
+export const DocumentTreeNodeSchema = z.lazy(() => z.object({
+    id: z.string(),
+    name: z.string().optional(),
+    children: z.array(DocumentTreeNodeSchema),
+    statusId: z.number().optional(),
+    emoji: z.string().optional(),
+    emojiType: z.string().optional(),
+    updated: z.string().optional(),
+}));
+export const ActiveTrashTreeSchema = z.object({
+    id: z.string(),
+    children: z.array(DocumentTreeNodeSchema),
+});
+export const DocumentTreeFullSchema = {
+    projectId: z.number(),
+    activeTree: ActiveTrashTreeSchema.optional(),
+    trashTree: ActiveTrashTreeSchema.optional(),
+};
+export const DocumentTreeFullSchemaZ = z.object(DocumentTreeFullSchema);

package/build/utils/generateFieldsDescription.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+/**
+ * Generate GraphQL like fields and type specs from Zod types
+ */
+export function generateFieldsDescription(outputSchema, importantFields = [], typeName = 'Output') {
+    const allFields = Object.keys(outputSchema.shape);
+    // Generate Example Query
+    const exampleQueryFields = importantFields.length > 0 ? importantFields : allFields;
+    // Generate Output Schema
+    const gqlTypeDef = generateGraphQLType(typeName, outputSchema);
+    return `
+Specify the fields to retrieve using GraphQL query syntax.
+Example (query):
+{
+  ${exampleQueryFields.join('\n  ')}
+}
+Output schema (type definition):
+${gqlTypeDef}
+  `.trim();
+}
+function generateGraphQLType(typeName, schema) {
+    const lines = [`type ${typeName} {`];
+    for (const [key, value] of Object.entries(schema.shape)) {
+        lines.push(`  ${key}: ${mapZodTypeToGraphQLType(value)}`);
+    }
+    lines.push('}');
+    return lines.join('\n');
+}
+/**
+ * Zod to graphql
+ */
+function mapZodTypeToGraphQLType(zodType) {
+    if (zodType instanceof z.ZodString)
+        return 'String!';
+    if (zodType instanceof z.ZodNumber)
+        return 'Int!';
+    if (zodType instanceof z.ZodBoolean)
+        return 'Boolean!';
+    if (zodType instanceof z.ZodNullable)
+        return mapZodTypeToGraphQLType(zodType.unwrap()).replace(/!$/, '');
+    if (zodType instanceof z.ZodOptional)
+        return mapZodTypeToGraphQLType(zodType.unwrap()).replace(/!$/, '');
+    // Spec: a nested part is JSON
+    if (zodType instanceof z.ZodObject)
+        return 'JSON';
+    return 'String';
+}

package/build/utils/resolveIdOrKey.js

@@ -0,0 +1,25 @@
+/**
+ * Generic resolver for entity identification by ID or named field (e.g., key, name, slug).
+ * @param entity - The entity name, e.g., "project"
+ * @param fieldName - The name of the alternative to `id`, e.g., "key", "name", "slug"
+ * @param values - An object with `id?: number` and `[fieldName]?: string`
+ * @param t - Translator
+ */
+function resolveIdOrField(entity, fieldName, values, t) {
+    const value = tryResolveIdOrField(fieldName, values);
+    if (value === undefined) {
+        return {
+            ok: false,
+            error: new Error(t(`${entity.toUpperCase()}_ID_OR_${fieldName.toUpperCase()}_REQUIRED`, `${capitalize(entity)} ID or ${fieldName} is required`)),
+        };
+    }
+    return { ok: true, value };
+}
+function tryResolveIdOrField(fieldName, values) {
+    return values.id !== undefined ? values.id : values[fieldName];
+}
+export const resolveIdOrKey = (entity, values, t) => resolveIdOrField(entity, 'key', values, t);
+export const resolveIdOrName = (entity, values, t) => resolveIdOrField(entity, 'name', values, t);
+function capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}

package/build/utils/runToolSafely.js

@@ -0,0 +1,18 @@
+/**
+ * Runs a tool handler safely, catching any errors and converting to SafeResult.
+ * The `onError` handler defines how to turn unknown errors into ErrorLike objects.
+ */
+export function runToolSafely(fn, onError) {
+    return async (input) => {
+        try {
+            const data = await fn(input);
+            return { kind: 'ok', data };
+        }
+        catch (err) {
+            if (onError) {
+                return onError(err);
+            }
+            return { kind: 'error', message: 'Unknown: ' + err };
+        }
+    };
+}

package/build/utils/tokenCounter.js

@@ -0,0 +1,11 @@
+export function countTokens(text) {
+    // Normalize whitespace (convert tabs and newlines to spaces)
+    const normalized = text
+        .replace(/\s+/g, ' ') // Replace multiple whitespace with a single space
+        .replace(/[\n\t]/g, ' ') // Replace newlines and tabs with a space
+        .trim();
+    // Split into words and individual symbols
+    const tokens = normalized.match(/\w+|[^\s\w]/g);
+    // Return the number of tokens
+    return tokens ? tokens.length : 0;
+}

package/build/utils/toolRegistrar.js

@@ -0,0 +1,12 @@
+import { registerTools } from '../registerTools.js';
+import { enableToolset } from '../utils/toolsetUtils.js';
+export function createToolRegistrar(server, toolsetGroup, options) {
+    return {
+        async enableToolsetAndRefresh(toolset) {
+            const msg = enableToolset(toolsetGroup, toolset);
+            registerTools(server, toolsetGroup, options);
+            await server.server.sendToolListChanged();
+            return msg;
+        },
+    };
+}

package/build/utils/toolsetUtils.js

@@ -0,0 +1,48 @@
+import { allTools } from '../tools/tools.js';
+export function getToolset(group, name) {
+    return group.toolsets.find((t) => t.name === name);
+}
+export function enableToolset(group, name) {
+    const ts = getToolset(group, name);
+    if (!ts)
+        return `Toolset ${name} not found`;
+    if (ts.enabled)
+        return `Toolset ${name} is already enabled`;
+    ts.enabled = true;
+    return `Toolset ${name} enabled`;
+}
+export function getEnabledTools(group) {
+    return group.toolsets.filter((ts) => ts.enabled).flatMap((ts) => ts.tools);
+}
+export function listAvailableToolsets(group) {
+    return group.toolsets.map((ts) => ({
+        name: ts.name,
+        description: ts.description,
+        currentlyEnabled: ts.enabled,
+        canEnable: true,
+    }));
+}
+export function listToolsetTools(group, name) {
+    const ts = getToolset(group, name);
+    return (ts?.tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        toolset: name,
+        canEnable: true,
+    })) ?? []);
+}
+export const buildToolsetGroup = (backlog, helper, enabledToolsets) => {
+    const toolsetGroup = allTools(backlog, helper);
+    const knownNames = toolsetGroup.toolsets.map((ts) => ts.name);
+    const unknown = enabledToolsets.filter((name) => name !== 'all' && !knownNames.includes(name));
+    if (unknown.length > 0) {
+        console.warn(`⚠️ Unknown toolsets: ${unknown.join(', ')}`);
+    }
+    const allEnabled = enabledToolsets.includes('all');
+    return {
+        toolsets: toolsetGroup.toolsets.map((ts) => ({
+            ...ts,
+            enabled: allEnabled || enabledToolsets.includes(ts.name),
+        })),
+    };
+};

package/build/utils/wrapServerWithToolRegistry.js

@@ -0,0 +1,16 @@
+// This function takes an McpServer instance and extends it with a tool registration mechanism that prevents duplicate tool registrations.
+export function wrapServerWithToolRegistry(server) {
+    const s = server;
+    if (!s.__registeredToolNames) {
+        s.__registeredToolNames = new Set();
+    }
+    s.registerOnce = (name, description, schema, handler) => {
+        if (s.__registeredToolNames.has(name)) {
+            console.warn(`Skipping duplicate tool registration: ${name}`);
+            return;
+        }
+        s.__registeredToolNames.add(name);
+        s.tool(name, description, schema, handler);
+    };
+    return s;
+}

package/build/version.js

@@ -0,0 +1 @@
+export const VERSION = '0.4.0';

package/build/version.template.js

@@ -0,0 +1 @@
+export const VERSION = '__VERSION__';