suggest_minestom_libraries

Instructions

Implementation Reference

• src/minestom/libraries.ts:276-331 (handler)

  The main handler function for the suggest_minestom_libraries tool. Parses input (category, includeLiveResults, repoRoot, useCase), inspects the Minestom environment, selects curated libraries by scoring them against the use case, optionally fetches live GitHub results, merges and deduplicates results, and returns the output.

  export const suggestMinestomLibrariesTool: TanStackServerTool = toolDefinition({
  	description:
  		"Use this when you want Minestom ecosystem suggestions grounded in the official libraries directory, with optional live GitHub topic lookups.",
  	inputSchema: suggestMinestomLibrariesInputSchema,
  	name: "suggest_minestom_libraries",
  	outputSchema: suggestMinestomLibrariesOutputSchema,
  }).server(async (args) => {
  	const { category, includeLiveResults, repoRoot, useCase } =
  		suggestMinestomLibrariesInputSchema.parse(args);
  	const environment = await inspectMinestomEnvironment(repoRoot).catch(
  		() => undefined,
  	);
  	const curated = selectCuratedLibraries(useCase, category, environment);
  	const live = includeLiveResults
  		? await fetchLiveLibraries(useCase, category)
  		: { results: [], warning: undefined };
  
  	const mergedResults = uniqueBy(
  		[...curated.results, ...live.results].filter(
  			(entry) =>
  				!environment?.existingLibraries.some(
  					(library) =>
  						library.repoUrl.toLowerCase() === entry.repoUrl.toLowerCase(),
  				),
  		),
  		(entry) => entry.repoUrl.toLowerCase(),
  	);
  
  	return suggestMinestomLibrariesOutputSchema.parse({
  		categoryFilter: category,
  		curatedResults: curated.results,
  		environment,
  		liveResults: live.results,
  		matchedCategories: uniqueBy(
  			[
  				...curated.inferredCategories.filter(
  					(value): value is z.infer<typeof libraryCategorySchema> => {
  						return (libraryCategorySchema.options as string[]).includes(value);
  					},
  				),
  				...curated.results.map((entry) => entry.category),
  				...live.results.map((entry) => entry.category),
  			],
  			(value) => value,
  		),
  		mergedResults,
  		query: useCase,
  		warning:
  			live.warning ??
  			(environment &&
  			(!environment.jvmProject.isLikelyJvmProject ||
  				environment.detectedTopics.length === 0)
  				? "No strong JVM-backed Minestom repository signals were detected in the inspected environment; suggestions are primarily use-case driven."
  				: undefined),
  	});
  });

• src/minestom/libraries.ts:19-42 (schema)

  Input schema defining the tool's parameters: category (optional filter), includeLiveResults (boolean, defaults false), repoRoot (optional path), and useCase (required text describing the problem space).

  const suggestMinestomLibrariesInputSchema = z.object({
  	category: libraryCategorySchema
  		.optional()
  		.describe(
  			"Optional curated category filter to narrow the ecosystem suggestions.",
  		),
  	includeLiveResults: z
  		.boolean()
  		.default(false)
  		.describe(
  			"When true, also search live GitHub repositories tagged with the Minestom library topic.",
  		),
  	repoRoot: z
  		.string()
  		.optional()
  		.describe(
  			"Absolute or relative path to the target Minestom repository. Defaults to the current working directory for environment-aware suggestions.",
  		),
  	useCase: z
  		.string()
  		.describe(
  			"Describe the problem space, such as command framework, world persistence, debug rendering, or Kotlin coroutines.",
  		),
  });

• src/minestom/libraries.ts:44-53 (schema)

  Output schema defining the tool's response: categoryFilter, curatedResults, environment, liveResults, matchedCategories, mergedResults, query, and optional warning.

  const suggestMinestomLibrariesOutputSchema = z.object({
  	categoryFilter: libraryCategorySchema.optional(),
  	curatedResults: z.array(librarySuggestionSchema),
  	environment: environmentSummarySchema.optional(),
  	liveResults: z.array(librarySuggestionSchema),
  	matchedCategories: z.array(libraryCategorySchema),
  	mergedResults: z.array(librarySuggestionSchema),
  	query: z.string(),
  	warning: z.string().optional(),
  });

• src/tools.ts:18-28 (registration)

  Registration of the suggestMinestomLibrariesTool in the tools array. The tool is imported from ./minestom/libraries.js and pushed into the server's tool collection.

  tools.push(
  	pingTool,
  	createGetServerInfoTool(toolNames),
  	inspectMinestomEnvironmentTool,
  	inspectMinestomBuildTool,
  	explainMinestomPatternTool,
  	lookupMinestomApiTool,
  	planMinestomFeatureTool,
  	reviewMinestomDesignTool,
  	suggestMinestomLibrariesTool,
  );

• src/minestom/libraries.ts:90-110 (helper)

  Helper that infers a library category from a live GitHub repository's description and name, falling back to 'gameplay' if no match.

  function inferCategoryForLiveRepo(
  	useCase: string,
  	description: string,
  	name: string,
  ): z.infer<typeof libraryCategorySchema> {
  	const inferred = inferCategoriesFromUseCase(
  		`${useCase} ${description} ${name}`,
  	)[0];
  
  	switch (inferred) {
  		case "commands":
  		case "concurrency":
  		case "world-storage":
  		case "models-and-ui":
  		case "gameplay":
  		case "debugging":
  			return inferred;
  		default:
  			return "gameplay";
  	}
  }