Carbon Voice

Instructions

Implementation Reference

• src/server.ts:899-914 (handler)

  The handler function for the 'run_ai_action_for_shared_link' MCP tool. It calls the simplified API to create an AI response for shared links, handles authentication, formats the MCP tool response, and logs errors.

  async (
    args: CreateShareLinkAIResponse,
    { authInfo },
  ): Promise<McpToolResponse> => {
    try {
      return formatToMCPToolResponse(
        await simplifiedApi.createShareLinkAIResponse(
          args,
          setCarbonVoiceAuthHeader(authInfo?.token),
        ),
      );
    } catch (error) {
      logger.error('Error running ai action for shared link:', { error });
      return formatToMCPToolResponse(error);
    }
  },

• src/server.ts:887-915 (registration)

  Registration of the 'run_ai_action_for_shared_link' tool using server.registerTool, including description, input schema, annotations, and inline handler.

  server.registerTool(
    'run_ai_action_for_shared_link',
    {
      description:
        'Run an AI Action (Prompt) for a shared link. You can run an AI Action for a shared link by its ID or a list of shared link IDs. ' +
        'You can also provide the language of the response.',
      inputSchema: createShareLinkAIResponseBody.shape,
      annotations: {
        readOnlyHint: false,
        destructiveHint: false,
      },
    },
    async (
      args: CreateShareLinkAIResponse,
      { authInfo },
    ): Promise<McpToolResponse> => {
      try {
        return formatToMCPToolResponse(
          await simplifiedApi.createShareLinkAIResponse(
            args,
            setCarbonVoiceAuthHeader(authInfo?.token),
          ),
        );
      } catch (error) {
        logger.error('Error running ai action for shared link:', { error });
        return formatToMCPToolResponse(error);
      }
    },
  );

• src/generated/carbon-voice-api/CarbonVoiceSimplifiedAPI.zod.ts:306-310 (schema)

  Zod schema definition for the input to the tool: createShareLinkAIResponseBody, used as inputSchema in registration. Defines prompt_id, share_link_ids array, and optional language.

  export const createShareLinkAIResponseBody = zod.object({
    "prompt_id": zod.string(),
    "share_link_ids": zod.array(zod.string()),
    "language": zod.string().optional()
  })

• src/generated/models/CreateShareLinkAIResponse.ts:1-80 (schema)

  TypeScript interface for CreateShareLinkAIResponse, used as type for args in the handler.

  /**
   * Generated by orval v7.9.0 🍺
   * Do not edit manually.
   * Carbon Voice Simplified API
   * # Introduction
  
  The simplified version of the Carbon Voice API is designed to enhance usability for third-party clients looking to 
  seamlessly integrate with our application. By streamlining authentication methods, providing clear error handling guidelines, 
  and implementing straightforward rate limiting policies, we ensure that developers can quickly and efficiently connect to our services. 
  This user-friendly approach minimizes complexity, making it easier for external applications to leverage the powerful communication 
  features of Carbon Voice without extensive technical overhead.
  
  This API is designed for people who feel comfortable integrating with RESTful APIs.
  
  ## Full API Version
  We also have a full version of the API. You can find it [here](/docs).
  
  ## Terminology
   
  * **Workspace**: An area that groups together people and Conversations.
  * **Conversation**: A channel of communication. A grouping of people and messages related to a given topic.
  * **Collaborators**: A group of people who are part of a Conversation.
  * **Discussion**: Any post into a conversation
  * **CarbonLink**: A link (on a website, QR code, or phone call) to start a conversation.
  
  ## BaseURL
  
  This API is served over HTTPS.
  
  All URLs referenced in the documentation have the following base: https://api.carbonvoice.app/api/simplified.
  
  ## Authentication
  
  There are three ways to authenticate with this API:
  
  * with an OAuth2 Access Token in the Authorization request header field 
  (which uses the Bearer authentication scheme to transmit the Access Token)
  * with your Client ID and Client Secret credentials
  * with a PXToken
  
  Each endpoint supports only one option.
  
  <SecurityDefinitions />
  
  ## Errors
  
  When an error occurs, you will receive an error object. Most of these error objects 
  contain an error code and an error description so that your applications can more 
  efficiently identify the problem.
  
  If you get an 4xx HTTP response code, then you can assume that there is a bad request
  from your end. In this case, check the [Error Responses section](#section/Introduction/Error-Responses) for more context.
  
  5xx errors suggest a problem on our end, so in this case, check [Carbon Voice's Status](https://status.carbonvoice.app)
   to see how our systems are doing.
  
  In any other case you can use our support options.
  
  ## Error Responses
  
  `{ "success": false, requestId: "uuid", errmsg: "error message"`
  
  ## Rate-Limiting 
  
  This API is subject to rate limiting. The limits differ per endpoint.
  
  If you exceed the provided rate limit for a given endpoint, you will receive the 429
  Too Many Requests response with the following message: Too many requests. Check the
  X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
  
  For details on rate limiting, refer to Rate Limit Policy.
  
  ## Support
  
  If you have problems or need help with your case, you can always reach out to our Support.
  
   * OpenAPI spec version: 1.0.0
   */
  
  export interface CreateShareLinkAIResponse {

• src/utils/format-to-mcp-tool-response.ts:3-25 (helper)

  Utility function to format API responses or errors into MCP ToolResponse format, used in the handler.

  import { McpToolResponse } from '../interfaces';
  import { getTraceId } from '../transports/http/utils/request-context';
  
  const isErrorWithDetails = (
    error: unknown,
  ): error is { code?: string; message?: string; details?: unknown } => {
    return typeof error === 'object' && error !== null;
  };
  
  export const formatToMCPToolResponse = (data: unknown): McpToolResponse => {
    try {
      return {
        content: [{ type: 'text', text: JSON.stringify(data) }],
      };
    } catch (error: unknown) {
      logger.error('Error formatting response:', { data, error });
  
      let code = 'UNKNOWN_ERROR';
      let message = 'Error formatting response';
      let details;
  
      if (isErrorWithDetails(error)) {
        code = error?.code || code;