@debugg-ai/debugg-ai-mcp 1.0.57 → 1.0.59

package/README.md

@@ -32,7 +32,7 @@ docker run -i --rm --init -e DEBUGGAI_API_KEY=your_api_key quinnosha/debugg-ai-m
 
 ## Tools
 
-The server exposes **18** tools. The headline one is `check_app_in_browser`; the rest manage projects, environments, credentials, and workflow execution history.
+The server exposes **21** tools. The headline one is `check_app_in_browser`; the rest manage projects, environments, credentials, workflow execution history, and the teams/repos needed to create new projects.
 
 ### `check_app_in_browser`
 
@@ -55,9 +55,17 @@ Runs an AI browser agent against your app. The agent navigates, interacts, and r
 |------|---------|
 | `list_projects` | List projects accessible to your API key. Optional `q` for name/repo search. |
 | `get_project` | Fetch a project by `uuid`. Simplified shape (no team/runner internals). |
+| `create_project` | Create a new project. Needs `name`, `platform` (e.g. `web`), `teamUuid` (from `list_teams`), and `repoUuid` (from `list_repos`). |
 | `update_project` | PATCH a project's `name` or `description`. |
 | `delete_project` | Destructive delete. Cascades envs, creds, and history. |
 
+### Teams and repos (prerequisites for `create_project`)
+
+| Tool | Purpose |
+|------|---------|
+| `list_teams` | Paginated list of teams accessible to the API key; optional `q` for search. |
+| `list_repos` | Paginated list of GitHub-linked repos; optional `q` for search. Use repos with `isGithubAuthorized: true` when creating a project. |
+
 ### Environment management (scoped to a project)
 
 | Tool | Purpose |
@@ -86,6 +94,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.

package/dist/handlers/createProjectHandler.js

@@ -0,0 +1,31 @@
+import { Logger } from '../utils/logger.js';
+import { handleExternalServiceError } from '../utils/errors.js';
+import { DebuggAIServerClient } from '../services/index.js';
+import { config } from '../config/index.js';
+const logger = new Logger({ module: 'createProjectHandler' });
+export async function createProjectHandler(input, _context) {
+    const start = Date.now();
+    logger.toolStart('create_project', {
+        name: input.name,
+        platform: input.platform,
+        teamUuid: input.teamUuid,
+        repoUuid: input.repoUuid,
+    });
+    try {
+        const client = new DebuggAIServerClient(config.api.key);
+        await client.init();
+        const project = await client.createProject({
+            name: input.name,
+            platform: input.platform,
+            teamUuid: input.teamUuid,
+            repoUuid: input.repoUuid,
+        });
+        const payload = { created: true, project };
+        logger.toolComplete('create_project', Date.now() - start);
+        return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+    }
+    catch (error) {
+        logger.toolError('create_project', error, Date.now() - start);
+        throw handleExternalServiceError(error, 'DebuggAI', 'create_project');
+    }
+}

package/dist/handlers/index.js

@@ -16,3 +16,6 @@ export * from './deleteProjectHandler.js';
 export * from './listExecutionsHandler.js';
 export * from './getExecutionHandler.js';
 export * from './cancelExecutionHandler.js';
+export * from './listTeamsHandler.js';
+export * from './listReposHandler.js';
+export * from './createProjectHandler.js';

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/handlers/listReposHandler.js

@@ -0,0 +1,27 @@
+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: 'listReposHandler' });
+export async function listReposHandler(input, _context) {
+    const start = Date.now();
+    const pagination = toPaginationParams({ page: input.page, pageSize: input.pageSize });
+    logger.toolStart('list_repos', { q: input.q, ...pagination });
+    try {
+        const client = new DebuggAIServerClient(config.api.key);
+        await client.init();
+        const { pageInfo, repos } = await client.listRepos(pagination, input.q);
+        const payload = {
+            filter: { q: input.q ?? null },
+            pageInfo,
+            repos,
+        };
+        logger.toolComplete('list_repos', Date.now() - start);
+        return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+    }
+    catch (error) {
+        logger.toolError('list_repos', error, Date.now() - start);
+        throw handleExternalServiceError(error, 'DebuggAI', 'list_repos');
+    }
+}

package/dist/handlers/listTeamsHandler.js

@@ -0,0 +1,27 @@
+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: 'listTeamsHandler' });
+export async function listTeamsHandler(input, _context) {
+    const start = Date.now();
+    const pagination = toPaginationParams({ page: input.page, pageSize: input.pageSize });
+    logger.toolStart('list_teams', { q: input.q, ...pagination });
+    try {
+        const client = new DebuggAIServerClient(config.api.key);
+        await client.init();
+        const { pageInfo, teams } = await client.listTeams(pagination, input.q);
+        const payload = {
+            filter: { q: input.q ?? null },
+            pageInfo,
+            teams,
+        };
+        logger.toolComplete('list_teams', Date.now() - start);
+        return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+    }
+    catch (error) {
+        logger.toolError('list_teams', error, Date.now() - start);
+        throw handleExternalServiceError(error, 'DebuggAI', 'list_teams');
+    }
+}

package/dist/services/index.js

@@ -116,24 +116,89 @@ 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 ?? [],
+        };
+    }
+    async listTeams(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/teams/', params);
+        return {
+            pageInfo: makePageInfo(pagination.page, pagination.pageSize, response?.count ?? 0, response?.next),
+            teams: (response?.results ?? []).map((t) => ({
+                uuid: t.uuid,
+                name: t.name,
+                description: t.description ?? null,
+                memberCount: t.memberCount ?? 0,
+                ownerCount: t.ownerCount ?? 0,
+                currentUserRole: t.currentUserRole ?? null,
+            })),
+        };
+    }
+    async listRepos(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/repos/', params);
+        return {
+            pageInfo: makePageInfo(pagination.page, pagination.pageSize, response?.count ?? 0, response?.next),
+            repos: (response?.results ?? []).map((r) => ({
+                uuid: r.uuid,
+                name: r.name,
+                url: r.url ?? '',
+                description: r.description ?? null,
+                isPrivate: !!r.isPrivate,
+                isGithubAuthorized: !!r.isGithubAuthorized,
+                githubAccountLogin: r.githubAccountLogin ?? null,
+            })),
+        };
+    }
+    async createProject(input) {
+        if (!this.tx)
+            throw new Error('Client not initialized — call init() first');
+        // Backend expects `team` and `repo` keys (UUIDs). MCP surfaces them as
+        // teamUuid/repoUuid for clarity about what kind of UUID they are.
+        const body = {
+            name: input.name,
+            platform: input.platform,
+            team: input.teamUuid,
+            repo: input.repoUuid,
+        };
+        const p = await this.tx.post('api/v1/projects/', body);
+        return this.mapProjectDetail(p);
     }
     /**
-     * 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 +207,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 +296,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 +351,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/createProject.js

@@ -0,0 +1,25 @@
+import { CreateProjectInputSchema } from '../types/index.js';
+import { createProjectHandler } from '../handlers/createProjectHandler.js';
+const DESCRIPTION = `Create a new DebuggAI project. Required: name, platform (e.g. "web"), teamUuid (from list_teams), repoUuid (from list_repos). Returns {created: true, project: {uuid, name, slug, platform, repoName, ...}}. The repo must be GitHub-linked to the account. Use list_teams + list_repos first to discover valid UUIDs.`;
+export function buildCreateProjectTool() {
+    return {
+        name: 'create_project',
+        title: 'Create Project',
+        description: DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Project name. Required.', minLength: 1 },
+                platform: { type: 'string', description: 'Platform (e.g. "web"). Required.', minLength: 1 },
+                teamUuid: { type: 'string', description: 'Team UUID (from list_teams). Required.' },
+                repoUuid: { type: 'string', description: 'GitHub repo UUID (from list_repos). Required — repo must be GitHub-linked.' },
+            },
+            required: ['name', 'platform', 'teamUuid', 'repoUuid'],
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedCreateProjectTool() {
+    const tool = buildCreateProjectTool();
+    return { ...tool, inputSchema: CreateProjectInputSchema, handler: createProjectHandler };
+}

package/dist/tools/index.js

@@ -16,6 +16,9 @@ import { buildDeleteProjectTool, buildValidatedDeleteProjectTool } from './delet
 import { buildListExecutionsTool, buildValidatedListExecutionsTool } from './listExecutions.js';
 import { buildGetExecutionTool, buildValidatedGetExecutionTool } from './getExecution.js';
 import { buildCancelExecutionTool, buildValidatedCancelExecutionTool } from './cancelExecution.js';
+import { buildListTeamsTool, buildValidatedListTeamsTool } from './listTeams.js';
+import { buildListReposTool, buildValidatedListReposTool } from './listRepos.js';
+import { buildCreateProjectTool, buildValidatedCreateProjectTool } from './createProject.js';
 let _tools = null;
 let _validatedTools = null;
 const toolRegistry = new Map();
@@ -42,6 +45,9 @@ export function initTools(ctx) {
         buildListExecutionsTool(),
         buildGetExecutionTool(),
         buildCancelExecutionTool(),
+        buildListTeamsTool(),
+        buildListReposTool(),
+        buildCreateProjectTool(),
     ];
     const validated = [
         buildValidatedTestPageChangesTool(ctx),
@@ -62,6 +68,9 @@ export function initTools(ctx) {
         buildValidatedListExecutionsTool(),
         buildValidatedGetExecutionTool(),
         buildValidatedCancelExecutionTool(),
+        buildValidatedListTeamsTool(),
+        buildValidatedListReposTool(),
+        buildValidatedCreateProjectTool(),
     ];
     _tools = tools;
     _validatedTools = validated;

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/tools/listRepos.js

@@ -0,0 +1,23 @@
+import { ListReposInputSchema } from '../types/index.js';
+import { listReposHandler } from '../handlers/listReposHandler.js';
+const DESCRIPTION = `List GitHub repos linked to the current account. Paginated — every response includes pageInfo {page, pageSize, totalCount, totalPages, hasMore}; default pageSize 20, max 200. Optional q filters by repo name via backend search. Use this to discover repoUuid values required by create_project. Prefer repos with isGithubAuthorized:true since the backend needs a valid GitHub installation.`;
+export function buildListReposTool() {
+    return {
+        name: 'list_repos',
+        title: 'List Linked Repos',
+        description: DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                q: { type: 'string', description: 'Optional: filter by repo name.' },
+                page: { type: 'number', description: 'Optional: 1-indexed page number.', minimum: 1 },
+                pageSize: { type: 'number', description: 'Optional: items per page. Default 20, max 200.', minimum: 1, maximum: 200 },
+            },
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedListReposTool() {
+    const tool = buildListReposTool();
+    return { ...tool, inputSchema: ListReposInputSchema, handler: listReposHandler };
+}

package/dist/tools/listTeams.js

@@ -0,0 +1,23 @@
+import { ListTeamsInputSchema } from '../types/index.js';
+import { listTeamsHandler } from '../handlers/listTeamsHandler.js';
+const DESCRIPTION = `List teams accessible to the current API key. Paginated — every response includes pageInfo {page, pageSize, totalCount, totalPages, hasMore}; default pageSize 20, max 200. Optional q filters by team name via backend search. Use this to discover teamUuid values required by create_project.`;
+export function buildListTeamsTool() {
+    return {
+        name: 'list_teams',
+        title: 'List Teams',
+        description: DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                q: { type: 'string', description: 'Optional: filter by team name.' },
+                page: { type: 'number', description: 'Optional: 1-indexed page number.', minimum: 1 },
+                pageSize: { type: 'number', description: 'Optional: items per page. Default 20, max 200.', minimum: 1, maximum: 200 },
+            },
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedListTeamsTool() {
+    const tool = buildListTeamsTool();
+    return { ...tool, inputSchema: ListTeamsInputSchema, handler: listTeamsHandler };
+}

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,24 @@ 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();
+export const ListTeamsInputSchema = z.object({
+    q: z.string().min(1).optional(),
+    page: z.number().int().min(1).optional(),
+    pageSize: z.number().int().min(1).optional(),
+}).strict();
+export const ListReposInputSchema = z.object({
+    q: z.string().min(1).optional(),
+    page: z.number().int().min(1).optional(),
+    pageSize: z.number().int().min(1).optional(),
+}).strict();
+export const CreateProjectInputSchema = z.object({
+    name: z.string().min(1),
+    platform: z.string().min(1),
+    teamUuid: z.string().uuid(),
+    repoUuid: z.string().uuid(),
 }).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.57",
+  "version": "1.0.59",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "bin": {