Minestom MCP Server

Instructions

Implementation Reference

• src/minestom/knowledge.ts:102-144 (handler)

  The handler function for the lookup_minestom_api tool, which performs a search against the apiCatalog based on the provided symbol and topic.

  }).server(async (args) => {
  	const { symbol, topic } = lookupMinestomApiInputSchema.parse(args);
  	const candidates = apiCatalog.filter(
  		(entry) => !topic || entry.topic === topic,
  	);
  
  	const rankedMatches = candidates
  		.map((entry) => ({
  			entry,
  			score: scoreTextQuery(symbol, [
  				entry.symbol,
  				entry.displayName,
  				entry.packageName,
  				entry.summary,
  				entry.whyItMatters,
  				...entry.relatedSymbols,
  				...entry.keywords,
  			]),
  		}))
  		.filter(({ score }) => score > 0)
  		.sort((left, right) => right.score - left.score)
  		.slice(0, 5)
  		.map(({ entry }) => entry);
  
  	const fallbackMatches =
  		rankedMatches.length > 0
  			? rankedMatches
  			: candidates.slice(0, Math.min(3, candidates.length));
  
  	const warning =
  		rankedMatches.length > 0
  			? undefined
  			: topic
  				? `No strong curated API match for "${symbol}" under ${topic}; returning the main APIs for that topic instead.`
  				: `No strong curated API match for "${symbol}" was found; returning the first curated Minestom APIs instead.`;
  
  	return lookupMinestomApiOutputSchema.parse({
  		bestMatches: fallbackMatches,
  		query: symbol,
  		topicFilter: topic,
  		warning,
  	});
  });

• src/minestom/knowledge.ts:76-94 (schema)

  The input and output schemas for the lookup_minestom_api tool using Zod.

  const lookupMinestomApiInputSchema = z.object({
  	symbol: z
  		.string()
  		.describe(
  			"Class, interface, or API symbol to look up, such as EventNode or SchedulerManager.",
  		),
  	topic: minestomTopicSchema
  		.optional()
  		.describe(
  			"Optional topic filter to keep the lookup scoped to one Minestom subsystem.",
  		),
  });
  
  const lookupMinestomApiOutputSchema = z.object({
  	bestMatches: z.array(apiReferenceSchema),
  	query: z.string(),
  	topicFilter: minestomTopicSchema.optional(),
  	warning: z.string().optional(),
  });

• src/minestom/knowledge.ts:96-101 (registration)

  The registration of the lookup_minestom_api tool as a TanStackServerTool.

  export const lookupMinestomApiTool: TanStackServerTool = toolDefinition({
  	description:
  		"Use this when you need curated Minestom API matches with package names, why they matter, related APIs, and javadoc links.",
  	inputSchema: lookupMinestomApiInputSchema,
  	name: "lookup_minestom_api",
  	outputSchema: lookupMinestomApiOutputSchema,