plan_minestom_feature

Instructions

Implementation Reference

• src/minestom/planning.ts:65-112 (handler)

  The server handler function that executes the 'plan_minestom_feature' tool logic. It parses input, builds file paths from blueprints, resolves key APIs, constructs implementation steps, and returns a validated output containing files, implementationSteps, keyApis, topics, threadSafetyNotes, and verificationSteps.

  }).server(async (args) => {
  	const { featureType, language, packageName, targetName, useCases } =
  		planMinestomFeatureInputSchema.parse(args);
  	const blueprint = getFeatureBlueprint(featureType);
  	const extension = language === "kotlin" ? "kt" : "java";
  	const packagePath = packageName.replaceAll(".", "/");
  
  	const files = blueprint.fileTemplates.map((template) => {
  		const className = template.suffix
  			? `${targetName}${template.suffix}`
  			: targetName;
  
  		return {
  			path: `src/main/${language}/${packagePath}/${className}.${extension}`,
  			purpose: template.purpose,
  		};
  	});
  
  	const keyApis = getApisBySymbols(blueprint.keyApiSymbols).map((api) => ({
  		javadocUrl: api.javadocUrl,
  		packageName: api.packageName,
  		symbol: api.symbol,
  	}));
  
  	const summary =
  		useCases.length > 0
  			? `${blueprint.summary} Prioritize these use cases: ${useCases.join("; ")}.`
  			: blueprint.summary;
  
  	return planMinestomFeatureOutputSchema.parse({
  		featureType,
  		files,
  		implementationSteps: [
  			...blueprint.implementationSteps,
  			...(useCases.length > 0
  				? [
  						`Fold the requested behavior into the design without breaking the main Minestom ownership boundary: ${useCases.join("; ")}.`,
  					]
  				: []),
  		],
  		keyApis,
  		primaryTopic: blueprint.primaryTopic,
  		summary,
  		supportingTopics: blueprint.supportingTopics,
  		threadSafetyNotes: blueprint.threadSafetyNotes,
  		verificationSteps: blueprint.verificationSteps,
  	});
  });

• src/minestom/planning.ts:12-34 (schema)

  Input schema (planMinestomFeatureInputSchema) defining the expected parameters: featureType, language, packageName, targetName, and useCases.

  const planMinestomFeatureInputSchema = z.object({
  	featureType: minestomFeatureTypeSchema.describe(
  		"The kind of Minestom feature you want to plan.",
  	),
  	language: languageSchema
  		.default("java")
  		.describe("The target JVM language for the implementation."),
  	packageName: z
  		.string()
  		.default("dev.example.minestom")
  		.describe("Base package name for the generated outline."),
  	targetName: z
  		.string()
  		.describe(
  			"A short feature name such as SpawnCommand or LobbyJoinListener.",
  		),
  	useCases: z
  		.array(z.string())
  		.default([])
  		.describe(
  			"Optional behavior notes or acceptance criteria to fold into the plan.",
  		),
  });

• src/minestom/planning.ts:36-57 (schema)

  Output schema (planMinestomFeatureOutputSchema) defining the structure of the tool response: featureType, files, implementationSteps, keyApis, primaryTopic, summary, supportingTopics, threadSafetyNotes, verificationSteps.

  const planMinestomFeatureOutputSchema = z.object({
  	featureType: minestomFeatureTypeSchema,
  	files: z.array(
  		z.object({
  			path: z.string(),
  			purpose: z.string(),
  		}),
  	),
  	implementationSteps: z.array(z.string()),
  	keyApis: z.array(
  		z.object({
  			javadocUrl: z.string().url(),
  			packageName: z.string(),
  			symbol: z.string(),
  		}),
  	),
  	primaryTopic: minestomTopicSchema,
  	summary: z.string(),
  	supportingTopics: z.array(minestomTopicSchema),
  	threadSafetyNotes: z.array(z.string()),
  	verificationSteps: z.array(z.string()),
  });

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

  The tool is registered as a TanStackServerTool in the tools array. On line 25, planMinestomFeatureTool is pushed into the tools list alongside other tools.

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

• src/minestom/catalog.ts:1133-1137 (helper)

  getFeatureBlueprint() helper used by the handler to retrieve the FeatureBlueprint for a given MinestomFeatureType. The featureBlueprints record contains fileTemplates, implementationSteps, keyApiSymbols, primaryTopic, supportingTopics, threadSafetyNotes, and verificationSteps for each feature type.

  export function getFeatureBlueprint(
  	featureType: MinestomFeatureType,
  ): FeatureBlueprint {
  	return featureBlueprints[featureType];
  }