Goal Story MCP Server

Instructions

Implementation Reference

• src/index.ts:752-773 (handler)

  MCP tool registration and handler implementation. The async function constructs a POST request to `/schedules/stories` endpoint with `goal_id` and `timeSettings`, executes it via `doRequest` helper, and returns the formatted result.

  server.tool(
    CREATE_SCHEDULED_STORY_TOOL.name,
    CREATE_SCHEDULED_STORY_TOOL.description,
    CREATE_SCHEDULED_STORY_TOOL.inputSchema.shape,
    async (args) => {
      const url = `${GOALSTORY_API_BASE_URL}/schedules/stories`;
      const body = {
        goal_id: args.goal_id,
        timeSettings: args.timeSettings,
      };
      const result = await doRequest(url, "POST", body);
      return {
        content: [
          {
            type: "text",
            text: `Scheduled story created:\n${JSON.stringify(result, null, 2)}`,
          },
        ],
        isError: false,
      };
    },
  );

• src/tools.ts:491-503 (schema)

  Tool specification object defining the name, description, and Zod input schema. References TimeSettingsSchema for the timeSettings parameter.

  export const CREATE_SCHEDULED_STORY_TOOL = {
    name: "goalstory_create_scheduled_story",
    description:
      "Schedule automatic story generation for a specific goal. Requires the goal ID and the desired time settings (hour and minute).",
    inputSchema: z.object({
      goal_id: z
        .string()
        .describe(
          "Unique identifier of the goal for which to schedule story generation.",
        ),
      timeSettings: TimeSettingsSchema,
    }),
  };

• src/tools.ts:412-466 (schema)

  Zod schema defining the structure for timeSettings (hour as 1-12 string, AM/PM period, and UTC offset string).

  export const TimeSettingsSchema = z
    .object({
      hour: z.enum([
        "1",
        "2",
        "3",
        "4",
        "5",
        "6",
        "7",
        "8",
        "9",
        "10",
        "11",
        "12",
      ]),
      period: z.enum(["AM", "PM"]),
      utcOffset: z
        .enum([
          "-12:00",
          "-11:00",
          "-10:00",
          "-09:00",
          "-08:00",
          "-07:00",
          "-06:00",
          "-05:00",
          "-04:00",
          "-03:00",
          "-02:00",
          "-01:00",
          "±00:00",
          "+01:00",
          "+02:00",
          "+03:00",
          "+04:00",
          "+05:00",
          "+06:00",
          "+07:00",
          "+08:00",
          "+09:00",
          "+10:00",
          "+11:00",
          "+12:00",
          "+13:00",
          "+14:00",
        ])
        .describe(
          "Choose a current UTC offset based on the user's location (accounting for adjustments like daylight savings time for instance). For example, the UTC offset for Los Angeles, California is -08:00 during standard time (PST, Pacific Standard Time) and -07:00 during daylight saving time (PDT, Pacific Daylight Time).",
        ),
    })
    .describe(
      "Specifies the time of day (hour and minute) for the scheduled story generation.",
    );

• src/index.ts:62-122 (helper)

  Generic HTTP request helper function used by all tool handlers to make authenticated API calls to the GoalStory backend.

  async function doRequest<T = any>(
    url: string,
    method: string,
    body?: unknown,
  ): Promise<T> {
    console.error("Making request to:", url);
    console.error("Method:", method);
    console.error("Body:", body ? JSON.stringify(body) : "none");
  
    try {
      const response = await axios({
        url,
        method,
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${GOALSTORY_API_TOKEN}`,
        },
        data: body,
        timeout: 10000, // 10 second timeout
        validateStatus: function (status) {
          return status >= 200 && status < 500; // Accept all status codes less than 500
        },
      });
      console.error("Response received:", response.status);
      return response.data as T;
    } catch (err) {
      console.error("Request failed with error:", err);
  
      if (axios.isAxiosError(err)) {
        if (err.code === "ECONNABORTED") {
          throw new Error(
            `Request timed out after 10 seconds. URL: ${url}, Method: ${method}`,
          );
        }
        if (err.response) {
          // The request was made and the server responded with a status code
          // that falls out of the range of 2xx
          throw new Error(
            `HTTP Error ${
              err.response.status
            }. URL: ${url}, Method: ${method}, Body: ${JSON.stringify(
              body,
            )}. Error text: ${JSON.stringify(err.response.data)}`,
          );
        } else if (err.request) {
          // The request was made but no response was received
          throw new Error(
            `No response received from server. URL: ${url}, Method: ${method}`,
          );
        } else {
          // Something happened in setting up the request that triggered an Error
          throw new Error(`Request setup failed: ${err.message}`);
        }
      } else {
        // Something else happened
        throw new Error(
          `Unexpected error: ${err instanceof Error ? err.message : String(err)}`,
        );
      }
    }
  }