Goal Story MCP Server

Instructions

Implementation Reference

• src/index.ts:284-323 (handler)

  The MCP tool handler function that proxies a PATCH request to the GoalStory API endpoint /goals/:id, constructs the request body from input args, executes the request using doRequest helper, and returns formatted response.
  server.tool( UPDATE_GOAL_TOOL.name, UPDATE_GOAL_TOOL.description, UPDATE_GOAL_TOOL.inputSchema.shape, async (args) => { const url = `${GOALSTORY_API_BASE_URL}/goals/${args.id}`; const body = { id: args.id, ...(args.name ? { name: args.name } : {}), ...(typeof args.status === "number" ? { status: args.status } : {}), ...(args.description ? { description: args.description, } : {}), ...(args.outcome ? { outcome: args.outcome } : {}), ...(args.evidence ? { evidence: args.evidence } : {}), ...(args.story_mode ? { story_mode: args.story_mode, } : {}), ...(args.belief_mode ? { belief_mode: args.belief_mode, } : {}), }; const result = await doRequest(url, "PATCH", body); return { content: [ { type: "text", text: `Goal updated:\n${JSON.stringify(result, null, 2)}`, }, ], isError: false, }; }, );
• src/tools.ts:99-139 (schema)

  Tool definition object containing name, description, and Zod inputSchema for validation used by MCP server.tool registration.
  export const UPDATE_GOAL_TOOL = { name: "goalstory_update_goal", description: "Update goal details including name, status, description, outcomes, evidence of completion, and story/belief modes that influence how stories are generated.", inputSchema: z.object({ id: z.string().describe("Unique identifier of the goal to be updated."), name: z.string().optional().describe("Refined or clarified goal title."), status: z .number() .optional() .describe( "Goal progress status: 0 = active/in progress, 1 = successfully completed.", ), description: z .string() .optional() .describe("Enhanced goal context, motivation, or outcome details."), outcome: z .string() .optional() .describe( "Actual results and impact achieved through goal completion or progress.", ), evidence: z .string() .optional() .describe( "Concrete proof, measurements, or observations of goal progress/completion.", ), story_mode: z .string() .optional() .describe("Updated narrative style for future goal achievement stories."), belief_mode: z .string() .optional() .describe( "Refined understanding of how personal beliefs shape this goal.", ), }), };
• src/types.ts:25-36 (schema)

  TypeScript interface defining the input shape for goal updates, mirroring the Zod schema with minor field differences.
  export interface GoalstoryUpdateGoalInput { id: string; // Required name?: string; status?: number; // 0=Pending, 1=Complete description?: string; story?: string; notes?: string; outcome?: string; evidence?: string; story_mode?: string; belief_mode?: string; }
• src/index.ts:62-122 (helper)

  Generic HTTP request helper function used by all tool handlers to proxy requests to the GoalStory API with authentication, 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)}`, ); } } }
• src/index.ts:284-323 (registration)

  MCP server registration of the tool using server.tool(), referencing the tool definition from tools.ts and providing the inline handler implementation.
  server.tool( UPDATE_GOAL_TOOL.name, UPDATE_GOAL_TOOL.description, UPDATE_GOAL_TOOL.inputSchema.shape, async (args) => { const url = `${GOALSTORY_API_BASE_URL}/goals/${args.id}`; const body = { id: args.id, ...(args.name ? { name: args.name } : {}), ...(typeof args.status === "number" ? { status: args.status } : {}), ...(args.description ? { description: args.description, } : {}), ...(args.outcome ? { outcome: args.outcome } : {}), ...(args.evidence ? { evidence: args.evidence } : {}), ...(args.story_mode ? { story_mode: args.story_mode, } : {}), ...(args.belief_mode ? { belief_mode: args.belief_mode, } : {}), }; const result = await doRequest(url, "PATCH", body); return { content: [ { type: "text", text: `Goal updated:\n${JSON.stringify(result, null, 2)}`, }, ], isError: false, }; }, );