PureScript MCP Server

Instructions

Implementation Reference

• index.js:1101-1112 (handler)

  Handler function for 'pursIdeUsages' tool. Validates input parameters (module, namespace, identifier), constructs params, sends 'usages' command to purs ide server via sendCommandToPursIde, and returns the JSON-formatted result.
  "pursIdeUsages": async (args) => { if (!args || typeof args.module !== 'string' || typeof args.namespace !== 'string' || typeof args.identifier !== 'string') { throw new Error("Invalid input: 'module', 'namespace', and 'identifier' (strings) are required for pursIdeUsages."); } const params = { module: args.module, namespace: args.namespace, identifier: args.identifier }; const result = await sendCommandToPursIde({ command: "usages", params }); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; },
• index.js:758-771 (schema)

  Input schema definition for 'pursIdeUsages' tool, specifying required parameters: module, namespace (value/type/kind), identifier.
  { name: "pursIdeUsages", description: "Find everywhere a specific function, type, or value is used across the project. PREREQUISITES: IDE server running and modules loaded. Essential for refactoring - shows impact of changes. If you plan to refactor, get usages before refactoring so you can make changes to all places that function is used.", inputSchema: { type: "object", properties: { module: { type: "string", description: "Module where the identifier is defined." }, namespace: { type: "string", enum: ["value", "type", "kind"], description: "Namespace of the identifier." }, identifier: { type: "string", description: "The identifier to find usages for." } }, required: ["module", "namespace", "identifier"], additionalProperties: false } },
• index.js:1101-1113 (registration)

  Registration of the handler in INTERNAL_TOOL_HANDLERS map, which is used in tools/call to dispatch to the handler.
  "pursIdeUsages": async (args) => { if (!args || typeof args.module !== 'string' || typeof args.namespace !== 'string' || typeof args.identifier !== 'string') { throw new Error("Invalid input: 'module', 'namespace', and 'identifier' (strings) are required for pursIdeUsages."); } const params = { module: args.module, namespace: args.namespace, identifier: args.identifier }; const result = await sendCommandToPursIde({ command: "usages", params }); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; }, "pursIdeList": async (args) => {
• index.js:1158-1164 (registration)

  Registration via tools/list endpoint returning TOOL_DEFINITIONS array containing the pursIdeUsages tool definition (not excluded).
  if (method === 'tools/list') { const toolsToExclude = ['query_purescript_ast', 'query_purs_ide']; // Keep query_purs_ide for now, for direct access if needed const filteredToolDefinitions = TOOL_DEFINITIONS.filter( tool => !toolsToExclude.includes(tool.name) ); return createSuccessResponse(id, { tools: filteredToolDefinitions }); }
• index.js:169-204 (helper)

  Helper function sendCommandToPursIde that establishes TCP connection to purs ide server, sends JSON command (like {command: 'usages', params}), receives and parses JSON response. Core communication layer used by the handler.
  function sendCommandToPursIde(commandPayload) { return new Promise((resolve, reject) => { if (!pursIdeProcess || !pursIdeIsReady || !pursIdeServerPort) { return reject(new Error("purs ide server is not running or not ready.")); } const client = new net.Socket(); let responseData = ''; client.connect(pursIdeServerPort, '127.0.0.1', () => { logToStderr(`[MCP Client->purs ide]: Sending command: ${JSON.stringify(commandPayload).substring(0,100)}...`, 'debug'); client.write(JSON.stringify(commandPayload) + '\n'); }); client.on('data', (data) => { responseData += data.toString(); if (responseData.includes('\n')) { const completeResponses = responseData.split('\n').filter(Boolean); responseData = ''; if (completeResponses.length > 0) { try { resolve(JSON.parse(completeResponses[0].trim())); } catch (e) { reject(new Error(`Failed to parse JSON response from purs ide: ${e.message}. Raw: ${completeResponses[0]}`)); } } client.end(); } }); client.on('end', () => { if (responseData.trim()) { try { resolve(JSON.parse(responseData.trim())); } catch (e) { reject(new Error(`Failed to parse JSON response from purs ide on end: ${e.message}. Raw: ${responseData}`));} } }); client.on('close', () => { logToStderr(`[MCP Client->purs ide]: Connection closed.`, 'debug'); }); client.on('error', (err) => reject(new Error(`TCP connection error with purs ide server: ${err.message}`))); }); }