Create Project Environment

Instructions

Implementation Reference

• handlers/createEnvironmentHandler.ts:14-100 (handler)

  Main handler function for create_environment. Resolves the project (via projectUuid or git repo detection), calls client.createEnvironment() to create the environment, and optionally seeds credentials. Returns the created environment and any credentials. Handles errors with logging.

  export async function createEnvironmentHandler(
    input: CreateEnvironmentInput,
    _context: ToolContext,
  ): Promise<ToolResponse> {
    const start = Date.now();
    logger.toolStart('create_environment', {
      name: input.name,
      hasUrl: !!input.url,
      projectUuid: input.projectUuid,
    });
  
    try {
      const client = new DebuggAIServerClient(config.api.key);
      await client.init();
  
      let projectUuid = input.projectUuid;
      if (!projectUuid) {
        const repoName = detectRepoName();
        if (!repoName) {
          const payload = {
            error: 'NoProjectResolved',
            message: 'No git repo detected and no projectUuid provided. Pass projectUuid (get it from search_projects) or invoke from a directory with a git origin.',
          };
          return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
        }
        const project = await client.findProjectByRepoName(repoName);
        if (!project) {
          const payload = {
            error: 'NoProjectResolved',
            message: `No DebuggAI project found for repo "${repoName}". Pass projectUuid explicitly.`,
          };
          return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
        }
        projectUuid = project.uuid;
      }
  
      const env = await client.createEnvironment(projectUuid, {
        name: input.name,
        url: input.url,
        description: input.description,
      });
  
      const payload: Record<string, any> = {
        created: true,
        projectUuid,
        environment: env,
      };
  
      // Optional credentials seed: best-effort per-cred. Success goes to
      // credentials[]; failure goes to credentialWarnings[] (never blocks env creation).
      if (input.credentials && input.credentials.length > 0) {
        const created: Array<{ uuid: string; label: string; username: string; role: string | null; environmentUuid: string }> = [];
        const warnings: Array<{ label: string; error: string }> = [];
        for (const seed of input.credentials) {
          try {
            const cred = await client.createCredential(projectUuid, env.uuid, {
              label: seed.label,
              username: seed.username,
              password: seed.password,
              role: seed.role,
            });
            // Defensive: drop any stray password from the response shape
            created.push({
              uuid: cred.uuid,
              label: cred.label,
              username: cred.username,
              role: cred.role ?? null,
              environmentUuid: cred.environmentUuid,
            });
          } catch (err: any) {
            warnings.push({
              label: seed.label,
              error: err?.message ?? String(err),
            });
          }
        }
        payload.credentials = created;
        if (warnings.length > 0) payload.credentialWarnings = warnings;
      }
  
      logger.toolComplete('create_environment', Date.now() - start);
      return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
    } catch (error) {
      logger.toolError('create_environment', error as Error, Date.now() - start);
      throw handleExternalServiceError(error, 'DebuggAI', 'create_environment');
    }
  }

• types/index.ts:95-102 (schema)

  Zod schema for CreateEnvironmentInput: name (required), url (required), description (optional), projectUuid (optional), credentials (optional array of credential seeds). Also defines the CreateEnvironmentInput type.

  export const CreateEnvironmentInputSchema = z.object({
    name: z.string().min(1, 'name is required'),
    url: z.string().url('url is required for standard environments'),
    description: z.string().optional(),
    projectUuid: z.string().uuid().optional(),
    credentials: z.array(CredentialSeedSchema).optional(),
  }).strict();
  export type CreateEnvironmentInput = z.infer<typeof CreateEnvironmentInputSchema>;

• tools/createEnvironment.ts:1-50 (registration)

  Tool definition and registration. buildCreateEnvironmentTool() defines the tool schema (name, title, description, inputSchema). buildValidatedCreateEnvironmentTool() wraps it with Zod schema validation and the handler function.

  import { Tool } from '@modelcontextprotocol/sdk/types.js';
  import { CreateEnvironmentInputSchema, ValidatedTool } from '../types/index.js';
  import { createEnvironmentHandler } from '../handlers/createEnvironmentHandler.js';
  
  const DESCRIPTION = `Create a new environment under a DebuggAI project. Both name and url are required (backend rejects standard environments without a URL). Optional description. Defaults to the project resolved from the current git repo; pass projectUuid to target a different project (get UUIDs via search_projects).
  
  OPTIONAL credentials seed: pass \`credentials: [{label, username, password, role?}]\` to create login credentials alongside the environment in a single call. Each cred is created best-effort; failures go to \`credentialWarnings\` without blocking env creation. Passwords are write-only and NEVER returned.
  
  Returns the created environment's uuid (and the seeded credentials, if any). Reference the env uuid when running check_app_in_browser.`;
  
  export function buildCreateEnvironmentTool(): Tool {
    return {
      name: 'create_environment',
      title: 'Create Project Environment',
      description: DESCRIPTION,
      inputSchema: {
        type: 'object',
        properties: {
          name: {
            type: 'string',
            description: 'Short label for the environment (e.g. "staging", "production"). Required.',
            minLength: 1,
          },
          url: {
            type: 'string',
            description: 'Base URL for the environment (e.g. https://staging.example.com). Required.',
          },
          description: {
            type: 'string',
            description: 'Optional: free-text description.',
          },
          projectUuid: {
            type: 'string',
            description: 'Optional: UUID of the target project. Defaults to the project resolved from the current git repo.',
          },
        },
        required: ['name', 'url'],
        additionalProperties: false,
      },
    };
  }
  
  export function buildValidatedCreateEnvironmentTool(): ValidatedTool {
    const tool = buildCreateEnvironmentTool();
    return {
      ...tool,
      inputSchema: CreateEnvironmentInputSchema,
      handler: createEnvironmentHandler,
    };
  }

• services/index.ts:284-302 (helper)

  Service-layer helper that makes the API call to create an environment via POST to api/v1/projects/{projectUuid}/environments/. Also includes createCredential helper (line 426-449) used for optional credential seeding.

  public async createEnvironment(
    projectUuid: string,
    input: { name: string; url?: string; description?: string },
  ): Promise<{ uuid: string; name: string; url: string; isActive: boolean }> {
    if (!this.tx) throw new Error('Client not initialized — call init() first');
    const body: Record<string, any> = { name: input.name };
    if (input.url) body.url = input.url;
    if (input.description) body.description = input.description;
    const response = await this.tx.post<any>(
      `api/v1/projects/${projectUuid}/environments/`,
      body,
    );
    return {
      uuid: response.uuid,
      name: response.name,
      url: response.url || response.activeUrl || '',
      isActive: response.isActive,
    };
  }

• tools/index.ts:55-69 (registration)

  Tools registry where buildValidatedCreateEnvironmentTool() is registered into the toolRegistry map and included in the validated tools list at init time.

    _validatedTools = validated;
  
    toolRegistry.clear();
    for (const v of validated) toolRegistry.set(v.name, v);
  }
  
  export function getTools(): Tool[] {
    if (!_tools) initTools(null);
    return _tools!;
  }
  
  export function getTool(name: string): ValidatedTool | undefined {
    if (!_validatedTools) initTools(null);
    return toolRegistry.get(name);
  }