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}`)));
      });
  }