createWorkspace

Instructions

Implementation Reference

• src/tools/createWorkspace.ts:38-68 (handler)

  The main handler function for the 'createWorkspace' tool. It POSTs to the /workspaces endpoint with workspace data (name, type, description, about, teamId) via the PostmanAPIClient.

  export async function handler(
    args: z.infer<typeof parameters>,
    extra: { client: PostmanAPIClient; headers?: IsomorphicHeaders; serverContext?: ServerContext }
  ): Promise<CallToolResult> {
    try {
      const endpoint = `/workspaces`;
      const query = new URLSearchParams();
      const url = query.toString() ? `${endpoint}?${query.toString()}` : endpoint;
      const bodyPayload: any = {};
      if (args.workspace !== undefined) bodyPayload.workspace = args.workspace;
      const options: any = {
        body: JSON.stringify(bodyPayload),
        contentType: ContentType.Json,
        headers: extra.headers,
      };
      const result = await extra.client.post(url, options);
      return {
        content: [
          {
            type: 'text',
            text: `${typeof result === 'string' ? result : JSON.stringify(result, null, 2)}`,
          },
        ],
      };
    } catch (e: unknown) {
      if (e instanceof McpError) {
        throw e;
      }
      throw asMcpError(e);
    }
  }

• src/tools/createWorkspace.ts:9-29 (schema)

  Zod schema defining the input parameters for createWorkspace: workspace object with name (required string), type (enum: personal/private/public/team/partner), description (optional), about (optional), and teamId (optional string).

  export const parameters = z.object({
    workspace: z
      .object({
        name: z.string().describe("The workspace's name."),
        type: z
          .enum(['personal', 'private', 'public', 'team', 'partner'])
          .describe(
            'The type of workspace:\n- `personal`\n- `private` — Private workspaces are available on Postman [**Team** and **Enterprise** plans](https://www.postman.com/pricing).\n- `public`\n- `team`\n- `partner` — [Partner Workspaces](https://learning.postman.com/docs/collaborating-in-postman/using-workspaces/partner-workspaces/) are available on Postman [**Team** and **Enterprise** plans](https://www.postman.com/pricing)).\n'
          ),
        description: z.string().describe("The workspace's description.").optional(),
        about: z.string().describe('A brief summary about the workspace.').optional(),
        teamId: z
          .string()
          .describe(
            'The team ID to assign to the workspace. This property is required if Postman [Organizations](https://learning.postman.com/docs/administration/managing-your-team/overview) is enabled.'
          )
          .optional(),
      })
      .describe('Information about the workspace.')
      .optional(),
  });

• src/tools/createWorkspace.ts:30-36 (schema)

  Annotations/metadata for the createWorkspace tool including title, readOnlyHint, destructiveHint, and idempotentHint.

  export const annotations = {
    title:
      'Creates a new [workspace](https://learning.postman.com/docs/collaborating-in-postman/using-workspaces/creating-workspaces/).',
    readOnlyHint: false,
    destructiveHint: false,
    idempotentHint: false,
  };

• src/enabledResources.ts:108-109 (registration)

  Registration of 'createWorkspace' in the 'full' enabled resources list (line 109), and also in the 'minimal' set (line 169). This determines which toolset includes this tool.

  // Workspaces
  'createWorkspace',

• src/index.ts:263-343 (registration)

  Dynamic registration of all tools (including createWorkspace) via server.registerTool(). The tool module is loaded dynamically and its method, description, parameters, and handler are used to register with the MCP server.

  for (const tool of tools) {
    server.registerTool(
      tool.method,
      {
        description: tool.description,
        inputSchema: tool.parameters.shape,
        annotations: tool.annotations || {},
      },
      async (args, extra) => {
        const toolName = tool.method;
        // Keep start event on stderr only to reduce client noise
        log('info', `Tool invocation started: ${toolName}`, { toolName });
  
        try {
          const start = Date.now();
  
          const result = await tool.handler(args, {
            client,
            headers: {
              ...extra?.requestInfo?.headers,
              'user-agent': clientInfo?.name,
            },
            serverContext,
          });
  
          const durationMs = Date.now() - start;
          // Completion: stderr only to avoid spamming client logs
          log('info', `Tool invocation completed: ${toolName} (${durationMs}ms)`, {
            toolName,
            durationMs,
          });
  
          // Apply template rendering
          if (result.content?.[0]?.type === 'text') {
            const rendered = renderTemplate(toolName, result.content[0].text);
            if (rendered) {
              return { content: [{ type: 'text' as const, text: rendered }] };
            }
          }
  
          return result;
        } catch (error: any) {
          const errMsg = String(error?.message || error);
          // Failures: notify both server stderr and client
          logBoth(server, 'error', `Tool invocation failed: ${toolName}: ${errMsg}`, { toolName });
          if (error instanceof McpError) {
            const httpStatus = (error.data as Record<string, unknown>)?.httpStatus;
            if (typeof httpStatus === 'number') {
              const rawBody = String((error.data as Record<string, unknown>)?.cause ?? '');
              let parsedBody: Record<string, unknown> | null = null;
              try {
                parsedBody = JSON.parse(rawBody) as Record<string, unknown>;
              } catch {
                /* not JSON */
              }
  
              // Unwrap common { error: { ... } } API response pattern
              const errorObj =
                parsedBody?.error && typeof parsedBody.error === 'object'
                  ? (parsedBody.error as Record<string, unknown>)
                  : parsedBody;
  
              const rendered = renderErrorTemplate(toolName, httpStatus, {
                toolName,
                statusCode: httpStatus,
                args,
                errorMessage: error.message,
                errorBody: rawBody,
                error: errorObj,
              });
              if (rendered) {
                throw new McpError(error.code, rendered, error.data);
              }
            }
            throw error;
          }
          throw new McpError(ErrorCode.InternalError, `API error: ${error.message}`);
        }
      }
    );
  }