@1mcp/agent 0.30.3 → 0.31.0-beta1

package/README.md

@@ -17,6 +17,7 @@ A unified Model Context Protocol server implementation that aggregates multiple
 ## Features
 
 - **🔄 Unified Interface**: Aggregates multiple MCP servers into one
+- **🧭 CLI Mode for Agents**: Preferred workflow for Codex, Claude, and other AI agents using progressive disclosure
 - **🔒 OAuth 2.1 Authentication**: Production-ready security with scope-based authorization
 - **⚡ High Performance**: Efficient request forwarding with proper error handling
 - **🛡️ Security First**: Stdio transport isolation, input sanitization, and comprehensive audit logging
@@ -58,7 +59,13 @@ npx -y @1mcp/agent --help
 1mcp
 ```
 
-### 4. Connect Your AI Assistant
+### 4. Choose One Interface
+
+Do not configure the same agent to use both direct MCP access and CLI mode at the same time.
+
+If you switch an agent to CLI mode, remove that agent's existing MCP server configuration first. We recommend CLI mode for Codex, Claude, and similar agent-style sessions.
+
+**If you intentionally want direct MCP mode instead**, connect that client to the unified endpoint:
 
 **For Cursor**, add to `~/.cursor/mcp.json`:
 
@@ -94,7 +101,15 @@ npx -y @1mcp/agent --help
 claude mcp add -t http 1mcp "http://127.0.0.1:3050/mcp?app=claude-code"
 ```
 
-That's it! All your MCP servers are now available through one unified endpoint. 🎉
+**Recommended: for Codex, Claude, and other agent-style CLI sessions, the user should run `1mcp cli-setup` instead of configuring direct MCP attachment:**
+
+```bash
+1mcp cli-setup --codex
+# or
+1mcp cli-setup --claude --scope repo --repo-root .
+```
+
+That's it! Your MCP servers stay behind one unified 1MCP runtime, and each agent should use one mode only. For agent sessions, the recommended choice is CLI mode. 🎉
 
 ## Commands
 
@@ -104,9 +119,65 @@ That's it! All your MCP servers are now available through one unified endpoint.
 - **`1mcp mcp add <name>`** - Add a new MCP server to configuration
 - **`1mcp mcp list`** - List all configured MCP servers
 - **`1mcp mcp status [name]`** - Show server status and details
+- **`1mcp instructions`** - Show the CLI playbook and current server inventory for agent workflows
+- **`1mcp inspect [target]`** - Inspect available servers, tools, and tool schemas from a running 1MCP instance
+- **`1mcp run <server>/<tool>`** - Call a tool against a running 1MCP instance
+- **`1mcp cli-setup --codex|--claude`** - Install bootstrap hooks and startup references for Codex or Claude
 
 For detailed command usage, run: `1mcp <command> --help`
 
+### CLI Workflow
+
+The user-facing setup step is `1mcp cli-setup`. After that, the following CLI workflow is what the AI agent will normally run against a running `1mcp serve` instance.
+
+You can still run these commands manually to test the setup:
+
+```bash
+# Shell 1: start the aggregated MCP server
+1mcp serve
+
+# Shell 2: commands the AI agent will normally run
+1mcp instructions
+1mcp inspect context7
+1mcp inspect context7/get-library-docs
+1mcp run context7/get-library-docs --args '{"context7CompatibleLibraryID":"/mongodb/docs","topic":"aggregation pipeline"}'
+```
+
+### Why CLI Mode?
+
+CLI mode is the preferred path for agent sessions because it replaces broad direct-MCP exposure inside the agent loop with progressive disclosure:
+
+- `instructions` gives the playbook and current inventory
+- `inspect <server>` narrows discovery to one server
+- `inspect <server>/<tool>` narrows again to one tool schema
+- `run` executes only the chosen tool
+
+This keeps MCP as the backend protocol while giving the agent a thinner frontend workflow with less tool and schema noise in context.
+
+For a given agent, choose only one mode:
+
+- Direct MCP mode: keep that agent's MCP server config
+- CLI mode: remove that agent's MCP server config, run `cli-setup`, and let the AI agent use the CLI workflow
+
+What the user normally runs:
+
+```bash
+1mcp cli-setup --codex
+# or
+1mcp cli-setup --claude --scope repo --repo-root .
+```
+
+What the AI agent normally runs after that:
+
+```bash
+1mcp instructions
+1mcp inspect filesystem
+1mcp inspect filesystem/read_file
+1mcp run filesystem/read_file --args '{"path":"./mcp.json"}'
+```
+
+You may run those commands manually to verify the setup, but they are primarily designed for the agent workflow.
+
 ## Documentation
 
 📚 **[Complete Documentation](https://docs.1mcp.app)** - Comprehensive guides, API reference, and examples
@@ -124,6 +195,8 @@ For detailed command usage, run: `1mcp <command> --help`
 
 1MCP acts as a proxy, managing and aggregating multiple MCP servers. It starts and stops these servers as subprocesses and forwards requests from AI assistants to the appropriate server. This architecture allows for a single point of entry for all MCP traffic, simplifying management and reducing overhead.
 
+For agent sessions, 1MCP also provides a CLI mode on top of that runtime. MCP remains the interoperability layer behind `1mcp serve`; CLI mode changes how the agent discovers and calls tools so the workflow stays selective and scriptable.
+
 ## Contributing
 
 Contributions are welcome! Please read our [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.

package/build/commands/auth/index.d.ts

@@ -0,0 +1,3 @@
+import type { Argv } from 'yargs';
+export declare function setupAuthCommands(yargs: Argv): Argv;
+//# sourceMappingURL=index.d.ts.map

package/build/commands/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAElC,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,CAiEnD"}

package/build/commands/auth/index.js

@@ -0,0 +1,47 @@
+import { runCliCommand } from '../../commands/shared/commandRunner.js';
+import { globalOptions } from '../../globalOptions.js';
+export function setupAuthCommands(yargs) {
+    return yargs.command('auth <subcommand>', 'Manage authentication profiles for secured 1MCP serve instances', (commandYargs) => {
+        commandYargs
+            .command('login', 'Save a bearer token for a 1MCP server URL', (sub) => sub
+            .options(globalOptions || {})
+            .option('url', {
+            alias: 'u',
+            describe: '1MCP server URL (auto-detected if omitted)',
+            type: 'string',
+        })
+            .option('token', {
+            alias: 't',
+            describe: 'Bearer token (reads from stdin if omitted)',
+            type: 'string',
+        }), async (argv) => {
+            const { authLoginCommand } = await import('./login.js');
+            await runCliCommand(argv, authLoginCommand);
+        })
+            .command('status', 'Show saved authentication profiles', (sub) => sub.options(globalOptions || {}).option('url', {
+            alias: 'u',
+            describe: 'Check a specific server URL',
+            type: 'string',
+        }), async (argv) => {
+            const { authStatusCommand } = await import('./status.js');
+            await runCliCommand(argv, authStatusCommand);
+        })
+            .command('logout', 'Remove a saved authentication profile', (sub) => sub
+            .options(globalOptions || {})
+            .option('url', {
+            alias: 'u',
+            describe: 'Server URL to remove',
+            type: 'string',
+        })
+            .option('all', {
+            describe: 'Remove all saved profiles',
+            type: 'boolean',
+            default: false,
+        }), async (argv) => {
+            const { authLogoutCommand } = await import('./logout.js');
+            await runCliCommand(argv, authLogoutCommand);
+        })
+            .demandCommand(1, 'Specify a subcommand: login, status, or logout');
+    });
+}
+//# sourceMappingURL=index.js.map

package/build/commands/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAItD,MAAM,UAAU,iBAAiB,CAAC,KAAW;IAC3C,OAAO,KAAK,CAAC,OAAO,CAClB,mBAAmB,EACnB,iEAAiE,EACjE,CAAC,YAAY,EAAE,EAAE;QACf,YAAY;aACT,OAAO,CACN,OAAO,EACP,2CAA2C,EAC3C,CAAC,GAAG,EAAE,EAAE,CACN,GAAG;aACA,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC;aAC5B,MAAM,CAAC,KAAK,EAAE;YACb,KAAK,EAAE,GAAG;YACV,QAAQ,EAAE,4CAA4C;YACtD,IAAI,EAAE,QAAQ;SACf,CAAC;aACD,MAAM,CAAC,OAAO,EAAE;YACf,KAAK,EAAE,GAAG;YACV,QAAQ,EAAE,4CAA4C;YACtD,IAAI,EAAE,QAAQ;SACf,CAAC,EACN,KAAK,EAAE,IAAI,EAAE,EAAE;YACb,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;YACxD,MAAM,aAAa,CAAC,IAA8C,EAAE,gBAAgB,CAAC,CAAC;QACxF,CAAC,CACF;aACA,OAAO,CACN,QAAQ,EACR,oCAAoC,EACpC,CAAC,GAAG,EAAE,EAAE,CACN,GAAG,CAAC,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE;YAC7C,KAAK,EAAE,GAAG;YACV,QAAQ,EAAE,6BAA6B;YACvC,IAAI,EAAE,QAAQ;SACf,CAAC,EACJ,KAAK,EAAE,IAAI,EAAE,EAAE;YACb,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;YAC1D,MAAM,aAAa,CAAC,IAA+C,EAAE,iBAAiB,CAAC,CAAC;QAC1F,CAAC,CACF;aACA,OAAO,CACN,QAAQ,EACR,uCAAuC,EACvC,CAAC,GAAG,EAAE,EAAE,CACN,GAAG;aACA,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC;aAC5B,MAAM,CAAC,KAAK,EAAE;YACb,KAAK,EAAE,GAAG;YACV,QAAQ,EAAE,sBAAsB;YAChC,IAAI,EAAE,QAAQ;SACf,CAAC;aACD,MAAM,CAAC,KAAK,EAAE;YACb,QAAQ,EAAE,2BAA2B;YACrC,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,KAAK;SACf,CAAC,EACN,KAAK,EAAE,IAAI,EAAE,EAAE;YACb,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;YAC1D,MAAM,aAAa,CAAC,IAA+C,EAAE,iBAAiB,CAAC,CAAC;QAC1F,CAAC,CACF;aACA,aAAa,CAAC,CAAC,EAAE,gDAAgD,CAAC,CAAC;IACxE,CAAC,CACF,CAAC;AACJ,CAAC"}

package/build/commands/auth/login.d.ts

@@ -0,0 +1,7 @@
+import type { GlobalOptions } from '../../globalOptions.js';
+export interface AuthLoginOptions extends GlobalOptions {
+    url?: string;
+    token?: string;
+}
+export declare function authLoginCommand(options: AuthLoginOptions): Promise<void>;
+//# sourceMappingURL=login.d.ts.map

package/build/commands/auth/login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/login.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAI3D,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiD/E"}

package/build/commands/auth/login.js

@@ -0,0 +1,83 @@
+import { ApiClient } from '../../commands/shared/apiClient.js';
+import { normalizeServerUrl, saveAuthProfile } from '../../commands/shared/authProfileStore.js';
+import { API_INSPECT_ENDPOINT } from '../../constants/api.js';
+import { stripMcpSuffix } from '../../utils/urlUtils.js';
+import { discoverServerWithPidFile } from '../../utils/validation/urlDetection.js';
+export async function authLoginCommand(options) {
+    const { url: discoveredUrl, source } = await discoverServerWithPidFile(options['config-dir'], options.url);
+    const baseUrl = normalizeServerUrl(stripMcpSuffix(discoveredUrl));
+    if (source !== 'user') {
+        process.stderr.write(`Auto-detected server at ${baseUrl} (via ${source})\n`);
+    }
+    // Probe without auth — if it succeeds, auth is disabled
+    const probeClient = new ApiClient({ baseUrl });
+    const probeResponse = await probeClient.get(API_INSPECT_ENDPOINT);
+    if (probeResponse.ok) {
+        process.stdout.write(`Auth is not required on ${baseUrl} (auth is disabled). No login needed.\n`);
+        return;
+    }
+    // Resolve token: explicit flag > stdin > localhost auto-generate
+    let token = options.token || (await readTokenFromStdin());
+    if (!token && isLocalhostUrl(baseUrl)) {
+        token = await tryCliTokenGeneration(baseUrl);
+    }
+    if (!token) {
+        throw new Error('No token provided. Use --token or pipe a token via stdin.\n' +
+            `To get a token, visit ${baseUrl}/oauth or run the OAuth flow.`);
+    }
+    // Validate token
+    const client = new ApiClient({ baseUrl, bearerToken: token });
+    const response = await client.get(API_INSPECT_ENDPOINT);
+    if (response.status === 401 || response.status === 403) {
+        throw new Error(`Authentication failed: token was rejected by ${baseUrl}`);
+    }
+    if (!response.ok && response.status !== 0) {
+        process.stderr.write(`Warning: server returned HTTP ${response.status}, saving token anyway.\n`);
+    }
+    await saveAuthProfile(options['config-dir'], {
+        serverUrl: baseUrl,
+        token,
+        savedAt: Date.now(),
+    });
+    process.stdout.write(`Saved authentication profile for ${baseUrl}\n`);
+}
+function isLocalhostUrl(url) {
+    try {
+        const hostname = new URL(url).hostname;
+        return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]';
+    }
+    catch {
+        return false;
+    }
+}
+async function tryCliTokenGeneration(baseUrl) {
+    try {
+        const client = new ApiClient({ baseUrl });
+        const response = await client.post('/api/auth/cli-token', {});
+        if (response.ok && response.data?.token) {
+            process.stderr.write('Auto-generated CLI token for localhost.\n');
+            return response.data.token;
+        }
+    }
+    catch {
+        // endpoint not available, fall through
+    }
+    return null;
+}
+async function readTokenFromStdin() {
+    if (process.stdin.isTTY) {
+        return null;
+    }
+    return new Promise((resolve) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => {
+            resolve(data.trim() || null);
+        });
+        process.stdin.on('error', () => resolve(null));
+    });
+}
+//# sourceMappingURL=login.js.map

package/build/commands/auth/login.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.js","sourceRoot":"","sources":["../../../src/commands/auth/login.ts"],"names":[],"mappings":"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"}

package/build/commands/auth/logout.d.ts

@@ -0,0 +1,7 @@
+import type { GlobalOptions } from '../../globalOptions.js';
+export interface AuthLogoutOptions extends GlobalOptions {
+    url?: string;
+    all?: boolean;
+}
+export declare function authLogoutCommand(options: AuthLogoutOptions): Promise<void>;
+//# sourceMappingURL=logout.d.ts.map

package/build/commands/auth/logout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logout.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/logout.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAI3D,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0CjF"}

package/build/commands/auth/logout.js

@@ -0,0 +1,46 @@
+import { deleteAuthProfile, listAuthProfiles, normalizeServerUrl } from '../../commands/shared/authProfileStore.js';
+import { stripMcpSuffix } from '../../utils/urlUtils.js';
+import { discoverServerWithPidFile } from '../../utils/validation/urlDetection.js';
+export async function authLogoutCommand(options) {
+    if (options.all) {
+        const profiles = await listAuthProfiles(options['config-dir']);
+        if (profiles.length === 0) {
+            process.stdout.write('No saved profiles to remove.\n');
+            return;
+        }
+        for (const profile of profiles) {
+            await deleteAuthProfile(options['config-dir'], profile.serverUrl);
+        }
+        process.stdout.write(`Removed ${profiles.length} profile${profiles.length !== 1 ? 's' : ''}.\n`);
+        return;
+    }
+    if (!options.url) {
+        let discoveredUrl;
+        let source;
+        try {
+            ({ url: discoveredUrl, source } = await discoverServerWithPidFile(options['config-dir']));
+        }
+        catch {
+            throw new Error('Specify --url <server-url> or --all. No running server detected for auto-discovery.');
+        }
+        const baseUrl = normalizeServerUrl(stripMcpSuffix(discoveredUrl));
+        process.stderr.write(`Auto-detected server at ${baseUrl} (via ${source})\n`);
+        const removed = await deleteAuthProfile(options['config-dir'], baseUrl);
+        if (removed) {
+            process.stdout.write(`Removed profile for ${baseUrl}\n`);
+        }
+        else {
+            process.stdout.write(`No saved profile for ${baseUrl}\n`);
+        }
+        return;
+    }
+    const baseUrl = normalizeServerUrl(options.url);
+    const removed = await deleteAuthProfile(options['config-dir'], baseUrl);
+    if (removed) {
+        process.stdout.write(`Removed profile for ${baseUrl}\n`);
+    }
+    else {
+        process.stdout.write(`No saved profile for ${baseUrl}\n`);
+    }
+}
+//# sourceMappingURL=logout.js.map

package/build/commands/auth/logout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logout.js","sourceRoot":"","sources":["../../../src/commands/auth/logout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,0CAA0C,CAAC;AAEnH,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,yBAAyB,EAAE,MAAM,uCAAuC,CAAC;AAOlF,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAA0B;IAChE,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAChB,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;QAC/D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;YACvD,OAAO;QACT,CAAC;QACD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,MAAM,iBAAiB,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QACpE,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,QAAQ,CAAC,MAAM,WAAW,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QACjG,OAAO;IACT,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;QACjB,IAAI,aAAqB,CAAC;QAC1B,IAAI,MAAc,CAAC;QAEnB,IAAI,CAAC;YACH,CAAC,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,MAAM,yBAAyB,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAC5F,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,qFAAqF,CAAC,CAAC;QACzG,CAAC;QAED,MAAM,OAAO,GAAG,kBAAkB,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC,CAAC;QAClE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,2BAA2B,OAAO,SAAS,MAAM,KAAK,CAAC,CAAC;QAC7E,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;QACxE,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,OAAO,IAAI,CAAC,CAAC;QAC3D,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wBAAwB,OAAO,IAAI,CAAC,CAAC;QAC5D,CAAC;QACD,OAAO;IACT,CAAC;IAED,MAAM,OAAO,GAAG,kBAAkB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;IACxE,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,OAAO,IAAI,CAAC,CAAC;IAC3D,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wBAAwB,OAAO,IAAI,CAAC,CAAC;IAC5D,CAAC;AACH,CAAC"}

package/build/commands/auth/status.d.ts

@@ -0,0 +1,6 @@
+import type { GlobalOptions } from '../../globalOptions.js';
+export interface AuthStatusOptions extends GlobalOptions {
+    url?: string;
+}
+export declare function authStatusCommand(options: AuthStatusOptions): Promise<void>;
+//# sourceMappingURL=status.d.ts.map

package/build/commands/auth/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/status.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAI3D,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BjF"}

package/build/commands/auth/status.js

@@ -0,0 +1,54 @@
+import { ApiClient } from '../../commands/shared/apiClient.js';
+import { listAuthProfiles, loadAuthProfile, normalizeServerUrl } from '../../commands/shared/authProfileStore.js';
+import { API_INSPECT_ENDPOINT } from '../../constants/api.js';
+import { stripMcpSuffix } from '../../utils/urlUtils.js';
+import { discoverServerWithPidFile } from '../../utils/validation/urlDetection.js';
+export async function authStatusCommand(options) {
+    if (options.url) {
+        await showProfileStatus(options['config-dir'], normalizeServerUrl(options.url));
+        return;
+    }
+    // Try auto-discovery first
+    try {
+        const { url: discoveredUrl, source } = await discoverServerWithPidFile(options['config-dir']);
+        const baseUrl = normalizeServerUrl(stripMcpSuffix(discoveredUrl));
+        process.stderr.write(`Auto-detected server at ${baseUrl} (via ${source})\n`);
+        await showProfileStatus(options['config-dir'], baseUrl);
+        return;
+    }
+    catch {
+        // No server found, fall through to list all profiles
+    }
+    const profiles = await listAuthProfiles(options['config-dir']);
+    if (profiles.length === 0) {
+        process.stdout.write('No saved authentication profiles.\n');
+        return;
+    }
+    process.stdout.write(`Saved profiles (${profiles.length}):\n`);
+    for (const profile of profiles) {
+        const savedAt = new Date(profile.savedAt).toLocaleString();
+        process.stdout.write(`  - ${profile.serverUrl}  (saved ${savedAt})\n`);
+    }
+}
+async function showProfileStatus(configDir, baseUrl) {
+    const profile = await loadAuthProfile(configDir, baseUrl);
+    if (!profile) {
+        process.stdout.write(`No saved profile for ${baseUrl}\n`);
+        return;
+    }
+    const savedAt = new Date(profile.savedAt).toLocaleString();
+    process.stdout.write(`Profile: ${baseUrl}\n`);
+    process.stdout.write(`  Saved: ${savedAt}\n`);
+    const client = new ApiClient({ baseUrl, bearerToken: profile.token });
+    const response = await client.get(API_INSPECT_ENDPOINT);
+    if (response.ok) {
+        process.stdout.write(`  Status: connected\n`);
+    }
+    else if (response.status === 401 || response.status === 403) {
+        process.stdout.write(`  Status: token rejected (HTTP ${response.status})\n`);
+    }
+    else {
+        process.stdout.write(`  Status: unreachable (${response.error ?? `HTTP ${response.status}`})\n`);
+    }
+}
+//# sourceMappingURL=status.js.map

package/build/commands/auth/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../../src/commands/auth/status.ts"],"names":[],"mappings":"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"}

package/build/commands/cliSetup/cliSetup.d.ts

@@ -0,0 +1,12 @@
+import type { GlobalOptions } from '../../globalOptions.js';
+import { type CliSetupTarget } from './setupFiles.js';
+export interface CliSetupCommandOptions extends GlobalOptions {
+    scope?: string;
+    claude?: boolean;
+    codex?: boolean;
+    'repo-root'?: string;
+}
+export declare function cliSetupCommand(options: CliSetupCommandOptions): Promise<void>;
+export declare function formatCodexConfigNotice(): string;
+export declare function resolveCliSetupTargetsFromFlags(options: Pick<CliSetupCommandOptions, 'claude' | 'codex'>): CliSetupTarget[];
+//# sourceMappingURL=cliSetup.d.ts.map

package/build/commands/cliSetup/cliSetup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliSetup.d.ts","sourceRoot":"","sources":["../../../src/commands/cliSetup/cliSetup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAAE,KAAK,cAAc,EAAkE,MAAM,iBAAiB,CAAC;AAEtH,MAAM,WAAW,sBAAuB,SAAQ,aAAa;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAapF;AAED,wBAAgB,uBAAuB,IAAI,MAAM,CAmBhD;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,IAAI,CAAC,sBAAsB,EAAE,QAAQ,GAAG,OAAO,CAAC,GACxD,cAAc,EAAE,CAmBlB"}

package/build/commands/cliSetup/cliSetup.js

@@ -0,0 +1,49 @@
+import { formatCliSetupOutput, resolveCliSetupScope, writeCliSetupFiles } from './setupFiles.js';
+export async function cliSetupCommand(options) {
+    const targets = resolveCliSetupTargetsFromFlags(options);
+    const results = await writeCliSetupFiles({
+        repoRoot: options['repo-root'] ?? process.cwd(),
+        scope: resolveCliSetupScope(options.scope),
+        targets,
+    });
+    process.stdout.write(`${formatCliSetupOutput(results)}\n`);
+    if (targets.includes('codex')) {
+        process.stdout.write(`\n${formatCodexConfigNotice()}\n`);
+    }
+}
+export function formatCodexConfigNotice() {
+    const configContent = [
+        'approval_policy = "on-request"',
+        'sandbox_mode    = "workspace-write"',
+        '',
+        '[sandbox_workspace_write]',
+        'network_access = true',
+        '',
+        '[features]',
+        'codex_hooks = true',
+    ].join('\n');
+    return [
+        'Action required: update your Codex config.toml (~/.codex/config.toml) to include:',
+        '',
+        configContent,
+        '',
+        'This enables hooks support and allows 1MCP to run within the Codex sandbox.',
+    ].join('\n');
+}
+export function resolveCliSetupTargetsFromFlags(options) {
+    const targets = [];
+    if (options.codex) {
+        targets.push('codex');
+    }
+    if (options.claude) {
+        targets.push('claude');
+    }
+    if (targets.length === 0) {
+        throw new Error('Specify exactly one client: use `--codex` or `--claude`.');
+    }
+    if (targets.length > 1) {
+        throw new Error('Specify only one client at a time: use either `--codex` or `--claude`.');
+    }
+    return targets;
+}
+//# sourceMappingURL=cliSetup.js.map

package/build/commands/cliSetup/cliSetup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliSetup.js","sourceRoot":"","sources":["../../../src/commands/cliSetup/cliSetup.ts"],"names":[],"mappings":"AAEA,OAAO,EAAuB,oBAAoB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAStH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAA+B;IACnE,MAAM,OAAO,GAAG,+BAA+B,CAAC,OAAO,CAAC,CAAC;IACzD,MAAM,OAAO,GAAG,MAAM,kBAAkB,CAAC;QACvC,QAAQ,EAAE,OAAO,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE;QAC/C,KAAK,EAAE,oBAAoB,CAAC,OAAO,CAAC,KAAK,CAAC;QAC1C,OAAO;KACR,CAAC,CAAC;IAEH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,oBAAoB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3D,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,uBAAuB,EAAE,IAAI,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC;AAED,MAAM,UAAU,uBAAuB;IACrC,MAAM,aAAa,GAAG;QACpB,gCAAgC;QAChC,qCAAqC;QACrC,EAAE;QACF,2BAA2B;QAC3B,uBAAuB;QACvB,EAAE;QACF,YAAY;QACZ,oBAAoB;KACrB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,OAAO;QACL,mFAAmF;QACnF,EAAE;QACF,aAAa;QACb,EAAE;QACF,6EAA6E;KAC9E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,MAAM,UAAU,+BAA+B,CAC7C,OAAyD;IAEzD,MAAM,OAAO,GAAqB,EAAE,CAAC;IAErC,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACzB,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC,CAAC;IAC5F,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/build/commands/cliSetup/index.d.ts

@@ -0,0 +1,3 @@
+import type { Argv } from 'yargs';
+export declare function setupCliSetupCommand(yargs: Argv): Argv;
+//# sourceMappingURL=index.d.ts.map

package/build/commands/cliSetup/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/cliSetup/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAElC,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,CA4DtD"}

package/build/commands/cliSetup/index.js

@@ -0,0 +1,52 @@
+import { globalOptions } from '../../globalOptions.js';
+export function setupCliSetupCommand(yargs) {
+    return yargs.command('cli-setup', 'Install 1MCP CLI hooks and reference files for Codex and Claude', (commandYargs) => commandYargs
+        .options(globalOptions || {})
+        .option('scope', {
+        describe: 'Setup scope',
+        type: 'string',
+        choices: ['global', 'repo', 'all'],
+        default: 'global',
+    })
+        .option('codex', {
+        describe: 'Install setup files for Codex only',
+        type: 'boolean',
+        default: false,
+    })
+        .option('claude', {
+        describe: 'Install setup files for Claude only',
+        type: 'boolean',
+        default: false,
+    })
+        .option('repo-root', {
+        describe: 'Repository root used for repo-scoped setup',
+        type: 'string',
+    })
+        .check((argv) => {
+        const selected = [argv.codex, argv.claude].filter(Boolean);
+        if (selected.length === 0) {
+            throw new Error('Specify exactly one client: use `--codex` or `--claude`.');
+        }
+        if (selected.length > 1) {
+            throw new Error('Specify only one client at a time: use either `--codex` or `--claude`.');
+        }
+        return true;
+    })
+        .example('$0 cli-setup --codex', 'Install global Codex hooks and reference files')
+        .example('$0 cli-setup --claude --scope repo --repo-root .', 'Install repo-local Claude hooks and reference files')
+        .example('$0 cli-setup --codex --scope all', 'Install global and repo-local Codex setup')
+        .epilogue('This command writes hook config and lightweight startup-file references. Errors are written to stderr only.'), async (argv) => {
+        const { configureGlobalLogger } = await import('../../logger/configureGlobalLogger.js');
+        const { cliSetupCommand } = await import('./cliSetup.js');
+        configureGlobalLogger(argv, 'stdio');
+        try {
+            await cliSetupCommand(argv);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`${message}\n`);
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=index.js.map

package/build/commands/cliSetup/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/cliSetup/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAItD,MAAM,UAAU,oBAAoB,CAAC,KAAW;IAC9C,OAAO,KAAK,CAAC,OAAO,CAClB,WAAW,EACX,iEAAiE,EACjE,CAAC,YAAY,EAAE,EAAE,CACf,YAAY;SACT,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC;SAC5B,MAAM,CAAC,OAAO,EAAE;QACf,QAAQ,EAAE,aAAa;QACvB,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC;QAClC,OAAO,EAAE,QAAQ;KAClB,CAAC;SACD,MAAM,CAAC,OAAO,EAAE;QACf,QAAQ,EAAE,oCAAoC;QAC9C,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,KAAK;KACf,CAAC;SACD,MAAM,CAAC,QAAQ,EAAE;QAChB,QAAQ,EAAE,qCAAqC;QAC/C,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,KAAK;KACf,CAAC;SACD,MAAM,CAAC,WAAW,EAAE;QACnB,QAAQ,EAAE,4CAA4C;QACtD,IAAI,EAAE,QAAQ;KACf,CAAC;SACD,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE;QACd,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC3D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;QAC9E,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC,CAAC;QAC5F,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;SACD,OAAO,CAAC,sBAAsB,EAAE,gDAAgD,CAAC;SACjF,OAAO,CACN,kDAAkD,EAClD,qDAAqD,CACtD;SACA,OAAO,CAAC,kCAAkC,EAAE,2CAA2C,CAAC;SACxF,QAAQ,CACP,6GAA6G,CAC9G,EACL,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,MAAM,EAAE,qBAAqB,EAAE,GAAG,MAAM,MAAM,CAAC,sCAAsC,CAAC,CAAC;QACvF,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;QAE1D,qBAAqB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC;YACH,MAAM,eAAe,CAAC,IAA6C,CAAC,CAAC;QACvE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;YACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/build/commands/cliSetup/setupFiles.d.ts

@@ -0,0 +1,24 @@
+export declare const CLI_SETUP_TARGETS: readonly ["codex", "claude"];
+export type CliSetupTarget = (typeof CLI_SETUP_TARGETS)[number];
+export declare const CLI_SETUP_SCOPES: readonly ["global", "repo", "all"];
+export type CliSetupScope = (typeof CLI_SETUP_SCOPES)[number];
+interface WriteCliSetupOptions {
+    repoRoot: string;
+    scope: CliSetupScope;
+    targets: CliSetupTarget[];
+}
+export interface CliSetupWriteResult {
+    path: string;
+    changed: boolean;
+    kind: 'hook' | 'startup-doc' | 'managed-doc';
+    target: CliSetupTarget;
+    scope: Exclude<CliSetupScope, 'all'>;
+}
+export declare function resolveCliSetupScope(rawScope?: string): CliSetupScope;
+export declare function writeCliSetupFiles(options: WriteCliSetupOptions): Promise<CliSetupWriteResult[]>;
+export declare function formatCliSetupOutput(results: CliSetupWriteResult[]): string;
+export declare function renderManagedDocContent(): string;
+export declare function renderStartupDocManagedBlock(startupDocPath: string, managedDocPath: string): string;
+export declare function upsertStartupDocManagedBlock(existingContent: string, managedBlock: string): string;
+export {};
+//# sourceMappingURL=setupFiles.d.ts.map

package/build/commands/cliSetup/setupFiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupFiles.d.ts","sourceRoot":"","sources":["../../../src/commands/cliSetup/setupFiles.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,iBAAiB,8BAA+B,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,eAAO,MAAM,gBAAgB,oCAAqC,CAAC;AACnE,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAkB9D,UAAU,oBAAoB;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,aAAa,CAAC;IAC7C,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,OAAO,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;CACtC;AAsBD,wBAAgB,oBAAoB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,aAAa,CAWrE;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAiBtG;AAsBD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,MAAM,CAO3E;AAED,wBAAgB,uBAAuB,IAAI,MAAM,CAkBhD;AAED,wBAAgB,4BAA4B,CAAC,cAAc,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAGnG;AAED,wBAAgB,4BAA4B,CAAC,eAAe,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAelG"}