@grec0/mcp-mantis 0.3.2

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.
@@ -0,0 +1,51 @@
1
+ import { z } from 'zod';
2
+ import { ENUM_CONFIG_OPTIONS } from '../constants.js';
3
+ import { handler, jsonResult } from './shared.js';
4
+ const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true };
5
+ export function registerMetaTools(server, client) {
6
+ server.registerTool('mantis_whoami', {
7
+ title: 'Whoami',
8
+ description: 'Returns the authenticated Mantis user (id, name, access level, accessible projects). Use it to verify the API token works.',
9
+ inputSchema: {},
10
+ annotations: READ_ONLY,
11
+ }, handler(async () => jsonResult(await client.getMe())));
12
+ server.registerTool('mantis_list_projects', {
13
+ title: 'List projects',
14
+ description: 'Lists all projects accessible to the token owner, including nested versions, categories and custom field definitions.',
15
+ inputSchema: {},
16
+ annotations: READ_ONLY,
17
+ }, handler(async () => jsonResult(await client.getProjects())));
18
+ server.registerTool('mantis_get_project', {
19
+ title: 'Get project',
20
+ description: 'Returns a single project by id with its versions, categories and custom fields.',
21
+ inputSchema: { project_id: z.number().int().positive() },
22
+ annotations: READ_ONLY,
23
+ }, handler(async ({ project_id }) => jsonResult(await client.getProject(project_id))));
24
+ server.registerTool('mantis_list_project_users', {
25
+ title: 'List project members',
26
+ description: 'Lists the members of a project (id, login name, access level). Use it to find valid handler names for assignment.',
27
+ inputSchema: { project_id: z.number().int().positive() },
28
+ annotations: READ_ONLY,
29
+ }, handler(async ({ project_id }) => jsonResult(await client.getProjectUsers(project_id))));
30
+ server.registerTool('mantis_get_enums', {
31
+ title: 'Get enumerations',
32
+ description: 'Returns the common Mantis enumerations (status, priority, severity, resolution, reproducibility, etc.) as {id,name,label} lists. ' +
33
+ 'This instance is localized (Spanish names) — use it to map issue status/priority codes and to learn valid names for status changes.',
34
+ inputSchema: {},
35
+ annotations: READ_ONLY,
36
+ }, handler(async () => jsonResult(await client.getConfig([...ENUM_CONFIG_OPTIONS]))));
37
+ server.registerTool('mantis_get_config', {
38
+ title: 'Get config options',
39
+ description: 'Reads arbitrary Mantis configuration options exposed to the REST API, e.g. ["status_enum_string","bug_resolved_status_threshold"].',
40
+ inputSchema: {
41
+ options: z.array(z.string().min(1)).min(1).describe('Config option names to read.'),
42
+ },
43
+ annotations: READ_ONLY,
44
+ }, handler(async ({ options }) => jsonResult(await client.getConfig(options))));
45
+ server.registerTool('mantis_list_filters', {
46
+ title: 'List stored filters',
47
+ description: 'Lists stored filters, optionally scoped to a project. Pass a filter id to mantis_list_issues to run it.',
48
+ inputSchema: { project_id: z.number().int().positive().optional() },
49
+ annotations: READ_ONLY,
50
+ }, handler(async ({ project_id }) => jsonResult(await client.listFilters(project_id))));
51
+ }
@@ -0,0 +1,29 @@
1
+ import { z } from 'zod';
2
+ import { handler, jsonResult } from './shared.js';
3
+ /**
4
+ * Posts a note to an issue and returns the created note (enriched with view_url
5
+ * when the id is known). Shared by add_note, update_issue and resolve_issue.
6
+ */
7
+ export async function postNote(client, issueId, text, viewState) {
8
+ const body = { text, view_state: { name: viewState } };
9
+ const raw = await client.post(`/issues/${issueId}/notes`, body);
10
+ const note = (raw.note ?? raw);
11
+ const noteId = note.id;
12
+ if (typeof noteId === 'number') {
13
+ return { ...note, view_url: client.buildNoteViewUrl(issueId, noteId) };
14
+ }
15
+ return note;
16
+ }
17
+ export function registerNoteTools(server, client) {
18
+ server.registerTool('mantis_add_note', {
19
+ title: 'Add note to issue',
20
+ description: 'Adds a note (comment) to an issue. Use private=true for an internal note visible only to ' +
21
+ 'developers/managers. To change a field and comment in one call, use mantis_update_issue with its "note" parameter instead.',
22
+ inputSchema: {
23
+ issue_id: z.number().int().positive().describe('Numeric issue id.'),
24
+ text: z.string().min(1).describe('Note body (plain text or Markdown).'),
25
+ private: z.boolean().optional().describe('Create as a private note (default false).'),
26
+ },
27
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
28
+ }, handler(async ({ issue_id, text, private: priv }) => jsonResult(await postNote(client, issue_id, text, priv ? 'private' : 'public'))));
29
+ }
@@ -0,0 +1,49 @@
1
+ import { z } from 'zod';
2
+ import { RELATIONSHIP_NAME_TO_ID } from '../constants.js';
3
+ import { MantisApiError } from '../mantis.js';
4
+ import { handler, jsonResult } from './shared.js';
5
+ const WRITE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false };
6
+ const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, idempotentHint: true };
7
+ function resolveRelationshipTypeId(value) {
8
+ if (typeof value === 'number' && Number.isInteger(value))
9
+ return value;
10
+ const asString = String(value).trim();
11
+ if (/^\d+$/.test(asString))
12
+ return Number(asString);
13
+ const id = RELATIONSHIP_NAME_TO_ID[asString.toLowerCase().replace(/\s+/g, '_')];
14
+ if (id === undefined) {
15
+ const valid = [...new Set(Object.keys(RELATIONSHIP_NAME_TO_ID))].join(', ');
16
+ throw new MantisApiError(400, `Invalid relationship type "${asString}". Valid: ${valid}.`);
17
+ }
18
+ return id;
19
+ }
20
+ export function registerRelationshipTools(server, client) {
21
+ server.registerTool('mantis_add_relationship', {
22
+ title: 'Add issue relationship',
23
+ description: 'Links two issues. type is one of: related_to, duplicate_of, has_duplicate, depends_on (parent_of), blocks (child_of) — or a numeric type id.',
24
+ inputSchema: {
25
+ issue_id: z.number().int().positive().describe('Source issue id.'),
26
+ target_id: z.number().int().positive().describe('Target (other) issue id.'),
27
+ type: z
28
+ .union([z.string(), z.number().int().nonnegative()])
29
+ .describe('Relationship type name or numeric id.'),
30
+ },
31
+ annotations: WRITE,
32
+ }, handler(async ({ issue_id, target_id, type }) => {
33
+ const typeId = resolveRelationshipTypeId(type);
34
+ const body = { issue: { id: target_id }, type: { id: typeId } };
35
+ return jsonResult(await client.post(`/issues/${issue_id}/relationships`, body));
36
+ }));
37
+ server.registerTool('mantis_remove_relationship', {
38
+ title: 'Remove issue relationship',
39
+ description: 'Removes a relationship from an issue by relationship id.',
40
+ inputSchema: {
41
+ issue_id: z.number().int().positive().describe('Issue id owning the relationship.'),
42
+ relationship_id: z.number().int().positive().describe('Relationship id to delete.'),
43
+ },
44
+ annotations: DESTRUCTIVE,
45
+ }, handler(async ({ issue_id, relationship_id }) => {
46
+ await client.delete(`/issues/${issue_id}/relationships/${relationship_id}`);
47
+ return jsonResult({ deleted: true, issue_id, relationship_id });
48
+ }));
49
+ }
@@ -0,0 +1,72 @@
1
+ import { z } from 'zod';
2
+ import { MantisApiError } from '../mantis.js';
3
+ /** MantisBT reference: at least one of id or name must be provided. */
4
+ export const ref = z
5
+ .object({ id: z.number().int().optional(), name: z.string().optional() })
6
+ .refine((o) => o.id !== undefined || o.name !== undefined, {
7
+ message: "At least one of 'id' or 'name' must be provided",
8
+ });
9
+ export const customFieldEntry = z.object({
10
+ field: ref.describe('Custom field reference: { id } or { name }'),
11
+ value: z.coerce.string().describe('Field value as string'),
12
+ });
13
+ export function jsonResult(data) {
14
+ return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
15
+ }
16
+ export function errorResult(error) {
17
+ let text;
18
+ if (error instanceof MantisApiError) {
19
+ const code = error.code === undefined ? '' : ` code=${error.code}`;
20
+ text = `Mantis error (HTTP ${error.status}${code}): ${error.message}`;
21
+ }
22
+ else if (error instanceof Error) {
23
+ text = `Error: ${error.message}`;
24
+ }
25
+ else {
26
+ text = `Error: ${String(error)}`;
27
+ }
28
+ return { content: [{ type: 'text', text }], isError: true };
29
+ }
30
+ /** Wraps a handler so thrown errors become clean, model-readable tool errors. */
31
+ export function handler(fn) {
32
+ return async (args) => {
33
+ try {
34
+ return await fn(args);
35
+ }
36
+ catch (error) {
37
+ return errorResult(error);
38
+ }
39
+ };
40
+ }
41
+ /** Adds view_url to an issue and each of its notes so humans can jump to the UI. */
42
+ export function enrichIssue(client, issue, fallbackId) {
43
+ const id = issue.id ?? fallbackId;
44
+ if (id === undefined)
45
+ return issue;
46
+ const enriched = { ...issue, view_url: client.buildIssueViewUrl(id) };
47
+ if (Array.isArray(issue.notes)) {
48
+ enriched.notes = issue.notes.map((note) => note.id === undefined ? note : { ...note, view_url: client.buildNoteViewUrl(id, note.id) });
49
+ }
50
+ return enriched;
51
+ }
52
+ /** Extracts the single issue object from a `{ issues: [...] }` REST response. */
53
+ export function unwrapIssue(result, fallbackId) {
54
+ const record = (result ?? {});
55
+ const issue = record.issues?.[0] ?? record.issue ?? result;
56
+ if (issue.id === undefined && fallbackId !== undefined)
57
+ issue.id = fallbackId;
58
+ return issue;
59
+ }
60
+ /** Worker-pool: run `fn` over items with at most `concurrency` in flight at once. */
61
+ export async function runWithConcurrency(items, concurrency, fn) {
62
+ const results = new Array(items.length);
63
+ let next = 0;
64
+ async function worker() {
65
+ while (next < items.length) {
66
+ const i = next++;
67
+ results[i] = await fn(items[i], i);
68
+ }
69
+ }
70
+ await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => worker()));
71
+ return results;
72
+ }
package/package.json ADDED
@@ -0,0 +1,79 @@
1
+ {
2
+ "name": "@grec0/mcp-mantis",
3
+ "version": "0.3.2",
4
+ "description": "A TypeScript MCP stdio server for the MantisBT REST API: read, resolve, comment on issues, plus local semantic search.",
5
+ "license": "MIT",
6
+ "author": "@grec0",
7
+ "homepage": "https://github.com/gcorroto/mcp-mantis",
8
+ "bugs": "https://github.com/gcorroto/mcp-mantis/issues",
9
+ "repository": {
10
+ "type": "git",
11
+ "url": "git+https://github.com/gcorroto/mcp-mantis.git"
12
+ },
13
+ "keywords": [
14
+ "mcp",
15
+ "model-context-protocol",
16
+ "mantis",
17
+ "mantisbt",
18
+ "bugtracker",
19
+ "issue-tracker",
20
+ "rest"
21
+ ],
22
+ "type": "module",
23
+ "main": "dist/index.js",
24
+ "bin": {
25
+ "mcp-mantis": "dist/mcp.js"
26
+ },
27
+ "files": [
28
+ "dist/**/*",
29
+ "README.md",
30
+ "LICENSE"
31
+ ],
32
+ "publishConfig": {
33
+ "registry": "https://registry.npmjs.org/",
34
+ "access": "public"
35
+ },
36
+ "engines": {
37
+ "node": ">=22"
38
+ },
39
+ "scripts": {
40
+ "dev": "tsx watch src/index.ts",
41
+ "dev:mcp": "tsx watch src/mcp.ts",
42
+ "start": "node dist/index.js",
43
+ "start:mcp": "node dist/mcp.js",
44
+ "build": "tsc -p tsconfig.json",
45
+ "typecheck": "tsc --noEmit",
46
+ "lint": "eslint src --max-warnings=0",
47
+ "format": "prettier --write .",
48
+ "format:check": "prettier --check .",
49
+ "test": "npm run build && node --test",
50
+ "security": "npm audit --omit=dev",
51
+ "check": "npm run typecheck && npm run lint && npm run format:check",
52
+ "version:patch": "npm version patch --no-git-tag-version",
53
+ "version:minor": "npm version minor --no-git-tag-version",
54
+ "version:major": "npm version major --no-git-tag-version",
55
+ "prerelease": "npm run build && npm test",
56
+ "release:patch": "npm run prerelease && npm version patch -m \"chore: release v%s\" && npm publish && git push --follow-tags",
57
+ "release:minor": "npm run prerelease && npm version minor -m \"chore: release v%s\" && npm publish && git push --follow-tags",
58
+ "release:major": "npm run prerelease && npm version major -m \"chore: release v%s\" && npm publish && git push --follow-tags"
59
+ },
60
+ "dependencies": {
61
+ "@modelcontextprotocol/sdk": "^1.17.4",
62
+ "dotenv": "^16.6.1",
63
+ "express": "5.1.0",
64
+ "zod": "^3.25.76"
65
+ },
66
+ "devDependencies": {
67
+ "@eslint/js": "^9.30.1",
68
+ "@types/express": "^5.0.3",
69
+ "@types/node": "^22.15.32",
70
+ "eslint": "^9.30.1",
71
+ "prettier": "^3.6.2",
72
+ "tsx": "^4.19.4",
73
+ "typescript": "^5.8.3",
74
+ "typescript-eslint": "^8.35.0"
75
+ },
76
+ "optionalDependencies": {
77
+ "@huggingface/transformers": "^3.8.1"
78
+ }
79
+ }