codeant-cli 0.5.9 → 0.5.10

package/mcp.md

@@ -11,7 +11,7 @@ The CodeAnt CLI ships an MCP (Model Context Protocol) server that exposes CodeAn
 | Name | Read/Write | What it does |
 |------|------------|--------------|
 | `codeant_scans_orgs` | read | List authenticated CodeAnt orgs. |
-| `codeant_scans_repos` | read | List repos in an org. |
+| `codeant_scans_repos` | read | List repos in an org (slim records, paged: `search`, `limit`, `offset`, `full`). |
 | `codeant_scans_history` | read | Recent scan runs for a repo. |
 | `codeant_scans_get` | read | Severity/category summary for one scan. |
 | `codeant_scans_results` | read | Full findings (SAST, SCA, secrets, IaC, …) for one scan. |
@@ -20,10 +20,10 @@ The CodeAnt CLI ships an MCP (Model Context Protocol) server that exposes CodeAn
 | `codeant_hotlist_list` | read | Prioritized organization-wide Hotlist findings with stable IDs. |
 | `codeant_hotlist_get` | read | One complete Hotlist finding by stable ID. |
 | `codeant_findings_antipatterns` | read | Anti-pattern findings across selected or all organization repos (paged: `limit`, `offset`, `all`). |
-| `codeant_cloud_scan_history` | read | AWS/Azure/GCP CSPM, VM, or container scan history. |
-| `codeant_cloud_findings_list` | read | Findings for one CSPM, VM, or container scan (VM/container paged: `limit`, `offset`, `all`). |
+| `codeant_cloud_scan_history` | read | AWS/Azure/GCP CSPM, VM, or container scan history (newest first, 10 per provider by default and up to 200, paged with `limit`/`offset`, without per-service rollups unless `full`). |
+| `codeant_cloud_findings_list` | read | Findings for one CSPM, VM, or container scan (paged: `limit`, `offset`, `all`; compliance mappings only with `full`). |
 | `codeant_cloud_finding_get` | read | Full detail for one cloud finding UID. |
-| `codeant_pentest_history` | read | Pentest engagement history. |
+| `codeant_pentest_history` | read | Pentest engagement history (paged: `limit`, `offset`, `full`). |
 | `codeant_pentest_issues` | read | All available issues for a pentest engagement. |
 | `codeant_pentest_report` | read | Full pentest customer report. |
 | `codeant_api_get` | read | Authenticated GET request to any relative CodeAnt app API path, with exact org/provider context. |
@@ -31,7 +31,9 @@ The CodeAnt CLI ships an MCP (Model Context Protocol) server that exposes CodeAn
 | `codeant_pr_get` | read | Detail for a PR/MR. |
 | `codeant_pr_comments` | read | Comments on a PR, filtered. |
 | `codeant_comments_search` | read | Free-text search across CodeAnt review comments. |
-| `codeant_review_local` | read | Run a CodeAnt review on local working-copy changes. |
+| `codeant_review_local` | read | Run a CodeAnt review on local working-copy changes in the server's working directory. |
+| `codeant_login` | auth | Start browser sign-in; returns the sign-in link immediately. Call again to confirm. |
+| `codeant_logout` | auth | Revoke and clear the saved token (shared with the CLI). |
 | `codeant_scans_start` | **write** | Trigger a new scan. Gated. |
 | `codeant_pr_resolve` | **write** | Resolve a PR conversation thread. Gated. |
 | `codeant_api_request` | **write** | Authenticated POST/PUT/PATCH/DELETE request to a relative CodeAnt app API path, with exact org/provider context. Gated. |
@@ -40,17 +42,24 @@ Write tools are only registered when `CODEANT_READ_ONLY=0`. Default = read-only.
 
 For complete finding coverage, examples, tenant/provider selection, and response details, see the [CodeAnt findings documentation](https://docs.codeant.ai/cli/findings).
 
-Every tool carries MCP annotations (`title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so the client can decide whether to auto-approve calls.
+Every tool carries MCP annotations (`title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so the client can decide whether to auto-approve calls. The server also sends `instructions` (discovery order, paging, auth recovery) in its `initialize` result.
+
+Results are compact JSON. Any result over `CODEANT_MCP_MAX_RESULT_CHARS` characters is refused with an error and a narrowing hint; [src/mcp/shape.js](src/mcp/shape.js) holds the MCP-only projections and page defaults. CLI commands keep their full output.
+
+`codeant_login` runs sign-in in the background: the first call returns `{ status: "pending", loginUrl, browserOpened }`, and the next call returns `{ status: "success" }` once the user finishes. The token is read from `~/.codeant/config.json` on every request, so CLI logins and logouts apply to a running server.
 
 ## Configuration (env vars)
 
 | Var | Purpose | Default |
 |-----|---------|---------|
-| `CODEANT_API_TOKEN` | API token (CodeAnt account → settings → API). Required. | — |
-| `CODEANT_API_URL` | API base URL. Override for self-hosted. | `https://api.codeant.ai` |
-| `CODEANT_READ_ONLY` | `1` to hide write tools, `0` to expose them. | `1` |
+| `CODEANT_API_TOKEN` | API token. Optional: without it the server uses the token saved by `codeant login` or `codeant_login`. | — |
+| `CODEANT_API_URL` | API base URL. Override for self-hosted. | `https://service.codeant.ai` |
+| `CODEANT_DASHBOARD_URL` | Web app URL used by `codeant_login`. Needed on self-hosted base URLs. | detected |
+| `CODEANT_READ_ONLY` | `0` or `false` exposes write tools; anything else hides them. | read-only |
+| `CODEANT_TELEMETRY_DISABLED` | `1` or `true` stops usage events (PostHog, tied to the API token). | enabled |
+| `CODEANT_MCP_MAX_RESULT_CHARS` | Largest tool result, in characters, before the server refuses it with a hint. | `80000` |
 
-The CLI also reads these from `~/.codeant/config.json` when not set in env. For MCP usage prefer env — it keeps per-client config explicit.
+The token, base URL, and dashboard URL fall back to `~/.codeant/config.json` when not set in env. PR tools also need an SCM token (`GITHUB_TOKEN`, `GITLAB_TOKEN`, `BITBUCKET_TOKEN`, `AZURE_DEVOPS_TOKEN`) and, for Azure DevOps, `AZURE_DEVOPS_ORG_URL`.
 
 ---
 
@@ -109,10 +118,13 @@ npm run mcpb:build
 open -a Claude dist/codeant.mcpb
 ```
 
-Claude pops an install dialog asking for the `user_config` fields:
-- **CodeAnt API token** (sensitive, required)
-- **API base URL** (defaults to `https://api.codeant.ai`)
+Claude pops an install dialog asking for the `user_config` fields (all optional):
+- **CodeAnt API token** (sensitive; leave blank and call `codeant_login` instead)
+- **API base URL** (defaults to `https://api.codeant.ai`, which the CLI maps to `https://service.codeant.ai`)
+- **Dashboard URL** (self-hosted only; used by `codeant_login`)
 - **Read-only mode** (defaults to on)
+- **Disable telemetry** (defaults to off)
+- SCM tokens and self-hosted SCM URLs for the PR tools
 
 After install, manage it in **Settings → Connectors**.
 
@@ -162,7 +174,7 @@ cd dist/mcpb-stage
   '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'; sleep 1) | node server/index.js
 ```
 
-Expect 23 tools in the `tools/list` response (or 26 if `CODEANT_READ_ONLY=0`).
+Expect 24 tools in the `tools/list` response (or 27 if `CODEANT_READ_ONLY=0`). `tests/mcp/server.test.js` checks that this list matches the manifest's `tools`.
 
 ### Bumping the version
 
@@ -191,9 +203,9 @@ CodeAnt's MCP server uses stdio + a packaged bundle, so the submission route is
 
 Reviewer notes worth preparing:
 
-- **Auth model.** CodeAnt uses a user-scoped API token entered into `user_config.api_token`. The token never leaves the user's machine — the bundle talks to `api.codeant.ai` (or the user's self-hosted URL) directly. No third-party OAuth flow needed.
+- **Auth model.** Users sign in with the `codeant_login` tool (browser sign-in, token saved to `~/.codeant/config.json`) or paste a token into `user_config.api_token`. The token is stored only on the user's machine (`~/.codeant/config.json`) and is sent only to the CodeAnt API (or the user's self-hosted URL) as a Bearer token — never to any third party. No third-party OAuth flow needed.
 - **Sandbox creds.** Email support@codeant.ai for a reviewer sandbox token; paste it into the submission form's reviewer-notes field along with an org slug that has scans + PRs to browse.
-- **Write tools.** Gated behind `user_config.read_only` (defaults to on). Reviewers can toggle off to test `codeant_scans_start` / `codeant_pr_resolve`.
+- **Write tools.** Gated behind `user_config.read_only` (defaults to on). Reviewers can toggle off to test `codeant_scans_start` / `codeant_pr_resolve` / `codeant_api_request`.
 
 ---
 
@@ -204,5 +216,8 @@ Reviewer notes worth preparing:
 | Server fails to start in Claude Desktop | `~/Library/Logs/Claude/mcp-server-codeant.log` |
 | Tool calls return errors | Same log — server stderr is captured there. |
 | Tool not listed at all | Check `CODEANT_READ_ONLY` — write tools are hidden when set to `1`. |
-| Auth errors on every tool | Confirm `CODEANT_API_TOKEN` is set in the MCP env (not just in `~/.codeant/config.json`). |
+| Auth errors on every tool | Call `codeant_login`, or run `codeant login` in a terminal; the server reads `~/.codeant/config.json` on every request. An explicit `CODEANT_API_TOKEN` in the MCP env takes precedence, so check it is current. |
+| `codeant_login` fails on a self-hosted instance | Set `CODEANT_DASHBOARD_URL` (or the MCPB **Dashboard URL** setting, or `codeant set-dashboard-url`). |
+| A tool returns "Result too large" | Follow the hint (smaller `limit`, filters, `fields`), or raise `CODEANT_MCP_MAX_RESULT_CHARS` if your client accepts larger results. |
+| `codeant_review_local` returns "Could not find a .git directory" | The client started the server outside a git repository (Claude Desktop does). Use a project-scoped client such as Claude Code. |
 | MCPB install dialog never appears | Open `.mcpb` with `open -a Claude dist/codeant.mcpb` to force the desktop app to handle it. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeant-cli",
-  "version": "0.5.9",
+  "version": "0.5.10",
   "description": "Code review CLI tool",
   "type": "module",
   "repository": {

package/src/commands/scans/results.js

@@ -30,6 +30,7 @@ export async function runResults(opts = {}) {
     limit = 100,
     offset = 0,
     failFast = false,
+    returnEnvelope = false,
   } = opts;
 
   if (!repo) {
@@ -145,7 +146,8 @@ export async function runResults(opts = {}) {
     });
   }
 
-  // 10. Render + emit
+  // 10. Render + emit (MCP callers take the envelope instead of stdout)
+  if (returnEnvelope) return envelope;
   const rendered = formatter.render(envelope);
   emit(rendered, outputPath, envelope.findings.length);
 }

package/src/mcp/server.js

@@ -12,14 +12,14 @@ import { runDismissed, runOverrides } from '../commands/scans/dismissed.js';
 import { runStartScan } from '../commands/scans/start-scan.js';
 import { runReviewHeadless } from '../reviewHeadless.js';
 import * as scm from '../scm/index.js';
-import { isAlreadyLoggedIn, runLoginFlow } from '../utils/loginFlow.js';
-import { getConfigValue } from '../utils/config.js';
+import { awaitLoginCompletion, isAlreadyLoggedIn, startLoginFlow } from '../utils/loginFlow.js';
 import { runHotlistGet, runHotlistList } from '../hotlist/client.js';
 import { logoutCodeAnt } from '../utils/logout.js';
 import { runApiRequest } from '../commands/api/request.js';
 import { runOrganizationAntipatterns } from '../findings/antipatterns.js';
 import { runCloudFindingGet, runCloudFindings, runCloudHistory } from '../findings/cloud.js';
 import { runPentestHistory, runPentestIssues, runPentestReport } from '../findings/pentest.js';
+import { maxResultChars, shapeCloudFindings, shapeCloudHistory, shapePentestHistory, shapeRepos, tooLarge } from './shape.js';
 
 const require = createRequire(import.meta.url);
 const pkg = require('../../package.json');
@@ -34,28 +34,48 @@ function isReadOnly() {
   return v !== '0' && v.toLowerCase() !== 'false';
 }
 
-function ok(value) {
-  return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+const INSTRUCTIONS = `CodeAnt AI tools for repository scans, organization-wide security findings, cloud security, pentests, pull requests, and local code review.
+
+- Start with codeant_scans_orgs. When it lists more than one connection, pass org and service to the Hotlist, anti-pattern, cloud, pentest, and API tools.
+- Repository findings: codeant_scans_repos (use full_name) -> codeant_scans_history or codeant_scans_get -> codeant_scans_results, once per repository. Parallel calls are safe.
+- Prioritized findings across the organization: codeant_hotlist_list, then codeant_hotlist_get for one finding.
+- Cloud security: codeant_cloud_scan_history -> codeant_cloud_findings_list (pass status "FAIL" to skip passing checks) -> codeant_cloud_finding_get. Pentests: codeant_pentest_history -> codeant_pentest_issues or codeant_pentest_report.
+- List tools return one page with a total. Page with limit and offset (cursor and next_cursor for the Hotlist), and narrow with filters instead of requesting everything. Results over the size limit are refused with a hint.
+- codeant_review_local and the pull request tools work on the git repository in this server's working directory. Outside a repository, pass name and remote to the pull request tools; local review is unavailable.
+- Pull request and comment tools call GitHub, GitLab, Bitbucket, or Azure DevOps directly and need a token for that provider.
+- On an authentication error ("Missing API key", "Invalid API key", or access denied), call codeant_login with force: true (a configured token may be stale), show the returned loginUrl to the user, and after they finish signing in call codeant_login again without force to confirm.`;
+
+function textResult(text, hint) {
+  if (text.length > maxResultChars()) return fail(tooLarge(text.length, hint));
+  return { content: [{ type: 'text', text }] };
+}
+
+function ok(value, hint) {
+  return textResult(JSON.stringify(value), hint);
 }
 
 function fail(err) {
-  const message = err instanceof Error ? err.message : String(err);
+  const body = err instanceof Error ? { error: err.message } : err && typeof err === 'object' ? err : { error: String(err) };
   return {
     isError: true,
-    content: [{ type: 'text', text: JSON.stringify({ error: message }, null, 2) }],
+    content: [{ type: 'text', text: JSON.stringify(body) }],
   };
 }
 
+function maskToken(token) {
+  return token ? `${token.slice(0, 8)}…` : null;
+}
+
 function resolveRepoOpts(input) {
   const remote = input.remote || scm.detectRemote();
   const name = input.name || scm.detectRepoName();
-  const defaultBranch = input.defaultBranch || scm.detectDefaultBranch();
   if (!remote) throw new Error('Could not detect remote. Pass `remote` (github|gitlab|bitbucket|azure).');
   if (!name) throw new Error('Could not detect repo name. Pass `name` (owner/repo).');
-  return { ...input, remote, name, defaultBranch };
+  return { ...input, remote, name };
 }
 
-// Capture stdout from a function that writes JSON to stdout (used for `scans results` and `scans start-scan`).
+// Capture stdout from a function that writes JSON to stdout (only `scans start-scan`, a write tool).
+// It swaps the global stdout writer, so overlapping calls must not use it.
 async function captureStdout(fn) {
   const chunks = [];
   const origWrite = process.stdout.write.bind(process.stdout);
@@ -71,22 +91,25 @@ async function captureStdout(fn) {
   return chunks.join('');
 }
 
-async function ensureAuthenticated() {
-  const envToken = process.env.CODEANT_API_TOKEN;
-  if (envToken && envToken.trim()) return;
-  if (isAlreadyLoggedIn()) {
-    process.env.CODEANT_API_TOKEN = getConfigValue('apiKeyV2');
-    return;
-  }
+function hasEnvToken() {
+  return !!process.env.CODEANT_API_TOKEN?.trim();
+}
 
+// The saved token is read from ~/.codeant/config.json on every request, so a
+// `codeant login` in another terminal takes effect without restarting the server.
+function warnIfUnauthenticated() {
+  if (hasEnvToken() || isAlreadyLoggedIn()) return;
   console.error('[codeant-mcp] No API token configured. Call the codeant_login tool to sign in, or set CODEANT_API_TOKEN.');
 }
 
-export async function startMcpServer() {
-  await ensureAuthenticated();
+export function createMcpServer() {
+  warnIfUnauthenticated();
 
-  const server = new McpServer({ name: 'codeant', version: pkg.version });
+  const server = new McpServer({ name: 'codeant', version: pkg.version }, { instructions: INSTRUCTIONS });
   const readOnly = isReadOnly();
+  let login = null;
+  // codeant_login calls run one at a time so concurrent calls share one sign-in.
+  let loginQueue = Promise.resolve();
 
   // ─── Scans: discovery ────────────────────────────────────────────────────
   server.registerTool(
@@ -106,14 +129,18 @@ export async function startMcpServer() {
     'codeant_scans_repos',
     {
       title: 'List repositories in a CodeAnt org',
-      description: 'List repositories connected to CodeAnt for a given organization. Use this to enumerate repos before fanning out org-wide queries (e.g. "secrets across all repos"). If `org` is omitted and the user has exactly one org, it is auto-picked.',
+      description: 'List repositories connected to CodeAnt for a given organization, most recently pushed first. Use this to enumerate repos before fanning out org-wide queries (e.g. "secrets across all repos"). Returns one page of slim records (full_name, default_branch, language, pushed_at, ...) with total and next_offset. If `org` is omitted and the user has exactly one org, it is auto-picked.',
       inputSchema: {
         org: z.string().optional().describe('Organization name. Optional when only one org is authenticated.'),
+        search: z.string().optional().describe('Case-insensitive substring match on the repository name.'),
+        limit: z.number().int().positive().max(1000).optional().describe('Max repositories returned (default 100).'),
+        offset: z.number().int().nonnegative().optional().describe('Pagination offset (default 0).'),
+        full: z.boolean().optional().describe('Return the complete provider records instead of slim ones. Default false.'),
       },
       annotations: READ,
     },
-    async ({ org }) => {
-      try { return ok(await runRepos({ org })); } catch (err) { return fail(err); }
+    async ({ org, ...shape }) => {
+      try { return ok(shapeRepos(await runRepos({ org }), shape), 'Use search, or a smaller limit with offset.'); } catch (err) { return fail(err); }
     }
   );
 
@@ -171,34 +198,30 @@ export async function startMcpServer() {
         filterDismissed: z.boolean().optional().describe('Exclude dismissed findings (default false). When false, dismissed findings carry metadata.dismissed.'),
         includeFalsePositives: z.boolean().optional().describe('Include false positives, including user-marked ones (default true). When true, they carry metadata.false_positive.'),
         fields: z.string().optional().describe('Project findings to a subset of fields (comma-separated).'),
-        limit: z.number().int().positive().max(500).optional().describe('Max findings per page (default 100).'),
+        limit: z.number().int().positive().max(500).optional().describe('Max findings per page (default 50).'),
         offset: z.number().int().nonnegative().optional().describe('Pagination offset (default 0).'),
       },
       annotations: READ,
     },
     async (input) => {
       try {
-        const text = await captureStdout(() =>
-          runResults({
-            repo: input.repo,
-            scan: input.scan,
-            branch: input.branch,
-            types: input.types ?? 'all',
-            severity: input.severity,
-            path: input.path,
-            check: input.check,
-            filterDismissed: input.filterDismissed ?? false,
-            includeFalsePositives: input.includeFalsePositives ?? true,
-            format: 'json',
-            output: undefined,
-            fields: input.fields,
-            limit: input.limit ?? 100,
-            offset: input.offset ?? 0,
-            failFast: false,
-          })
-        );
-        // runResults already emits JSON; pass it through unparsed to preserve shape.
-        return { content: [{ type: 'text', text: text || '{}' }] };
+        const envelope = await runResults({
+          repo: input.repo,
+          scan: input.scan,
+          branch: input.branch,
+          types: input.types ?? 'all',
+          severity: input.severity,
+          path: input.path,
+          check: input.check,
+          filterDismissed: input.filterDismissed ?? false,
+          includeFalsePositives: input.includeFalsePositives ?? true,
+          fields: input.fields,
+          limit: input.limit ?? 50,
+          offset: input.offset ?? 0,
+          failFast: false,
+          returnEnvelope: true,
+        });
+        return ok(envelope, 'Use a smaller limit with offset, filter by types, severity, path, or check, or project fields.');
       } catch (err) {
         return fail(err);
       }
@@ -254,15 +277,17 @@ export async function startMcpServer() {
         ticketStatuses: z.array(z.enum(['created', 'not_created'])).optional(),
         compliance: z.array(z.string()).optional(),
         validation: z.array(z.enum(['exploit_confirmed'])).optional(),
-        limit: z.number().int().positive().max(100).optional(),
-        cursor: z.string().optional(),
+        limit: z.number().int().positive().max(100).optional().describe('Page size (default 10).'),
+        cursor: z.string().optional().describe('next_cursor from a previous page.'),
         all: z.boolean().optional().describe('Fetch every matching page. Default false.'),
         maxWaitSeconds: z.number().int().nonnegative().max(600).optional(),
       },
       annotations: READ,
     },
     async (input) => {
-      try { return ok(await runHotlistList(input)); } catch (err) { return fail(err); }
+      try {
+        return ok(await runHotlistList({ ...input, limit: input.limit ?? 10 }), 'Page with limit and cursor instead of all, or add filters such as severities or types.');
+      } catch (err) { return fail(err); }
     }
   );
 
@@ -295,14 +320,16 @@ export async function startMcpServer() {
         service: z.enum(['github', 'gitlab', 'bitbucket', 'azuredevops']).optional(),
         providerBaseUrl: z.string().url().optional(),
         repos: z.array(z.string()).optional().describe('Repositories in owner/repo form. Omit to query every repository.'),
-        limit: z.union([z.literal(25), z.literal(100), z.literal(500)]).optional().describe('Page size (default 500).'),
+        limit: z.union([z.literal(25), z.literal(100), z.literal(500)]).optional().describe('Page size (default 25).'),
         offset: z.number().int().nonnegative().optional().describe('Start offset, a multiple of limit (default 0).'),
         all: z.boolean().optional().describe('Fetch every page from offset on instead of one page.'),
       },
       annotations: READ,
     },
     async (input) => {
-      try { return ok(await runOrganizationAntipatterns(input)); } catch (err) { return fail(err); }
+      try {
+        return ok(await runOrganizationAntipatterns({ ...input, limit: input.limit ?? 25 }), 'Page with limit and offset instead of all, or pass fewer repos.');
+      } catch (err) { return fail(err); }
     }
   );
 
@@ -318,11 +345,16 @@ export async function startMcpServer() {
         provider: z.enum(['aws', 'azure', 'gcp', 'all']).optional().describe('Default all.'),
         kind: z.enum(['cspm', 'vm', 'container']).optional().describe('Default cspm.'),
         latest: z.boolean().optional().describe('Return latest scans instead of complete history. CSPM only.'),
+        limit: z.number().int().positive().max(200).optional().describe('Max scans returned per provider, newest first (default 10).'),
+        offset: z.number().int().nonnegative().optional().describe('Pagination offset within each provider (default 0).'),
+        full: z.boolean().optional().describe('Keep per-service, compliance, and region rollups on each scan. Default false.'),
       },
       annotations: READ,
     },
-    async (input) => {
-      try { return ok(await runCloudHistory(input)); } catch (err) { return fail(err); }
+    async ({ limit, offset, full, ...input }) => {
+      try {
+        return ok(shapeCloudHistory(await runCloudHistory(input), { limit: limit ?? 10, offset: offset ?? 0, full }), 'Pass a single provider, a smaller limit, or latest: true.');
+      } catch (err) { return fail(err); }
     }
   );
 
@@ -330,7 +362,7 @@ export async function startMcpServer() {
     'codeant_cloud_findings_list',
     {
       title: 'List cloud security findings',
-      description: 'Fetch findings for one AWS, Azure, or GCP CSPM, VM, or container scan. VM and container results are paged (limit/offset/all) and carry total.',
+      description: 'Fetch findings for one AWS, Azure, or GCP CSPM, VM, or container scan. Results are paged (limit/offset/all) and carry total; pass status "FAIL" to skip passing CSPM checks. Compliance mappings are omitted unless full is true.',
       inputSchema: {
         org: z.string().optional(),
         service: z.enum(['github', 'gitlab', 'bitbucket', 'azuredevops']).optional(),
@@ -348,14 +380,22 @@ export async function startMcpServer() {
         subscriptionId: z.string().optional(),
         exploitAttemptedOnly: z.boolean().optional(),
         minDaysUnused: z.number().int().nonnegative().optional(),
-        limit: z.union([z.literal(25), z.literal(100), z.literal(500)]).optional().describe('Page size (default 500).'),
+        limit: z.union([z.literal(25), z.literal(100), z.literal(500)]).optional().describe('Page size (default 25).'),
         offset: z.number().int().nonnegative().optional().describe('Start offset, a multiple of limit (default 0).'),
         all: z.boolean().optional().describe('Fetch every page from offset on instead of one page.'),
+        full: z.boolean().optional().describe('Keep compliance mappings on each finding. Default false.'),
       },
       annotations: READ,
     },
-    async (input) => {
-      try { return ok(await runCloudFindings(input)); } catch (err) { return fail(err); }
+    async ({ full, ...input }) => {
+      try {
+        const limit = input.limit ?? 25;
+        const result = await runCloudFindings({ ...input, limit });
+        return ok(
+          shapeCloudFindings(result, { kind: input.kind ?? 'cspm', limit, offset: input.offset ?? 0, all: input.all, full }),
+          'Filter by status (for example "FAIL"), severity, or cloudService, or page with limit and offset instead of all.',
+        );
+      } catch (err) { return fail(err); }
     }
   );
 
@@ -388,16 +428,21 @@ export async function startMcpServer() {
     'codeant_pentest_history',
     {
       title: 'List pentest engagements',
-      description: 'List every pentest engagement visible in the CodeAnt Pentesting UI, including status and finding counts.',
+      description: 'List pentest engagements visible in the CodeAnt Pentesting UI, newest first, including status and finding counts. Returns one page with total and next_offset.',
       inputSchema: {
         org: z.string().optional(),
         service: z.enum(['github', 'gitlab', 'bitbucket', 'azuredevops']).optional(),
         providerBaseUrl: z.string().url().optional(),
+        limit: z.number().int().positive().max(500).optional().describe('Max engagements returned (default 25).'),
+        offset: z.number().int().nonnegative().optional().describe('Pagination offset (default 0).'),
+        full: z.boolean().optional().describe('Keep credit and billing details on each engagement. Default false.'),
       },
       annotations: READ,
     },
-    async (input) => {
-      try { return ok(await runPentestHistory(input)); } catch (err) { return fail(err); }
+    async ({ limit, offset, full, ...input }) => {
+      try {
+        return ok(shapePentestHistory(await runPentestHistory(input), { limit: limit ?? 25, offset: offset ?? 0, full }), 'Use a smaller limit with offset.');
+      } catch (err) { return fail(err); }
     }
   );
 
@@ -445,7 +490,7 @@ export async function startMcpServer() {
     'codeant_api_get',
     {
       title: 'Call a CodeAnt GET API',
-      description: 'Call any authenticated GET endpoint on the configured CodeAnt API host. The path must be relative (for example /extension/scans2/validate); absolute URLs are rejected.',
+      description: 'Call any authenticated GET endpoint on the configured CodeAnt API host, for read APIs no dedicated tool covers. The path must be relative and start with a single "/"; absolute URLs are rejected. Returns { ok, status, tenant, data }; non-2xx responses come back with ok: false.',
       inputSchema: {
         path: z.string().startsWith('/'),
         org: z.string().optional().describe('Organization name. Required when the login has multiple matching connections.'),
@@ -470,12 +515,11 @@ export async function startMcpServer() {
       inputSchema: {
         name: z.string().optional().describe('Repository in owner/repo form. Auto-detected if omitted.'),
         remote: z.enum(['github', 'gitlab', 'bitbucket', 'azure']).optional().describe('Auto-detected if omitted.'),
-        defaultBranch: z.string().optional(),
-        sourceBranch: z.string().optional(),
-        author: z.string().optional().describe('Filter by author login (fuzzy).'),
+        sourceBranch: z.string().optional().describe('Source branch. Exact match, except substring on Bitbucket.'),
+        author: z.string().optional().describe('Author. Substring of the login on GitHub and Bitbucket, exact username on GitLab, identity ID on Azure DevOps.'),
         state: z.enum(['open', 'closed']).optional().describe('Default "open".'),
-        limit: z.number().int().positive().max(100).optional(),
-        offset: z.number().int().nonnegative().optional(),
+        limit: z.number().int().positive().max(100).optional().describe('Max results (default 20).'),
+        offset: z.number().int().nonnegative().optional().describe('Pagination offset, rounded down to a multiple of limit on GitHub and GitLab; ignored on Bitbucket and Azure DevOps.'),
       },
       annotations: READ,
     },
@@ -486,7 +530,6 @@ export async function startMcpServer() {
           await scm.listPullRequests({
             name: opts.name,
             remote: opts.remote,
-            defaultBranch: opts.defaultBranch,
             sourceBranch: opts.sourceBranch,
             authorLogin: opts.author,
             state: opts.state ?? 'open',
@@ -502,12 +545,11 @@ export async function startMcpServer() {
     'codeant_pr_get',
     {
       title: 'Get pull request details',
-      description: 'Fetch detailed information for a single PR/MR including review analysis.',
+      description: 'Fetch one PR/MR: provider metadata (title, state, branches, author, dates) and reviewer approval states.',
       inputSchema: {
         prNumber: z.number().int().positive(),
         name: z.string().optional(),
         remote: z.enum(['github', 'gitlab', 'bitbucket', 'azure']).optional(),
-        defaultBranch: z.string().optional(),
       },
       annotations: READ,
     },
@@ -518,7 +560,6 @@ export async function startMcpServer() {
           await scm.getPullRequest({
             name: opts.name,
             remote: opts.remote,
-            defaultBranch: opts.defaultBranch,
             prNumber: input.prNumber,
           })
         );
@@ -530,14 +571,12 @@ export async function startMcpServer() {
     'codeant_pr_comments',
     {
       title: 'List PR comments',
-      description: 'List comments on a PR/MR with optional filters (CodeAnt-authored only, resolved/unresolved, date range).',
+      description: 'List comments on a PR/MR, optionally only CodeAnt-authored ones or those in a date range. GitLab, Bitbucket, and Azure DevOps comments carry a resolved flag; GitHub comments do not.',
       inputSchema: {
         prNumber: z.number().int().positive(),
         name: z.string().optional(),
         remote: z.enum(['github', 'gitlab', 'bitbucket', 'azure']).optional(),
-        defaultBranch: z.string().optional(),
         codeantGenerated: z.boolean().optional().describe('Only return comments authored by CodeAnt.'),
-        addressed: z.boolean().optional().describe('Filter by addressed/resolved status.'),
         createdAfter: z.string().optional().describe('ISO 8601.'),
         createdBefore: z.string().optional().describe('ISO 8601.'),
       },
@@ -550,10 +589,8 @@ export async function startMcpServer() {
           await scm.listPullRequestComments({
             name: opts.name,
             remote: opts.remote,
-            defaultBranch: opts.defaultBranch,
             prNumber: input.prNumber,
             codeantGenerated: input.codeantGenerated,
-            addressed: input.addressed,
             createdAfter: input.createdAfter,
             createdBefore: input.createdBefore,
           })
@@ -566,14 +603,12 @@ export async function startMcpServer() {
     'codeant_comments_search',
     {
       title: 'Search CodeAnt review comments',
-      description: 'Search across CodeAnt review comments by free-text query. Returns matching comments with repo, PR, and file context.',
+      description: 'Case-insensitive text search over review comments on the 10 most recently updated PRs/MRs of one repository (open ones only on Bitbucket and Azure DevOps). Matches comments from every author; each result has isCodeantComment, prNumber, path, and line.',
       inputSchema: {
         query: z.string(),
         name: z.string().optional(),
         remote: z.enum(['github', 'gitlab', 'bitbucket', 'azure']).optional(),
-        limit: z.number().int().positive().max(50).optional(),
-        includeAddressed: z.boolean().optional(),
-        createdAfter: z.string().optional().describe('ISO 8601.'),
+        limit: z.number().int().positive().max(50).optional().describe('Max matching comments returned (default 10).'),
       },
       annotations: READ,
     },
@@ -586,8 +621,6 @@ export async function startMcpServer() {
             remote: opts.remote,
             query: input.query,
             limit: input.limit ?? 10,
-            includeAddressed: input.includeAddressed ?? false,
-            createdAfter: input.createdAfter,
           })
         );
       } catch (err) { return fail(err); }
@@ -599,7 +632,7 @@ export async function startMcpServer() {
     'codeant_review_local',
     {
       title: 'Review local working-copy changes',
-      description: 'Run a CodeAnt AI review on local working-copy changes and return the findings as JSON. Does not modify files — pair with editor tools to apply fixes. Use this for "review my changes" / "check my staged files" prompts.',
+      description: 'Run a CodeAnt AI review on local working-copy changes and return the findings as JSON. Reviews the git repository in the server\'s working directory, so it needs a client that starts the server inside the project. Does not modify files — pair with editor tools to apply fixes. Use this for "review my changes" / "check my staged files" prompts.',
       inputSchema: {
         scope: z
           .enum(['all', 'uncommitted', 'staged-only', 'committed', 'last-commit', 'last-n-commits', 'base-branch', 'base-commit'])
@@ -626,32 +659,79 @@ export async function startMcpServer() {
           onProgress: () => {},
           onFilesReady: () => {},
         });
-        return ok(result);
+        return result?.error ? fail(result) : ok(result);
       } catch (err) { return fail(err); }
     }
   );
 
   // ─── Auth (always registered — login is needed even in read-only mode) ───
+  // Sign-in runs in the background so the login URL reaches the user right away,
+  // even when no browser can be opened (SSH, containers).
+  async function beginLogin() {
+    const controller = new AbortController();
+    const { token, loginUrl, pollUrl, browserOpened } = await startLoginFlow();
+    const attempt = { status: 'pending', loginUrl, browserOpened, controller };
+    awaitLoginCompletion({ token, pollUrl, signal: controller.signal })
+      .then(() => {
+        // A cancelled login (logout or a newer sign-in aborted this one) must not
+        // restore its token, even if the in-flight poll had already succeeded.
+        if (controller.signal.aborted) {
+          attempt.status = 'aborted';
+          return;
+        }
+        attempt.status = 'success';
+        attempt.token = token;
+        // An explicit CODEANT_API_TOKEN would otherwise keep taking precedence over the new login.
+        if (hasEnvToken()) process.env.CODEANT_API_TOKEN = token;
+      })
+      .catch((err) => {
+        attempt.status = controller.signal.aborted ? 'aborted' : 'failed';
+        attempt.error = err.message;
+      });
+    return attempt;
+  }
+
+  function pendingLogin(attempt) {
+    return {
+      status: 'pending',
+      loginUrl: attempt.loginUrl,
+      browserOpened: attempt.browserOpened,
+      message: attempt.browserOpened
+        ? 'A browser window opened for CodeAnt sign-in. If it did not appear, open loginUrl. After signing in, call codeant_login again to confirm; sign-in is detected within about 10 seconds.'
+        : 'Open loginUrl in a browser to sign in to CodeAnt, then call codeant_login again to confirm; sign-in is detected within about 10 seconds. The link expires in 10 minutes.',
+    };
+  }
+
+  async function handleLogin({ force }) {
+    try {
+      if (login && !force) {
+        if (login.status === 'pending') return ok(pendingLogin(login));
+        const finished = login;
+        login = null;
+        if (finished.status === 'success') return ok({ status: 'success', token: maskToken(finished.token) });
+        return fail(new Error(`${finished.error} Call codeant_login again to start a new sign-in.`));
+      }
+      if (!force && (hasEnvToken() || isAlreadyLoggedIn())) return ok({ alreadyLoggedIn: true });
+      login?.controller.abort();
+      login = await beginLogin();
+      return ok(pendingLogin(login));
+    } catch (err) { return fail(err); }
+  }
+
   server.registerTool(
     'codeant_login',
     {
       title: 'Sign in to CodeAnt AI',
-      description: 'Opens the configured CodeAnt dashboard in the user\'s browser and waits up to 10 minutes for them to complete sign-in. Tell the user to check their browser and finish the flow there. On success the API token is saved to ~/.codeant/config.json (apiKeyV2) and set on the running MCP process, so subsequent tool calls are authenticated without restart. Returns { alreadyLoggedIn: true } immediately if a token is already configured, unless `force` is true.',
+      description: 'Start browser sign-in to CodeAnt AI. Returns immediately with { status: "pending", loginUrl, browserOpened }: show loginUrl to the user (the browser may not open, for example over SSH), then call codeant_login again after they finish to get { status: "success" }. The link expires after 10 minutes. The token is saved to ~/.codeant/config.json (apiKeyV2), which the CodeAnt CLI shares, and later calls use it without a restart. Returns { alreadyLoggedIn: true } if a token is already configured; pass force: true when tools reject that token.',
       inputSchema: {
-        force: z.boolean().optional().describe('Re-authenticate even if a token is already configured. Default false.'),
+        force: z.boolean().optional().describe('Start a new sign-in even if a token is already configured, for example when tools reject it as invalid. Default false.'),
       },
       annotations: { ...WRITE_NON_DESTRUCTIVE, idempotentHint: true },
     },
-    async ({ force }) => {
-      try {
-        const envToken = process.env.CODEANT_API_TOKEN;
-        if (!force && ((envToken && envToken.trim()) || isAlreadyLoggedIn())) {
-          return ok({ alreadyLoggedIn: true });
-        }
-        const { token, loginUrl } = await runLoginFlow();
-        const masked = token ? `${token.slice(0, 8)}…` : null;
-        return ok({ status: 'success', loginUrl, token: masked });
-      } catch (err) { return fail(err); }
+    ({ force }) => {
+      const run = loginQueue.then(() => handleLogin({ force }));
+      loginQueue = run.catch(() => {});
+      return run;
     }
   );
 
@@ -659,12 +739,14 @@ export async function startMcpServer() {
     'codeant_logout',
     {
       title: 'Sign out of CodeAnt AI',
-      description: 'Clears the saved API token from ~/.codeant/config.json and unsets CODEANT_API_TOKEN on the running MCP process. Returns { wasLoggedIn: false } immediately if no token was configured.',
+      description: 'Revoke the API token on the server, clear it from ~/.codeant/config.json (which also signs out the CodeAnt CLI), unset CODEANT_API_TOKEN on the running MCP process, and cancel a pending codeant_login. Returns { wasLoggedIn: false } immediately if no token was configured.',
       inputSchema: {},
       annotations: { ...WRITE_NON_DESTRUCTIVE, idempotentHint: true },
     },
     async () => {
       try {
+        login?.controller.abort();
+        login = null;
         const result = await logoutCodeAnt();
         return ok({
           ...result,
@@ -715,7 +797,7 @@ export async function startMcpServer() {
       async (input) => {
         try {
           const text = await captureStdout(() => runStartScan(input));
-          return { content: [{ type: 'text', text: text || '{}' }] };
+          return textResult(text || '{}');
         } catch (err) { return fail(err); }
       }
     );
@@ -753,6 +835,11 @@ export async function startMcpServer() {
     );
   }
 
+  return server;
+}
+
+export async function startMcpServer() {
+  const server = createMcpServer();
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }

package/src/mcp/shape.js

@@ -0,0 +1,83 @@
+// Result shaping for MCP clients, which cap how much tool output they accept.
+// CLI commands keep returning the full payloads; only MCP responses are trimmed.
+
+const DEFAULT_MAX_RESULT_CHARS = 80_000;
+
+const REPO_FIELDS = ['full_name', 'name', 'private', 'visibility', 'default_branch', 'language', 'description', 'archived', 'pushed_at'];
+const CLOUD_SCAN_DETAIL = ['per_service', 'service_rollup', 'compliance_rollup', 'regions'];
+
+export function maxResultChars() {
+  const configured = Number(process.env.CODEANT_MCP_MAX_RESULT_CHARS);
+  return Number.isInteger(configured) && configured > 0 ? configured : DEFAULT_MAX_RESULT_CHARS;
+}
+
+function page(items, { limit, offset = 0 }) {
+  const slice = items.slice(offset, offset + limit);
+  const end = offset + slice.length;
+  return { items: slice, total: items.length, offset, limit, next_offset: end < items.length ? end : null };
+}
+
+function pick(record, fields) {
+  const picked = {};
+  for (const field of fields) if (field in record) picked[field] = record[field];
+  return Object.keys(picked).length ? picked : record;
+}
+
+function omit(record, fields) {
+  const kept = { ...record };
+  for (const field of fields) delete kept[field];
+  return kept;
+}
+
+export function shapeRepos(result, { search, limit = 100, offset = 0, full = false } = {}) {
+  let repos = result.repos || [];
+  if (search) {
+    const query = search.toLowerCase();
+    repos = repos.filter((repo) => String(repo.full_name || repo.name || '').toLowerCase().includes(query));
+  }
+  const { items, ...pagination } = page(repos, { limit, offset });
+  return { org: result.org, ...pagination, repos: full ? items : items.map((repo) => pick(repo, REPO_FIELDS)) };
+}
+
+export function shapePentestHistory(result, { limit = 25, offset = 0, full = false } = {}) {
+  const { history = [], ...rest } = result;
+  const { items, ...pagination } = page(history, { limit, offset });
+  return { ...rest, ...pagination, history: full ? items : items.map((entry) => omit(entry, ['credit_unlock'])) };
+}
+
+function shapeCloudScans(result, { limit, offset, full }) {
+  if (!Array.isArray(result?.scans)) return result;
+  const { items, ...pagination } = page(result.scans, { limit, offset });
+  return {
+    ...result,
+    ...pagination,
+    total: result.total ?? pagination.total,
+    scans: full ? items : items.map((scan) => omit(scan, CLOUD_SCAN_DETAIL)),
+  };
+}
+
+export function shapeCloudHistory(result, { limit = 10, offset = 0, full = false } = {}) {
+  if (!result.providers) return shapeCloudScans(result, { limit, offset, full });
+  const providers = Object.fromEntries(
+    Object.entries(result.providers).map(([provider, value]) => [provider, shapeCloudScans(value, { limit, offset, full })]),
+  );
+  return { ...result, providers };
+}
+
+// CSPM findings come back unpaged (thousands per scan); VM/container results are
+// already paged by the API, so only the per-finding detail is trimmed for them.
+export function shapeCloudFindings(result, { kind = 'cspm', limit = 25, offset = 0, all = false, full = false } = {}) {
+  const { findings = [], ...rest } = result;
+  const trim = (items) => (full ? items : items.map((finding) => omit(finding, ['compliance'])));
+  if (kind !== 'cspm') return { ...rest, findings: trim(findings) };
+  const { items, ...pagination } = page(findings, { limit: all ? findings.length : limit, offset });
+  return { ...rest, ...pagination, total: rest.total ?? pagination.total, findings: trim(items) };
+}
+
+export function tooLarge(length, hint) {
+  const max = maxResultChars();
+  return {
+    error: `Result too large: ${length} characters (about ${Math.round(length / 4)} tokens), over the ${max}-character limit for one tool result.`,
+    hint: `${hint || 'Narrow the request with limit/offset, filters, or fields where the tool supports them.'} Set CODEANT_MCP_MAX_RESULT_CHARS to raise the limit.`,
+  };
+}

package/src/scm/azure/client.js

@@ -7,7 +7,7 @@ export function getConnection() {
   if (!token) throw new Error('Azure DevOps token not found. Set AZURE_DEVOPS_TOKEN env var or run `codeant set-token azure <token>`.');
 
   const orgUrl = process.env.AZURE_DEVOPS_ORG_URL || getConfigValue('azureDevOpsOrgUrl');
-  if (!orgUrl) throw new Error('Azure DevOps org URL not found. Set AZURE_DEVOPS_ORG_URL env var or run `codeant set-azure-org <url>`.');
+  if (!orgUrl) throw new Error('Azure DevOps org URL not found. Set the AZURE_DEVOPS_ORG_URL env var (for example https://dev.azure.com/<org>) or add azureDevOpsOrgUrl to ~/.codeant/config.json.');
 
   const authHandler = azdev.getPersonalAccessTokenHandler(token);
   return new azdev.WebApi(orgUrl, authHandler);

package/src/utils/loginFlow.js

@@ -4,6 +4,7 @@ import { getBaseUrl, getDashboardUrl } from './baseUrl.js';
 
 const DEFAULT_POLL_INTERVAL = 10_000;
 const DEFAULT_TIMEOUT = 10 * 60 * 1000;
+const BROWSER_SPAWN_TIMEOUT = 2_000;
 
 export function isAlreadyLoggedIn() {
   return !!getConfigValue('apiKeyV2');
@@ -16,16 +17,24 @@ export async function startLoginFlow() {
   const loginUrl = `${dashboardUrl}?ideLoginToken=${token}`;
   const pollUrl = `${baseUrl}/extension/login/status?apiKey=${token}`;
 
-  let browserOpened = false;
+  const browserOpened = await openBrowser(loginUrl);
+  return { token, loginUrl, pollUrl, browserOpened };
+}
+
+// `open` returns the launcher process without an 'error' listener, so a missing
+// launcher (SSH, containers) would otherwise crash the MCP server.
+async function openBrowser(url) {
   try {
     const { default: open } = await import('open');
-    await open(loginUrl);
-    browserOpened = true;
+    const child = await open(url);
+    return await new Promise((resolve) => {
+      child.once('error', () => resolve(false));
+      child.once('spawn', () => resolve(true));
+      setTimeout(() => resolve(true), BROWSER_SPAWN_TIMEOUT).unref?.();
+    });
   } catch {
-    // Caller can fall back to printing loginUrl.
+    return false;
   }
-
-  return { token, loginUrl, pollUrl, browserOpened };
 }
 
 export async function awaitLoginCompletion({
@@ -47,29 +56,26 @@ export async function awaitLoginCompletion({
     try {
       const response = await fetch(pollUrl);
       const data = await response.json();
-      if (data.status === 'yes') {
+      // Do not save the token if the login was aborted while this poll was in flight.
+      if (data.status === 'yes' && !signal?.aborted) {
         setConfigValue('apiKeyV2', token);
-        process.env.CODEANT_API_TOKEN = token;
         return { ok: true, token };
       }
     } catch {
       // Network blip — keep polling.
     }
 
+    if (signal?.aborted) throw new Error('Login aborted');
+
     const remaining = deadline - Date.now();
     if (remaining <= 0) break;
-    await new Promise((resolve) => setTimeout(resolve, Math.min(pollIntervalMs, remaining)));
+    await new Promise((resolve) => {
+      const onAbort = () => { clearTimeout(timer); resolve(); };
+      const timer = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(); }, Math.min(pollIntervalMs, remaining));
+      signal?.addEventListener('abort', onAbort, { once: true });
+    });
   }
 
+  if (signal?.aborted) throw new Error('Login aborted');
   throw new Error('Login timed out. Please try again.');
 }
-
-export async function runLoginFlow({
-  pollIntervalMs = DEFAULT_POLL_INTERVAL,
-  timeoutMs = DEFAULT_TIMEOUT,
-  signal,
-} = {}) {
-  const { token, loginUrl, pollUrl, browserOpened } = await startLoginFlow();
-  const result = await awaitLoginCompletion({ token, pollUrl, pollIntervalMs, timeoutMs, signal });
-  return { ...result, loginUrl, browserOpened };
-}