OSRS MCP Server

Instructions

Implementation Reference

• index.ts:384-407 (handler)

  Handler implementation for the 'search_spritetypes' tool (shared with other search_*types tools). Parses input arguments using FileSearchSchema, derives the filename 'spritetypes.txt' from the tool name, checks if the file exists, and executes the search using the searchFile helper with pagination support.

  case "search_varptypes":
  case "search_varbittypes":
  case "search_iftypes":
  case "search_invtypes":
  case "search_loctypes":
  case "search_npctypes":
  case "search_objtypes":
  case "search_rowtypes":
  case "search_seqtypes":
  case "search_soundtypes":
  case "search_spottypes":
  case "search_spritetypes":
  case "search_tabletypes":
      const { query, page: filePage = 1, pageSize: filePageSize = 10 } = FileSearchSchema.parse(args);
      const filename = `${name.replace('search_', '')}.txt`;
      const filePath = path.join(DATA_DIR, filename);
      
      if (!fileExists(filename)) {
          return responseToString({ error: `${filename} not found in data directory` });
      }
      
      const fileResults = await searchFile(filePath, query, filePage, filePageSize);
      return responseToString(fileResults);

• index.ts:49-53 (schema)

  Input schema (FileSearchSchema) used by 'search_spritetypes' tool for validating query term, page, and pageSize parameters.

  const FileSearchSchema = z.object({
      query: z.string().describe("The term to search for in the file"),
      page: z.number().int().min(1).optional().default(1).describe("Page number for pagination"),
      pageSize: z.number().int().min(1).max(100).optional().default(10).describe("Number of results per page")
  });

• index.ts:314-318 (registration)

  Registration of the 'search_spritetypes' tool in the ListTools response, specifying name, description, and input schema.

      name: "search_spritetypes",
      description: "Search the spritetypes.txt file for sprite image definitions used in the interface.",
      inputSchema: convertZodToJsonSchema(FileSearchSchema),
  },
  {

• index.ts:99-165 (helper)

  Helper function searchFile that implements the core search logic: performs case-insensitive line matching (after replacing spaces with underscores in query), paginates results, formats lines as ID-value pairs where possible, and returns structured results with pagination info. Used by the search_spritetypes handler.

  async function searchFile(filePath: string, searchTerm: string, page: number = 1, pageSize: number = 10): Promise<any> {
      //replace spaces with underscores
      searchTerm = searchTerm.replace(" ", "_");
      return new Promise((resolve, reject) => {
          if (!fs.existsSync(filePath)) {
              reject(new Error(`File not found: ${filePath}`));
              return;
          }
  
          const results: {line: string, lineNumber: number}[] = [];
          const fileStream = fs.createReadStream(filePath);
          const rl = readline.createInterface({
              input: fileStream,
              crlfDelay: Infinity
          });
  
          let lineNumber = 0;
          
          rl.on('line', (line) => {
              lineNumber++;
              if (line.toLowerCase().includes(searchTerm.toLowerCase())) {
                  results.push({ line, lineNumber });
              }
          });
  
          rl.on('close', () => {
              const totalResults = results.length;
              const totalPages = Math.ceil(totalResults / pageSize);
              const startIndex = (page - 1) * pageSize;
              const endIndex = startIndex + pageSize;
              const paginatedResults = results.slice(startIndex, endIndex);
  
              // Process the results to extract key-value pairs if possible
              const formattedResults = paginatedResults.map(result => {
                  // Try to format as key-value pair (common for ID data files)
                  const parts = result.line.split(/\s+/);
                  if (parts.length >= 2) {
                      const id = parts[0];
                      const value = parts.slice(1).join(' ');
                      return {
                          ...result,
                          id,
                          value,
                          formatted: `${id}\t${value}`
                      };
                  }
                  return result;
              });
  
              resolve({
                  results: formattedResults,
                  pagination: {
                      page,
                      pageSize,
                      totalResults,
                      totalPages,
                      hasNextPage: page < totalPages,
                      hasPreviousPage: page > 1
                  }
              });
          });
  
          rl.on('error', (err) => {
              reject(err);
          });
      });
  }