Skip to content
Back to search

mantisbt-mcp-Unofficial

A simple, unofficial MCP (Model Context Protocol) implementation for Mantis Bug Tracker, built in a straightforward manner with a connection to the Mantis API.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/coelho-coie--mantisbt-mcp-unofficial/badge.svg)](/listings/coelho-coie--mantisbt-mcp-unofficial)

HTML

<a href="/listings/coelho-coie--mantisbt-mcp-unofficial"><img src="/api/listings/coelho-coie--mantisbt-mcp-unofficial/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone <repository-url> Mantis-MCP
cd Mantis-MCP
npm install
npm run build
npm test

Create a `.env` file from the template:

cp .env.example .env

Then set `MANTIS_BASE_URL` and `MANTIS_API_TOKEN`. Connect the server to your MCP client:

{
  "mcpServers": {
    "mantisbt": {
      "command": "node",
      "args": ["/absolute/path/to/Mantis-MCP/dist/index.js"],
      "env": {
        "MANTIS_BASE_URL": "https://mantis.example.com",
        "MANTIS_API_TOKEN": "your_token_here"
      }
    }
  }
}

Restart the client and run `check_mantis_connection` to confirm the setup.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 417 lines
  1. # MantisBT MCP Server
  2. A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that connects AI assistants to [MantisBT](https://mantisbt.org/), the open-source bug tracker. It exposes 25 tools covering the MantisBT REST API, a context-aggregation tool for an assignee's open work, and a local vector store that powers semantic search and engineering efficiency analytics.
  3. ## Features
  4. - **Full REST coverage.** Issues, notes, time tracking, relationships, tags, attachments, monitoring, projects, versions, filters, users, and server configuration.
  5. - **LLM-ready context.** `get_my_unresolved_assigned_context` gathers every unresolved issue assigned to a user, including notes, history, and custom fields, and summarizes them by project, priority, and status. Binary attachments are excluded and can be downloaded on demand.
  6. - **Works around API limits.** MantisBT's REST API cannot filter by assignee and status together. The server combines native filters with a bounded paginated scan and client-side filtering.
  7. - **Deployment-friendly URLs.** Accepts the site root, `/api/rest`, or `/api/rest/index.php`, and falls back automatically on servers without `mod_rewrite`.
  8. - **Local semantic search.** Issues are embedded into 256-dimension vectors on your machine (no model download, no network), stored in one JSON file, and searched by cosine similarity. An OpenAI-compatible embedding endpoint can be used instead.
  9. - **Engineering efficiency analytics.** Computes throughput, lead time (mean, P50, P90), reopen rate, assignment ping-pong, stagnant and overdue work, per-assignee breakdown, recurring semantic clusters of problems, and a deterministic 0–100 efficiency score with diagnostics.
  10. ## About the vector store (optional)
  11. The vector store is a local index of your MantisBT issues. Every other tool works without it.
  12. **What it is for**
  13. - **Semantic search** (`search_vector_issues`): describe a problem and get the most similar issues by cosine similarity. Useful for finding duplicates and earlier bugs with the same cause, without scanning the API on every question.
  14. - **Recurring-problem clusters** (`analyze_project_efficiency`): groups similar issues, such as several "payment timeout" reports, to show where the team repeats work. The same report adds throughput, lead time (mean, P50, P90), reopen rate, assignment ping-pong, stagnant and overdue work, and a 0-100 score. Most of those metrics are plain calculations on MantisBT data; only the clustering and search use similarity.
  15. - **Offline and fast:** vectors live in one local JSON file, with no model download and no network. Fill it with `sync_issues_to_vector_store`.
  16. **Limits**
  17. - The default embedder hashes words and character trigrams. It matches shared words and patterns, not meaning, so "slow" and "lag" may not match. An OpenAI-compatible embedding endpoint can replace it, at the cost of sending issue text to a third party.
  18. - The file is loaded fully into memory. It suits thousands of issues, not millions.
  19. - It contains issue text, so treat it as confidential. It is git-ignored and written with owner-only permissions.
  20. - Changing the embedding mode requires running `sync_issues_to_vector_store` again.
  21. ## Requirements
  22. - Node.js 18 or later (uses the global `fetch`)
  23. - A MantisBT instance with the REST API enabled
  24. - A MantisBT API token for an account with the permissions you need
  25. ## Quick Start
  26. ```bash
  27. git clone <repository-url> Mantis-MCP
  28. cd Mantis-MCP
  29. npm install
  30. npm run build
  31. npm test
  32. ```
  33. Create a `.env` file from the template:
  34. ```bash
  35. cp .env.example .env
  36. ```
  37. Then set `MANTIS_BASE_URL` and `MANTIS_API_TOKEN`. Connect the server to your MCP client:
  38. ```json
  39. {
  40. "mcpServers": {
  41. "mantisbt": {
  42. "command": "node",
  43. "args": ["/absolute/path/to/Mantis-MCP/dist/index.js"],
  44. "env": {
  45. "MANTIS_BASE_URL": "https://mantis.example.com",
  46. "MANTIS_API_TOKEN": "your_token_here"
  47. }
  48. }
  49. }
  50. }
  51. ```
  52. Restart the client and run `check_mantis_connection` to confirm the setup.
  53. ## Installation Tutorial for Agents
  54. This section is written for an AI agent (for example, a coding assistant) that installs the server on behalf of a user. Run each step in order. After each step, check the stated expected result before continuing. If a check fails, stop and report the output to the user. Do not skip steps or invent values.
  55. ### Step 1: Check prerequisites
  56. Run:
  57. ```bash
  58. node -v
  59. npm -v
  60. ```
  61. Expected: Node.js major version 18 or higher. npm is installed with Node.js.
  62. If Node.js is missing or older than 18, stop and ask the user to install Node.js 18 or later. Do not install it silently.
  63. ### Step 2: Get the code
  64. If the repository is not already on disk:
  65. ```bash
  66. git clone <repository-url> Mantis-MCP
  67. cd Mantis-MCP
  68. ```
  69. If it is already on disk, change into its directory. The directory must contain `package.json` and `src/`.
  70. ### Step 3: Install dependencies
  71. ```bash
  72. npm install
  73. ```
  74. Expected: the command exits with code 0. Dependencies are `@modelcontextprotocol/sdk` and `zod`. Development dependencies are `typescript` and `@types/node`.
  75. ### Step 4: Build
  76. ```bash
  77. npm run build
  78. ```
  79. Expected: the command exits with code 0 and creates `dist/index.js`. Verify the file exists before continuing.
  80. ### Step 5: Run the tests
  81. ```bash
  82. npm test
  83. ```
  84. Expected output includes `# pass 4` and `# fail 0`. The tests do not contact MantisBT, so they pass without credentials. If any test fails, stop and report the failing test name and its output.
  85. ### Step 6: Create the configuration file
  86. Copy the template:
  87. ```bash
  88. cp .env.example .env
  89. ```
  90. On Windows PowerShell, use `Copy-Item .env.example .env`.
  91. Then ask the user for two values. Do not invent them:
  92. | Variable | What to ask the user for |
  93. |----------|--------------------------|
  94. | `MANTIS_BASE_URL` | The MantisBT site URL, for example `https://mantis.example.com`. |
  95. | `MANTIS_API_TOKEN` | An API token created in MantisBT under the user's account settings. |
  96. Edit `.env` and replace the two placeholder values. Leave the other variables at their defaults unless the user asks for a change. Never print the token in chat output, and never commit `.env`.
  97. ### Step 7: Register the server in the MCP client
  98. Use the client's own MCP configuration. The entry must start the compiled server with Node.js. Use an absolute path to `dist/index.js`:
  99. ```json
  100. {
  101. "mcpServers": {
  102. "mantisbt": {
  103. "command": "node",
  104. "args": ["<absolute-path-to-repo>/dist/index.js"],
  105. "env": {
  106. "MANTIS_BASE_URL": "<value from .env>",
  107. "MANTIS_API_TOKEN": "<value from .env>"
  108. }
  109. }
  110. }
  111. }
  112. ```
  113. Replace `<absolute-path-to-repo>` with the full path to the repository on this machine. Replace the two `<value from .env>` placeholders with the actual values. Where the client accepts it, the `env` block can be omitted if the server reads `.env` from the repository root (not from the working directory). The server does this automatically.
  114. Where the config file lives depends on the client. Look up the client's documentation for MCP server configuration instead of guessing a path. Save the change, then restart or reload the client so it starts the server.
  115. ### Step 8: Verify the connection
  116. From the MCP client, call the tool `check_mantis_connection` with no arguments.
  117. Expected: the result reports a successful connection and the authenticated user. If the result has `isError: true`, use the troubleshooting table below. Report the error text to the user.
  118. Then call `get_current_user`. Expected: the profile of the token's user. This confirms the token works for user-specific endpoints.
  119. ### Step 9 (optional): Build the vector index
  120. Only do this if the user wants semantic search or efficiency analytics:
  121. 1. Call `sync_issues_to_vector_store` with `max_pages: 2` to test on a small set.
  122. 2. If that succeeds, the index can be grown with larger `max_pages` values.
  123. The index is written to `.mantis-vector-store.json` in the repository directory, or to the path in `MANTIS_VECTOR_DB_PATH`.
  124. ### Troubleshooting
  125. | Symptom | Check | Fix |
  126. |---------|-------|-----|
  127. | `npm install` fails | Node.js and npm versions, network access | Upgrade Node.js to 18 or later. Retry. |
  128. | `npm run build` fails | Output of `tsc` | Report the TypeScript error. Do not edit source files to make it pass without the user's approval. |
  129. | `Set MANTIS_BASE_URL and MANTIS_API_TOKEN ...` | `.env` exists and has real values; client `env` block | Fix the values in `.env` or the client `env` block. |
  130. | `HTTP 401` | Token value | Ask the user to create a new token in MantisBT and update it. |
  131. | `HTTP 404` on every call | `MANTIS_BASE_URL` value | The server already tries `/api/rest` and then `/api/rest/index.php`. Confirm the site URL is correct and that the REST API is enabled. |
  132. | Client shows no tools | Path in client config is absolute and correct; client was restarted | Fix the path, then restart the client. |
  133. | `node: command not found` in the client | `node` is not on the client's PATH | Put the full path to the `node` executable in `command`. |
  134. ### Installation checklist
  135. - [ ] Node.js 18 or later is installed
  136. - [ ] `npm install` exits with code 0
  137. - [ ] `npm run build` exits with code 0 and `dist/index.js` exists
  138. - [ ] `npm test` reports 4 passing tests
  139. - [ ] `.env` exists with real `MANTIS_BASE_URL` and `MANTIS_API_TOKEN`
  140. - [ ] The MCP client config points to the absolute path of `dist/index.js`
  141. - [ ] The client was restarted
  142. - [ ] `check_mantis_connection` succeeds
  143. ## Tools at a Glance
  144. | Group | Tools |
  145. |-------|-------|
  146. | Context for LLMs | `get_my_unresolved_assigned_context` |
  147. | Vector store and analytics | `sync_issues_to_vector_store`, `search_vector_issues`, `analyze_project_efficiency` |
  148. | Issues | `get_issue_full_context`, `list_issues`, `create_issue`, `update_issue`, `delete_issue` |
  149. | Notes and time tracking | `add_issue_note`, `delete_issue_note` |
  150. | Relationships, tags, attachments, monitoring | `add_issue_relationship`, `delete_issue_relationship`, `get_issue_attachment`, `add_issue_attachment`, `attach_issue_tags`, `detach_issue_tag`, `monitor_issue` |
  151. | Projects, versions, filters, users, settings | `check_mantis_connection`, `list_projects`, `get_project`, `create_project_version`, `list_filters`, `get_current_user`, `get_mantis_config` |
  152. Parameters and examples for every tool are in [docs/TOOLS.md](docs/TOOLS.md).
  153. ## Tutorial for LLMs
  154. This section is written for the AI assistant that calls these tools. Follow it to pick the right tool, call it with valid arguments, and report results accurately.
  155. ### 1. Ground rules
  156. - **Check the connection first** when a call fails or when you are unsure the server is configured. Call `check_mantis_connection`. If it returns an error, report the error text to the user. Do not guess a fix.
  157. - **Use IDs, not names, in write calls.** `issue_id`, `project_id`, `handler_id`, and `user_id` are integers. Look them up with `list_projects`, `get_current_user`, or `list_issues` first.
  158. - **Prefer the narrowest tool.** Use `get_issue_full_context` for one issue, not `list_issues` followed by many reads.
  159. - **Keep payloads small.** Download attachments only when the content is needed, with `get_issue_attachment`.
  160. - **Treat errors as data.** A result with `isError: true` contains `{"error": "..."}`. Quote the message to the user and stop that branch. Do not retry the same call unchanged.
  161. - **Confirm before destructive actions.** `delete_issue` and `delete_issue_note` cannot be undone. Ask the user first unless they clearly asked for the deletion.
  162. ### 2. Choose a tool by intent
  163. | The user asks for... | Call |
  164. |----------------------|------|
  165. | "What do I have to work on?" | `get_my_unresolved_assigned_context` |
  166. | "What's going on with issue #42?" | `get_issue_full_context` |
  167. | "Show open bugs in project 3" | `list_issues` with `project_id` and `only_unresolved` |
  168. | "Have we seen this problem before?" | `sync_issues_to_vector_store`, then `search_vector_issues` |
  169. | "How healthy is project 3?" | `analyze_project_efficiency` |
  170. | "Open a bug for X" | `create_issue` |
  171. | "Mark #42 as in progress for Ana" | `update_issue` |
  172. | "Log 1h30 on #42" | `add_issue_note` with `time_tracking_duration` |
  173. | "Is #42 a duplicate of #17?" | `add_issue_relationship` with `relationship_type: "duplicate-of"` |
  174. ### 3. Workflows
  175. **A. Daily triage of my work**
  176. 1. Call `get_my_unresolved_assigned_context`. Use the executive summary for an overview.
  177. 2. For the top items, call `get_issue_full_context` with each `issue_id` to read the description and notes.
  178. 3. Report the list grouped by priority. Do not invent details missing from the result.
  179. ```json
  180. { "name": "get_my_unresolved_assigned_context", "arguments": { "project_id": 3, "max_pages": 5 } }
  181. ```
  182. **B. Investigate a bug**
  183. 1. `get_issue_full_context` with `issue_id`.
  184. 2. `search_vector_issues` with `query` set to the issue summary, and `only_unresolved: false` to find past solutions. Results need a prior `sync_issues_to_vector_store`. If the store is empty, the result contains an explanatory message.
  185. 3. Report the closest matches with their `id` and similarity score. Say that the match is semantic, not proof of a duplicate.
  186. ```json
  187. { "name": "search_vector_issues", "arguments": { "query": "timeout in PIX payment webhook", "top_k": 5, "min_similarity": 0.1 } }
  188. ```
  189. **C. Build the vector index**
  190. 1. `sync_issues_to_vector_store` with `project_id` and `max_pages`. Start small (`max_pages: 2`) to check the result.
  191. 2. Report what the result says about the sync. Re-run after large changes in MantisBT.
  192. ```json
  193. { "name": "sync_issues_to_vector_store", "arguments": { "project_id": 3, "max_pages": 5 } }
  194. ```
  195. **D. Project efficiency review**
  196. 1. `analyze_project_efficiency` with `project_id`. Leave `auto_sync` at `true` unless the user says not to sync.
  197. 2. Report the Efficiency Score, the throughput and lead time figures, and the `diagnostics` list in that order.
  198. 3. Use `top_stale_unresolved_issues` and `assignee_efficiency` to suggest concrete next steps. Do not change any issue without the user's approval.
  199. ```json
  200. { "name": "analyze_project_efficiency", "arguments": { "project_id": 3, "stale_threshold_hours": 168 } }
  201. ```
  202. **E. Create and update an issue**
  203. 1. Confirm the `project_id` and `category_name` with `list_projects`, which returns categories.
  204. 2. `create_issue` with a clear `summary` and a full `description`. Include `steps_to_reproduce` when the user provides them.
  205. 3. Use the returned `id` in later calls. Use `update_issue` only for fields the user asked to change.
  206. ```json
  207. { "name": "create_issue", "arguments": { "project_id": 3, "category_name": "Bug", "summary": "Checkout fails with 504 on PIX QR code", "description": "Observed on staging after the last deploy.", "priority_name": "high" } }
  208. ```
  209. **F. Log work and comment**
  210. 1. `add_issue_note` with `text`, `view_state` (`public` unless the user says private), and `time_tracking_duration` in `HH:MM` format when the user gives hours.
  211. 2. Report the result to the user and quote any ID it returns.
  212. ```json
  213. { "name": "add_issue_note", "arguments": { "issue_id": 42, "text": "Root cause found in the connection pool.", "view_state": "public", "time_tracking_duration": "01:30" } }
  214. ```
  215. **G. Read an attachment**
  216. 1. `get_issue_full_context` lists attachment metadata (`id`, `filename`, `size_bytes`, `content_type`).
  217. 2. Call `get_issue_attachment` with `issue_id` and `attachment_id` only if the content is needed. Do not download binary files just to describe them.
  218. ### 4. Reporting results
  219. - Lead with the answer, then the supporting figures.
  220. - Quote issue IDs and summaries exactly as returned.
  221. - Mark anything inferred, such as a semantic match or a suggested next step, as an inference.
  222. - If a call fails, say which tool failed, the error message, and what the user can check (URL, token, permissions, IDs).
  223. ### 5. Common errors
  224. | Error text contains | Likely cause | What to tell the user |
  225. |---------------------|--------------|-----------------------|
  226. | `Set MANTIS_BASE_URL and MANTIS_API_TOKEN` | Configuration missing | Add both variables to the MCP client `env` block or the server `.env`. |
  227. | `HTTP 401` | Token invalid or expired | Create a new API token in MantisBT. |
  228. | `HTTP 403` | Account lacks permission | The token's account cannot perform this action. |
  229. | `HTTP 404` | Wrong ID, or REST path issue | Verify the ID with `list_issues` or `list_projects`. Run `check_mantis_connection`. |
  230. | `Issue #N not found.` | ID does not exist | Ask the user to confirm the ID. |
  231. | "No issues found in the vector store" | Index is empty | Run `sync_issues_to_vector_store` first. |
  232. ## Configuration
  233. | Variable | Required | Default |
  234. |----------|----------|---------|
  235. | `MANTIS_BASE_URL` | Yes | none |
  236. | `MANTIS_API_TOKEN` | Yes | none |
  237. | `MANTIS_RESOLVED_THRESHOLD` | No | `80` |
  238. | `MANTIS_VECTOR_DB_PATH` | No | `.mantis-vector-store.json` |
  239. | `MANTIS_EMBEDDING_API_URL` | No | local embedder |
  240. | `MANTIS_EMBEDDING_API_KEY` | No | none |
  241. | `MANTIS_EMBEDDING_MODEL` | No | `text-embedding-3-small` |
  242. | `MANTIS_ALLOW_EXTERNAL_EMBEDDINGS` | No | `false` (external embeddings need this opt-in) |
  243. | `MANTIS_ALLOW_DELETE` | No | `false` (all DELETE calls blocked) |
  244. | `MANTIS_ALLOW_HTTP` | No | `false` (non-https URLs rejected, except localhost) |
  245. | `MANTIS_READ_ONLY` | No | `false` (set `true` to block all write calls: POST, PATCH, PUT, DELETE) |
  246. Resolution order, security notes, and examples are in [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
  247. ## Project Structure
  248. ```
  249. Mantis-MCP/
  250. ├── src/
  251. │ ├── index.ts # Entry point, configuration, MantisBT HTTP client, tool registration
  252. │ ├── vectorStore.ts # Embeddings, issue metrics, persistence, search, efficiency analytics
  253. │ └── test.ts # Integration tests (node:test) with a stubbed MantisBT API
  254. ├── docs/
  255. │ ├── ARCHITECTURE.md # Modules, request lifecycle, vector store internals, design decisions
  256. │ ├── TOOLS.md # Reference for all 25 tools
  257. │ ├── CONFIGURATION.md # Environment variables, resolution order, client setup
  258. │ ├── TESTING.md # Test strategy, cases, and how to add tests
  259. │ └── designs/ # Design records for the MCP server and the analytics feature
  260. ├── .env.example # Configuration template
  261. ├── package.json
  262. └── tsconfig.json
  263. ```
  264. Generated files (`dist/`, `.env`, `.mantis-vector-store.json`) are git-ignored.
  265. ## Documentation
  266. | Document | Contents |
  267. |----------|----------|
  268. | [ARCHITECTURE.md](docs/ARCHITECTURE.md) | How the server is built and why |
  269. | [TOOLS.md](docs/TOOLS.md) | Tool-by-tool parameter reference |
  270. | [CONFIGURATION.md](docs/CONFIGURATION.md) | Setup and environment variables |
  271. | [TESTING.md](docs/TESTING.md) | Running and extending the test suite |
  272. | [designs/mantisbt-mcp.md](docs/designs/mantisbt-mcp.md) | Design specification for the MCP server |
  273. | [designs/vector-efficiency-analytics.md](docs/designs/vector-efficiency-analytics.md) | Design specification for the vector store and analytics |
  274. ## Development
  275. ```bash
  276. npm run dev # TypeScript in watch mode
  277. npm run build # Compile src/ to dist/
  278. npm start # Run the compiled server
  279. npm test # Run the test suite
  280. ```
  281. ## Limitations
  282. - The vector store is a single JSON file loaded into memory. It suits thousands of issues, not millions.
  283. - The default embedder captures shared words and character patterns, not meaning. Use an external embedding endpoint if you need synonym-level matching.
  284. - Changing the embedding mode requires re-running `sync_issues_to_vector_store`.
  285. - The server exposes the MantisBT API as the authenticated user. Its permissions are the permissions of the token.
  286. ## Security
  287. - **Issue content is untrusted.** Anyone who can file or comment on an issue can plant instructions that your AI client may follow (prompt injection). Require human approval for write tools (`update_issue`, `add_issue_note`, `add_issue_attachment`, `create_issue`).
  288. - **Deletes are off by default.** `delete_issue`, `delete_issue_note`, `delete_issue_relationship`, and tag removal fail unless `MANTIS_ALLOW_DELETE=true`.
  289. - **Read-only mode.** Set `MANTIS_READ_ONLY=true` to reject every write call; this is the strongest mitigation against prompt injection through issue text.
  290. - **Use a least-privilege token**, ideally a dedicated read-only account.
  291. - **Vector store is plaintext.** `.mantis-vector-store.json` holds issue content unencrypted; it is written with mode `0600` on POSIX and with an `icacls` ACL restricted to the current user on Windows (best effort). It is not encrypted.
  292. - **https is required** for `MANTIS_BASE_URL` and `MANTIS_EMBEDDING_API_URL` (localhost excepted); redirects are not followed.
  293. - **Embedding API is opt-in.** When configured, issue text leaves your machine.
  294. - **The vector store holds issue text.** It is written with owner-only permissions and git-ignored; keep it out of shared folders.
  295. Report vulnerabilities as described in [SECURITY.md](SECURITY.md).
  296. ## Disclaimer
  297. This is an unofficial, community project. It is not affiliated with or endorsed by MantisBT or its maintainers.
  298. ## License
  299. [MIT](LICENSE). You may use, copy, and modify this project freely, including commercially, as long as the license notice is kept.
  300. ## Citation
  301. If you use this project, please credit it with a link to the repository: <https://github.com/coelho-coie/mantisbt-mcp-Unofficial>. This is a request, not a license requirement; the license stays MIT.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.