Activity Reporting MCP Server

Instructions

Implementation Reference

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

  Core handler function that executes the tool logic by sending a POST request to the GDE API endpoint '/activity-drafts/stories' with the provided StoryDraft data.

  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:491-566 (registration)

  Registration of the 'submit_story' tool in the listTools response, including detailed input schema for validation.

  {
    name: "submit_story",
    description: "Submit a story activity draft",
    inputSchema: {
      type: "object",
      properties: {
        title: {
          type: "string",
          description: "Title of the story",
          minLength: 3,
          maxLength: 200,
        },
        description: {
          type: "string",
          description: "Description",
          maxLength: 2000,
        },
        activityDate: {
          type: "string",
          pattern: "^\\d{4}-\\d{2}-\\d{2}$",
          description: "Activity Date (YYYY-MM-DD format)",
        },
        whyIsSignificant: {
          type: "string",
          maxLength: 2000,
          description: "Why is it significant",
        },
        significanceType: {
          type: "string",
          enum: Object.values(SignificanceType),
          description: "Significance type",
        },
        activityUrl: {
          type: "string",
          maxLength: 500,
          pattern: "^https?://.*",
          description: "Link",
        },
        tags: {
          type: "array",
          items: { type: "string" },
          description: "Tags (optional)",
          minItems: 0,
        },
        metrics: {
          type: "object",
          properties: {
            impact: {
              type: "integer",
              minimum: 1,
              description: "Impact (views, reads, attendees, etc.)",
            },
          },
          required: ["impact"],
        },
        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",
        "whyIsSignificant",
        "significanceType",
        "activityUrl",
        "metrics",
      ],
    },
  },

• src/server.ts:591-592 (handler)

  Switch case that handles 'submit_story' tool calls by invoking the shared submitActivityDraft with the 'stories' endpoint.

  case "submit_story":
    return await this.submitActivityDraft("stories", args as unknown as StoryDraft);

• src/interfaces/StoryDraft.ts:13-25 (schema)

  TypeScript interface defining the structure of StoryDraft, used for type-checking the tool input arguments.

  export interface StoryDraft extends ActivityDraftBase {
    /** Explanation of why this story is significant */
    whyIsSignificant: string;
    /** Type of significance or impact category */
    significanceType: SignificanceType;
    /** URL link to the story or related content */
    activityUrl: string;
    /** Metrics related to impact */
    metrics: {
      /** Impact measurement (views, reads, attendees, etc.) */
      impact: number;
    };
  }