Search spaces on demand and accept pasted space links

Adds API q/space_id filters, link paste in mantis-setup, and mantis-resolve-space for Claude slash commands. Stops loading the full space catalog up front.

Author: AnasMaar

.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     {
       "name": "mantis",
       "description": "Mantis MCP: spaces, threads, and map context for Claude Code",
-      "version": "1.0.7",
+      "version": "1.0.8",
       "source": "./"
     }
   ]

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mantis",
   "description": "Connect Claude Code to Mantis MCP — explore maps, clusters, and notebooks in your spaces",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "author": {
     "name": "MIT Mantis"
   },

bin/mantis-resolve-space.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { loadConfig } from '../lib/config.js';
+import { resolveSpaceFromInput } from '../lib/spaces.js';
+
+const input = process.argv.slice(2).join(' ').trim();
+if (!input) {
+  console.error(JSON.stringify({ error: 'Provide a space link or UUID' }));
+  process.exit(1);
+}
+
+try {
+  const cfg = loadConfig();
+  if (!cfg.apiKey || !cfg.apiBaseUrl) {
+    throw new Error('Run mantis-setup first (API key + URL).');
+  }
+  const space = await resolveSpaceFromInput(cfg.apiBaseUrl, cfg.apiKey, input);
+  if (!space) {
+    console.error(JSON.stringify({ error: 'Space not found or no access' }));
+    process.exit(1);
+  }
+  process.stdout.write(JSON.stringify({ space, threadCleared: true }));
+} catch (e) {
+  console.error(JSON.stringify({ error: e.message }));
+  process.exit(1);
+}

bin/mantis-setup.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import { fetchAccessibleSpaces } from '../lib/fetch.js';
 import { DEFAULT_API_BASE, loadConfig, normalizeBaseUrl, saveConfig } from '../lib/config.js';
 import { pickSpace, pickThread } from '../lib/picker.js';
 import { installClaudePlugin } from '../lib/claude-plugin.js';
@@ -17,21 +16,9 @@ async function main() {
   const apiKey = (await promptSecret('API key', { default: prev.apiKey }))?.trim();
   if (!apiKey) die('API key is required.');
 
-  process.stdout.write('  \x1b[2m… fetching spaces\x1b[0m');
-  let spaces;
-  try {
-    spaces = await fetchAccessibleSpaces(apiBaseUrl, apiKey);
-    process.stdout.write('\r\x1b[K');
-  } catch (e) {
-    process.stdout.write('\r\x1b[K');
-    die(`Could not list spaces: ${e.message}`);
-  }
-  if (!spaces.length) die('No spaces found.');
-
-  success(`${spaces.length} space(s) found`);
   saveConfig({ apiBaseUrl, apiKey });
 
-  await pickSpace('', spaces);
+  const afterSpace = await pickSpace();
   const final = await pickThread();
   saveConfig({ ...final, apiBaseUrl, apiKey });
 

lib/api.js

@@ -31,9 +31,13 @@ async function request(baseUrl, apiKey, method, pathname, { params, body } = {})
   return data;
 }
 
-export function listSpaces(baseUrl, apiKey, { scope = 'accessible', limit = 20, offset = 0 } = {}) {
+export function listSpaces(
+  baseUrl,
+  apiKey,
+  { scope = 'accessible', limit = 20, offset = 0, q, space_id } = {},
+) {
   return request(baseUrl, apiKey, 'GET', '/api/v1/me/spaces/', {
-    params: { scope, limit, offset },
+    params: { scope, limit, offset, q, space_id },
   });
 }
 

lib/list-cli.js

@@ -1,5 +1,6 @@
-import { fetchAccessibleSpaces, fetchThreads } from './fetch.js';
 import { loadConfig } from './config.js';
+import { searchSpaces } from './spaces.js';
+import { fetchThreads } from './fetch.js';
 
 export function filterItems(items, query, keys) {
   const terms = (query || '').trim().toLowerCase().split(/\s+/).filter(Boolean);
@@ -15,18 +16,17 @@ export async function spacesForPrompt(filter = '', { limit = 4, offset = 0 } = {
   if (!cfg.apiKey || !cfg.apiBaseUrl) {
     throw new Error('Run mantis-setup first (API key + URL).');
   }
-  const all = filterItems(
-    await fetchAccessibleSpaces(cfg.apiBaseUrl, cfg.apiKey),
-    filter,
-    ['name', 'id'],
-  );
-  const page = all.slice(offset, offset + limit);
+  const page = await searchSpaces(cfg.apiBaseUrl, cfg.apiKey, {
+    q: filter,
+    limit,
+    offset,
+  });
   return {
-    spaces: page,
-    total: all.length,
+    spaces: page.spaces || [],
+    total: page.total,
     offset,
     limit,
-    hasMore: offset + limit < all.length,
+    hasMore: offset + limit < page.total,
     filter,
   };
 }

lib/picker.js

@@ -1,15 +1,26 @@
-import { createSpaceState, fetchAccessibleSpaces, fetchThreads } from './fetch.js';
+import { createSpaceState, fetchThreads } from './fetch.js';
 import { loadConfig, saveConfig } from './config.js';
-import { filterItems } from './list-cli.js';
+import { searchSpaces, resolveSpaceFromInput } from './spaces.js';
+import { parseSpaceIdFromInput } from './space-id.js';
 import { die, info, promptInput, promptSearch, success } from './ui.js';
 
+const BROWSE_PAGE = 20;
+
 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 async function requireConfig() {
   const cfg = loadConfig();
   if (!cfg.apiKey || !cfg.apiBaseUrl) {
@@ -18,17 +29,14 @@ export async function requireConfig() {
   return cfg;
 }
 
-function spaceChoices(spaces, query) {
-  const list = filterItems(spaces, query, ['name', 'id']);
-  return list.map((s) => ({
-    name: spaceLabel(s),
-    value: s,
-    description: s.id,
-  }));
-}
-
 function threadChoices(threads, query) {
-  const list = filterItems(threads, query, ['name', 'id']);
+  const terms = (query || '').trim().toLowerCase();
+  const list = terms
+    ? threads.filter((t) => {
+        const hay = `${t.name} ${t.id}`.toLowerCase();
+        return hay.includes(terms);
+      })
+    : threads;
   const out = [
     { name: '➕ Create new thread', value: '__new__', description: 'New space state' },
   ];
@@ -43,19 +51,45 @@ function threadChoices(threads, query) {
   return out;
 }
 
-export async function pickSpace(initialFilter = '', preloadedSpaces = null) {
+async function pickSpaceByLink(cfg) {
+  const raw = await promptInput('Paste Mantis space link or UUID (Enter to browse)', {
+    default: '',
+  });
+  if (!raw?.trim()) return null;
+  const space = await resolveSpaceFromInput(cfg.apiBaseUrl, cfg.apiKey, raw);
+  if (!space) die('Space not found or you do not have access.');
+  return saveSpace(cfg, space);
+}
+
+export async function pickSpace() {
   const cfg = await requireConfig();
-  const spaces = preloadedSpaces ?? (await fetchAccessibleSpaces(cfg.apiBaseUrl, cfg.apiKey));
-  if (!spaces.length) die('No spaces found.');
 
   if (!process.stdin.isTTY) {
-    return saveSpace(cfg, spaces[0]);
+    const page = await searchSpaces(cfg.apiBaseUrl, cfg.apiKey, { limit: 1 });
+    if (!page.spaces?.length) die('No spaces found.');
+    return saveSpace(cfg, page.spaces[0]);
   }
 
+  const fromLink = await pickSpaceByLink(cfg);
+  if (fromLink) return fromLink;
+
   const picked = await promptSearch(
-    'Select space (↑↓ move, type to filter)',
-    async (input) => spaceChoices(spaces, input || initialFilter),
+    'Select space (↑↓ type to search, paste link in previous step)',
+    async (input) => {
+      const id = parseSpaceIdFromInput(input);
+      if (id) {
+        const one = await resolveSpaceFromInput(cfg.apiBaseUrl, cfg.apiKey, input);
+        return one ? spaceChoices([one]) : [{ name: 'No match for that link/id', value: null, disabled: true }];
+      }
+      const page = await searchSpaces(cfg.apiBaseUrl, cfg.apiKey, {
+        q: input || '',
+        limit: BROWSE_PAGE,
+        offset: 0,
+      });
+      return spaceChoices(page.spaces || []);
+    },
   );
+  if (!picked) die('No space selected.');
   return saveSpace(cfg, picked);
 }
 

lib/space-id.js

@@ -0,0 +1,13 @@
+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;
+  const pathMatch = t.match(/\/space\/([0-9a-f-]{36})/i);
+  if (pathMatch) return pathMatch[1].toLowerCase();
+  const uuidMatch = t.match(UUID_RE);
+  if (uuidMatch) return uuidMatch[0].toLowerCase();
+  return null;
+}

lib/spaces.js

@@ -0,0 +1,48 @@
+import { listSpaces } from './api.js';
+import { parseSpaceIdFromInput } from './space-id.js';
+
+export async function fetchSpaceById(baseUrl, apiKey, spaceId) {
+  const page = await listSpaces(baseUrl, apiKey, {
+    scope: 'accessible',
+    space_id: spaceId,
+    limit: 1,
+    offset: 0,
+  });
+  return page.spaces?.[0] ?? null;
+}
+
+export async function resolveSpaceFromInput(baseUrl, apiKey, text) {
+  const id = parseSpaceIdFromInput(text);
+  if (!id) return null;
+  return fetchSpaceById(baseUrl, apiKey, id);
+}
+
+/** One page of spaces; optional name/id search — does not load the full catalog. */
+export async function searchSpaces(
+  baseUrl,
+  apiKey,
+  { q = '', limit = 20, offset = 0, scope = 'accessible' } = {},
+) {
+  const id = parseSpaceIdFromInput(q);
+  if (id) {
+    const one = await fetchSpaceById(baseUrl, apiKey, id);
+    return {
+      spaces: one ? [one] : [],
+      total: one ? 1 : 0,
+      limit: 1,
+      offset: 0,
+    };
+  }
+  const page = await listSpaces(baseUrl, apiKey, {
+    scope,
+    limit,
+    offset,
+    q: q.trim() || undefined,
+  });
+  return {
+    spaces: page.spaces || [],
+    total: page.total ?? (page.spaces || []).length,
+    limit: page.limit ?? limit,
+    offset: page.offset ?? offset,
+  };
+}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "mantis-claude-code",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Claude Code plugin for Mantis — MCP setup, space/thread selection, and platform skills",
   "type": "module",
   "license": "MIT",