mantisai-cli 2.0.1 → 3.0.0

package/lib/services/context-service.js

@@ -0,0 +1,22 @@
+import { mcpUrl } from '../utils/url.js';
+
+export class ContextService {
+  constructor({ configStore }) {
+    this.configStore = configStore;
+  }
+
+  status() {
+    const cfg = this.configStore.load();
+    return {
+      configPath: this.configStore.configPath(),
+      apiBaseUrl: cfg.apiBaseUrl || '(not set — use mantis setup)',
+      mcpUrl: cfg.apiBaseUrl ? mcpUrl(cfg) : '(run setup)',
+      apiKeyHint: cfg.apiKey ? `***${cfg.apiKey.slice(-6)}` : '(not set)',
+      spaceName: cfg.spaceName || '-',
+      spaceId: cfg.spaceId || '-',
+      threadName: cfg.spaceStateName || '-',
+      threadId: cfg.spaceStateId || '-',
+      hasThread: Boolean(cfg.spaceStateId),
+    };
+  }
+}

package/lib/services/map-service.js

@@ -0,0 +1,114 @@
+import path from 'node:path';
+
+import { fieldSummary, inferFieldTypes } from '../utils/fields.js';
+import { boolOption } from '../utils/cli-args.js';
+import { spaceUrl } from '../utils/url.js';
+
+export class MapService {
+  constructor({ configStore, client, spaces, csvReader, ui }) {
+    this.configStore = configStore;
+    this.client = client;
+    this.spaces = spaces;
+    this.csvReader = csvReader;
+    this.ui = ui;
+  }
+
+  async _chooseExistingSpace(filter = '') {
+    const page = await this.spaces.search({ q: filter, limit: 12 });
+    if (!page.spaces?.length) throw new Error('No spaces found.');
+    return this.ui.promptSelect('Which space should receive this map?', page.spaces.map((s) => ({
+      name: `${s.name} · ${s.map_count ?? 0} map(s) · ${s.role || 'space'}`,
+      value: s,
+      description: s.id,
+    })));
+  }
+
+  async _resolveSpaceTarget(cfg, opts) {
+    let mode = opts.spaceMode;
+    if (!mode) {
+      mode = await this.ui.promptSelect('Where should this map go?', [
+        { name: 'Create a new space', value: 'new' },
+        { name: 'Add to an existing space', value: 'existing' },
+      ]);
+    }
+
+    if (mode === 'existing') {
+      if (opts.spaceId) {
+        const space = opts.spaceName ? null : await this.spaces.fetchById(opts.spaceId);
+        return { spaceId: opts.spaceId, spaceName: opts.spaceName || space?.name };
+      }
+      const picked = await this._chooseExistingSpace(opts.spaceSearch || '');
+      return { spaceId: picked.id, spaceName: picked.name };
+    }
+
+    const spaceName = opts.spaceName || await this.ui.promptInput('New space name', {
+      default: path.basename(opts.file, path.extname(opts.file)) || 'Mantis Map',
+    });
+    const isPublic = opts.public != null
+      ? boolOption(opts.public)
+      : await this.ui.promptConfirm('Make this space public?', { default: false });
+    return { spaceName, isPublic };
+  }
+
+  async createMap(file, opts = {}) {
+    const cfg = this.configStore.requireAuth();
+    const mapName = opts.mapName || await this.ui.promptInput('Map name', {
+      default: path.basename(file, path.extname(file)),
+    });
+    const headers = this.csvReader.readHeaders(file);
+    const dataTypes = opts.dataTypes ? JSON.parse(opts.dataTypes) : inferFieldTypes(headers, opts);
+    this.ui.info(`Fields: ${fieldSummary(headers, dataTypes).join(' | ')}`);
+
+    const target = await this._resolveSpaceTarget(cfg, { ...opts, file });
+
+    let spaceId = target.spaceId;
+    let spaceName = target.spaceName;
+    if (!spaceId) {
+      const space = await this.client.createSpace({ name: target.spaceName, isPublic: target.isPublic });
+      spaceId = space.id;
+      spaceName = space.name;
+      this.ui.info(`Created space: ${spaceName} (${spaceId})`);
+    }
+
+    const result = await this.client.createMapInSpace(spaceId, {
+      file,
+      mapName,
+      dataTypes,
+      selectedFields: opts.selectedFields,
+      fieldWeights: opts.fieldWeights,
+    });
+
+    const primaryMapId = result.map_id || result.base_map_id || result.map_ids?.[0];
+    target.spaceName = spaceName;
+    this.ui.success('Map creation started');
+    this.ui.info(`Space: ${target.spaceName || spaceId} (${spaceId})`);
+    this.ui.info(`Map:   ${mapName}${primaryMapId ? ` (${primaryMapId})` : ''}`);
+    if (spaceId) this.ui.info(`Link:  ${spaceUrl(cfg.apiBaseUrl, spaceId)}`);
+
+    const activate = opts.activate != null
+      ? boolOption(opts.activate)
+      : await this.ui.promptConfirm('Set this as the active Mantis space and thread?', { default: true });
+    let thread = null;
+    if (activate) {
+      const threadName = opts.threadName || await this.ui.promptInput('Thread name', { default: `${mapName} Exploration` });
+      thread = await this.client.createSpaceState(spaceId, threadName);
+      const next = {
+        ...cfg,
+        spaceId,
+        spaceName: target.spaceName || mapName,
+        spaceStateId: thread.id,
+        spaceStateName: thread.name,
+      };
+      this.configStore.save(next);
+      this.ui.success(`Active thread: ${thread.name}`);
+    }
+
+    return {
+      ...result,
+      space_id: spaceId,
+      map_id: primaryMapId,
+      space_url: spaceId ? spaceUrl(cfg.apiBaseUrl, spaceId) : undefined,
+      thread,
+    };
+  }
+}

package/lib/services/query-service.js

@@ -0,0 +1,50 @@
+export function filterItems(items, query, keys) {
+  const terms = (query || '').trim().toLowerCase().split(/\s+/).filter(Boolean);
+  if (!terms.length) return items;
+  return items.filter((item) => {
+    const hay = keys.map((k) => String(item[k] ?? '')).join(' ').toLowerCase();
+    return terms.every((t) => hay.includes(t));
+  });
+}
+
+export class QueryService {
+  constructor({ configStore, spaces }) {
+    this.configStore = configStore;
+    this.spaces = spaces;
+  }
+
+  async spacesForPrompt(filter = '', { limit = 4, offset = 0 } = {}) {
+    this.configStore.requireAuth();
+    const page = await this.spaces.search({ q: filter, limit, offset });
+    return {
+      spaces: page.spaces || [],
+      total: page.total,
+      offset,
+      limit,
+      hasMore: offset + limit < page.total,
+      filter,
+    };
+  }
+
+  async threadsForPrompt(filter = '', { limit = 4, offset = 0 } = {}) {
+    const cfg = this.configStore.requireAuth();
+    if (!cfg.spaceId) throw new Error('Pick a space first (mantis select space).');
+
+    const all = filterItems(
+      await this.spaces.fetchThreads(cfg.spaceId),
+      filter,
+      ['name', 'id'],
+    );
+    const page = all.slice(offset, offset + limit);
+    return {
+      threads: page,
+      total: all.length,
+      offset,
+      limit,
+      hasMore: offset + limit < all.length,
+      spaceId: cfg.spaceId,
+      spaceName: cfg.spaceName,
+      filter,
+    };
+  }
+}

package/lib/services/selection-service.js

@@ -0,0 +1,174 @@
+import { BROWSE_PAGE, DEFAULT_THREAD_NAME } from '../constants.js';
+import { parseSpaceIdFromInput } from '../utils/space-id.js';
+import { defaultThreadName, findThreadByName } from '../utils/threads.js';
+
+function spaceLabel(s) {
+  const name = s.name || '(unnamed)';
+  const maps = s.map_count != null ? ` · ${s.map_count} map(s)` : '';
+  const role = s.role ? ` · ${s.role}` : '';
+  return name + maps + role;
+}
+
+function spaceChoices(spaces) {
+  return spaces.map((s) => ({
+    name: spaceLabel(s),
+    value: s,
+    description: s.id,
+  }));
+}
+
+export class SelectionService {
+  constructor({ configStore, spaces, client, ui }) {
+    this.configStore = configStore;
+    this.spaces = spaces;
+    this.client = client;
+    this.ui = ui;
+  }
+
+  _saveSpace(cfg, space) {
+    const changed = cfg.spaceId !== space.id;
+    const next = { ...cfg, spaceId: space.id, spaceName: space.name };
+    if (changed) {
+      delete next.spaceStateId;
+      delete next.spaceStateName;
+    }
+    this.configStore.save(next);
+    this.ui.success(`Space: ${space.name}`);
+    if (changed) this.ui.info('Thread cleared — run: mantis select thread');
+    return next;
+  }
+
+  _saveThread(cfg, thread) {
+    const next = { ...cfg, spaceStateId: thread.id, spaceStateName: thread.name };
+    this.configStore.save(next);
+    this.ui.success(`Thread: ${thread.name}`);
+    return next;
+  }
+
+  _threadChoices(threads, query) {
+    const terms = (query || '').trim().toLowerCase();
+    const list = terms
+      ? threads.filter((t) => `${t.name} ${t.id}`.toLowerCase().includes(terms))
+      : threads;
+    const out = [{ name: '➕ Create new thread', value: '__new__', description: 'New space state' }];
+    for (const t of list) {
+      const when = t.updated_at ? String(t.updated_at).slice(0, 10) : '';
+      out.push({ name: t.name || '(unnamed)', value: t, description: when || t.id });
+    }
+    return out;
+  }
+
+  async _pickSpaceByLink(cfg) {
+    const raw = await this.ui.promptInput('Paste Mantis space link or UUID (Enter to browse)', { default: '' });
+    if (!raw?.trim()) return null;
+    const space = await this.spaces.resolveFromInput(raw);
+    if (!space) this.ui.die('Space not found or you do not have access.');
+    return this._saveSpace(cfg, space);
+  }
+
+  async pickSpace(initialFilter = '') {
+    const cfg = this.configStore.requireAuth();
+
+    if (!process.stdin.isTTY) {
+      const page = await this.spaces.search({ q: initialFilter, limit: 1 });
+      if (!page.spaces?.length) this.ui.die('No spaces found.');
+      return this._saveSpace(cfg, page.spaces[0]);
+    }
+
+    const fromLink = await this._pickSpaceByLink(cfg);
+    if (fromLink) return fromLink;
+
+    const picked = await this.ui.promptSearch(
+      'Select space (↑↓ type to search, paste link in previous step)',
+      async (input) => {
+        const id = parseSpaceIdFromInput(input);
+        if (id) {
+          const one = await this.spaces.resolveFromInput(input);
+          return one ? spaceChoices([one]) : [{ name: 'No match for that link/id', value: null, disabled: true }];
+        }
+        const page = await this.spaces.search({
+          q: input || initialFilter || '',
+          limit: BROWSE_PAGE,
+          offset: 0,
+        });
+        return spaceChoices(page.spaces || []);
+      },
+    );
+    if (!picked) this.ui.die('No space selected.');
+    return this._saveSpace(cfg, picked);
+  }
+
+  async pickThread(initialFilter = '') {
+    const cfg = this.configStore.requireAuth();
+    if (!cfg.spaceId) this.ui.die('Pick a space first: mantis select space');
+
+    const threads = await this.spaces.fetchThreads(cfg.spaceId);
+
+    if (!process.stdin.isTTY) {
+      if (!threads.length) this.ui.die('No threads. Run interactively to create one.');
+      return this._saveThread(cfg, threads[0]);
+    }
+
+    const picked = await this.ui.promptSearch(
+      `Thread in "${cfg.spaceName || 'space'}" (↑↓, type to filter)`,
+      async (input) => this._threadChoices(threads, input || initialFilter),
+    );
+
+    if (picked === '__new__') {
+      const defaultName = defaultThreadName(DEFAULT_THREAD_NAME, threads);
+      const name = await this.ui.promptInput('Thread name', { default: defaultName });
+      return this._createThread(cfg, threads, name || defaultName);
+    }
+    return this._saveThread(cfg, picked);
+  }
+
+  async _createThread(cfg, threads, name) {
+    const trimmed = String(name || DEFAULT_THREAD_NAME).trim() || DEFAULT_THREAD_NAME;
+    const existing = findThreadByName(threads, trimmed);
+    if (existing) {
+      this.ui.info(`Thread "${trimmed}" already exists — using it.`);
+      return this._saveThread(cfg, existing);
+    }
+    const created = await this.client.createSpaceState(cfg.spaceId, trimmed);
+    return this._saveThread(cfg, created);
+  }
+
+  setSpace(id, name = '') {
+    const cfg = this.configStore.load();
+    const changed = cfg.spaceId !== id;
+    const next = {
+      ...cfg,
+      spaceId: id,
+      spaceName: name || cfg.spaceName,
+      ...(changed ? { spaceStateId: undefined, spaceStateName: undefined } : {}),
+    };
+    this.configStore.save(next);
+    return { ok: true, spaceId: id, spaceName: name, threadCleared: changed, needThread: changed };
+  }
+
+  async setThread(arg, arg2) {
+    const cfg = this.configStore.requireAuth();
+    if (!cfg.spaceId) throw new Error('Run mantis setup and pick a space first.');
+
+    let thread;
+    if (arg === '--new') {
+      const threads = await this.spaces.fetchThreads(cfg.spaceId);
+      const name = arg2 || defaultThreadName(DEFAULT_THREAD_NAME, threads);
+      const existing = findThreadByName(threads, name);
+      thread = existing || await this.client.createSpaceState(cfg.spaceId, name);
+    } else {
+      thread = { id: arg, name: arg2 || arg };
+    }
+
+    const next = { ...cfg, spaceStateId: thread.id, spaceStateName: thread.name };
+    this.configStore.save(next);
+    return { ok: true, spaceStateId: thread.id, name: thread.name };
+  }
+
+  async resolveSpace(input) {
+    this.configStore.requireAuth();
+    const space = await this.spaces.resolveFromInput(input);
+    if (!space) throw new Error('Space not found or no access');
+    return { space, threadCleared: true };
+  }
+}

package/lib/services/setup-service.js

@@ -0,0 +1,81 @@
+import { DEFAULT_API_BASE, DEVELOPER_PORTAL_URL } from '../constants.js';
+import { normalizeBaseUrl, mcpUrl } from '../utils/url.js';
+
+const PROVIDERS = new Set(['claude', 'opencode']);
+
+export class SetupService {
+  constructor({ configStore, selection, claudeSkills, opencodeSkills, ui }) {
+    this.configStore = configStore;
+    this.selection = selection;
+    this.claudeSkills = claudeSkills;
+    this.opencodeSkills = opencodeSkills;
+    this.ui = ui;
+  }
+
+  async run() {
+    const prev = this.configStore.load();
+    this.ui.banner('Mantis setup', 'API credentials and workspace context');
+
+    const apiBaseUrl = normalizeBaseUrl(
+      await this.ui.promptInput('Mantis API URL', {
+        default: prev.apiBaseUrl || process.env.MANTIS_API_URL || DEFAULT_API_BASE,
+      }),
+    );
+    this.ui.info(`API keys: ${DEVELOPER_PORTAL_URL}`);
+    const apiKey = (await this.ui.promptSecret('API key (Ctrl+click link above to open portal)', {
+      default: prev.apiKey,
+    }))?.trim();
+    if (!apiKey) this.ui.die('API key is required.');
+
+    let cfg = { ...prev, apiBaseUrl, apiKey };
+    this.configStore.save(cfg);
+
+    if (!cfg.spaceId) {
+      cfg = await this.selection.pickSpace();
+    } else {
+      this.ui.info(`Space: ${cfg.spaceName || cfg.spaceId} (unchanged)`);
+    }
+
+    if (!cfg.spaceStateId) {
+      if (!cfg.spaceId) this.ui.die('Pick a space before choosing a thread.');
+      cfg = await this.selection.pickThread();
+    } else {
+      this.ui.info(`Thread: ${cfg.spaceStateName || cfg.spaceStateId} (unchanged)`);
+    }
+
+    this.configStore.save(cfg);
+
+    console.log('');
+    this.ui.success('Setup complete');
+    this.ui.info(`Space:  ${cfg.spaceName || '-'} (${cfg.spaceId || '-'})`);
+    this.ui.info(`Thread: ${cfg.spaceStateName || '-'} (${cfg.spaceStateId || '-'})`);
+    this.ui.info(`MCP:    ${mcpUrl(cfg)}`);
+    this.ui.info('Explore with: mantis tools && mantis use get_space_context');
+    this.ui.info('Editor skills: mantis setup claude | mantis setup opencode');
+    console.log('');
+  }
+
+  runProvider(provider) {
+    const p = String(provider || '').toLowerCase();
+    if (!PROVIDERS.has(p)) {
+      throw new Error(`Unknown provider "${provider}". Use: claude, opencode`);
+    }
+
+    if (p === 'claude') {
+      const { skillsDir, installed } = this.claudeSkills.sync();
+      this.ui.banner('Mantis skills → Claude Code');
+      this.ui.success(`Synced ${installed.length} skill(s) to ${skillsDir}`);
+      for (const s of installed) this.ui.info(`${s.slash}  ← skills/${s.source}`);
+      this.ui.info('Try /mantis or /mantis-connect in Claude Code.');
+      return { provider: p, skillsDir, installed };
+    }
+
+    const { globalSkillsDir, projectSkillsDir, installed } = this.opencodeSkills.sync();
+    this.ui.banner('Mantis skills → OpenCode');
+    this.ui.success(`Synced ${installed.length} skill(s)`);
+    this.ui.info(`Global:  ${globalSkillsDir}`);
+    this.ui.info(`Project: ${projectSkillsDir}`);
+    for (const s of installed) this.ui.info(`${s.slash}  ← skills/${s.source}`);
+    return { provider: p, globalSkillsDir, projectSkillsDir, installed };
+  }
+}

package/lib/services/tool-service.js

@@ -0,0 +1,26 @@
+import { DISABLED_MCP_TOOLS } from '../constants.js';
+
+function disabledToolError(name) {
+  if (name === 'create_space') {
+    return 'create_space is disabled in the CLI. Use: mantis setup or mantis select space';
+  }
+  return `${name} is disabled in the CLI. Use: mantis create map or mantis create codebase`;
+}
+
+export class ToolService {
+  constructor({ mcp }) {
+    this.mcp = mcp;
+  }
+
+  async listTools() {
+    const data = await this.mcp.listTools();
+    return {
+      tools: (data.tools || []).filter((t) => !DISABLED_MCP_TOOLS.has(t.name)),
+    };
+  }
+
+  useTool(name, args = {}) {
+    if (DISABLED_MCP_TOOLS.has(name)) throw new Error(disabledToolError(name));
+    return this.mcp.callTool(name, args);
+  }
+}

package/lib/types.js

@@ -0,0 +1,30 @@
+/** @typedef {Object} MantisConfig
+ * @property {string} [apiBaseUrl]
+ * @property {string} [apiKey]
+ * @property {string} [spaceId]
+ * @property {string} [spaceName]
+ * @property {string} [spaceStateId]
+ * @property {string} [spaceStateName]
+ */
+
+/** @typedef {Object} Space
+ * @property {string} id
+ * @property {string} name
+ * @property {number} [map_count]
+ * @property {string} [role]
+ */
+
+/** @typedef {Object} Thread
+ * @property {string} id
+ * @property {string} name
+ * @property {string} [updated_at]
+ */
+
+/** @typedef {Object} SpacePage
+ * @property {Space[]} spaces
+ * @property {number} total
+ * @property {number} [limit]
+ * @property {number} [offset]
+ */
+
+export {};

package/lib/utils/cli-args.js

@@ -0,0 +1,29 @@
+export function parseListArgs(argv, { defaultLimit = 4 } = {}) {
+  let filter = '';
+  let offset = 0;
+  let limit = defaultLimit;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--offset') {
+      offset = parseInt(argv[++i], 10) || 0;
+      continue;
+    }
+    if (a === '--limit') {
+      limit = parseInt(argv[++i], 10) || defaultLimit;
+      continue;
+    }
+    if (a === '--filter') {
+      filter = argv[++i] ?? '';
+      continue;
+    }
+    filter = argv.slice(i).join(' ').trim();
+    break;
+  }
+  return { filter, offset, limit };
+}
+
+export function boolOption(value, fallback = false) {
+  if (value == null) return fallback;
+  if (typeof value === 'boolean') return value;
+  return ['1', 'true', 'yes', 'public'].includes(String(value).toLowerCase());
+}

package/lib/utils/package-root.js

@@ -0,0 +1,7 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const PACKAGE_ROOT = path.resolve(__dirname, '../..');
+export const SKILLS_DIR = path.join(PACKAGE_ROOT, 'skills');

package/lib/utils/skills-sync.js

@@ -0,0 +1,43 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function installSkillName(sourceDir) {
+  return sourceDir === 'mantis' ? 'mantis' : `mantis-${sourceDir}`;
+}
+
+export function listSkillSources(skillsDir) {
+  return fs.readdirSync(skillsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && fs.existsSync(path.join(skillsDir, d.name, 'SKILL.md')))
+    .map((d) => d.name)
+    .sort();
+}
+
+export function prepareSkillContent(content, installName) {
+  if (!content.startsWith('---\n')) {
+    return `---\nname: ${installName}\n---\n\n${content}`;
+  }
+  const match = content.match(/^---\n([\s\S]*?)\n---([\s\S]*)$/);
+  if (!match) return content;
+  let yaml = match[1];
+  const body = match[2];
+  yaml = /^name:\s/m.test(yaml)
+    ? yaml.replace(/^name:\s.*$/m, `name: ${installName}`)
+    : `name: ${installName}\n${yaml}`;
+  return `---\n${yaml}\n---${body}`;
+}
+
+export function syncSkills({ skillsDir, targets, installName = installSkillName }) {
+  const installed = [];
+  for (const source of listSkillSources(skillsDir)) {
+    const name = installName(source);
+    const raw = fs.readFileSync(path.join(skillsDir, source, 'SKILL.md'), 'utf8');
+    const content = prepareSkillContent(raw, name);
+    for (const root of targets) {
+      const dest = path.join(root, name);
+      fs.mkdirSync(dest, { recursive: true });
+      fs.writeFileSync(path.join(dest, 'SKILL.md'), content);
+    }
+    installed.push({ source, name, slash: `/${name}` });
+  }
+  return installed;
+}

package/lib/{space-id.js → utils/space-id.js}

@@ -1,7 +1,6 @@
 const UUID_RE =
   /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
 
-/** Extract space UUID from a Mantis URL (/space/{id}), raw UUID, or search text containing one. */
 export function parseSpaceIdFromInput(text) {
   const t = (text || '').trim();
   if (!t) return null;

package/lib/utils/threads.js

@@ -0,0 +1,12 @@
+export function findThreadByName(threads, name) {
+  return threads.find((t) => t.name === name) ?? null;
+}
+
+export function defaultThreadName(base, threads) {
+  if (!findThreadByName(threads, base)) return base;
+  for (let n = 2; n < 100; n++) {
+    const candidate = `${base} ${n}`;
+    if (!findThreadByName(threads, candidate)) return candidate;
+  }
+  return `${base} ${Date.now()}`;
+}

package/lib/utils/tool-args.js

@@ -0,0 +1,38 @@
+export function parseToolArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--args') {
+      Object.assign(args, JSON.parse(argv[++i] || '{}'));
+      continue;
+    }
+    if (!a.startsWith('--')) continue;
+    const key = a.slice(2).replace(/-/g, '_');
+    const next = argv[i + 1];
+    if (next && !next.startsWith('--')) {
+      args[key] = coerceValue(next);
+      i++;
+    } else {
+      args[key] = true;
+    }
+  }
+  return args;
+}
+
+function coerceValue(v) {
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  if (v !== '' && !Number.isNaN(Number(v))) return Number(v);
+  return v;
+}
+
+export function parseUseCommand(argv) {
+  const idx = argv.indexOf('use');
+  if (idx === -1 || !argv[idx + 1]) {
+    throw new Error('Usage: mantis use <tool> [--args JSON] [--key value ...]');
+  }
+  return {
+    tool: argv[idx + 1],
+    args: parseToolArgs(argv.slice(idx + 2)),
+  };
+}

package/lib/utils/url.js

@@ -0,0 +1,33 @@
+import { DEFAULT_API_BASE } from '../constants.js';
+
+export function normalizeBaseUrl(url) {
+  return String(url || '').trim().replace(/\/+$/, '');
+}
+
+export function mcpUrl(cfg) {
+  const base = normalizeBaseUrl(cfg.apiBaseUrl || process.env.MANTIS_API_URL || DEFAULT_API_BASE);
+  return `${base}/mcp_integrated/`;
+}
+
+export function frontendBaseUrl(apiBaseUrl) {
+  const root = normalizeBaseUrl(apiBaseUrl).replace(/\/api\/?$/, '');
+  let url;
+  try {
+    url = new URL(root);
+  } catch {
+    return root;
+  }
+  if (/^(localhost|127\.0\.0\.1)$/i.test(url.hostname)) {
+    url.port = '3000';
+    return url.origin;
+  }
+  if (/(^|\.)kellis-h200-1\.csail\.mit\.edu$/i.test(url.hostname)) {
+    url.hostname = 'mantis.csail.mit.edu';
+    return url.origin;
+  }
+  return root;
+}
+
+export function spaceUrl(apiBaseUrl, spaceId) {
+  return `${frontendBaseUrl(apiBaseUrl)}/space/${spaceId}`;
+}