@denvermullets/jait 1.2.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,7 @@
1
1
  interface RequestOptions {
2
2
  method?: string;
3
3
  body?: Record<string, unknown>;
4
+ form?: FormData;
4
5
  params?: Record<string, string | number | undefined>;
5
6
  }
6
7
  export declare function apiRequest<T>(path: string, options?: RequestOptions): Promise<T>;
@@ -13,7 +13,7 @@ function getConfig() {
13
13
  }
14
14
  export async function apiRequest(path, options = {}) {
15
15
  const { baseUrl, token } = getConfig();
16
- const { method = "GET", body, params } = options;
16
+ const { method = "GET", body, form, params } = options;
17
17
  const url = new URL(`${baseUrl}${path}`);
18
18
  if (params) {
19
19
  for (const [key, value] of Object.entries(params)) {
@@ -24,13 +24,15 @@ export async function apiRequest(path, options = {}) {
24
24
  }
25
25
  const headers = {
26
26
  Authorization: `Bearer ${token}`,
27
- "Content-Type": "application/json",
28
27
  Accept: "application/json",
29
28
  };
29
+ // For multipart, fetch sets Content-Type itself so it can include the boundary.
30
+ if (!form)
31
+ headers["Content-Type"] = "application/json";
30
32
  const response = await fetch(url.toString(), {
31
33
  method,
32
34
  headers,
33
- body: body ? JSON.stringify(body) : undefined,
35
+ body: form ?? (body ? JSON.stringify(body) : undefined),
34
36
  });
35
37
  if (!response.ok) {
36
38
  const errorBody = await response.text();
@@ -45,5 +47,14 @@ export async function apiRequest(path, options = {}) {
45
47
  }
46
48
  throw new Error(`API error ${response.status}: ${message}`);
47
49
  }
48
- return response.json();
50
+ // Some endpoints (e.g. a 204 No Content on DELETE) return an empty body.
51
+ // Guard against JSON.parse throwing "Unexpected end of JSON input".
52
+ if (response.status === 204) {
53
+ return undefined;
54
+ }
55
+ const text = await response.text();
56
+ if (!text) {
57
+ return undefined;
58
+ }
59
+ return JSON.parse(text);
49
60
  }
@@ -0,0 +1,16 @@
1
+ import { z } from "zod";
2
+ export declare const filePathsSchema: z.ZodOptional<z.ZodArray<z.ZodString>>;
3
+ export interface LocalFile {
4
+ filename: string;
5
+ data: Uint8Array<ArrayBuffer>;
6
+ }
7
+ export interface Attachment {
8
+ id: number;
9
+ filename: string;
10
+ content_type: string;
11
+ byte_size: number;
12
+ url: string;
13
+ }
14
+ export declare function readLocalFiles(paths: string[]): Promise<LocalFile[]>;
15
+ export declare function buildMultipart(root: string, fields: Record<string, unknown>, files: LocalFile[]): FormData;
16
+ export declare function formatAttachments(attachments: Attachment[]): string;
@@ -0,0 +1,64 @@
1
+ import { readFile, stat } from "node:fs/promises";
2
+ import { homedir } from "node:os";
3
+ import { basename, resolve } from "node:path";
4
+ import { z } from "zod";
5
+ export const filePathsSchema = z
6
+ .array(z.string())
7
+ .optional()
8
+ .describe("Local file paths to attach (absolute, or ~/...). Uploaded to the issue alongside any other changes; existing attachments are kept.");
9
+ function expandPath(path) {
10
+ if (path === "~" || path.startsWith("~/")) {
11
+ return resolve(homedir(), path.slice(2));
12
+ }
13
+ return resolve(path);
14
+ }
15
+ // Reads every file up front so a bad path fails the call before anything is
16
+ // written, rather than leaving a half-created issue behind.
17
+ export async function readLocalFiles(paths) {
18
+ return Promise.all(paths.map(async (path) => {
19
+ const fullPath = expandPath(path);
20
+ const info = await stat(fullPath).catch(() => null);
21
+ if (!info?.isFile()) {
22
+ throw new Error(`Attachment not found or not a file: ${path}`);
23
+ }
24
+ const buffer = await readFile(fullPath);
25
+ return { filename: basename(fullPath), data: new Uint8Array(buffer) };
26
+ }));
27
+ }
28
+ // Encodes { root: fields, files } the way Rails parses multipart params:
29
+ // root[key]=value, root[key][]=each array item, root[files][]=each upload.
30
+ // An empty array is sent as a single blank item so it still clears the
31
+ // association (Rails drops blank ids), matching `label_ids: []` over JSON.
32
+ export function buildMultipart(root, fields, files) {
33
+ const form = new FormData();
34
+ for (const [key, value] of Object.entries(fields)) {
35
+ if (value === undefined || value === null)
36
+ continue;
37
+ if (Array.isArray(value)) {
38
+ if (value.length === 0)
39
+ form.append(`${root}[${key}][]`, "");
40
+ for (const item of value)
41
+ form.append(`${root}[${key}][]`, String(item));
42
+ }
43
+ else {
44
+ form.append(`${root}[${key}]`, String(value));
45
+ }
46
+ }
47
+ for (const file of files) {
48
+ // Content type is left to the server, which sniffs it from name + bytes.
49
+ form.append(`${root}[files][]`, new Blob([file.data]), file.filename);
50
+ }
51
+ return form;
52
+ }
53
+ function formatBytes(bytes) {
54
+ if (bytes < 1024)
55
+ return `${bytes} B`;
56
+ if (bytes < 1024 * 1024)
57
+ return `${(bytes / 1024).toFixed(1)} KB`;
58
+ return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
59
+ }
60
+ export function formatAttachments(attachments) {
61
+ return attachments
62
+ .map((a) => `${a.filename} (${a.content_type}, ${formatBytes(a.byte_size)})`)
63
+ .join(", ");
64
+ }
@@ -1,12 +1,16 @@
1
1
  import { z } from "zod";
2
2
  import { apiRequest } from "../api-client.js";
3
+ import { buildMultipart, filePathsSchema, formatAttachments, readLocalFiles, } from "../attachments.js";
3
4
  function formatComment(comment, indent = 0) {
4
5
  const pad = " ".repeat(indent);
5
6
  const author = comment.user ? comment.user.name : "Unknown";
6
7
  const lines = [
7
8
  `${pad}#${comment.id} by ${author} at ${comment.created_at}`,
8
- `${pad} ${comment.body}`,
9
+ `${pad} ${comment.body ?? ""}`,
9
10
  ];
11
+ if (comment.attachments && comment.attachments.length > 0) {
12
+ lines.push(`${pad} Attachments: ${formatAttachments(comment.attachments)}`);
13
+ }
10
14
  if (comment.replies && comment.replies.length > 0) {
11
15
  for (const reply of comment.replies) {
12
16
  lines.push(formatComment(reply, indent + 1));
@@ -25,19 +29,24 @@ export function registerCommentTools(server) {
25
29
  content: [{ type: "text", text: text || "No comments on this issue." }],
26
30
  };
27
31
  });
28
- server.tool("create_comment", "Post a new comment on an issue. The author is derived from the API token. Pass parent_id to reply to an existing comment.", {
32
+ server.tool("create_comment", "Post a new comment on an issue. The author is derived from the API token. Pass parent_id to reply to an existing comment, and file_paths to attach local files.", {
29
33
  team_id: z.number().describe("Team ID"),
30
34
  issue_id: z.number().describe("Issue ID"),
31
- body: z.string().describe("Comment text"),
35
+ body: z
36
+ .string()
37
+ .optional()
38
+ .describe("Comment text. May be omitted when file_paths is given."),
32
39
  parent_id: z
33
40
  .number()
34
41
  .optional()
35
42
  .describe("Parent comment ID to reply to"),
36
- }, async ({ team_id, issue_id, body, parent_id }) => {
37
- const comment = await apiRequest(`/api/v1/teams/${team_id}/issues/${issue_id}/comments`, {
38
- method: "POST",
39
- body: { comment: { body, parent_id } },
40
- });
43
+ file_paths: filePathsSchema,
44
+ }, async ({ team_id, issue_id, body, parent_id, file_paths }) => {
45
+ const files = await readLocalFiles(file_paths ?? []);
46
+ const fields = { body, parent_id };
47
+ const comment = await apiRequest(`/api/v1/teams/${team_id}/issues/${issue_id}/comments`, files.length > 0
48
+ ? { method: "POST", form: buildMultipart("comment", fields, files) }
49
+ : { method: "POST", body: { comment: fields } });
41
50
  return {
42
51
  content: [
43
52
  {
@@ -1,6 +1,30 @@
1
1
  import { z } from "zod";
2
2
  import { apiRequest } from "../api-client.js";
3
3
  export function registerIssueDependencyTools(server) {
4
+ server.tool("list_issue_dependencies", "List every dependency (blocking relationship) attached to an issue, including each dependency record's ID. Use this to find the dependency_id required by remove_issue_dependency.", {
5
+ team_id: z.number().describe("Team ID"),
6
+ issue_id: z.number().describe("The issue ID whose dependencies to list"),
7
+ }, async ({ team_id, issue_id }) => {
8
+ const deps = await apiRequest(`/api/v1/teams/${team_id}/issues/${issue_id}/issue_dependencies`);
9
+ if (deps.length === 0) {
10
+ return {
11
+ content: [
12
+ { type: "text", text: "No dependencies found for this issue." },
13
+ ],
14
+ };
15
+ }
16
+ const text = deps
17
+ .map((dep) => {
18
+ const relation = dep.direction === "blocked_by"
19
+ ? `blocked by ${dep.blocking_issue.identifier} (${dep.blocking_issue.title})`
20
+ : `blocking ${dep.blocked_issue.identifier} (${dep.blocked_issue.title})`;
21
+ return `[dep #${dep.id}] This issue is ${relation}`;
22
+ })
23
+ .join("\n");
24
+ return {
25
+ content: [{ type: "text", text }],
26
+ };
27
+ });
4
28
  server.tool("create_issue_dependency", "Create a blocking relationship between two issues. Use direction 'blocking' to mark the issue as blocking the target, or 'blocked_by' to mark it as blocked by the target.", {
5
29
  team_id: z.number().describe("Team ID"),
6
30
  issue_id: z.number().describe("The source issue ID"),
@@ -1,2 +1,61 @@
1
1
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
+ import { type Attachment } from "../attachments.js";
3
+ interface Issue {
4
+ id: number;
5
+ identifier: string;
6
+ title: string;
7
+ description?: string;
8
+ priority: string;
9
+ estimate: number | null;
10
+ due_date: string | null;
11
+ lane: {
12
+ id: number;
13
+ name: string;
14
+ };
15
+ assignee: {
16
+ id: number;
17
+ name: string;
18
+ } | null;
19
+ creator: {
20
+ id: number;
21
+ name: string;
22
+ };
23
+ project: {
24
+ id: number;
25
+ name: string;
26
+ } | null;
27
+ labels: {
28
+ id: number;
29
+ name: string;
30
+ }[];
31
+ attachments?: Attachment[];
32
+ milestone?: {
33
+ id: number;
34
+ name: string;
35
+ } | null;
36
+ parent_issue?: {
37
+ id: number;
38
+ identifier: string;
39
+ title: string;
40
+ } | null;
41
+ blocking_issues?: {
42
+ id: number;
43
+ identifier: string;
44
+ title: string;
45
+ dependency_id: number;
46
+ }[];
47
+ blocked_issues?: {
48
+ id: number;
49
+ identifier: string;
50
+ title: string;
51
+ dependency_id: number;
52
+ }[];
53
+ started_at: string | null;
54
+ completed_at: string | null;
55
+ canceled_at: string | null;
56
+ created_at: string;
57
+ updated_at: string;
58
+ }
59
+ export declare function formatIssue(issue: Issue, detailed?: boolean): string;
2
60
  export declare function registerIssueTools(server: McpServer): void;
61
+ export {};
@@ -1,9 +1,10 @@
1
1
  import { z } from "zod";
2
2
  import { apiRequest } from "../api-client.js";
3
+ import { buildMultipart, filePathsSchema, formatAttachments, readLocalFiles, } from "../attachments.js";
3
4
  const priorityEnum = z
4
5
  .enum(["urgent", "high", "medium", "low", "no_priority"])
5
6
  .describe("Issue priority");
6
- function formatIssue(issue, detailed = false) {
7
+ export function formatIssue(issue, detailed = false) {
7
8
  const lines = [
8
9
  `**${issue.identifier}**: ${issue.title}`,
9
10
  ` Status: ${issue.lane.name} | Priority: ${issue.priority} | ID: ${issue.id}`,
@@ -21,14 +22,21 @@ function formatIssue(issue, detailed = false) {
21
22
  if (detailed) {
22
23
  if (issue.description)
23
24
  lines.push(` Description: ${issue.description}`);
25
+ if (issue.attachments && issue.attachments.length > 0)
26
+ lines.push(` Attachments: ${formatAttachments(issue.attachments)}`);
24
27
  if (issue.milestone)
25
28
  lines.push(` Milestone: ${issue.milestone.name}`);
26
29
  if (issue.parent_issue)
27
30
  lines.push(` Parent: ${issue.parent_issue.identifier} — ${issue.parent_issue.title}`);
28
- if (issue.blocking_issues && issue.blocking_issues.length > 0)
29
- lines.push(` Blocking: ${issue.blocking_issues.map((i) => `${i.identifier} (${i.title})`).join(", ")}`);
31
+ // API semantics (from the Rails issue serializer / associations):
32
+ // blocked_issues = issues THIS issue blocks (its dependents) -> "Blocking:"
33
+ // blocking_issues = issues that block THIS issue (its blockers) -> "Blocked by:"
34
+ // Each entry includes [dep #N], the IssueDependency record id, which is the
35
+ // dependency_id required by remove_issue_dependency.
30
36
  if (issue.blocked_issues && issue.blocked_issues.length > 0)
31
- lines.push(` Blocked by: ${issue.blocked_issues.map((i) => `${i.identifier} (${i.title})`).join(", ")}`);
37
+ lines.push(` Blocking: ${issue.blocked_issues.map((i) => `${i.identifier} (${i.title}) [dep #${i.dependency_id}]`).join(", ")}`);
38
+ if (issue.blocking_issues && issue.blocking_issues.length > 0)
39
+ lines.push(` Blocked by: ${issue.blocking_issues.map((i) => `${i.identifier} (${i.title}) [dep #${i.dependency_id}]`).join(", ")}`);
32
40
  lines.push(` Creator: ${issue.creator.name}`);
33
41
  lines.push(` Created: ${issue.created_at}`);
34
42
  lines.push(` Updated: ${issue.updated_at}`);
@@ -41,6 +49,13 @@ function formatIssue(issue, detailed = false) {
41
49
  }
42
50
  return lines.join("\n");
43
51
  }
52
+ // create/update respond with the summary serializer, which omits attachments,
53
+ // so confirm what was uploaded from the request side.
54
+ function attachedNote(files) {
55
+ if (files.length === 0)
56
+ return "";
57
+ return `\n Attached: ${files.map((f) => f.filename).join(", ")}`;
58
+ }
44
59
  export function registerIssueTools(server) {
45
60
  server.tool("list_issues", "List issues for a team, with optional filters", {
46
61
  team_id: z.number().describe("Team ID"),
@@ -71,6 +86,27 @@ export function registerIssueTools(server) {
71
86
  content: [{ type: "text", text: formatIssue(issue, true) }],
72
87
  };
73
88
  });
89
+ server.tool("get_issue_by_identifier", "Get full details of an issue by its shortcode/identifier (e.g. 'CMZ-324'). The team is inferred from the identifier prefix, so no team_id is needed.", {
90
+ identifier: z
91
+ .string()
92
+ .describe("Issue shortcode, e.g. 'CMZ-324' (case-insensitive)"),
93
+ }, async ({ identifier }) => {
94
+ const normalized = identifier.trim().toUpperCase();
95
+ if (!/^[A-Z]+-\d+$/.test(normalized)) {
96
+ return {
97
+ content: [
98
+ {
99
+ type: "text",
100
+ text: `Error: '${identifier}' is not a valid issue identifier. Expected a shortcode like 'CMZ-324'.`,
101
+ },
102
+ ],
103
+ };
104
+ }
105
+ const issue = await apiRequest(`/api/v1/issues/by_identifier/${encodeURIComponent(normalized)}`);
106
+ return {
107
+ content: [{ type: "text", text: formatIssue(issue, true) }],
108
+ };
109
+ });
74
110
  server.tool("create_issue", "Create a new issue on a team. If lane_id is omitted, defaults to the Backlog lane.", {
75
111
  team_id: z.number().describe("Team ID"),
76
112
  title: z.string().describe("Issue title"),
@@ -90,7 +126,9 @@ export function registerIssueTools(server) {
90
126
  estimate: z.number().optional().describe("Estimate value"),
91
127
  milestone_id: z.number().optional().describe("Milestone ID"),
92
128
  parent_issue_id: z.number().optional().describe("Parent issue ID"),
93
- }, async ({ team_id, title, description, priority, lane_id, assignee_id, project_id, label_ids, due_date, estimate, milestone_id, parent_issue_id, }) => {
129
+ file_paths: filePathsSchema,
130
+ }, async ({ team_id, title, description, priority, lane_id, assignee_id, project_id, label_ids, due_date, estimate, milestone_id, parent_issue_id, file_paths, }) => {
131
+ const files = await readLocalFiles(file_paths ?? []);
94
132
  let resolvedLaneId = lane_id;
95
133
  if (!resolvedLaneId) {
96
134
  const lanes = await apiRequest(`/api/v1/teams/${team_id}/lanes`);
@@ -107,29 +145,27 @@ export function registerIssueTools(server) {
107
145
  }
108
146
  resolvedLaneId = backlog.id;
109
147
  }
110
- const issue = await apiRequest(`/api/v1/teams/${team_id}/issues`, {
111
- method: "POST",
112
- body: {
113
- issue: {
114
- title,
115
- description,
116
- priority: priority || "no_priority",
117
- lane_id: resolvedLaneId,
118
- assignee_id,
119
- project_id,
120
- label_ids,
121
- due_date,
122
- estimate,
123
- milestone_id,
124
- parent_issue_id,
125
- },
126
- },
127
- });
148
+ const fields = {
149
+ title,
150
+ description,
151
+ priority: priority || "no_priority",
152
+ lane_id: resolvedLaneId,
153
+ assignee_id,
154
+ project_id,
155
+ label_ids,
156
+ due_date,
157
+ estimate,
158
+ milestone_id,
159
+ parent_issue_id,
160
+ };
161
+ const issue = await apiRequest(`/api/v1/teams/${team_id}/issues`, files.length > 0
162
+ ? { method: "POST", form: buildMultipart("issue", fields, files) }
163
+ : { method: "POST", body: { issue: fields } });
128
164
  return {
129
165
  content: [
130
166
  {
131
167
  type: "text",
132
- text: `Issue created successfully:\n\n${formatIssue(issue, true)}`,
168
+ text: `Issue created successfully:\n\n${formatIssue(issue, true)}${attachedNote(files)}`,
133
169
  },
134
170
  ],
135
171
  };
@@ -146,7 +182,9 @@ export function registerIssueTools(server) {
146
182
  label_ids: z.array(z.number()).optional().describe("Set label IDs"),
147
183
  due_date: z.string().optional().describe("Due date in YYYY-MM-DD format"),
148
184
  estimate: z.number().optional().describe("Estimate value"),
149
- }, async ({ team_id, issue_id, title, description, priority, lane_id, assignee_id, project_id, label_ids, due_date, estimate, }) => {
185
+ file_paths: filePathsSchema,
186
+ }, async ({ team_id, issue_id, title, description, priority, lane_id, assignee_id, project_id, label_ids, due_date, estimate, file_paths, }) => {
187
+ const files = await readLocalFiles(file_paths ?? []);
150
188
  const fields = {};
151
189
  if (title !== undefined)
152
190
  fields.title = title;
@@ -166,15 +204,14 @@ export function registerIssueTools(server) {
166
204
  fields.due_date = due_date;
167
205
  if (estimate !== undefined)
168
206
  fields.estimate = estimate;
169
- const issue = await apiRequest(`/api/v1/teams/${team_id}/issues/${issue_id}`, {
170
- method: "PATCH",
171
- body: { issue: fields },
172
- });
207
+ const issue = await apiRequest(`/api/v1/teams/${team_id}/issues/${issue_id}`, files.length > 0
208
+ ? { method: "PATCH", form: buildMultipart("issue", fields, files) }
209
+ : { method: "PATCH", body: { issue: fields } });
173
210
  return {
174
211
  content: [
175
212
  {
176
213
  type: "text",
177
- text: `Issue updated successfully:\n\n${formatIssue(issue, true)}`,
214
+ text: `Issue updated successfully:\n\n${formatIssue(issue, true)}${attachedNote(files)}`,
178
215
  },
179
216
  ],
180
217
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@denvermullets/jait",
3
- "version": "1.2.0",
3
+ "version": "1.4.0",
4
4
  "description": "MCP server for Just Another Issue Tracker",
5
5
  "type": "module",
6
6
  "bin": {
@@ -11,18 +11,19 @@
11
11
  ],
12
12
  "scripts": {
13
13
  "build": "tsc",
14
+ "test": "yarn build && node --test \"test/**/*.test.mjs\"",
14
15
  "start": "node dist/index.js",
15
16
  "dev": "tsc --watch",
16
17
  "prepack": "yarn build",
17
18
  "prepublishOnly": "yarn build"
18
19
  },
19
20
  "dependencies": {
20
- "@modelcontextprotocol/sdk": "^1.29.0",
21
- "zod": "^4.3.6"
21
+ "@modelcontextprotocol/sdk": "^1.30.1",
22
+ "zod": "^4.6.5"
22
23
  },
23
24
  "devDependencies": {
24
- "@types/node": "^22.0.0",
25
- "typescript": "^5.7.0"
25
+ "@types/node": "^26.6.3",
26
+ "typescript": "^7.0.2"
26
27
  },
27
28
  "engines": {
28
29
  "node": ">=18.0.0"