@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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Goyo Corroto
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,133 @@
1
+ # mcp-mantis
2
+
3
+ [![Node.js](https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js&logoColor=white)](https://nodejs.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![MCP](https://img.shields.io/badge/MCP-stdio-5A45FF)](https://modelcontextprotocol.io/)
4
+
5
+ An MCP stdio server that gives an AI assistant direct access to a MantisBT tracker,
6
+ oriented to **issue resolvers**: read issues (with images), change status, resolve,
7
+ assign, comment and link — plus **local semantic search** over issues.
8
+
9
+ > **REST, not SOAP.** This server uses the MantisBT **REST API** (Mantis 2.27+), the supported and
10
+ > non-deprecated integration path. The legacy SOAP API is not used and does not need to be enabled.
11
+
12
+ ## Setup
13
+
14
+ Requires Node.js 22+ (uses the built-in global `fetch`).
15
+
16
+ ```bash
17
+ npm install
18
+ cp .env.example .env
19
+ ```
20
+
21
+ Then edit `.env`:
22
+
23
+ | Variable | Required | Notes |
24
+ | ------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
25
+ | `MANTIS_REST_BASE_URL` | yes | Must include `index.php` when URL rewriting is disabled on the host. |
26
+ | `MANTIS_TOKEN` | yes | API token from Mantis: **My Account → API Tokens → Create**. No username/password; the token is the `Authorization` header. |
27
+ | `MANTIS_READONLY` | no | `false` (default) enables write tools. Set `true` for read-only. A blank value keeps the default. |
28
+ | `MANTIS_SEARCH_ENABLED` | no | `true` (default) registers semantic search tools. Needs the optional `@huggingface/transformers`. |
29
+ | `MANTIS_SEARCH_MODEL` / `MANTIS_SEARCH_DIR` / `MANTIS_SEARCH_THREADS` | no | Embedding model, index directory, ONNX threads. |
30
+ | `MANTIS_TIMEOUT_MS`, `MANTIS_METADATA_TTL_MS`, `MANTIS_DEFAULT_PAGE_SIZE`, `MANTIS_MAX_PAGE_SIZE` | no | Tuning. |
31
+
32
+ ## Register with Claude Code
33
+
34
+ From npm (published package), no local checkout needed — the token is supplied here, never stored in the repo:
35
+
36
+ ```bash
37
+ claude mcp add mantis \
38
+ -e MANTIS_REST_BASE_URL=https://mantis.example.com/api/rest/index.php \
39
+ -e MANTIS_TOKEN=your-token-here \
40
+ -- npx -y @grec0/mcp-mantis
41
+ ```
42
+
43
+ Or from a local build:
44
+
45
+ ```bash
46
+ npm run build
47
+ claude mcp add mantis -- node /path/to/mcp-mantis/dist/mcp.js
48
+ ```
49
+
50
+ Equivalent `.mcp.json` (the `env` block is where `MANTIS_TOKEN` belongs):
51
+
52
+ ```json
53
+ {
54
+ "mcpServers": {
55
+ "mantis": {
56
+ "command": "npx",
57
+ "args": ["-y", "@grec0/mcp-mantis"],
58
+ "env": {
59
+ "MANTIS_REST_BASE_URL": "https://mantis.example.com/api/rest/index.php",
60
+ "MANTIS_TOKEN": "your-token-here",
61
+ "MANTIS_READONLY": "false"
62
+ }
63
+ }
64
+ }
65
+ }
66
+ ```
67
+
68
+ ## Tools
69
+
70
+ **Read**
71
+
72
+ | Tool | Purpose |
73
+ | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
74
+ | `mantis_whoami` | Authenticated user + accessible projects. |
75
+ | `mantis_list_projects` / `mantis_get_project` | Projects with versions, categories, custom fields. |
76
+ | `mantis_list_project_users` | Project members (valid handler names for assignment). |
77
+ | `mantis_list_issues` | Paginated issues, lightweight summary by default (use `mantis_get_issue` for full detail). Client-side filters: `status` (name or `"open"`), `assigned_to`, `reporter_id`, date range. |
78
+ | `mantis_get_issue` / `mantis_get_issues` | One issue (complete) / batch fetch by ids. |
79
+ | `mantis_get_issue_attachment` | Download an attachment; images come back viewable. |
80
+ | `mantis_get_enums` / `mantis_get_config` | Enumerations ({id,name,label}) / raw config options. |
81
+ | `mantis_list_filters` | Stored filters (feed a `filter_id` into `mantis_list_issues`). |
82
+
83
+ **Resolve / write** (registered when `MANTIS_READONLY=false`)
84
+
85
+ | Tool | Purpose |
86
+ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
87
+ | `mantis_update_issue` | Partial update: status, resolution, handler, priority, fields… Accepts localized/canonical enum names. Optional `note` and `dry_run`. |
88
+ | `mantis_resolve_issue` | Sets **both** status and resolution (defaults `resuelta` / `fixed`) + optional note. |
89
+ | `mantis_assign_issue` | Assign to a handler by login name (or id), optional status change + note. |
90
+ | `mantis_add_note` | Add a public/private note. |
91
+ | `mantis_add_relationship` / `mantis_remove_relationship` | Link issues (related, duplicate, blocks, depends…). |
92
+
93
+ **Semantic search** (registered when `MANTIS_SEARCH_ENABLED=true`)
94
+
95
+ | Tool | Purpose |
96
+ | ----------------------------- | ------------------------------------------------------------------------------------- |
97
+ | `mantis_rebuild_search_index` | Build/update the local vector index from issues (first run downloads the model). |
98
+ | `mantis_search_issues` | Natural-language search (multilingual). Optional `select`, `highlight`, date filters. |
99
+ | `mantis_search_index_status` | Index fill level and last sync. |
100
+
101
+ Enum names accept the instance's localized names _and_ the canonical English labels (e.g. `asignada`
102
+ or `confirmed`). `mantis_list_issues` `status="open"` uses the live `bug_resolved_status_threshold`.
103
+ Ad-hoc free-text search is not a server-side REST filter — use `mantis_search_issues` or a stored `filter_id`.
104
+
105
+ ## Commands
106
+
107
+ | Command | Purpose |
108
+ | --------------------------------------- | ------------------------------------------------------------ |
109
+ | `npm run dev:mcp` / `npm run start:mcp` | Run the MCP stdio server (reload / built). |
110
+ | `npm run build` | Compile TypeScript into `dist/`. |
111
+ | `npm run check` | Type-check, lint and format-check. |
112
+ | `npm run dev` | Express health server (`GET /health`, `GET /health/mantis`). |
113
+
114
+ ## Project structure
115
+
116
+ ```
117
+ src/
118
+ ├── config.ts # Validated environment configuration
119
+ ├── constants.ts # Enum aliases, relationship types
120
+ ├── date-filter.ts # Shared date-range filtering
121
+ ├── mantis.ts # MantisBT REST client (fetch, enum/handler resolution, caching)
122
+ ├── tools/ # meta, issues, notes, relationships, shared helpers
123
+ ├── search/ # embedder (Transformers.js), vector store, sync, search tools
124
+ ├── server.ts # Tool registration
125
+ ├── mcp.ts # MCP stdio executable
126
+ └── index.ts # Express health endpoints
127
+ ```
128
+
129
+ ## Security
130
+
131
+ `.env` is git-ignored (only `.env.example` is committed) — never commit the token. Write access is
132
+ scoped to the token owner's Mantis permissions; set `MANTIS_READONLY=true` to disable all mutations.
133
+ Health endpoints expose no credentials or user data. Run `npm run check` before committing.
package/dist/config.js ADDED
@@ -0,0 +1,95 @@
1
+ import { homedir } from 'node:os';
2
+ import { dirname, join } from 'node:path';
3
+ import { fileURLToPath } from 'node:url';
4
+ import { config as loadEnv } from 'dotenv';
5
+ // Load .env from the package root (dist/.. or src/..), so the server finds its
6
+ // configuration regardless of the working directory Claude Code launches it in.
7
+ // Variables already present in the environment (e.g. passed via `claude mcp add -e`)
8
+ // take precedence — dotenv does not override them.
9
+ loadEnv({ path: join(dirname(fileURLToPath(import.meta.url)), '..', '.env') });
10
+ function readPort(value) {
11
+ // A blank/whitespace-only value means "use the default", consistent with the
12
+ // other readers below (an empty string is not nullish, so `?? 3000` would not apply).
13
+ if (value === undefined || value.trim() === '')
14
+ return 3000;
15
+ const parsed = Number(value);
16
+ if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
17
+ throw new Error('PORT must be an integer between 1 and 65535.');
18
+ }
19
+ return parsed;
20
+ }
21
+ function readBaseUrl(value) {
22
+ const raw = (value ?? '').trim();
23
+ if (raw.length === 0) {
24
+ throw new Error('MANTIS_REST_BASE_URL is required, e.g. https://mantis.example.com/api/rest/index.php');
25
+ }
26
+ let url;
27
+ try {
28
+ url = new URL(raw);
29
+ }
30
+ catch {
31
+ throw new Error(`MANTIS_REST_BASE_URL is not a valid URL: ${raw}`);
32
+ }
33
+ if (url.protocol !== 'http:' && url.protocol !== 'https:') {
34
+ throw new Error('MANTIS_REST_BASE_URL must use http or https.');
35
+ }
36
+ // Normalise: drop any trailing slash so `${base}/issues` never double-slashes.
37
+ return raw.replace(/\/+$/, '');
38
+ }
39
+ function readBool(value, fallback) {
40
+ // A blank/whitespace-only value (e.g. `MANTIS_READONLY=` in .env) means
41
+ // "keep the default", not false — otherwise a blank line would silently
42
+ // flip the mode. Treat it the same as an unset variable.
43
+ const normalised = (value ?? '').trim().toLowerCase();
44
+ if (normalised === '')
45
+ return fallback;
46
+ if (['1', 'true', 'yes', 'on'].includes(normalised))
47
+ return true;
48
+ if (['0', 'false', 'no', 'off'].includes(normalised))
49
+ return false;
50
+ throw new Error(`Expected a boolean-like value but received "${value}".`);
51
+ }
52
+ function readPositiveInt(value, fallback, name) {
53
+ if (value === undefined || value.trim() === '')
54
+ return fallback;
55
+ const parsed = Number(value);
56
+ if (!Number.isInteger(parsed) || parsed < 1) {
57
+ throw new Error(`${name} must be a positive integer.`);
58
+ }
59
+ return parsed;
60
+ }
61
+ const defaultCacheDir = join(homedir(), '.cache', 'mcp-mantis');
62
+ export const config = {
63
+ host: process.env.HOST ?? '127.0.0.1',
64
+ port: readPort(process.env.PORT),
65
+ mantis: {
66
+ /** Full REST base up to and including `index.php` (needed when URL rewriting is disabled). */
67
+ baseUrl: readBaseUrl(process.env.MANTIS_REST_BASE_URL),
68
+ /** MantisBT API token (My Account -> API Tokens). Sent as the `Authorization` header. */
69
+ token: (process.env.MANTIS_TOKEN ?? '').trim(),
70
+ /**
71
+ * When true, write tools are not registered and the client refuses mutations.
72
+ * Defaults to false: this server is built for issue *resolvers* (status changes,
73
+ * notes, assignment), so write access is the primary use case.
74
+ */
75
+ readonly: readBool(process.env.MANTIS_READONLY, false),
76
+ /** Per-request timeout in milliseconds. */
77
+ timeoutMs: readPositiveInt(process.env.MANTIS_TIMEOUT_MS, 30_000, 'MANTIS_TIMEOUT_MS'),
78
+ /** Default page size for issue listings when the caller does not specify one. */
79
+ defaultPageSize: readPositiveInt(process.env.MANTIS_DEFAULT_PAGE_SIZE, 50, 'MANTIS_DEFAULT_PAGE_SIZE'),
80
+ /** Upper bound the list tool will accept for `page_size`. */
81
+ maxPageSize: readPositiveInt(process.env.MANTIS_MAX_PAGE_SIZE, 200, 'MANTIS_MAX_PAGE_SIZE'),
82
+ /** How long (ms) to cache metadata such as enums and the resolved-status threshold. */
83
+ metadataTtlMs: readPositiveInt(process.env.MANTIS_METADATA_TTL_MS, 300_000, 'MANTIS_METADATA_TTL_MS'),
84
+ },
85
+ search: {
86
+ /** Local semantic search over issues (Transformers.js). Disable with MANTIS_SEARCH_ENABLED=false. */
87
+ enabled: readBool(process.env.MANTIS_SEARCH_ENABLED, true),
88
+ /** Directory for the on-disk vector index. */
89
+ dir: process.env.MANTIS_SEARCH_DIR ?? join(defaultCacheDir, 'search'),
90
+ /** Embedding model (multilingual by default — issues are in Spanish). */
91
+ modelName: process.env.MANTIS_SEARCH_MODEL ?? 'Xenova/paraphrase-multilingual-MiniLM-L12-v2',
92
+ /** ONNX intra-op threads. */
93
+ numThreads: readPositiveInt(process.env.MANTIS_SEARCH_THREADS, 1, 'MANTIS_SEARCH_THREADS'),
94
+ },
95
+ };
@@ -0,0 +1,93 @@
1
+ // ---------------------------------------------------------------------------
2
+ // Relationship types
3
+ // The MantisBT REST API accepts numeric relationship type ids. These aliases let
4
+ // callers use readable names (add_relationship resolves them).
5
+ // ---------------------------------------------------------------------------
6
+ export const RELATIONSHIP_TYPES = {
7
+ DUPLICATE_OF: 0,
8
+ RELATED_TO: 1,
9
+ PARENT_OF: 2, // "depends on" — this issue depends on the target
10
+ CHILD_OF: 3, // "blocks" — this issue blocks the target
11
+ HAS_DUPLICATE: 4,
12
+ };
13
+ export const RELATIONSHIP_NAME_TO_ID = {
14
+ duplicate_of: RELATIONSHIP_TYPES.DUPLICATE_OF,
15
+ 'duplicate-of': RELATIONSHIP_TYPES.DUPLICATE_OF,
16
+ duplicateof: RELATIONSHIP_TYPES.DUPLICATE_OF,
17
+ related_to: RELATIONSHIP_TYPES.RELATED_TO,
18
+ 'related-to': RELATIONSHIP_TYPES.RELATED_TO,
19
+ relatedto: RELATIONSHIP_TYPES.RELATED_TO,
20
+ parent_of: RELATIONSHIP_TYPES.PARENT_OF,
21
+ 'parent-of': RELATIONSHIP_TYPES.PARENT_OF,
22
+ parentof: RELATIONSHIP_TYPES.PARENT_OF,
23
+ depends_on: RELATIONSHIP_TYPES.PARENT_OF,
24
+ 'depends-on': RELATIONSHIP_TYPES.PARENT_OF,
25
+ dependson: RELATIONSHIP_TYPES.PARENT_OF,
26
+ child_of: RELATIONSHIP_TYPES.CHILD_OF,
27
+ 'child-of': RELATIONSHIP_TYPES.CHILD_OF,
28
+ childof: RELATIONSHIP_TYPES.CHILD_OF,
29
+ blocks: RELATIONSHIP_TYPES.CHILD_OF,
30
+ has_duplicate: RELATIONSHIP_TYPES.HAS_DUPLICATE,
31
+ 'has-duplicate': RELATIONSHIP_TYPES.HAS_DUPLICATE,
32
+ hasduplicate: RELATIONSHIP_TYPES.HAS_DUPLICATE,
33
+ };
34
+ // ---------------------------------------------------------------------------
35
+ // Enum groups exposed by MantisBT config as `<group>_enum_string`.
36
+ // The REST API returns each already parsed as [{ id, name, label }].
37
+ // ---------------------------------------------------------------------------
38
+ export const ENUM_GROUPS = [
39
+ 'status',
40
+ 'priority',
41
+ 'severity',
42
+ 'resolution',
43
+ 'reproducibility',
44
+ ];
45
+ export const ENUM_CONFIG_OPTIONS = ENUM_GROUPS.map((g) => `${g}_enum_string`);
46
+ // ---------------------------------------------------------------------------
47
+ // Canonical English enum names for a standard MantisBT install. Used only as a
48
+ // FALLBACK alias when the live enum lookup (by localized name or label) misses —
49
+ // this instance is customized (Spanish names, extra statuses), so live enums win.
50
+ // Default resolved-status threshold (bug_resolved_status_threshold) is read live.
51
+ // ---------------------------------------------------------------------------
52
+ export const DEFAULT_RESOLVED_STATUS_THRESHOLD = 90;
53
+ export const CANONICAL_ENUM_NAMES = {
54
+ severity: {
55
+ 10: 'feature',
56
+ 20: 'trivial',
57
+ 30: 'text',
58
+ 40: 'tweak',
59
+ 50: 'minor',
60
+ 60: 'major',
61
+ 70: 'crash',
62
+ 80: 'block',
63
+ },
64
+ status: {
65
+ 10: 'new',
66
+ 20: 'feedback',
67
+ 30: 'acknowledged',
68
+ 40: 'confirmed',
69
+ 50: 'assigned',
70
+ 80: 'resolved',
71
+ 90: 'closed',
72
+ },
73
+ priority: { 10: 'none', 20: 'low', 30: 'normal', 40: 'high', 50: 'urgent', 60: 'immediate' },
74
+ resolution: {
75
+ 10: 'open',
76
+ 20: 'fixed',
77
+ 30: 'reopened',
78
+ 40: 'unable to duplicate',
79
+ 50: 'not fixable',
80
+ 60: 'duplicate',
81
+ 70: 'no change required',
82
+ 80: 'suspended',
83
+ 90: 'wont fix',
84
+ },
85
+ reproducibility: {
86
+ 10: 'always',
87
+ 30: 'sometimes',
88
+ 50: 'random',
89
+ 70: 'have not tried',
90
+ 90: 'unable to reproduce',
91
+ 100: 'N/A',
92
+ },
93
+ };
@@ -0,0 +1,58 @@
1
+ import { z } from 'zod';
2
+ /** Reusable Zod fragment — spread into any tool's inputSchema. */
3
+ export const dateFilterSchema = {
4
+ updated_after: z
5
+ .string()
6
+ .optional()
7
+ .describe('ISO-8601 timestamp — only issues updated strictly after this. Example: "2026-03-25T00:00:00Z"'),
8
+ updated_before: z
9
+ .string()
10
+ .optional()
11
+ .describe('ISO-8601 timestamp — only issues updated strictly before this.'),
12
+ created_after: z
13
+ .string()
14
+ .optional()
15
+ .describe('ISO-8601 timestamp — only issues created strictly after this.'),
16
+ created_before: z
17
+ .string()
18
+ .optional()
19
+ .describe('ISO-8601 timestamp — only issues created strictly before this.'),
20
+ };
21
+ /**
22
+ * True if the item's dates satisfy every active constraint (all exclusive).
23
+ * If a constraint is set but the item lacks that date field, returns false.
24
+ */
25
+ export function matchesDateFilter(item, filter) {
26
+ const { updated_after, updated_before, created_after, created_before } = filter;
27
+ if (updated_after !== undefined) {
28
+ if (!item.updated_at)
29
+ return false;
30
+ if (new Date(item.updated_at) <= new Date(updated_after))
31
+ return false;
32
+ }
33
+ if (updated_before !== undefined) {
34
+ if (!item.updated_at)
35
+ return false;
36
+ if (new Date(item.updated_at) >= new Date(updated_before))
37
+ return false;
38
+ }
39
+ if (created_after !== undefined) {
40
+ if (!item.created_at)
41
+ return false;
42
+ if (new Date(item.created_at) <= new Date(created_after))
43
+ return false;
44
+ }
45
+ if (created_before !== undefined) {
46
+ if (!item.created_at)
47
+ return false;
48
+ if (new Date(item.created_at) >= new Date(created_before))
49
+ return false;
50
+ }
51
+ return true;
52
+ }
53
+ export function hasDateFilter(filter) {
54
+ return (filter.updated_after !== undefined ||
55
+ filter.updated_before !== undefined ||
56
+ filter.created_after !== undefined ||
57
+ filter.created_before !== undefined);
58
+ }
package/dist/index.js ADDED
@@ -0,0 +1,30 @@
1
+ import express from 'express';
2
+ import { config } from './config.js';
3
+ import { MantisRestClient } from './mantis.js';
4
+ const app = express();
5
+ const client = new MantisRestClient(config.mantis);
6
+ app.disable('x-powered-by');
7
+ app.use(express.json({ limit: '100kb' }));
8
+ // Liveness only — deliberately does not expose the base URL or credentials.
9
+ app.get('/health', (_request, response) => {
10
+ const status = client.getStatus();
11
+ response.status(200).json({
12
+ status: 'ok',
13
+ readonly: status.readonly,
14
+ tokenConfigured: status.tokenConfigured,
15
+ });
16
+ });
17
+ // Reaches Mantis to validate the token/connectivity. Returns an opaque result —
18
+ // no user profile or internal URL is disclosed to unauthenticated callers.
19
+ app.get('/health/mantis', async (_request, response) => {
20
+ try {
21
+ await client.getMe();
22
+ response.status(200).json({ status: 'ok' });
23
+ }
24
+ catch {
25
+ response.status(502).json({ status: 'error' });
26
+ }
27
+ });
28
+ app.listen(config.port, config.host, () => {
29
+ console.info(`HTTP status endpoint listening on http://${config.host}:${config.port}/health`);
30
+ });