Get MantisBT Version

Instructions

Implementation Reference

• src/tools/version.ts:55-93 (handler)

  The async handler function for the 'get_mantis_version' tool. It calls client.getVersion() to get the installed version from the X-Mantis-Version response header, optionally fetches the latest release from GitHub via VersionHintService, parses and compares versions, and returns a JSON result with status (up-to-date, update-available, newer-than-release, or unknown).

    async ({ check_latest }) => {
      try {
        const installedRaw = await client.getVersion();
        const result: Record<string, unknown> = { installed_version: installedRaw };
  
        if (check_latest) {
          versionHint.triggerLatestVersionFetch();
          const latestRaw = await versionHint.waitForLatestVersion(5000);
  
          result.latest_version = latestRaw;
  
          if (latestRaw === null) {
            result.status = 'unknown';
            result.github_note = 'Could not fetch latest version from GitHub (timeout or network error).';
          } else {
            const installed = parseVersion(installedRaw);
            const latest = parseVersion(latestRaw);
            if (installed && latest) {
              const cmp = compareVersions(installed, latest);
              result.status = cmp === 0
                ? 'up-to-date'
                : cmp > 0
                  ? 'newer-than-release'
                  : 'update-available';
            } else {
              result.status = 'unknown';
            }
          }
        }
  
        return {
          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
        };
      } catch (error) {
        const msg = error instanceof Error ? error.message : String(error);
        return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
      }
    }
  );

• src/tools/version.ts:37-54 (schema)

  Tool registration and input schema for 'get_mantis_version'. Defines the tool name, title, description, annotations (readOnly, non-destructive, idempotent), and inputSchema with an optional 'check_latest' boolean parameter (default: true) that controls whether to compare against the latest GitHub release.

      'get_mantis_version',
      {
        title: 'Get MantisBT Version',
        description: `Returns the version of the connected MantisBT installation and optionally compares it against the latest official release on GitHub.
  
  The version is read from the X-Mantis-Version response header sent by every API call.
  The GitHub comparison requires an outbound HTTPS request to the GitHub API.`,
        inputSchema: z.object({
          check_latest: z.preprocess(coerceBool, z.boolean()).default(true).describe(
            'Whether to fetch the latest release from GitHub and compare (default: true)'
          ),
        }),
        annotations: {
          readOnlyHint: true,
          destructiveHint: false,
          idempotentHint: true,
        },
      },

• src/index.ts:78-78 (registration)

  Registration call that wires up the version tools (including get_mantis_version) into the MCP server. Called from the main createMcpServer() function with the server, client, versionHint service, and mcpVersion.

  registerVersionTools(server, client, versionHint, version);

• src/client.ts:190-201 (helper)

  MantisClient.getVersion() — makes a GET request to 'users/me' and extracts the MantisBT version from the X-Mantis-Version response header. Returns the header value or 'unknown'.

    async getVersion(): Promise<string> {
      const response = await fetch(await this.buildUrl('users/me'), {
        method: 'GET',
        headers: await this.headers(),
        signal: AbortSignal.timeout(MantisClient.TIMEOUT_MS),
      });
      if (!response.ok) {
        throw new MantisApiError(response.status, response.statusText);
      }
      return response.headers.get('X-Mantis-Version') ?? 'unknown';
    }
  }

• src/version-hint.ts:36-111 (helper)

  VersionHintService class used by the tool to fetch and cache the latest MantisBT version from GitHub tags. Includes triggerLatestVersionFetch() to start an async fetch, waitForLatestVersion() to block up to 5s waiting for the result, and parseVersion()/compareVersions() utilities for version comparison.

  export class VersionHintService {
    private installedVersion: string | null = null;
    private latestVersion: string | null = null;
    private fetchStarted = false;
  
    /** Called by MantisClient after every successful API response. */
    onSuccessfulResponse(response: Response): void {
      if (!this.installedVersion) {
        const v = response.headers.get('X-Mantis-Version');
        if (v) this.installedVersion = v;
      }
    }
  
    /**
     * Starts the GitHub fetch exactly once (fire-and-forget).
     * Safe to call multiple times — subsequent calls are no-ops.
     */
    triggerLatestVersionFetch(): void {
      if (this.fetchStarted) return;
      this.fetchStarted = true;
      void this.doFetch();
    }
  
    private async doFetch(): Promise<void> {
      try {
        const resp = await fetch(MANTISBT_TAGS_URL, {
          headers: {
            'Accept': 'application/vnd.github+json',
            'User-Agent': 'mantisbt-mcp-server',
          },
        });
        if (!resp.ok) return;
        const tags = await resp.json() as Array<{ name: string }>;
        const tag = tags.find(t => /^release-\d+\.\d+\.\d+$/.test(t.name));
        this.latestVersion = tag ? tag.name.replace('release-', '') : null;
      } catch {
        // Network error — no hint, no crash
      }
    }
  
    /**
     * Returns an update hint string if a newer version is known, or null.
     * Never blocks — returns null while the GitHub fetch is still in flight.
     */
    getUpdateHint(): string | null {
      if (!this.installedVersion || !this.latestVersion) return null;
      const installed = parseVersion(this.installedVersion);
      const latest = parseVersion(this.latestVersion);
      if (!installed || !latest) return null;
      if (compareVersions(installed, latest) < 0) {
        return (
          `Note: MantisBT ${this.latestVersion} is available ` +
          `(installed: ${this.installedVersion}) — updating may resolve this issue.`
        );
      }
      return null;
    }
  
    getInstalledVersion(): string | null { return this.installedVersion; }
    getLatestVersion(): string | null { return this.latestVersion; }
  
    /**
     * Waits up to `timeoutMs` for the GitHub fetch to complete.
     * Used by the get_mantis_version tool where blocking is acceptable.
     */
    async waitForLatestVersion(timeoutMs = 5000): Promise<string | null> {
      if (this.latestVersion !== null) return this.latestVersion;
      if (!this.fetchStarted) return null;
      const deadline = Date.now() + timeoutMs;
      while (Date.now() < deadline) {
        if (this.latestVersion !== null) return this.latestVersion;
        await new Promise(r => setTimeout(r, 100));
      }
      return null;
    }
  }