Activity Reporting MCP Server

Instructions

Implementation Reference

• src/server.ts:216-288 (registration)

  Registration of the 'submit_workshop' MCP tool, including name, description, and detailed JSON input schema.

  {
    name: "submit_workshop",
    description: "Submit a workshop activity draft",
    inputSchema: {
      type: "object",
      properties: {
        title: {
          type: "string",
          description: "What was the name of your workshop session?",
          minLength: 3,
          maxLength: 200,
        },
        description: {
          type: "string",
          description: "What was it about?",
          maxLength: 2000,
        },
        activityDate: {
          type: "string",
          pattern: "^\\d{4}-\\d{2}-\\d{2}$",
          description: "Date of your workshop (YYYY-MM-DD format)",
        },
        tags: {
          type: "array",
          items: { type: "string" },
          description: "Tags (optional)",
          minItems: 0,
        },
        metrics: {
          type: "object",
          properties: {
            attendees: {
              type: "integer",
              minimum: 1,
              description: "How many people have been trained?",
            },
          },
          required: ["attendees"],
        },
        eventFormat: {
          type: "string",
          enum: Object.values(EventFormat),
          description: "Select event format",
        },
        country: {
          type: "string",
          enum: Object.values(Country),
          description: "Country (required if eventFormat is In-Person or Hybrid)",
        },
        inPersonAttendees: {
          type: "integer",
          minimum: 0,
          description: "In-person attendees (required if eventFormat is Hybrid or In-Person)",
        },
        activityUrl: {
          type: "string",
          maxLength: 500,
          pattern: "^https?://.*",
          description: "Workshop/event link",
        },
        additionalInfo: {
          type: "string",
          maxLength: 2000,
          description: "Additional information (optional)",
        },
        private: {
          type: "boolean",
          description: "Do you want to make this activity private? (optional)",
        },
      },
      required: ["title", "description", "activityDate", "metrics", "eventFormat", "activityUrl"],
    },
  },

• src/server.ts:609-682 (handler)

  Core handler implementation: submits workshop activity draft via POST to /activity-drafts/workshop endpoint, handles errors and success responses.

  private async submitActivityDraft(
    endpoint: string,
    data:
      | ContentCreationDraft
      | PublicSpeakingDraft
      | WorkshopDraft
      | MentoringDraft
      | ProductFeedbackDraft
      | GooglerInteractionDraft
      | StoryDraft,
  ): Promise<{
    content: Array<{
      type: string;
      text: string;
    }>;
  }> {
    const url = `${this.baseUrl}/activity-drafts/${endpoint}`;
  
    try {
      const response = await fetch(url, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${this.accessToken}`,
        },
        body: JSON.stringify(data),
      });
  
      if (!response.ok) {
        const errorText = await response.text();
        let errorMessage = `GDE API error (${response.status})`;
  
        if (response.status === 401) {
          errorMessage = "❌ GDE authentication failed. Your ADVOCU_ACCESS_TOKEN may be expired or invalid.\n\nPlease check your Advocu access token configuration.";
        } else if (response.status === 400) {
          errorMessage = `❌ GDE API rejected the request:\n\n${errorText}\n\nPlease check:\n- All required fields are present\n- Field values match expected formats\n- Tags are valid\n- Date format is correct (YYYY-MM-DD)`;
        } else if (response.status === 429) {
          errorMessage = "⏱️ GDE API rate limit exceeded (30 requests/minute). Please wait and try again.";
        } else {
          errorMessage = `❌ GDE API error (${response.status}):\n\n${errorText}`;
        }
  
        // Return error as content instead of throwing
        return {
          content: [
            {
              type: "text",
              text: errorMessage,
            },
          ],
        };
      }
  
      const result = (await response.json()) as Record<string, unknown>;
  
      return {
        content: [
          {
            type: "text",
            text: `✅ GDE Activity draft submitted successfully!\n\nEndpoint: ${endpoint}\nStatus: ${response.status}\nResponse: ${JSON.stringify(result, null, 2)}`,
          },
        ],
      };
    } catch (error) {
      if (error instanceof McpError) {
        throw error;
      }
      const errorMsg = this.getErrorMessage(error);
      throw new McpError(
        ErrorCode.InternalError,
        `❌ Failed to submit GDE activity:\n\n${errorMsg}\n\nEndpoint: ${endpoint}`
      );
    }
  }

• src/server.ts:580-581 (handler)

  Dispatch case in tool request handler that routes 'submit_workshop' calls to the shared submitActivityDraft function with workshop-specific endpoint and type.

  case "submit_workshop":
    return await this.submitActivityDraft("workshop", args as unknown as WorkshopDraft);

• src/interfaces/WorkshopDraft.ts:14-28 (schema)

  TypeScript interface defining the structure of WorkshopDraft input, used for type safety in the handler.

  export interface WorkshopDraft extends ActivityDraftBase {
    /** Metrics related to training reach */
    metrics: {
      /** Number of people who have been trained */
      attendees: number;
    };
    /** Format of the event (In-Person, Virtual, or Hybrid) */
    eventFormat: EventFormat;
    /** Country where the event took place (required if eventFormat is In-Person or Hybrid) */
    country?: Country;
    /** Number of in-person attendees (required if eventFormat is Hybrid or In-Person) */
    inPersonAttendees?: number;
    /** URL link to the workshop or event */
    activityUrl: string;
  }