@tempoxyz/mercator 0.0.887 → 0.0.924
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.
- package/dist/claude-registrations.d.ts +3 -1
- package/dist/claude-registrations.js +5 -3
- package/dist/client-authorization.d.ts +12 -1
- package/dist/client-authorization.js +29 -15
- package/dist/client-binary.d.ts +81 -0
- package/dist/client-binary.js +192 -0
- package/dist/client-capabilities.js +3 -2
- package/dist/client-metadata.generated.d.ts +8 -1
- package/dist/client-metadata.generated.js +96 -14
- package/dist/clients.d.ts +15 -1
- package/dist/clients.js +99 -19
- package/dist/codex-registrations.d.ts +3 -1
- package/dist/codex-registrations.js +5 -3
- package/dist/command.d.ts +2 -0
- package/dist/command.js +10 -8
- package/dist/index.d.ts +2 -0
- package/dist/index.js +27 -9
- package/dist/refresh.d.ts +3 -0
- package/dist/refresh.js +8 -4
- package/dist/release.d.ts +9 -1
- package/dist/release.js +47 -28
- package/dist/setup-render.d.ts +1 -1
- package/dist/setup-render.js +33 -12
- package/dist/setup-update.js +2 -1
- package/dist/setup.d.ts +28 -0
- package/dist/setup.js +120 -24
- package/package.json +1 -1
|
@@ -5,4 +5,6 @@ export type ClaudeRegistration = {
|
|
|
5
5
|
action: string;
|
|
6
6
|
};
|
|
7
7
|
/** Inspect both registration surfaces without changing client configuration. */
|
|
8
|
-
export declare function inspectClaudeRegistrations(endpoint: string, run?: typeof runCapturedCommand
|
|
8
|
+
export declare function inspectClaudeRegistrations(endpoint: string, run?: typeof runCapturedCommand,
|
|
9
|
+
/** Executable chosen by the client resolver; defaults to `claude` on PATH. */
|
|
10
|
+
command?: string): Promise<ClaudeRegistration>;
|
|
@@ -14,9 +14,11 @@ const pluginList = z.array(z.object({
|
|
|
14
14
|
mcpServers: z.record(z.string(), z.unknown()).optional(),
|
|
15
15
|
}));
|
|
16
16
|
/** Inspect both registration surfaces without changing client configuration. */
|
|
17
|
-
export async function inspectClaudeRegistrations(endpoint, run = runCapturedCommand
|
|
17
|
+
export async function inspectClaudeRegistrations(endpoint, run = runCapturedCommand,
|
|
18
|
+
/** Executable chosen by the client resolver; defaults to `claude` on PATH. */
|
|
19
|
+
command = 'claude') {
|
|
18
20
|
const options = { includeStderr: true, maxOutputBytes: 128 * 1024, timeoutMs: 10_000 };
|
|
19
|
-
const listed = await run(
|
|
21
|
+
const listed = await run(command, ['plugin', 'list', '--json'], options);
|
|
20
22
|
let parsed;
|
|
21
23
|
try {
|
|
22
24
|
parsed = pluginList.safeParse(JSON.parse(listed.output));
|
|
@@ -48,7 +50,7 @@ export async function inspectClaudeRegistrations(endpoint, run = runCapturedComm
|
|
|
48
50
|
(server.data.url !== endpoint &&
|
|
49
51
|
!(hostedEndpoints.has(server.data.url) && hostedEndpoints.has(endpoint))))
|
|
50
52
|
return conflict('Mercator plugin MCP could not be matched to the requested endpoint. Existing entries were preserved. Inspect claude plugin list --json and verify the plugin in /mcp; use native plugin controls to change it.');
|
|
51
|
-
const standalone = await run(
|
|
53
|
+
const standalone = await run(command, ['mcp', 'get', 'mercator'], options);
|
|
52
54
|
if (standalone.code !== 0) {
|
|
53
55
|
if (/^No MCP server (?:found with name: mercator(?:\n|$)|named "mercator"\.)/i.test(standalone.output))
|
|
54
56
|
return {
|
|
@@ -1,3 +1,14 @@
|
|
|
1
1
|
import { type ClientId } from './clients.js';
|
|
2
2
|
/** Native authorization and free verification steps for the selected client. */
|
|
3
|
-
export declare function clientAuthorizationGuidance(client: ClientId, endpoint: string
|
|
3
|
+
export declare function clientAuthorizationGuidance(client: ClientId, endpoint: string,
|
|
4
|
+
/** Executable to name in shell steps; see `guidanceExecutable`. Undefined keeps the bare name. */
|
|
5
|
+
executable?: string, platform?: NodeJS.Platform): string | undefined;
|
|
6
|
+
/** Command prefix that runs `path` in the platform's default shell (PowerShell on Windows). */
|
|
7
|
+
export declare function shellCommand(path: string, platform?: NodeJS.Platform): string;
|
|
8
|
+
/** Steps that load a newly written registration in the client. */
|
|
9
|
+
export declare function clientActivationGuidance(client: ClientId): string;
|
|
10
|
+
/**
|
|
11
|
+
* Per-client readiness after setup. Setup cannot read a client's OAuth tokens, so a hosted
|
|
12
|
+
* OAuth registration stays `authorization_pending` until the user authorizes in that client.
|
|
13
|
+
*/
|
|
14
|
+
export declare function clientReadiness(client: ClientId, endpoint: string): 'authorization_pending' | 'registration_written';
|
|
@@ -1,20 +1,34 @@
|
|
|
1
1
|
import { isProtectedMcpEndpoint } from './client-endpoint.js';
|
|
2
|
-
import {
|
|
2
|
+
import { CLIENT_DEFINITIONS, CLIENT_METADATA } from './clients.js';
|
|
3
3
|
/** Native authorization and free verification steps for the selected client. */
|
|
4
|
-
export function clientAuthorizationGuidance(client, endpoint
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
? 'Run muse mcp login mercator to authorize if needed, then start a new Muse session and check /mcp.'
|
|
8
|
-
: 'Start a new Muse session and check /mcp.';
|
|
4
|
+
export function clientAuthorizationGuidance(client, endpoint,
|
|
5
|
+
/** Executable to name in shell steps; see `guidanceExecutable`. Undefined keeps the bare name. */
|
|
6
|
+
executable, platform = process.platform) {
|
|
9
7
|
if (!isProtectedMcpEndpoint(endpoint))
|
|
10
8
|
return undefined;
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
9
|
+
const command = CLIENT_DEFINITIONS[client].command;
|
|
10
|
+
const auth = executable && command && executable !== command
|
|
11
|
+
? CLIENT_METADATA[client].auth.replaceAll(`${command} mcp `, `${shellCommand(executable, platform)} mcp `)
|
|
12
|
+
: CLIENT_METADATA[client].auth;
|
|
13
|
+
return `${auth} Then call search_services and get_connection_status in ${CLIENT_METADATA[client].label}.`;
|
|
14
|
+
}
|
|
15
|
+
/** Command prefix that runs `path` in the platform's default shell (PowerShell on Windows). */
|
|
16
|
+
export function shellCommand(path, platform = process.platform) {
|
|
17
|
+
if (platform === 'win32')
|
|
18
|
+
return /^[\w.:\\/-]+$/.test(path) ? path : `& '${path.replaceAll("'", "''")}'`;
|
|
19
|
+
return /^[\w./:=@-]+$/.test(path) ? path : `'${path.replaceAll("'", "'\\''")}'`;
|
|
20
|
+
}
|
|
21
|
+
/** Steps that load a newly written registration in the client. */
|
|
22
|
+
export function clientActivationGuidance(client) {
|
|
23
|
+
return CLIENT_METADATA[client].activation;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Per-client readiness after setup. Setup cannot read a client's OAuth tokens, so a hosted
|
|
27
|
+
* OAuth registration stays `authorization_pending` until the user authorizes in that client.
|
|
28
|
+
*/
|
|
29
|
+
export function clientReadiness(client, endpoint) {
|
|
30
|
+
return CLIENT_METADATA[client].paymentMode === 'hosted-wallet' &&
|
|
31
|
+
isProtectedMcpEndpoint(endpoint)
|
|
32
|
+
? 'authorization_pending'
|
|
33
|
+
: 'registration_written';
|
|
20
34
|
}
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
import { type ClientId } from './clients.js';
|
|
2
|
+
/**
|
|
3
|
+
* Oldest client versions known to complete Mercator's hosted OAuth flow.
|
|
4
|
+
*
|
|
5
|
+
* Codex 0.151.0 is the first stable release containing openai/codex#40691, which reads and
|
|
6
|
+
* validates the RFC 9207 `iss` callback parameter. Codex 0.144.0 discards it and fails with
|
|
7
|
+
* "Authorization server response missing required issuer"; 0.155.0-alpha.16 is verified working.
|
|
8
|
+
*/
|
|
9
|
+
export declare const MINIMUM_CLIENT_VERSIONS: Readonly<Partial<Record<ClientId, string>>>;
|
|
10
|
+
/** Where a selected client executable came from, in precedence order. */
|
|
11
|
+
type ExecutableSource = 'flag' | 'environment' | 'path' | 'bundle';
|
|
12
|
+
/** One discovered client executable and its reported version, when probed. */
|
|
13
|
+
export type ClientExecutable = {
|
|
14
|
+
readonly path: string;
|
|
15
|
+
/** A later PATH match that the bare command name does not reach in the user's shell. */
|
|
16
|
+
readonly shadowed?: true;
|
|
17
|
+
readonly source: ExecutableSource;
|
|
18
|
+
readonly version?: string;
|
|
19
|
+
};
|
|
20
|
+
/**
|
|
21
|
+
* Selection outcome. `incompatible` means candidates exist but none meets the minimum version;
|
|
22
|
+
* an explicit override below the minimum still resolves, with `belowMinimum` set.
|
|
23
|
+
*/
|
|
24
|
+
export type ExecutableResolution = {
|
|
25
|
+
readonly status: 'resolved';
|
|
26
|
+
readonly executable: ClientExecutable;
|
|
27
|
+
readonly belowMinimum?: true;
|
|
28
|
+
readonly minimumVersion?: string;
|
|
29
|
+
/** Discovered candidates skipped for being older than the minimum version. */
|
|
30
|
+
readonly rejected?: readonly ClientExecutable[];
|
|
31
|
+
} | {
|
|
32
|
+
readonly status: 'incompatible';
|
|
33
|
+
readonly candidates: readonly ClientExecutable[];
|
|
34
|
+
readonly minimumVersion: string;
|
|
35
|
+
} | {
|
|
36
|
+
readonly status: 'invalid_override';
|
|
37
|
+
readonly path: string;
|
|
38
|
+
} | {
|
|
39
|
+
readonly status: 'missing';
|
|
40
|
+
};
|
|
41
|
+
/** Platform effects used by executable discovery; injectable for tests. */
|
|
42
|
+
export type ExecutableEffects = {
|
|
43
|
+
readonly env: Readonly<Record<string, string | undefined>>;
|
|
44
|
+
readonly home: string;
|
|
45
|
+
readonly platform: NodeJS.Platform;
|
|
46
|
+
readonly findOnPath: (command: string) => readonly string[];
|
|
47
|
+
readonly isExecutable: (path: string) => Promise<boolean>;
|
|
48
|
+
readonly readVersion: (path: string) => Promise<string | undefined>;
|
|
49
|
+
};
|
|
50
|
+
/** Environment variable that overrides one client's executable, e.g. `MERCATOR_CODEX_BIN`. */
|
|
51
|
+
export declare function executableOverrideVariable(client: ClientId): string;
|
|
52
|
+
/**
|
|
53
|
+
* Selects the executable setup should run for a command-based client.
|
|
54
|
+
*
|
|
55
|
+
* Precedence: `flagPath`, then `MERCATOR_<CLIENT>_BIN`, then discovery across PATH and known
|
|
56
|
+
* application bundles. Clients with a minimum version get every candidate probed with
|
|
57
|
+
* `--version` and the newest compatible one wins; others use the first candidate without
|
|
58
|
+
* launching it.
|
|
59
|
+
*/
|
|
60
|
+
export declare function resolveClientExecutable(client: ClientId, options?: {
|
|
61
|
+
readonly flagPath?: string;
|
|
62
|
+
}, overrides?: Partial<ExecutableEffects>): Promise<ExecutableResolution>;
|
|
63
|
+
/**
|
|
64
|
+
* Executable for client CLI calls outside setup (status, doctor, uninstall, refresh), so an
|
|
65
|
+
* override or app-bundle install is used consistently. Undefined keeps the PATH command name.
|
|
66
|
+
*/
|
|
67
|
+
export declare function resolvedExecutable(client: ClientId, resolve: typeof resolveClientExecutable | undefined): Promise<ClientExecutable | undefined>;
|
|
68
|
+
/** Absolute path counterpart of {@link resolvedExecutable}. */
|
|
69
|
+
export declare function resolvedExecutablePath(client: ClientId, resolve: typeof resolveClientExecutable | undefined): Promise<string | undefined>;
|
|
70
|
+
/**
|
|
71
|
+
* Path to print in user-run shell commands, or undefined when the bare command name already
|
|
72
|
+
* reaches the selected executable (the first PATH match). Keeps guidance short and portable.
|
|
73
|
+
*/
|
|
74
|
+
export declare function guidanceExecutable(executable: ClientExecutable | undefined): string | undefined;
|
|
75
|
+
/** Extracts the first semantic version (with optional prerelease) from `--version` output. */
|
|
76
|
+
export declare function parseClientVersion(output: string): string | undefined;
|
|
77
|
+
/** Compares semantic versions, ranking prereleases below their release (SemVer 2.0 §11). */
|
|
78
|
+
export declare function compareClientVersions(left: string, right: string): number;
|
|
79
|
+
/** Human-readable selection, e.g. `/opt/homebrew/bin/codex (0.155.0)`. */
|
|
80
|
+
export declare function describeExecutable(executable: ClientExecutable): string;
|
|
81
|
+
export {};
|
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
import { access, constants, stat } from 'node:fs/promises';
|
|
2
|
+
import { homedir } from 'node:os';
|
|
3
|
+
import { isAbsolute } from 'node:path';
|
|
4
|
+
import { bundlePaths, CLIENT_DEFINITIONS } from './clients.js';
|
|
5
|
+
import { findExecutables, runCapturedCommand } from './command.js';
|
|
6
|
+
/**
|
|
7
|
+
* Oldest client versions known to complete Mercator's hosted OAuth flow.
|
|
8
|
+
*
|
|
9
|
+
* Codex 0.151.0 is the first stable release containing openai/codex#40691, which reads and
|
|
10
|
+
* validates the RFC 9207 `iss` callback parameter. Codex 0.144.0 discards it and fails with
|
|
11
|
+
* "Authorization server response missing required issuer"; 0.155.0-alpha.16 is verified working.
|
|
12
|
+
*/
|
|
13
|
+
export const MINIMUM_CLIENT_VERSIONS = {
|
|
14
|
+
codex: '0.151.0',
|
|
15
|
+
};
|
|
16
|
+
/** Environment variable that overrides one client's executable, e.g. `MERCATOR_CODEX_BIN`. */
|
|
17
|
+
export function executableOverrideVariable(client) {
|
|
18
|
+
return `MERCATOR_${client.toUpperCase()}_BIN`;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Selects the executable setup should run for a command-based client.
|
|
22
|
+
*
|
|
23
|
+
* Precedence: `flagPath`, then `MERCATOR_<CLIENT>_BIN`, then discovery across PATH and known
|
|
24
|
+
* application bundles. Clients with a minimum version get every candidate probed with
|
|
25
|
+
* `--version` and the newest compatible one wins; others use the first candidate without
|
|
26
|
+
* launching it.
|
|
27
|
+
*/
|
|
28
|
+
export async function resolveClientExecutable(client, options = {}, overrides = {}) {
|
|
29
|
+
const effects = {
|
|
30
|
+
env: process.env,
|
|
31
|
+
findOnPath: (command) => findExecutables(command),
|
|
32
|
+
home: homedir(),
|
|
33
|
+
isExecutable,
|
|
34
|
+
platform: process.platform,
|
|
35
|
+
readVersion: readExecutableVersion,
|
|
36
|
+
...overrides,
|
|
37
|
+
};
|
|
38
|
+
const command = CLIENT_DEFINITIONS[client].command;
|
|
39
|
+
if (!command)
|
|
40
|
+
return { status: 'missing' };
|
|
41
|
+
const minimumVersion = MINIMUM_CLIENT_VERSIONS[client];
|
|
42
|
+
const explicit = options.flagPath
|
|
43
|
+
? { path: options.flagPath, source: 'flag' }
|
|
44
|
+
: effects.env[executableOverrideVariable(client)]
|
|
45
|
+
? {
|
|
46
|
+
path: effects.env[executableOverrideVariable(client)],
|
|
47
|
+
source: 'environment',
|
|
48
|
+
}
|
|
49
|
+
: undefined;
|
|
50
|
+
if (explicit) {
|
|
51
|
+
if (!isAbsolute(explicit.path) || !(await effects.isExecutable(explicit.path)))
|
|
52
|
+
return { path: explicit.path, status: 'invalid_override' };
|
|
53
|
+
const version = minimumVersion ? await effects.readVersion(explicit.path) : undefined;
|
|
54
|
+
const executable = { ...explicit, ...(version ? { version } : {}) };
|
|
55
|
+
return {
|
|
56
|
+
executable,
|
|
57
|
+
status: 'resolved',
|
|
58
|
+
...(minimumVersion ? { minimumVersion } : {}),
|
|
59
|
+
...(minimumVersion && !meetsMinimum(version, minimumVersion)
|
|
60
|
+
? { belowMinimum: true }
|
|
61
|
+
: {}),
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
const discovered = [];
|
|
65
|
+
const seen = new Set();
|
|
66
|
+
for (const path of effects.findOnPath(command)) {
|
|
67
|
+
if (seen.has(path))
|
|
68
|
+
continue;
|
|
69
|
+
seen.add(path);
|
|
70
|
+
discovered.push(discovered.length === 0
|
|
71
|
+
? { path, source: 'path' }
|
|
72
|
+
: { path, shadowed: true, source: 'path' });
|
|
73
|
+
}
|
|
74
|
+
for (const path of bundlePaths(CLIENT_DEFINITIONS[client], effects.home, effects.platform)) {
|
|
75
|
+
if (seen.has(path) || !(await effects.isExecutable(path)))
|
|
76
|
+
continue;
|
|
77
|
+
seen.add(path);
|
|
78
|
+
discovered.push({ path, source: 'bundle' });
|
|
79
|
+
}
|
|
80
|
+
if (discovered.length === 0)
|
|
81
|
+
return { status: 'missing' };
|
|
82
|
+
if (!minimumVersion)
|
|
83
|
+
return { executable: discovered[0], status: 'resolved' };
|
|
84
|
+
const probed = await Promise.all(discovered.map(async (candidate) => {
|
|
85
|
+
const version = await effects.readVersion(candidate.path);
|
|
86
|
+
return version ? { ...candidate, version } : candidate;
|
|
87
|
+
}));
|
|
88
|
+
const compatible = probed.filter(({ version }) => meetsMinimum(version, minimumVersion));
|
|
89
|
+
// Stable sort keeps PATH order among equal versions.
|
|
90
|
+
const newest = [...compatible].sort((left, right) => compareClientVersions(right.version, left.version))[0];
|
|
91
|
+
const rejected = probed.filter(({ version }) => !meetsMinimum(version, minimumVersion));
|
|
92
|
+
return newest
|
|
93
|
+
? {
|
|
94
|
+
executable: newest,
|
|
95
|
+
minimumVersion,
|
|
96
|
+
...(rejected.length > 0 ? { rejected } : {}),
|
|
97
|
+
status: 'resolved',
|
|
98
|
+
}
|
|
99
|
+
: { candidates: probed, minimumVersion, status: 'incompatible' };
|
|
100
|
+
}
|
|
101
|
+
/**
|
|
102
|
+
* Executable for client CLI calls outside setup (status, doctor, uninstall, refresh), so an
|
|
103
|
+
* override or app-bundle install is used consistently. Undefined keeps the PATH command name.
|
|
104
|
+
*/
|
|
105
|
+
export async function resolvedExecutable(client, resolve) {
|
|
106
|
+
if (!resolve || !CLIENT_DEFINITIONS[client].command)
|
|
107
|
+
return undefined;
|
|
108
|
+
const resolution = await resolve(client);
|
|
109
|
+
return resolution.status === 'resolved' ? resolution.executable : undefined;
|
|
110
|
+
}
|
|
111
|
+
/** Absolute path counterpart of {@link resolvedExecutable}. */
|
|
112
|
+
export async function resolvedExecutablePath(client, resolve) {
|
|
113
|
+
return (await resolvedExecutable(client, resolve))?.path;
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Path to print in user-run shell commands, or undefined when the bare command name already
|
|
117
|
+
* reaches the selected executable (the first PATH match). Keeps guidance short and portable.
|
|
118
|
+
*/
|
|
119
|
+
export function guidanceExecutable(executable) {
|
|
120
|
+
if (!executable)
|
|
121
|
+
return undefined;
|
|
122
|
+
return executable.source === 'path' && !executable.shadowed
|
|
123
|
+
? undefined
|
|
124
|
+
: executable.path;
|
|
125
|
+
}
|
|
126
|
+
/** Extracts the first semantic version (with optional prerelease) from `--version` output. */
|
|
127
|
+
export function parseClientVersion(output) {
|
|
128
|
+
return /\b(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\b/.exec(output)?.[1];
|
|
129
|
+
}
|
|
130
|
+
/** Compares semantic versions, ranking prereleases below their release (SemVer 2.0 §11). */
|
|
131
|
+
export function compareClientVersions(left, right) {
|
|
132
|
+
const [leftCore = '', leftPre] = splitVersion(left);
|
|
133
|
+
const [rightCore = '', rightPre] = splitVersion(right);
|
|
134
|
+
const a = leftCore.split('.').map(Number);
|
|
135
|
+
const b = rightCore.split('.').map(Number);
|
|
136
|
+
for (let index = 0; index < 3; index++) {
|
|
137
|
+
const difference = (a[index] ?? 0) - (b[index] ?? 0);
|
|
138
|
+
if (difference !== 0)
|
|
139
|
+
return Math.sign(difference);
|
|
140
|
+
}
|
|
141
|
+
if (leftPre === undefined || rightPre === undefined)
|
|
142
|
+
return leftPre === rightPre ? 0 : leftPre === undefined ? 1 : -1;
|
|
143
|
+
const x = leftPre.split('.');
|
|
144
|
+
const y = rightPre.split('.');
|
|
145
|
+
for (let index = 0; index < Math.max(x.length, y.length); index++) {
|
|
146
|
+
const l = x[index];
|
|
147
|
+
const r = y[index];
|
|
148
|
+
if (l === undefined)
|
|
149
|
+
return -1;
|
|
150
|
+
if (r === undefined)
|
|
151
|
+
return 1;
|
|
152
|
+
const ln = /^\d+$/.test(l);
|
|
153
|
+
const rn = /^\d+$/.test(r);
|
|
154
|
+
if (ln && rn && Number(l) !== Number(r))
|
|
155
|
+
return Math.sign(Number(l) - Number(r));
|
|
156
|
+
if (ln !== rn)
|
|
157
|
+
return ln ? -1 : 1;
|
|
158
|
+
if (l !== r)
|
|
159
|
+
return l < r ? -1 : 1;
|
|
160
|
+
}
|
|
161
|
+
return 0;
|
|
162
|
+
}
|
|
163
|
+
/** Human-readable selection, e.g. `/opt/homebrew/bin/codex (0.155.0)`. */
|
|
164
|
+
export function describeExecutable(executable) {
|
|
165
|
+
return `${executable.path}${executable.version ? ` (${executable.version})` : ''}`;
|
|
166
|
+
}
|
|
167
|
+
function splitVersion(version) {
|
|
168
|
+
const index = version.indexOf('-');
|
|
169
|
+
return index === -1
|
|
170
|
+
? [version, undefined]
|
|
171
|
+
: [version.slice(0, index), version.slice(index + 1)];
|
|
172
|
+
}
|
|
173
|
+
function meetsMinimum(version, minimum) {
|
|
174
|
+
return version !== undefined && compareClientVersions(version, minimum) >= 0;
|
|
175
|
+
}
|
|
176
|
+
async function isExecutable(path) {
|
|
177
|
+
try {
|
|
178
|
+
await access(path, constants.X_OK);
|
|
179
|
+
return (await stat(path)).isFile();
|
|
180
|
+
}
|
|
181
|
+
catch {
|
|
182
|
+
return false;
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
async function readExecutableVersion(path) {
|
|
186
|
+
const result = await runCapturedCommand(path, ['--version'], {
|
|
187
|
+
includeStderr: true,
|
|
188
|
+
maxOutputBytes: 4_096,
|
|
189
|
+
timeoutMs: 5_000,
|
|
190
|
+
});
|
|
191
|
+
return result.code === 0 ? parseClientVersion(result.output) : undefined;
|
|
192
|
+
}
|
|
@@ -23,7 +23,7 @@ export async function prepareSetupPlan(plan, run = runCapturedCommand) {
|
|
|
23
23
|
throw new Error(`The installed ${plan.command} CLI does not advertise ${flag} ${value}. ${guidance}`);
|
|
24
24
|
}
|
|
25
25
|
// JSON-based registration has no flags; require its actual set/config command help.
|
|
26
|
-
if (plan.
|
|
26
|
+
if (plan.check?.client === 'openclaw' &&
|
|
27
27
|
(!/\bset\b/i.test(help.output) || !/\b(?:json|config)\b/i.test(help.output)))
|
|
28
28
|
throw new Error(`The installed OpenClaw CLI does not advertise MCP JSON configuration. ${guidance}`);
|
|
29
29
|
const protectedEndpoint = plan.check !== undefined && isProtectedMcpEndpoint(plan.check.url);
|
|
@@ -33,7 +33,8 @@ export async function prepareSetupPlan(plan, run = runCapturedCommand) {
|
|
|
33
33
|
advertisesFlag(help.output, '--oauth-client-registration') &&
|
|
34
34
|
/\bdcr\b/.test(help.output))
|
|
35
35
|
return plan;
|
|
36
|
-
if (protectedEndpoint &&
|
|
36
|
+
if (protectedEndpoint &&
|
|
37
|
+
(plan.check?.client === 'codex' || plan.check?.client === 'openclaw')) {
|
|
37
38
|
const login = await run(plan.command, ['mcp', 'login', '--help'], helpOptions);
|
|
38
39
|
if (login.code !== 0 || !/\blogin\b/.test(login.output))
|
|
39
40
|
throw new Error(`The installed ${plan.command} CLI does not advertise native MCP OAuth login. ${guidance}`);
|
|
@@ -22,11 +22,18 @@ export type ClientId = (typeof Client)[keyof typeof Client];
|
|
|
22
22
|
export type ClientPaymentMode = 'hosted-wallet' | 'native-mpp';
|
|
23
23
|
/** Runtime-agnostic client metadata shared by setup and product surfaces. */
|
|
24
24
|
export type ClientMetadata = {
|
|
25
|
+
/** How to load a newly written registration (reload, restart, or new session). */
|
|
26
|
+
readonly activation: string;
|
|
27
|
+
/**
|
|
28
|
+
* How to complete the client's own OAuth for the hosted endpoint. Setup never verifies it;
|
|
29
|
+
* native-MPP clients describe their payment step instead.
|
|
30
|
+
*/
|
|
31
|
+
readonly auth: string;
|
|
25
32
|
readonly integration: 'MCP' | 'plugin + MCP';
|
|
26
33
|
readonly label: string;
|
|
27
34
|
readonly paymentMode: ClientPaymentMode;
|
|
28
35
|
};
|
|
29
|
-
/** Authoritative labels, integrations, and
|
|
36
|
+
/** Authoritative labels, integrations, activation and auth steps for supported clients. */
|
|
30
37
|
export declare const CLIENT_METADATA: Readonly<Record<ClientId, ClientMetadata>>;
|
|
31
38
|
/** Stable client IDs in setup and display order. */
|
|
32
39
|
export declare const CLIENT_IDS: ClientId[];
|
|
@@ -17,31 +17,113 @@ export const Client = {
|
|
|
17
17
|
Windsurf: 'windsurf',
|
|
18
18
|
Zed: 'zed',
|
|
19
19
|
};
|
|
20
|
-
/** Authoritative labels, integrations, and
|
|
20
|
+
/** Authoritative labels, integrations, activation and auth steps for supported clients. */
|
|
21
21
|
export const CLIENT_METADATA = {
|
|
22
22
|
claude: {
|
|
23
|
+
activation: 'Start a new Claude Code session, or run /reload-plugins for plugin changes (use /reload-plugins --force if it warns about the prompt cache). Restart Claude Code if Mercator is still missing.',
|
|
24
|
+
auth: 'In Claude Code, open /mcp, select Mercator, and authenticate.',
|
|
23
25
|
integration: 'plugin + MCP',
|
|
24
26
|
label: 'Claude Code',
|
|
25
27
|
paymentMode: 'hosted-wallet',
|
|
26
28
|
},
|
|
27
|
-
cline: {
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
29
|
+
cline: {
|
|
30
|
+
activation: 'Start a new Cline CLI session to load the settings file.',
|
|
31
|
+
auth: 'Run cline mcp, select Mercator, and complete browser authorization; use Authorize OAuth to retry.',
|
|
32
|
+
integration: 'MCP',
|
|
33
|
+
label: 'Cline',
|
|
34
|
+
paymentMode: 'hosted-wallet',
|
|
35
|
+
},
|
|
36
|
+
codex: {
|
|
37
|
+
activation: 'Fully quit and reopen the Codex desktop app, or exit and resume the Codex CLI. Plugin refresh alone may not load a standalone MCP registration.',
|
|
38
|
+
auth: 'Run codex mcp login mercator, or authorize Mercator in the desktop app MCP settings.',
|
|
39
|
+
integration: 'MCP',
|
|
40
|
+
label: 'Codex',
|
|
41
|
+
paymentMode: 'hosted-wallet',
|
|
42
|
+
},
|
|
43
|
+
continue: {
|
|
44
|
+
activation: 'Reload the editor window so Continue reads the workspace configuration.',
|
|
45
|
+
auth: 'Use Agent mode in Continue and complete the OAuth sign-in for Mercator.',
|
|
46
|
+
integration: 'MCP',
|
|
47
|
+
label: 'Continue',
|
|
48
|
+
paymentMode: 'hosted-wallet',
|
|
49
|
+
},
|
|
50
|
+
cursor: {
|
|
51
|
+
activation: 'Restart Cursor if Mercator is not listed under MCP servers.',
|
|
52
|
+
auth: 'Open the Cursor Customize page, find Mercator under MCP servers, and complete its OAuth sign-in.',
|
|
53
|
+
integration: 'MCP',
|
|
54
|
+
label: 'Cursor',
|
|
55
|
+
paymentMode: 'hosted-wallet',
|
|
56
|
+
},
|
|
57
|
+
gemini: {
|
|
58
|
+
activation: 'Start a new Gemini CLI session.',
|
|
59
|
+
auth: 'In Gemini CLI, run /mcp auth mercator and complete browser authorization.',
|
|
60
|
+
integration: 'MCP',
|
|
61
|
+
label: 'Gemini CLI',
|
|
62
|
+
paymentMode: 'hosted-wallet',
|
|
63
|
+
},
|
|
64
|
+
grok: {
|
|
65
|
+
activation: 'Restart Grok to load the registration.',
|
|
66
|
+
auth: 'In Grok, open /mcps, select Mercator, and press i to authorize. Over SSH, the browser must reach the printed loopback callback; use local port forwarding or authorize on a browser-capable host.',
|
|
67
|
+
integration: 'plugin + MCP',
|
|
68
|
+
label: 'Grok',
|
|
69
|
+
paymentMode: 'hosted-wallet',
|
|
70
|
+
},
|
|
71
|
+
hermes: {
|
|
72
|
+
activation: 'Start a new Hermes session.',
|
|
73
|
+
auth: 'No OAuth step: Hermes pays through the hermes-mpp plugin at /mcp. Finish the plugin and wallet steps setup prints before paid use.',
|
|
74
|
+
integration: 'MCP',
|
|
75
|
+
label: 'Hermes',
|
|
76
|
+
paymentMode: 'native-mpp',
|
|
77
|
+
},
|
|
78
|
+
kiro: {
|
|
79
|
+
activation: 'Restart Kiro if Mercator is not listed in its MCP controls.',
|
|
80
|
+
auth: 'Connect to Mercator from the Kiro MCP controls and complete the browser authorization it opens.',
|
|
81
|
+
integration: 'MCP',
|
|
82
|
+
label: 'Kiro',
|
|
83
|
+
paymentMode: 'hosted-wallet',
|
|
84
|
+
},
|
|
85
|
+
lmstudio: {
|
|
86
|
+
activation: 'Restart LM Studio if Mercator is not listed.',
|
|
87
|
+
auth: 'Enable Mercator in LM Studio and complete the browser authorization it opens.',
|
|
88
|
+
integration: 'MCP',
|
|
89
|
+
label: 'LM Studio',
|
|
90
|
+
paymentMode: 'hosted-wallet',
|
|
91
|
+
},
|
|
92
|
+
muse: {
|
|
93
|
+
activation: 'Start a new Muse session and check /mcp.',
|
|
94
|
+
auth: 'Run muse mcp login mercator to authorize.',
|
|
95
|
+
integration: 'MCP',
|
|
96
|
+
label: 'Muse Code',
|
|
97
|
+
paymentMode: 'hosted-wallet',
|
|
98
|
+
},
|
|
99
|
+
openclaw: {
|
|
100
|
+
activation: 'Start a new OpenClaw session to load the registration.',
|
|
101
|
+
auth: 'Run openclaw mcp login mercator. Remote browsers can use the documented --code fallback.',
|
|
102
|
+
integration: 'MCP',
|
|
103
|
+
label: 'OpenClaw',
|
|
104
|
+
paymentMode: 'hosted-wallet',
|
|
105
|
+
},
|
|
38
106
|
vscode: {
|
|
107
|
+
activation: 'Run MCP: List Servers from the Command Palette, select Mercator, and start it.',
|
|
108
|
+
auth: 'Complete the trust and sign-in prompts, then enable the Mercator tools in agent chat.',
|
|
39
109
|
integration: 'MCP',
|
|
40
110
|
label: 'Visual Studio Code',
|
|
41
111
|
paymentMode: 'hosted-wallet',
|
|
42
112
|
},
|
|
43
|
-
windsurf: {
|
|
44
|
-
|
|
113
|
+
windsurf: {
|
|
114
|
+
activation: 'Open MCPs in the Cascade panel and refresh if Mercator is not listed.',
|
|
115
|
+
auth: 'Select Mercator in the Cascade MCPs panel and complete OAuth authorization.',
|
|
116
|
+
integration: 'MCP',
|
|
117
|
+
label: 'Windsurf',
|
|
118
|
+
paymentMode: 'hosted-wallet',
|
|
119
|
+
},
|
|
120
|
+
zed: {
|
|
121
|
+
activation: 'Zed reloads settings automatically; confirm Mercator in Settings > AI > MCP Servers.',
|
|
122
|
+
auth: 'Complete the Mercator OAuth prompt in Settings > AI > MCP Servers, then use it from the Agent Panel.',
|
|
123
|
+
integration: 'MCP',
|
|
124
|
+
label: 'Zed',
|
|
125
|
+
paymentMode: 'hosted-wallet',
|
|
126
|
+
},
|
|
45
127
|
};
|
|
46
128
|
/** Stable client IDs in setup and display order. */
|
|
47
129
|
export const CLIENT_IDS = Object.keys(CLIENT_METADATA);
|
package/dist/clients.d.ts
CHANGED
|
@@ -6,10 +6,14 @@ type CommandPlan = {
|
|
|
6
6
|
check?: CommandCheck;
|
|
7
7
|
command: string;
|
|
8
8
|
kind: 'command';
|
|
9
|
+
/** Configuration file the client CLI writes; read for state instead of a CLI check. */
|
|
10
|
+
state?: Pick<FilePlan, 'config' | 'path' | 'serverContainer'>;
|
|
9
11
|
undo: string;
|
|
10
12
|
};
|
|
11
13
|
type CommandCheck = {
|
|
12
14
|
args: string[];
|
|
15
|
+
/** Selects client-specific output parsing independent of the resolved executable path. */
|
|
16
|
+
client: ClientId;
|
|
13
17
|
command: string;
|
|
14
18
|
requireOAuth?: true;
|
|
15
19
|
serverName?: string;
|
|
@@ -21,7 +25,7 @@ type FilePlan = {
|
|
|
21
25
|
config: Record<string, unknown>;
|
|
22
26
|
kind: 'file';
|
|
23
27
|
path: string;
|
|
24
|
-
serverContainer: 'context_servers' | 'mcpServers' | 'mcp_servers';
|
|
28
|
+
serverContainer: 'context_servers' | 'mcpServers' | 'mcp_servers' | 'servers';
|
|
25
29
|
undo: string;
|
|
26
30
|
};
|
|
27
31
|
export type SetupPlan = CommandPlan | FilePlan;
|
|
@@ -51,6 +55,10 @@ type SetupPlanOptions = {
|
|
|
51
55
|
};
|
|
52
56
|
type RemovalPlanOptions = Omit<SetupPlanOptions, 'url'>;
|
|
53
57
|
type ClientDefinition = ClientMetadata & {
|
|
58
|
+
/** Executables shipped inside desktop app bundles, relative to an Applications folder. */
|
|
59
|
+
readonly bundle?: {
|
|
60
|
+
readonly macos: readonly string[];
|
|
61
|
+
};
|
|
54
62
|
readonly command?: string;
|
|
55
63
|
readonly configFootprints?: (options: RemovalPlanOptions) => readonly string[];
|
|
56
64
|
readonly desktop?: {
|
|
@@ -65,6 +73,8 @@ export declare const CLIENT_DEFINITIONS: Readonly<Record<ClientId, ClientDefinit
|
|
|
65
73
|
export declare function setupPlan(client: ClientId, url: string, options?: {
|
|
66
74
|
cwd?: string;
|
|
67
75
|
env?: Readonly<Record<string, string | undefined>>;
|
|
76
|
+
/** Absolute executable selected by the client binary resolver. */
|
|
77
|
+
executable?: string;
|
|
68
78
|
home?: string;
|
|
69
79
|
platform?: NodeJS.Platform;
|
|
70
80
|
}): SetupPlan;
|
|
@@ -72,6 +82,8 @@ export declare function setupPlan(client: ClientId, url: string, options?: {
|
|
|
72
82
|
export declare function removalPlan(client: ClientId, options?: {
|
|
73
83
|
cwd?: string;
|
|
74
84
|
env?: Readonly<Record<string, string | undefined>>;
|
|
85
|
+
/** Absolute executable selected by the client binary resolver. */
|
|
86
|
+
executable?: string;
|
|
75
87
|
home?: string;
|
|
76
88
|
platform?: NodeJS.Platform;
|
|
77
89
|
}): RemovalPlan;
|
|
@@ -94,3 +106,5 @@ export declare function removeConfigFile(plan: Extract<RemovalPlan, {
|
|
|
94
106
|
}>, options?: {
|
|
95
107
|
dryRun?: boolean;
|
|
96
108
|
}): Promise<'missing' | 'planned' | 'removed'>;
|
|
109
|
+
/** App-bundled client executables on macOS, under system and user Applications folders. */
|
|
110
|
+
export declare function bundlePaths(definition: Pick<ClientDefinition, 'bundle'>, home: string, platform: NodeJS.Platform): string[];
|