Goal Story MCP Server

Instructions

Implementation Reference

• src/index.ts:518-530 (handler)

  The asynchronous handler function that executes the tool logic. It constructs the API URL using the provided step ID, performs a GET request to retrieve the step data using the doRequest helper, and returns the data formatted as a text content block in the MCP response format.
  async (args) => { const url = `${GOALSTORY_API_BASE_URL}/steps/${args.id}`; const result = await doRequest(url, "GET"); return { content: [ { type: "text", text: `Step data:\n${JSON.stringify(result, null, 2)}`, }, ], isError: false, }; },
• src/index.ts:514-531 (registration)

  The MCP server.tool() registration call that registers the 'goalstory_read_one_step' tool with its name, description, input schema shape, and inline handler function.
  server.tool( READ_ONE_STEP_TOOL.name, READ_ONE_STEP_TOOL.description, READ_ONE_STEP_TOOL.inputSchema.shape, async (args) => { const url = `${GOALSTORY_API_BASE_URL}/steps/${args.id}`; const result = await doRequest(url, "GET"); return { content: [ { type: "text", text: `Step data:\n${JSON.stringify(result, null, 2)}`, }, ], isError: false, }; }, );
• src/tools.ts:261-268 (schema)

  The tool specification object defining the name, description, and Zod input schema (requiring a string 'id' parameter). This object is imported and used in the server.tool registration.
  export const READ_ONE_STEP_TOOL = { name: "goalstory_read_one_step", description: "Get detailed information about a specific step to support focused discussion and story creation.", inputSchema: z.object({ id: z.string().describe("Unique identifier of the step to retrieve."), }), };
• src/types.ts:76-78 (schema)

  TypeScript interface defining the expected input shape for the tool (a single 'id' string property). Matches the Zod schema.
  export interface GoalstoryReadOneStepInput { id: string; }
• src/index.ts:62-122 (helper)

  The doRequest utility function used by the handler (and all other tools) to make authenticated HTTP requests to the backend GoalStory API, with logging, timeout, and comprehensive error handling.
  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)}`, ); } } }