@bevel-software/platform-core-frontend 0.9.1 → 0.11.0

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.
Files changed (40) hide show
  1. package/package.json +2 -2
  2. package/src/core/CoreAppShell.tsx +6 -0
  3. package/src/core/__tests__/AppChrome.test.tsx +3 -0
  4. package/src/core/registry.ts +25 -0
  5. package/src/lib/email.ts +25 -0
  6. package/src/modules/access/__tests__/ManageAccessDialog.placement.test.tsx +1 -1
  7. package/src/modules/access/__tests__/ManageAccessDialog.test.tsx +280 -4
  8. package/src/modules/access/api.ts +47 -13
  9. package/src/modules/access/components/ManageAccessDialog.tsx +119 -49
  10. package/src/modules/admin/__tests__/AdminRolesPage.capabilities.test.tsx +281 -0
  11. package/src/modules/admin/__tests__/AdminRolesPage.suggest.test.tsx +4 -4
  12. package/src/modules/admin/__tests__/DirectoryGroupsPage.test.tsx +438 -0
  13. package/src/modules/admin/components/AdminRolesPage.tsx +203 -411
  14. package/src/modules/admin/components/DirectoryGroupsPage.tsx +610 -0
  15. package/src/modules/admin/hooks/useExclusiveRunner.ts +27 -0
  16. package/src/modules/admin/services/groups.api.ts +151 -0
  17. package/src/modules/admin/services/roles.api.ts +57 -31
  18. package/src/modules/library/__tests__/LibraryRoutes.test.tsx +42 -3
  19. package/src/modules/library/__tests__/PluginPage.test.tsx +29 -0
  20. package/src/modules/library/__tests__/ToolPage.test.tsx +22 -0
  21. package/src/modules/library/__tests__/WorkspaceItemRoute.test.tsx +90 -0
  22. package/src/modules/library/components/LibraryPage.tsx +2 -2
  23. package/src/modules/library/components/PersonalPluginPage.tsx +2 -2
  24. package/src/modules/library/components/PluginPage.tsx +2 -2
  25. package/src/modules/library/components/tool-page/ToolPage.tsx +7 -1
  26. package/src/modules/library/routes/LibraryRoutes.tsx +6 -4
  27. package/src/modules/library/routes/WorkspaceItemRoute.tsx +33 -5
  28. package/src/modules/library/routes/library-paths.ts +30 -0
  29. package/src/modules/onboarding/__tests__/onboarding.test.tsx +63 -17
  30. package/src/modules/onboarding/agent-clients.ts +21 -7
  31. package/src/modules/onboarding/components/WelcomePage.tsx +1 -1
  32. package/src/modules/settings/settings-nav-items.tsx +9 -1
  33. package/src/modules/toolbar/components/ExternalAgentAccessPage.tsx +135 -20
  34. package/src/modules/toolbar/components/__tests__/ExternalAgentAccessPage.test.tsx +113 -14
  35. package/src/modules/update-check/__tests__/UpdateBanner.test.tsx +126 -0
  36. package/src/modules/update-check/components/UpdateBanner.tsx +92 -0
  37. package/src/modules/update-check/services/update-check.api.ts +24 -0
  38. package/src/shared/mcp/__tests__/connect-snippets.test.ts +66 -0
  39. package/src/shared/mcp/connect-snippets.ts +76 -0
  40. package/src/shared/mcp/index.ts +3 -0
@@ -95,6 +95,36 @@ export function urlForSkillFile(kbDirName: string, skillPath: string, file = 'SK
95
95
  return urlForItemFile(kbDirName, `${skillPath}/${file}`);
96
96
  }
97
97
 
98
+ /**
99
+ * The canonical URL of one MCP server declared in a plugin's `mcp.json`.
100
+ *
101
+ * One `mcp.json` declares SEVERAL servers, so the declaring file's URL alone
102
+ * cannot name which tool page to open — the server's slug rides along as a
103
+ * QUERY param (`?server=<slug>`). A query param and NOT the hash, deliberately:
104
+ * the `#…` fragment on tool URLs is the OAuth callback's outcome channel
105
+ * (`#authorized=…` / `#error=…` — see `pathForTool`), and the two must be able
106
+ * to coexist on one URL.
107
+ */
108
+ export function urlForMcpServer(kbDirName: string, mcpJsonPath: string, slug: string): string {
109
+ return `${urlForItemFile(kbDirName, mcpJsonPath)}?server=${encodeURIComponent(slug)}`;
110
+ }
111
+
112
+ /**
113
+ * Where a library item's card navigates — the ONE rule, shared by every
114
+ * card-open site so a card does the same thing wherever it is clicked: the
115
+ * item's canonical file URL, plus the `?server=` disambiguator when the item
116
+ * is an mcp.json-declared server (whose declaring file is shared with its
117
+ * sibling servers, so the file URL alone would not name it).
118
+ */
119
+ export function urlForLibraryItem(
120
+ kbDirName: string,
121
+ item: { kind: 'skill' | 'integration'; id: string; path: string },
122
+ ): string {
123
+ return item.kind === 'integration' && item.path.endsWith('/mcp.json')
124
+ ? urlForMcpServer(kbDirName, item.path, item.id)
125
+ : urlForItemFile(kbDirName, item.path);
126
+ }
127
+
98
128
  /**
99
129
  * Whether a location belongs to the LIBRARY surface — decided by URL SHAPE
100
130
  * alone, never by catalog contents: `/skills-and-tools/...`, or a
@@ -337,11 +337,36 @@ describe('WelcomePage', () => {
337
337
 
338
338
  it('shows one snippet at a time, following the picker', async () => {
339
339
  mountPage();
340
- // Claude default: the bare URL.
340
+ // Desktop agents default: the local hexis-mcp config, not the bare URL.
341
+ expect(screen.getByText(/@bevel-software\/hexis-mcp/)).toBeInTheDocument();
342
+ await userEvent.click(screen.getByRole('radio', { name: 'Claude' }));
341
343
  expect(screen.getByText(/\/api\/mcp$/)).toBeInTheDocument();
342
344
  expect(screen.queryByText(/mcpServers/)).toBeNull();
343
- await userEvent.click(screen.getByRole('radio', { name: 'Cursor & Others' }));
344
- expect(screen.getByText(/mcpServers/)).toBeInTheDocument();
345
+ await userEvent.click(screen.getByRole('radio', { name: 'Other' }));
346
+ expect(screen.getByText(/knowledge-base/)).toBeInTheDocument();
347
+ });
348
+
349
+ /**
350
+ * The RECOMMENDED default: the local server serves everything the hosted
351
+ * endpoint does plus the plugins' local-only tools, so the picker leads
352
+ * with it and the page opens on it. No key exists at onboarding time, so
353
+ * the snippet must carry the placeholder that tells someone what to paste
354
+ * — keyless is the interactive mode: the local server opens the browser
355
+ * to sign in on first run, so the config carries no key at all.
356
+ */
357
+ it('defaults to Desktop agents: the keyless hexis-mcp config', () => {
358
+ mountPage();
359
+ expect(screen.getByRole('radio', { name: 'Desktop agents' })).toHaveAttribute(
360
+ 'aria-checked',
361
+ 'true',
362
+ );
363
+ const snippet = screen.getByText(/mcpServers/).textContent!;
364
+ expect(snippet).toContain('@bevel-software/hexis-mcp');
365
+ // Keyless = interactive sign-in: no key env at all, not a placeholder —
366
+ // the server opens the browser on first run.
367
+ expect(snippet).not.toContain('HEXIS_CONNECTION_KEY');
368
+ // The hint says how identity arrives instead: browser sign-in on first run.
369
+ expect(screen.getByText(/your browser opens so you can sign in/)).toBeInTheDocument();
345
370
  });
346
371
 
347
372
  /**
@@ -349,11 +374,16 @@ describe('WelcomePage', () => {
349
374
  * only client with a documented install link, and it appears only when
350
375
  * Anthropic could actually reach this deployment — see `canDeepLink`. The
351
376
  * copy block stays either way; it is the route that always works.
377
+ *
378
+ * Every case selects the Claude option first: the picker now defaults to
379
+ * Desktop agents (the local server), and the install link belongs to the
380
+ * hosted claude.ai path alone.
352
381
  */
353
382
  describe('the Add to Claude link', () => {
354
- it('offers one-click connect on a reachable deployment', () => {
383
+ it('offers one-click connect on a reachable deployment', async () => {
355
384
  configureMcpUrl('https://kb.acme.com/api/mcp');
356
385
  mountPage();
386
+ await userEvent.click(screen.getByRole('radio', { name: 'Claude' }));
357
387
  const link = screen.getByRole('link', { name: 'Add to Claude' });
358
388
  const href = new URL(link.getAttribute('href')!);
359
389
  expect(href.origin + href.pathname).toBe('https://claude.ai/customize/connectors');
@@ -366,9 +396,10 @@ describe('WelcomePage', () => {
366
396
  * claude.ai cannot reach. A dead button on the first screen a self-hoster
367
397
  * sees reads as a broken product.
368
398
  */
369
- it('offers nothing to click on a localhost deployment', () => {
399
+ it('offers nothing to click on a localhost deployment', async () => {
370
400
  configureMcpUrl('http://localhost:3001/api/mcp');
371
401
  mountPage();
402
+ await userEvent.click(screen.getByRole('radio', { name: 'Claude' }));
372
403
  expect(screen.queryByRole('link', { name: 'Add to Claude' })).toBeNull();
373
404
  // …and the route that always works is still there.
374
405
  expect(screen.getByText('http://localhost:3001/api/mcp')).toBeInTheDocument();
@@ -379,26 +410,31 @@ describe('WelcomePage', () => {
379
410
  * employee who cannot change deployment config; naming an env var at them
380
411
  * is noise. The settings page, whose reader plausibly can, says it there.
381
412
  */
382
- it('does not lecture a new employee about deployment config', () => {
413
+ it('does not lecture a new employee about deployment config', async () => {
383
414
  configureMcpUrl('http://localhost:3001/api/mcp');
384
415
  mountPage();
416
+ await userEvent.click(screen.getByRole('radio', { name: 'Claude' }));
385
417
  expect(screen.queryByText(/PUBLIC_BACKEND_URL/)).toBeNull();
386
418
  });
387
419
 
388
420
  it('belongs to Claude alone', async () => {
389
421
  configureMcpUrl('https://kb.acme.com/api/mcp');
390
422
  mountPage();
423
+ // The default — Desktop agents — earns no install link either.
424
+ expect(screen.queryByRole('link', { name: 'Add to Claude' })).toBeNull();
425
+ await userEvent.click(screen.getByRole('radio', { name: 'Claude' }));
391
426
  expect(screen.getByRole('link', { name: 'Add to Claude' })).toBeInTheDocument();
392
427
  await userEvent.click(screen.getByRole('radio', { name: 'ChatGPT' }));
393
428
  expect(screen.queryByRole('link', { name: 'Add to Claude' })).toBeNull();
394
- await userEvent.click(screen.getByRole('radio', { name: 'Cursor & Others' }));
429
+ await userEvent.click(screen.getByRole('radio', { name: 'Other' }));
395
430
  expect(screen.queryByRole('link', { name: 'Add to Claude' })).toBeNull();
396
431
  });
397
432
 
398
433
  // Opening claude.ai must not hand it a handle on this window.
399
- it('opens in a new tab safely', () => {
434
+ it('opens in a new tab safely', async () => {
400
435
  configureMcpUrl('https://kb.acme.com/api/mcp');
401
436
  mountPage();
437
+ await userEvent.click(screen.getByRole('radio', { name: 'Claude' }));
402
438
  const link = screen.getByRole('link', { name: 'Add to Claude' });
403
439
  expect(link).toHaveAttribute('target', '_blank');
404
440
  expect(link).toHaveAttribute('rel', 'noopener noreferrer');
@@ -409,9 +445,10 @@ describe('WelcomePage', () => {
409
445
  * what the copy block shows a human must be the same string, or one of
410
446
  * them is lying.
411
447
  */
412
- it('hands Claude exactly the URL the copy block shows', () => {
448
+ it('hands Claude exactly the URL the copy block shows', async () => {
413
449
  configureMcpUrl('https://kb.acme.com/api/mcp');
414
450
  mountPage();
451
+ await userEvent.click(screen.getByRole('radio', { name: 'Claude' }));
415
452
  const href = new URL(
416
453
  screen.getByRole('link', { name: 'Add to Claude' }).getAttribute('href')!,
417
454
  );
@@ -425,7 +462,8 @@ describe('WelcomePage', () => {
425
462
  const writeText = stubClipboard();
426
463
  mountPage();
427
464
  await userEvent.click(screen.getByRole('button', { name: 'Copy' }));
428
- expect(writeText).toHaveBeenCalledWith(expect.stringContaining('/api/mcp'));
465
+ // The default snippet is the local server's config, not the hosted URL.
466
+ expect(writeText).toHaveBeenCalledWith(expect.stringContaining('@bevel-software/hexis-mcp'));
429
467
  // Copying is not Done: no server write, no navigation.
430
468
  expect(authFetchMock).not.toHaveBeenCalled();
431
469
  expect(screen.getByTestId('pathname')).toHaveTextContent(WELCOME_PATH);
@@ -464,9 +502,16 @@ describe('WelcomePage', () => {
464
502
  const group = screen.getByRole('radiogroup', { name: 'Your agent' });
465
503
  const options = screen.getAllByRole('radio');
466
504
  expect(group).toContainElement(options[0]!);
467
- expect(options.map((o) => o.getAttribute('aria-checked'))).toEqual(['true', 'false', 'false']);
505
+ // Desktop agents — the local server — leads, and is the default.
506
+ expect(options.map((o) => o.getAttribute('aria-checked'))).toEqual([
507
+ 'true',
508
+ 'false',
509
+ 'false',
510
+ 'false',
511
+ ]);
468
512
  await userEvent.click(screen.getByRole('radio', { name: 'ChatGPT' }));
469
513
  expect(screen.getAllByRole('radio').map((o) => o.getAttribute('aria-checked'))).toEqual([
514
+ 'false',
470
515
  'false',
471
516
  'true',
472
517
  'false',
@@ -476,25 +521,25 @@ describe('WelcomePage', () => {
476
521
  /**
477
522
  * `role="radiogroup"` is a promise about the keyboard, not just a label for
478
523
  * a screen reader: arrows select, and selection follows focus. The plugin
479
- * wraps, because three options in a row have no edge worth stopping at.
524
+ * wraps, because four options in a row have no edge worth stopping at.
480
525
  */
481
526
  it('drives the picker with the arrow keys, wrapping at both ends', async () => {
482
527
  mountPage();
483
528
  const checked = () =>
484
529
  screen.getAllByRole('radio').find((o) => o.getAttribute('aria-checked') === 'true');
485
530
 
486
- screen.getByRole('radio', { name: 'Claude' }).focus();
531
+ screen.getByRole('radio', { name: 'Desktop agents' }).focus();
487
532
  await userEvent.keyboard('{ArrowRight}');
488
- expect(checked()).toHaveAccessibleName('ChatGPT');
533
+ expect(checked()).toHaveAccessibleName('Claude');
489
534
  expect(checked()).toHaveFocus();
490
535
 
491
536
  // Off the end and round to the first.
492
- await userEvent.keyboard('{ArrowRight}{ArrowRight}');
493
- expect(checked()).toHaveAccessibleName('Claude');
537
+ await userEvent.keyboard('{ArrowRight}{ArrowRight}{ArrowRight}');
538
+ expect(checked()).toHaveAccessibleName('Desktop agents');
494
539
 
495
540
  // And backwards past the start, to the last.
496
541
  await userEvent.keyboard('{ArrowLeft}');
497
- expect(checked()).toHaveAccessibleName('Cursor & Others');
542
+ expect(checked()).toHaveAccessibleName('Other');
498
543
  });
499
544
 
500
545
  // Roving tabindex: the picker is ONE tab stop, not one per client.
@@ -504,6 +549,7 @@ describe('WelcomePage', () => {
504
549
  '0',
505
550
  '-1',
506
551
  '-1',
552
+ '-1',
507
553
  ]);
508
554
  });
509
555
 
@@ -1,9 +1,13 @@
1
- import { jsonConfigSnippet } from '../../shared/mcp';
1
+ import { hexisMcpJsonSnippet, jsonConfigSnippet, workspaceBaseUrl } from '../../shared/mcp';
2
2
 
3
3
  /**
4
- * The three ways an agent connects, named by PRODUCT rather than surface —
4
+ * The ways an agent connects, named by PRODUCT rather than surface —
5
5
  * someone knows which assistant they use before they know which build of it
6
- * they are in (prototype `AGENT_CLIENTS`).
6
+ * they are in (prototype `AGENT_CLIENTS`). The one exception is the first
7
+ * entry: the LOCAL server leads, because it is the recommended connection for
8
+ * every desktop agent — it serves everything the hosted endpoint does PLUS
9
+ * the plugins' local-only tools — and the entries after it exist for the
10
+ * agents that cannot run a local process (web assistants, cloud platforms).
7
11
  *
8
12
  * This file is now the welcome page's PICKER and nothing else: which clients
9
13
  * to offer, what to call them, and how to say where the snippet goes. The
@@ -20,7 +24,7 @@ import { jsonConfigSnippet } from '../../shared/mcp';
20
24
  */
21
25
 
22
26
  export interface AgentClient {
23
- id: 'claude' | 'chatgpt' | 'other';
27
+ id: 'claude' | 'chatgpt' | 'other' | 'local';
24
28
  label: string;
25
29
  /** Where the snippet goes, said as the path through that client's own UI. */
26
30
  hint: string;
@@ -29,10 +33,20 @@ export interface AgentClient {
29
33
  }
30
34
 
31
35
  export const AGENT_CLIENTS: AgentClient[] = [
36
+ {
37
+ id: 'local',
38
+ label: 'Desktop agents',
39
+ hint: 'Recommended for Claude Code, Claude Desktop, Cursor, Windsurf, Cline and any agent that runs on your machine: everything the options below give, plus your plugins’ local-only tools. Needs Node. The first time it starts, your browser opens so you can sign in.',
40
+ // The passed endpoint is deliberately unused: the local server takes the
41
+ // WORKSPACE address and asks it for the MCP endpoint itself
42
+ // (`GET /api/config`), so the URL every other client pastes is the wrong
43
+ // value here — see `workspaceBaseUrl`.
44
+ snip: () => hexisMcpJsonSnippet(workspaceBaseUrl()),
45
+ },
32
46
  {
33
47
  id: 'claude',
34
48
  label: 'Claude',
35
- hint: 'claude.ai or Claude Desktop: Settings → Connectors → Add custom connector, then paste this. In Claude Code, `claude mcp add` takes the same URL.',
49
+ hint: 'For claude.ai on the web: Settings → Connectors → Add custom connector, then paste this. (On your own machine, Desktop agents is the better connection.)',
36
50
  snip: (url) => url,
37
51
  },
38
52
  {
@@ -45,8 +59,8 @@ export const AGENT_CLIENTS: AgentClient[] = [
45
59
  },
46
60
  {
47
61
  id: 'other',
48
- label: 'Cursor & Others',
49
- hint: 'For clients that read their servers from a JSON config, like Cursor, Windsurf and Cline.',
62
+ label: 'Other',
63
+ hint: 'For web and cloud clients that read their servers from a JSON config but can’t run a local process.',
50
64
  snip: (url) => jsonConfigSnippet(url),
51
65
  },
52
66
  ];
@@ -38,7 +38,7 @@ export function WelcomePage() {
38
38
  const onboarding = useOnboarding();
39
39
  const toast = useLibraryToast();
40
40
  const navigate = useNavigate();
41
- const [clientId, setClientId] = useState<AgentClient['id']>('claude');
41
+ const [clientId, setClientId] = useState<AgentClient['id']>('local');
42
42
  const [copied, setCopied] = useState<'idle' | 'ok' | 'fail'>('idle');
43
43
 
44
44
  // Once, on arrival — this is what makes the welcome redirect one-time.
@@ -1,5 +1,5 @@
1
1
  import { useMemo } from 'react';
2
- import { Boxes, CircleUserRound, KeyRound, Lock, SlidersHorizontal, Users } from 'lucide-react';
2
+ import { Boxes, CircleUserRound, KeyRound, Lock, SlidersHorizontal, Users, UsersRound } from 'lucide-react';
3
3
  import { useAppRegistry, type AdminMenuItem } from '../../core/registry';
4
4
 
5
5
  /**
@@ -79,6 +79,14 @@ export const CORE_MENU_ITEMS: AdminMenuItem[] = [
79
79
  label: 'Roles & Members',
80
80
  path: '/roles-and-members',
81
81
  },
82
+ {
83
+ id: 'directory-groups',
84
+ section: 'admin',
85
+ order: 15,
86
+ icon: <UsersRound size={15} />,
87
+ label: 'Groups',
88
+ path: '/directory-groups',
89
+ },
82
90
  {
83
91
  id: 'user-accounts',
84
92
  section: 'admin',
@@ -6,11 +6,15 @@ import { PageShell } from '../../../shared/components/PageShell';
6
6
  import { buttonClasses } from '../../../shared/components';
7
7
  import {
8
8
  ConnectionInstructions,
9
+ CopyBlock,
9
10
  claudeCodeCommand,
11
+ hexisMcpClaudeCommand,
12
+ hexisMcpJsonSnippet,
10
13
  jsonConfigSnippet,
11
14
  langdockSnippet,
12
15
  mcpEndpointUrl,
13
16
  useCopyFeedback,
17
+ workspaceBaseUrl,
14
18
  } from '../../../shared/mcp';
15
19
  import {
16
20
  type ExternalApiKeySummary,
@@ -65,6 +69,14 @@ export function ExternalAgentAccessPage() {
65
69
  */
66
70
  const mcpUrl = mcpEndpointUrl();
67
71
 
72
+ /**
73
+ * The LOCAL server's address is the one exception to "everything quotes
74
+ * `mcpUrl`": `hexis-mcp` takes the workspace's base and resolves the MCP
75
+ * endpoint from it itself, so handing it the endpoint would be wrong twice
76
+ * over. See `workspaceBaseUrl` for why the origin is the right base.
77
+ */
78
+ const workspaceUrl = workspaceBaseUrl();
79
+
68
80
  const [tab, setTab] = useState<'agent' | 'autonomous'>('agent');
69
81
  const [keys, setKeys] = useState<ExternalApiKeySummary[]>([]);
70
82
  const [loading, setLoading] = useState(false);
@@ -188,25 +200,90 @@ export function ExternalAgentAccessPage() {
188
200
  {tab === 'agent' && (
189
201
  <div className="px-4 py-3 space-y-4">
190
202
  <p className="text-xs text-ink-muted leading-snug">
191
- Connect your own agent: Claude Code, Claude Desktop, Cursor and similar. No key
192
- needed: the first time the agent connects, your browser opens so you can sign in and
193
- choose which tools to share with it. Everything it saves appears under your name.
203
+ Pick where your agent runs. Everything it saves appears under your name.
194
204
  </p>
195
- {/* `buttonClasses`, not a hand-rolled class string — the one
196
- button primitive exists because 171 sites once shared 153
197
- variants between them, and its docstring prescribes exactly
198
- this shape for links. */}
199
- <Link
200
- to="/connect"
201
- target="_blank"
202
- rel="noopener noreferrer"
203
- className={buttonClasses({ variant: 'outline', size: 'sm', className: 'w-full' })}
204
- >
205
- <Wrench size={12} />
206
- Configure your tools
207
- <ExternalLink size={11} className="opacity-60" aria-hidden="true" />
208
- </Link>
209
- <ConnectionInstructions mcpUrl={mcpUrl} />
205
+ {/* LOCAL FIRST. The local server is the recommended connection for
206
+ every agent that can run it — it serves everything the hosted
207
+ endpoint does PLUS the plugins' local-only tools — so its drawer
208
+ leads, and the hosted URL follows for the agents that cannot
209
+ (web assistants, cloud platforms). Two CLOSED drawers, native
210
+ <details> (the SecretsPage "Advanced" precedent): the choice is
211
+ the headline, and neither config wall is worth reading until
212
+ the reader has picked their side of it. */}
213
+ <details className="border border-line rounded">
214
+ <summary className="cursor-pointer px-3 py-2 text-xs font-medium text-ink">
215
+ Desktop agents: Claude Code, Claude Desktop, Cursor, Windsurf, Cline and similar
216
+ </summary>
217
+ <div className="px-3 pb-3 space-y-2">
218
+ <p className="text-meta text-ink-muted leading-snug">
219
+ Recommended: runs this workspace as a local MCP server (needs Node), so the
220
+ agent gets everything the hosted endpoint serves, plus your plugins'
221
+ local-only tools — the ones{' '}
222
+ <span className="font-mono">list_local_tools</span> names. No key needed: the
223
+ first time it starts, your browser opens so you can sign in. (A pipeline that
224
+ can't open a browser passes an external API key instead — the{' '}
225
+ <button
226
+ type="button"
227
+ onClick={() => setTab('autonomous')}
228
+ className="underline text-ink-muted hover:text-ink"
229
+ >
230
+ Autonomous agents
231
+ </button>{' '}
232
+ tab shows that setup.)
233
+ </p>
234
+ {/* "(local server)" disambiguates from the hosted drawer's
235
+ ConnectionInstructions block, which labels ITS command
236
+ "Connect Claude Code" — two identically named blocks on one
237
+ page with different commands is a paste-the-wrong-one trap. */}
238
+ <CopyBlock
239
+ label="Connect Claude Code (local server)"
240
+ value={hexisMcpClaudeCommand(workspaceUrl)}
241
+ rows={3}
242
+ />
243
+ <p className="text-meta text-ink-muted leading-snug">
244
+ On Windows, prefer the JSON config below — this one-liner assumes a POSIX shell
245
+ (macOS, Linux, WSL or Git Bash).
246
+ </p>
247
+ <div>
248
+ <p className="text-meta text-ink-muted mb-1 leading-snug">
249
+ Cursor, Windsurf and Cline take this JSON in their MCP config. Claude
250
+ Desktop takes it too, in its config file: Settings → Developer → Edit
251
+ Config (its Connectors UI only adds remote servers).
252
+ </p>
253
+ <CopyBlock label={null} value={hexisMcpJsonSnippet(workspaceUrl)} rows={12} />
254
+ </div>
255
+ </div>
256
+ </details>
257
+
258
+ <details className="border border-line rounded">
259
+ <summary className="cursor-pointer px-3 py-2 text-xs font-medium text-ink">
260
+ Any other agent
261
+ </summary>
262
+ <div className="px-3 pb-3 space-y-3">
263
+ <p className="text-meta text-ink-muted leading-snug">
264
+ claude.ai, ChatGPT and other agents that can't run a process on your machine
265
+ connect to the hosted endpoint. No key needed: the first time the agent
266
+ connects, your browser opens so you can sign in and choose which tools to
267
+ share with it.
268
+ </p>
269
+ {/* `buttonClasses`, not a hand-rolled class string — the one
270
+ button primitive exists because 171 sites once shared 153
271
+ variants between them, and its docstring prescribes exactly
272
+ this shape for links. */}
273
+ <Link
274
+ to="/connect"
275
+ target="_blank"
276
+ rel="noopener noreferrer"
277
+ className={buttonClasses({ variant: 'outline', size: 'sm', className: 'w-full' })}
278
+ >
279
+ <Wrench size={12} />
280
+ Configure your tools
281
+ <ExternalLink size={11} className="opacity-60" aria-hidden="true" />
282
+ </Link>
283
+ <ConnectionInstructions mcpUrl={mcpUrl} />
284
+ </div>
285
+ </details>
286
+
210
287
  <p className="text-[11px] text-ink-muted leading-snug">
211
288
  Running an unattended pipeline or CI agent that can't open a browser? Use the{' '}
212
289
  <button
@@ -410,8 +487,45 @@ export function ExternalAgentAccessPage() {
410
487
  </div>
411
488
  <div>
412
489
  <div className="text-xs font-medium text-ink mb-1">
413
- Connect Claude Code
490
+ Desktop agents — the local server (recommended)
491
+ </div>
492
+ <p className="text-meta text-ink-muted mb-1 leading-snug">
493
+ For agents that run on your machine: Claude Code, Claude Desktop, Cursor,
494
+ Windsurf, Cline and similar. Runs this workspace as a local MCP server (needs
495
+ Node): the agent gets everything the hosted endpoint serves, plus your
496
+ plugins' local-only tools. In Claude Code:
497
+ </p>
498
+ <textarea
499
+ readOnly
500
+ value={hexisMcpClaudeCommand(workspaceUrl, reveal.plaintext)}
501
+ rows={3}
502
+ className="w-full font-mono text-meta bg-sunken border border-line rounded px-2 py-1.5 resize-none"
503
+ onFocus={(e) => e.currentTarget.select()}
504
+ />
505
+ <p className="text-meta text-ink-muted mt-1 leading-snug">
506
+ On Windows, prefer the JSON config below — this one-liner assumes a POSIX
507
+ shell (macOS, Linux, WSL or Git Bash).
508
+ </p>
509
+ <p className="text-meta text-ink-muted mt-2 mb-1 leading-snug">
510
+ Or as a JSON config, for Claude Desktop, Cursor, Windsurf, Cline and
511
+ similar:
512
+ </p>
513
+ <textarea
514
+ readOnly
515
+ value={hexisMcpJsonSnippet(workspaceUrl, reveal.plaintext)}
516
+ rows={13}
517
+ className="w-full font-mono text-meta bg-sunken border border-line rounded px-2 py-1.5 resize-none"
518
+ onFocus={(e) => e.currentTarget.select()}
519
+ />
520
+ </div>
521
+ <div>
522
+ <div className="text-xs font-medium text-ink mb-1">
523
+ Web agents and pipelines — the hosted endpoint
414
524
  </div>
525
+ <p className="text-meta text-ink-muted mb-1 leading-snug">
526
+ For agents that can't run a process on your machine, and for CI where
527
+ installing Node is unwanted. Claude Code, via the hosted endpoint:
528
+ </p>
415
529
  <textarea
416
530
  readOnly
417
531
  value={claudeCodeCommand(mcpUrl, reveal.plaintext)}
@@ -443,7 +557,8 @@ export function ExternalAgentAccessPage() {
443
557
  Other agents (JSON config)
444
558
  </div>
445
559
  <p className="text-[11px] text-ink-muted mb-1 leading-snug">
446
- Works with Claude Desktop, Cursor, Windsurf, Cline, and most clients that load servers from a JSON config.
560
+ The hosted endpoint for most clients that load servers from a JSON config —
561
+ when the local server above isn't wanted.
447
562
  </p>
448
563
  <textarea
449
564
  readOnly