@debugg-ai/debugg-ai-mcp 1.0.56 → 1.0.58

package/README.md

@@ -86,6 +86,20 @@ Runs an AI browser agent against your app. The agent navigates, interacts, and r
 | `get_execution` | Full detail for a single execution including node-level state. |
 | `cancel_execution` | Cancel an in-flight execution. |
 
+### Pagination
+
+Every `list_*` tool is paginated by default. Response shape:
+
+```json
+{
+  "filter": { "...echoed query params..." },
+  "pageInfo": { "page": 1, "pageSize": 20, "totalCount": 47, "totalPages": 3, "hasMore": true },
+  "<items>": [ ... ]
+}
+```
+
+Pass optional `page` (1-indexed, default 1) and `pageSize` (default 20, max 200; oversized values are clamped) to any list tool. No tool ever silently truncates results.
+
 ### Security invariants
 
 - Passwords are write-only. They never appear in any response body from any tool.
@@ -108,6 +122,18 @@ npm run test:e2e        # real end-to-end evals against the backend
 
 The eval suite spawns the built MCP server as a subprocess, exercises every tool against a real backend, and writes per-flow artifacts to `scripts/evals/artifacts/<timestamp>/`. See `scripts/evals/flows/` for the individual scenarios.
 
+### MCP registration: `debugg-ai-local` vs `debugg-ai`
+
+This repo ships a `.mcp.json` that registers a **project-scoped** server named `debugg-ai-local` pointing at `node dist/index.js` — the freshly-built local code. It only activates when Claude Code's working directory is this repo.
+
+Your other projects should use the **user-scoped** `debugg-ai` registration that pulls from the published npm package:
+
+```bash
+npm run mcp:global      # registers debugg-ai in ~/.claude.json to npx -y @debugg-ai/debugg-ai-mcp
+```
+
+After editing code here, run `npm run mcp:local` (which just rebuilds) so the next invocation of `debugg-ai-local` picks up your changes.
+
 ## Links
 
 [Dashboard](https://app.debugg.ai) · [Docs](https://debugg.ai/docs) · [Issues](https://github.com/debugg-ai/debugg-ai-mcp/issues) · [Discord](https://debugg.ai/discord)

package/dist/handlers/listCredentialsHandler.js

@@ -3,14 +3,17 @@ import { handleExternalServiceError } from '../utils/errors.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { config } from '../config/index.js';
 import { detectRepoName } from '../utils/gitContext.js';
+import { toPaginationParams, makePageInfo } from '../utils/pagination.js';
 const logger = new Logger({ module: 'listCredentialsHandler' });
 export async function listCredentialsHandler(input, _context) {
     const start = Date.now();
+    const pagination = toPaginationParams({ page: input.page, pageSize: input.pageSize });
     logger.toolStart('list_credentials', {
         environmentId: input.environmentId,
         projectUuid: input.projectUuid,
         q: input.q,
         role: input.role,
+        ...pagination,
     });
     try {
         const client = new DebuggAIServerClient(config.api.key);
@@ -22,6 +25,7 @@ export async function listCredentialsHandler(input, _context) {
                 const payload = {
                     error: 'NoProjectResolved',
                     message: 'No git repo detected and no projectUuid provided. Pass projectUuid (get it from list_projects) or invoke from a directory with a git origin.',
+                    pageInfo: makePageInfo(pagination.page, pagination.pageSize, 0, null),
                     credentials: [],
                 };
                 logger.toolComplete('list_credentials', Date.now() - start);
@@ -32,6 +36,7 @@ export async function listCredentialsHandler(input, _context) {
                 const payload = {
                     error: 'NoProjectResolved',
                     message: `No DebuggAI project found for repo "${repoName}". Pass projectUuid explicitly.`,
+                    pageInfo: makePageInfo(pagination.page, pagination.pageSize, 0, null),
                     credentials: [],
                 };
                 logger.toolComplete('list_credentials', Date.now() - start);
@@ -39,17 +44,34 @@ export async function listCredentialsHandler(input, _context) {
             }
             projectUuid = project.uuid;
         }
+        let pageInfo;
         let credentials = [];
         if (input.environmentId) {
-            credentials = await client.listCredentialsForEnvironment(projectUuid, input.environmentId, input.q, input.role);
+            // Paginated path — scoped to a single env.
+            const result = await client.listCredentialsPaginated(projectUuid, input.environmentId, pagination, input.q, input.role);
+            pageInfo = result.pageInfo;
+            credentials = result.credentials;
         }
         else {
-            // No environment filter — iterate all envs for the project
+            // No env filter — iterate all envs and merge. Synthesize pageInfo from the full
+            // result (client-side paginate the merged list for consistent shape).
             const envs = await client.listEnvironmentsForProject(projectUuid);
+            const all = [];
             for (const env of envs) {
                 const credsForEnv = await client.listCredentialsForEnvironment(projectUuid, env.uuid, input.q, input.role);
-                credentials.push(...credsForEnv);
+                all.push(...credsForEnv);
             }
+            const offset = (pagination.page - 1) * pagination.pageSize;
+            credentials = all.slice(offset, offset + pagination.pageSize);
+            const totalCount = all.length;
+            const totalPages = totalCount === 0 ? 0 : Math.ceil(totalCount / pagination.pageSize);
+            pageInfo = {
+                page: pagination.page,
+                pageSize: pagination.pageSize,
+                totalCount,
+                totalPages,
+                hasMore: offset + credentials.length < totalCount,
+            };
         }
         const payload = {
             project: { uuid: projectUuid },
@@ -58,7 +80,7 @@ export async function listCredentialsHandler(input, _context) {
                 q: input.q ?? null,
                 role: input.role ?? null,
             },
-            count: credentials.length,
+            pageInfo,
             credentials,
         };
         logger.toolComplete('list_credentials', Date.now() - start);

package/dist/handlers/listEnvironmentsHandler.js

@@ -3,10 +3,12 @@ import { handleExternalServiceError } from '../utils/errors.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { config } from '../config/index.js';
 import { detectRepoName } from '../utils/gitContext.js';
+import { toPaginationParams, makePageInfo } from '../utils/pagination.js';
 const logger = new Logger({ module: 'listEnvironmentsHandler' });
 export async function listEnvironmentsHandler(input, _context) {
     const start = Date.now();
-    logger.toolStart('list_environments', { projectUuid: input.projectUuid, q: input.q });
+    const pagination = toPaginationParams({ page: input.page, pageSize: input.pageSize });
+    logger.toolStart('list_environments', { projectUuid: input.projectUuid, q: input.q, ...pagination });
     try {
         const client = new DebuggAIServerClient(config.api.key);
         await client.init();
@@ -19,6 +21,7 @@ export async function listEnvironmentsHandler(input, _context) {
                 const payload = {
                     error: 'NoProjectResolved',
                     message: 'No git repo detected and no projectUuid provided. Pass projectUuid (get it from list_projects) or invoke from a directory with a git origin.',
+                    pageInfo: makePageInfo(pagination.page, pagination.pageSize, 0, null),
                     environments: [],
                 };
                 logger.toolComplete('list_environments', Date.now() - start);
@@ -29,6 +32,7 @@ export async function listEnvironmentsHandler(input, _context) {
                 const payload = {
                     error: 'NoProjectResolved',
                     message: `No DebuggAI project found for repo "${repoName}". Pass projectUuid explicitly or call list_projects to discover.`,
+                    pageInfo: makePageInfo(pagination.page, pagination.pageSize, 0, null),
                     environments: [],
                 };
                 logger.toolComplete('list_environments', Date.now() - start);
@@ -38,15 +42,15 @@ export async function listEnvironmentsHandler(input, _context) {
             projectName = project.name;
             projectRepoName = project.repo?.name ?? repoName;
         }
-        const environments = await client.listEnvironmentsForProject(projectUuid, input.q);
+        const { pageInfo, environments } = await client.listEnvironmentsPaginated(projectUuid, pagination, input.q);
         const payload = {
             project: {
                 uuid: projectUuid,
                 name: projectName,
                 repoName: projectRepoName,
             },
-            query: input.q ?? null,
-            count: environments.length,
+            filter: { q: input.q ?? null },
+            pageInfo,
             environments,
         };
         logger.toolComplete('list_environments', Date.now() - start);

package/dist/handlers/listExecutionsHandler.js

@@ -2,23 +2,23 @@ import { Logger } from '../utils/logger.js';
 import { handleExternalServiceError } from '../utils/errors.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { config } from '../config/index.js';
+import { toPaginationParams } from '../utils/pagination.js';
 const logger = new Logger({ module: 'listExecutionsHandler' });
 export async function listExecutionsHandler(input, _context) {
     const start = Date.now();
-    logger.toolStart('list_executions', { status: input.status, limit: input.limit });
+    const pagination = toPaginationParams({ page: input.page, pageSize: input.pageSize });
+    logger.toolStart('list_executions', { status: input.status, ...pagination });
     try {
         const client = new DebuggAIServerClient(config.api.key);
         await client.init();
-        const { count, executions } = await client.workflows.listExecutions({
+        const { pageInfo, executions } = await client.workflows.listExecutions({
             status: input.status,
-            limit: input.limit,
+            page: pagination.page,
+            pageSize: pagination.pageSize,
         });
         const payload = {
-            filter: {
-                status: input.status ?? null,
-                limit: input.limit ?? null,
-            },
-            count,
+            filter: { status: input.status ?? null },
+            pageInfo,
             executions,
         };
         logger.toolComplete('list_executions', Date.now() - start);

package/dist/handlers/listProjectsHandler.js

@@ -2,17 +2,19 @@ import { Logger } from '../utils/logger.js';
 import { handleExternalServiceError } from '../utils/errors.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { config } from '../config/index.js';
+import { toPaginationParams } from '../utils/pagination.js';
 const logger = new Logger({ module: 'listProjectsHandler' });
 export async function listProjectsHandler(input, _context) {
     const start = Date.now();
-    logger.toolStart('list_projects', { q: input.q });
+    const pagination = toPaginationParams({ page: input.page, pageSize: input.pageSize });
+    logger.toolStart('list_projects', { q: input.q, ...pagination });
     try {
         const client = new DebuggAIServerClient(config.api.key);
         await client.init();
-        const projects = await client.listProjects(input.q);
+        const { pageInfo, projects } = await client.listProjects(pagination, input.q);
         const payload = {
-            query: input.q ?? null,
-            count: projects.length,
+            filter: { q: input.q ?? null },
+            pageInfo,
             projects: projects.map(p => ({
                 uuid: p.uuid,
                 name: p.name,

package/dist/services/index.js

@@ -116,24 +116,34 @@ export class DebuggAIServerClient {
         await this.tx.delete(`api/v1/projects/${uuid}/`);
     }
     /**
-     * List projects accessible to the current API key.
+     * List projects accessible to the current API key. Paginated.
      * Optional q filters by project name / repo name server-side (backend `?search=`).
-     * Returns the first page only; pagination can be added if needed.
      */
-    async listProjects(q) {
+    async listProjects(pagination, q) {
         if (!this.tx)
             throw new Error('Client not initialized — call init() first');
-        const params = q ? { search: q } : undefined;
+        const { makePageInfo } = await import('../utils/pagination.js');
+        const params = { page: pagination.page, pageSize: pagination.pageSize };
+        if (q)
+            params.search = q;
         const response = await this.tx.get('api/v1/projects/', params);
-        return response?.results ?? [];
+        return {
+            pageInfo: makePageInfo(pagination.page, pagination.pageSize, response?.count ?? 0, response?.next),
+            projects: response?.results ?? [],
+        };
     }
     /**
-     * List environments for a project. Optional q filters by name via backend ?search=.
+     * List environments for a project. Paginated.
+     * Optional q filters by name via backend ?search=.
+     * The bare-array variant (no pagination) is still used internally by
+     * list_credentials when iterating across all envs.
      */
     async listEnvironmentsForProject(projectUuid, q) {
         if (!this.tx)
             throw new Error('Client not initialized — call init() first');
-        const params = q ? { search: q } : undefined;
+        const params = { pageSize: 200 };
+        if (q)
+            params.search = q;
         const response = await this.tx.get(`api/v1/projects/${projectUuid}/environments/`, params);
         return (response?.results ?? []).map((e) => ({
             uuid: e.uuid,
@@ -142,6 +152,24 @@ export class DebuggAIServerClient {
             isActive: e.isActive,
         }));
     }
+    async listEnvironmentsPaginated(projectUuid, pagination, q) {
+        if (!this.tx)
+            throw new Error('Client not initialized — call init() first');
+        const { makePageInfo } = await import('../utils/pagination.js');
+        const params = { page: pagination.page, pageSize: pagination.pageSize };
+        if (q)
+            params.search = q;
+        const response = await this.tx.get(`api/v1/projects/${projectUuid}/environments/`, params);
+        return {
+            pageInfo: makePageInfo(pagination.page, pagination.pageSize, response?.count ?? 0, response?.next),
+            environments: (response?.results ?? []).map((e) => ({
+                uuid: e.uuid,
+                name: e.name,
+                url: e.url || e.activeUrl || '',
+                isActive: e.isActive,
+            })),
+        };
+    }
     /**
      * Create a new environment under a project.
      * Backend requires `name`. Other fields optional.
@@ -213,13 +241,44 @@ export class DebuggAIServerClient {
         };
     }
     /**
-     * List credentials for a specific environment. q filters label/username client-side.
-     * role filters for exact match.
+     * List credentials for a specific environment. Unpaginated (fetches up to
+     * backend max pageSize). q filters label/username client-side (backend
+     * ?search= is inconsistent on this endpoint); role filters server-side.
+     * Used internally by list_credentials when iterating across envs.
      */
     async listCredentialsForEnvironment(projectUuid, envUuid, q, role) {
         if (!this.tx)
             throw new Error('Client not initialized — call init() first');
-        const response = await this.tx.get(`api/v1/projects/${projectUuid}/environments/${envUuid}/credentials/`);
+        const params = { pageSize: 200 };
+        if (role)
+            params.role = role;
+        const response = await this.tx.get(`api/v1/projects/${projectUuid}/environments/${envUuid}/credentials/`, params);
+        let creds = (response?.results ?? [])
+            .filter((c) => c.isActive)
+            .map((c) => ({
+            uuid: c.uuid,
+            label: c.label || c.username,
+            username: c.username,
+            role: c.role,
+            environmentUuid: envUuid,
+        }));
+        if (q) {
+            const needle = q.toLowerCase();
+            creds = creds.filter(c => c.label.toLowerCase().includes(needle) ||
+                c.username.toLowerCase().includes(needle));
+        }
+        return creds;
+    }
+    async listCredentialsPaginated(projectUuid, envUuid, pagination, q, role) {
+        if (!this.tx)
+            throw new Error('Client not initialized — call init() first');
+        const { makePageInfo } = await import('../utils/pagination.js');
+        const params = { page: pagination.page, pageSize: pagination.pageSize };
+        // Backend ?role= filter is currently ignored (bead hpo) — pass it anyway for future fix-forward,
+        // but re-apply the filter client-side so behavior is correct today.
+        if (role)
+            params.role = role;
+        const response = await this.tx.get(`api/v1/projects/${projectUuid}/environments/${envUuid}/credentials/`, params);
         let creds = (response?.results ?? [])
             .filter((c) => c.isActive)
             .map((c) => ({
@@ -237,7 +296,10 @@ export class DebuggAIServerClient {
         if (role) {
             creds = creds.filter(c => c.role === role);
         }
-        return creds;
+        return {
+            pageInfo: makePageInfo(pagination.page, pagination.pageSize, response?.count ?? 0, response?.next),
+            credentials: creds,
+        };
     }
     /**
      * Create a credential on an environment. password is write-only — never echoed back.

package/dist/services/workflows.js

@@ -48,14 +48,13 @@ export const createWorkflowsService = (tx) => {
             return response;
         },
         async listExecutions(filters) {
-            const params = {};
+            const { makePageInfo } = await import('../utils/pagination.js');
+            const params = { page: filters.page, pageSize: filters.pageSize };
             if (filters.status)
                 params.status = filters.status;
-            if (filters.limit)
-                params.pageSize = filters.limit; // backend uses page_size (snake_case via transport)
             const response = await tx.get('api/v1/workflows/executions/', params);
             return {
-                count: response?.count ?? 0,
+                pageInfo: makePageInfo(filters.page, filters.pageSize, response?.count ?? 0, response?.next),
                 executions: (response?.results ?? []).map((e) => ({
                     uuid: e.uuid,
                     workflow: e.workflow,

package/dist/tools/listCredentials.js

@@ -1,6 +1,6 @@
 import { ListCredentialsInputSchema } from '../types/index.js';
 import { listCredentialsHandler } from '../handlers/listCredentialsHandler.js';
-const DESCRIPTION = `List credentials for a DebuggAI project. By default targets the project resolved from the current git repo. Optional environmentId filters to a single environment. Optional q filters by label or username. Optional role filters for exact match (server-side). Optional projectUuid overrides the auto-detected project. Never returns passwords or secret values.`;
+const DESCRIPTION = `List credentials for a DebuggAI project. Paginated when scoped to a single environment (pass environmentId); otherwise iterates all envs and returns everything with pageInfo reflecting the total. Default pageSize 20, max 200. Optional q filters label/username (client-side); role filters server-side. Never returns passwords.`;
 export function buildListCredentialsTool() {
     return {
         name: 'list_credentials',
@@ -9,22 +9,12 @@ export function buildListCredentialsTool() {
         inputSchema: {
             type: 'object',
             properties: {
-                environmentId: {
-                    type: 'string',
-                    description: 'Optional: filter credentials to a single environment UUID.',
-                },
-                projectUuid: {
-                    type: 'string',
-                    description: 'Optional: UUID of the target project. Defaults to the project resolved from the current git repo.',
-                },
-                q: {
-                    type: 'string',
-                    description: 'Optional: filter by label or username (case-insensitive substring).',
-                },
-                role: {
-                    type: 'string',
-                    description: 'Optional: filter by exact role match (e.g. "admin", "guest").',
-                },
+                environmentId: { type: 'string', description: 'Optional: filter to a single environment. Required for true pagination.' },
+                projectUuid: { type: 'string', description: 'Optional: UUID of the target project. Defaults to git-auto-detect.' },
+                q: { type: 'string', description: 'Optional: filter by label or username.' },
+                role: { type: 'string', description: 'Optional: filter by exact role match.' },
+                page: { type: 'number', description: 'Optional: 1-indexed page number. Default 1.', minimum: 1 },
+                pageSize: { type: 'number', description: 'Optional: items per page. Default 20, max 200.', minimum: 1, maximum: 200 },
             },
             additionalProperties: false,
         },

package/dist/tools/listEnvironments.js

@@ -1,6 +1,6 @@
 import { ListEnvironmentsInputSchema } from '../types/index.js';
 import { listEnvironmentsHandler } from '../handlers/listEnvironmentsHandler.js';
-const DESCRIPTION = `List environments for a DebuggAI project. By default targets the project resolved from the current git repo; pass projectUuid to target a different project (get UUIDs via list_projects). Optional q filters by environment name via the backend search. Returns each environment's uuid, name, url, and isActive flag.`;
+const DESCRIPTION = `List environments for a DebuggAI project. Paginated — every response includes pageInfo {page, pageSize, totalCount, totalPages, hasMore}; default pageSize 20, max 200. By default targets the project resolved from the current git repo; pass projectUuid to target a different project. Optional q filters by environment name via backend search.`;
 export function buildListEnvironmentsTool() {
     return {
         name: 'list_environments',
@@ -9,14 +9,10 @@ export function buildListEnvironmentsTool() {
         inputSchema: {
             type: 'object',
             properties: {
-                projectUuid: {
-                    type: 'string',
-                    description: 'Optional: UUID of the project to query. Defaults to the project resolved from the current git repo.',
-                },
-                q: {
-                    type: 'string',
-                    description: 'Optional: filter environments by name (server-side search).',
-                },
+                projectUuid: { type: 'string', description: 'Optional: UUID of the project to query. Defaults to git-auto-detect.' },
+                q: { type: 'string', description: 'Optional: filter by environment name.' },
+                page: { type: 'number', description: 'Optional: 1-indexed page number. Default 1.', minimum: 1 },
+                pageSize: { type: 'number', description: 'Optional: items per page. Default 20, max 200.', minimum: 1, maximum: 200 },
             },
             additionalProperties: false,
         },

package/dist/tools/listExecutions.js

@@ -1,6 +1,6 @@
 import { ListExecutionsInputSchema } from '../types/index.js';
 import { listExecutionsHandler } from '../handlers/listExecutionsHandler.js';
-const DESCRIPTION = `List workflow execution history. Optional status filter (e.g. "completed", "running", "failed", "cancelled") passed to backend ?status=. Optional limit caps the page size (default 10). Returns {count, executions:[{uuid,workflow,status,mode,source,outcome,startedAt,completedAt,durationMs,timestamp}]} — summary shape only. Use get_execution for full detail on a single uuid.`;
+const DESCRIPTION = `List workflow execution history. Paginated — every response includes pageInfo {page, pageSize, totalCount, totalPages, hasMore}; default pageSize 20, max 200. Optional status filter (e.g. "completed", "running", "failed", "cancelled") passed to backend ?status=. Returns summary shape; use get_execution for full detail on a single uuid.`;
 export function buildListExecutionsTool() {
     return {
         name: 'list_executions',
@@ -10,7 +10,8 @@ export function buildListExecutionsTool() {
             type: 'object',
             properties: {
                 status: { type: 'string', description: 'Optional: filter by execution status.' },
-                limit: { type: 'number', description: 'Optional: page size cap.', minimum: 1, maximum: 200 },
+                page: { type: 'number', description: 'Optional: 1-indexed page number. Default 1.', minimum: 1 },
+                pageSize: { type: 'number', description: 'Optional: items per page. Default 20, max 200.', minimum: 1, maximum: 200 },
             },
             additionalProperties: false,
         },

package/dist/tools/listProjects.js

@@ -1,6 +1,6 @@
 import { ListProjectsInputSchema } from '../types/index.js';
 import { listProjectsHandler } from '../handlers/listProjectsHandler.js';
-const DESCRIPTION = `List DebuggAI projects accessible to the current API key. Optional "q" input filters by project name or repo name (passed through to the backend search). Returns uuid, name, slug, and repo for each project. Use this when you don't know which project to target or when the current git repo doesn't resolve to a DebuggAI project.`;
+const DESCRIPTION = `List DebuggAI projects accessible to the current API key. Paginated — every response includes pageInfo {page, pageSize, totalCount, totalPages, hasMore}; default pageSize 20, max 200. Optional "q" input filters by project name or repo name via backend search. Use this when you don't know which project to target or when the current git repo doesn't resolve to a DebuggAI project.`;
 export function buildListProjectsTool() {
     return {
         name: 'list_projects',
@@ -9,10 +9,9 @@ export function buildListProjectsTool() {
         inputSchema: {
             type: 'object',
             properties: {
-                q: {
-                    type: 'string',
-                    description: 'Optional search query to filter projects by name or repo name.',
-                },
+                q: { type: 'string', description: 'Optional: search by name or repo name.' },
+                page: { type: 'number', description: 'Optional: 1-indexed page number. Default 1.', minimum: 1 },
+                pageSize: { type: 'number', description: 'Optional: items per page. Default 20, max 200.', minimum: 1, maximum: 200 },
             },
             additionalProperties: false,
         },

package/dist/types/index.js

@@ -20,6 +20,8 @@ export const TestPageChangesInputSchema = z.object({
 export const ListEnvironmentsInputSchema = z.object({
     projectUuid: z.string().uuid().optional(),
     q: z.string().min(1).optional(),
+    page: z.number().int().min(1).optional(),
+    pageSize: z.number().int().min(1).optional(),
 }).strict();
 export const CreateEnvironmentInputSchema = z.object({
     name: z.string().min(1, 'name is required'),
@@ -74,7 +76,8 @@ export const DeleteProjectInputSchema = z.object({
 }).strict();
 export const ListExecutionsInputSchema = z.object({
     status: z.string().min(1).optional(),
-    limit: z.number().int().min(1).max(200).optional(),
+    page: z.number().int().min(1).optional(),
+    pageSize: z.number().int().min(1).optional(),
 }).strict();
 export const GetExecutionInputSchema = z.object({
     uuid: z.string().uuid(),
@@ -87,6 +90,8 @@ export const ListCredentialsInputSchema = z.object({
     projectUuid: z.string().uuid().optional(),
     q: z.string().min(1).optional(),
     role: z.string().min(1).optional(),
+    page: z.number().int().min(1).optional(),
+    pageSize: z.number().int().min(1).optional(),
 }).strict();
 export const CreateCredentialInputSchema = z.object({
     environmentId: z.string().uuid(),
@@ -98,6 +103,8 @@ export const CreateCredentialInputSchema = z.object({
 }).strict();
 export const ListProjectsInputSchema = z.object({
     q: z.string().min(1).optional(),
+    page: z.number().int().min(1).optional(),
+    pageSize: z.number().int().min(1).optional(),
 }).strict();
 /**
  * Error types

package/dist/utils/pagination.js

@@ -0,0 +1,32 @@
+/**
+ * Shared pagination helpers for list_* tools. Every list tool must expose
+ * {page?, pageSize?} inputs and return a consistent pageInfo object so
+ * callers never silently get truncated results.
+ */
+export const DEFAULT_PAGE_SIZE = 20;
+export const MAX_PAGE_SIZE = 200;
+/**
+ * Translate caller inputs into safe backend query params.
+ * Defaults page=1, pageSize=20. Clamps pageSize to [1, MAX_PAGE_SIZE=200].
+ * Returns snake_case keys matching the backend's `?page=&page_size=` convention.
+ */
+export function toPaginationParams(input) {
+    const page = Math.max(1, Math.floor(input.page ?? 1));
+    const pageSize = Math.min(MAX_PAGE_SIZE, Math.max(1, Math.floor(input.pageSize ?? DEFAULT_PAGE_SIZE)));
+    return { page, pageSize };
+}
+/**
+ * Build the pageInfo block for the MCP response from the backend's
+ * DRF-style list envelope (count + next + previous).
+ */
+export function makePageInfo(page, pageSize, count, next) {
+    const totalCount = count ?? 0;
+    const totalPages = totalCount === 0 ? 0 : Math.ceil(totalCount / pageSize);
+    return {
+        page,
+        pageSize,
+        totalCount,
+        totalPages,
+        hasMore: !!next,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "1.0.56",
+  "version": "1.0.58",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "bin": {
@@ -26,8 +26,8 @@
     "version:major": "npm version major --no-git-tag-version",
     "publish:check": "npm pack --dry-run",
     "prepublishOnly": "npm test && npm run build",
-    "mcp:local": "npm run build && claude mcp remove debugg-ai 2>/dev/null; claude mcp add debugg-ai -s user -e DEBUGGAI_API_KEY=KrvXlzVFXVZO82UErXye5N7CtnmBTu1GKULrJnwXRRU -e POSTHOG_API_KEY=phc_4h2Yov2P0Vc9UMqfKf3dYKSQ6THOs7N6LZR0VKYopZN -- node /Users/qosha/Repos/debugg-ai/debugg-ai-mcp/dist/index.js",
-    "mcp:npm": "claude mcp remove debugg-ai 2>/dev/null; claude mcp add debugg-ai -s user -e DEBUGGAI_API_KEY=KrvXlzVFXVZO82UErXye5N7CtnmBTu1GKULrJnwXRRU -e POSTHOG_API_KEY=phc_4h2Yov2P0Vc9UMqfKf3dYKSQ6THOs7N6LZR0VKYopZN -- npx -y @debugg-ai/debugg-ai-mcp"
+    "mcp:local": "npm run build && echo 'Local MCP built. Claude Code auto-registers it as debugg-ai-local from .mcp.json when cwd is this repo.'",
+    "mcp:global": "claude mcp remove debugg-ai 2>/dev/null; claude mcp add debugg-ai -s user -e DEBUGGAI_API_KEY=KrvXlzVFXVZO82UErXye5N7CtnmBTu1GKULrJnwXRRU -e POSTHOG_API_KEY=phc_4h2Yov2P0Vc9UMqfKf3dYKSQ6THOs7N6LZR0VKYopZN -- npx -y @debugg-ai/debugg-ai-mcp"
   },
   "keywords": [
     "debugg",