PureScript MCP Server

Instructions

Implementation Reference

• index.js:848-870 (handler)

  Handler function that implements getTopLevelDeclarationNames tool. Uses Tree-sitter to parse PureScript code, executes a custom query to capture names of various top-level declarations (functions, data types, classes, imports, signatures, instances, kind declarations), deduplicates, and returns as a JSON array of strings.

      "getTopLevelDeclarationNames": async (args) => {
          if (!treeSitterInitialized) throw new Error("Tree-sitter not initialized.");
          const code = await getCodeFromInput(args, true); // true for module-oriented
          const tree = purescriptTsParser.parse(code);
          const querySource = `
  [
    (function name: (variable) @name)
    (data name: (type) @name)
    (class_declaration (class_head (class_name (type) @name)))
    (type_alias name: (type) @name)
    (foreign_import name: (variable) @name)
    (signature name: (variable) @name)
    (class_instance (instance_name) @name)
    (kind_value_declaration name: (type) @name)
  ]
  `;
          const query = new Query(PureScriptLanguage, querySource);
          const captures = query.captures(tree.rootNode);
          const declarationNames = captures.map(capture => capture.node.text).filter(Boolean);
          // Deduplicate names
          const uniqueNames = [...new Set(declarationNames)];
          return { content: [{ type: "text", text: JSON.stringify(uniqueNames, null, 2) }] };
      },

• index.js:602-613 (registration)

  Tool registration in TOOL_DEFINITIONS array, used by 'tools/list' MCP method to advertise the tool's name, description, and input schema to clients.

      name: "getTopLevelDeclarationNames",
      description: "List all main definitions in PureScript code: function names, data types, type classes, etc. Gets just the names (like 'myFunction', 'MyDataType'). Fast analysis without needing IDE server.",
      inputSchema: {
          type: "object",
          properties: {
              filePath: { type: "string", description: "Absolute path to the PureScript file. Only absolute paths are supported." },
              code: { type: "string", description: "PureScript code string." }
          },
          additionalProperties: false,
          description: "Exactly one of 'filePath' or 'code' must be provided."
      }
  },

• index.js:604-612 (schema)

  JSON Schema defining the input parameters for the tool: exactly one of absolute filePath or inline code string.

  inputSchema: {
      type: "object",
      properties: {
          filePath: { type: "string", description: "Absolute path to the PureScript file. Only absolute paths are supported." },
          code: { type: "string", description: "PureScript code string." }
      },
      additionalProperties: false,
      description: "Exactly one of 'filePath' or 'code' must be provided."
  }

• index.js:126-151 (helper)

  Helper function to retrieve PureScript code from tool arguments, supporting either absolute file path (reads file) or inline code string. Validates inputs and used by multiple AST tools including this one.

  async function getCodeFromInput(args, isModuleOriented = true) {
      if (isModuleOriented) {
          const hasFilePath = args && typeof args.filePath === 'string';
          const hasCode = args && typeof args.code === 'string';
  
          if ((hasFilePath && hasCode) || (!hasFilePath && !hasCode)) {
              throw new Error("Invalid input: Exactly one of 'filePath' or 'code' must be provided for module-oriented tools.");
          }
          if (hasFilePath) {
              if (!path.isAbsolute(args.filePath)) {
                  throw new Error(`Invalid filePath: '${args.filePath}' is not an absolute path. Only absolute paths are supported.`);
              }
              try {
                  return await fs.readFile(args.filePath, 'utf-8');
              } catch (e) {
                  throw new Error(`Failed to read file at ${args.filePath}: ${e.message}`);
              }
          }
          return args.code;
      } else { // Snippet-oriented
          if (!args || typeof args.code !== 'string') {
              throw new Error("Invalid input: 'code' (string) is required for snippet-oriented tools.");
          }
          return args.code;
      }
  }