Minestom MCP Server

Instructions

Implementation Reference

• src/minestom/environment.ts:587-691 (handler)

  The function `inspectMinestomEnvironment` performs the actual scanning of the environment, including gathering files, detecting project roots, languages, build tools, and summarizing the Minestom project structure.

  export async function inspectMinestomEnvironment(repoRootInput?: string) {
  	const repoRoot = path.resolve(repoRootInput ?? process.cwd());
  	const scannedFiles = await collectTextFiles(repoRoot, MAX_SCANNED_FILES);
  	const buildFiles = scannedFiles
  		.map((file) => normalizeRelativePath(file.relativePath))
  		.filter((relativePath) => isBuildFile(relativePath))
  		.sort();
  	const runDirectories = await collectRunDirectories(repoRoot);
  	const wrapperFiles = await collectNamedFiles(
  		repoRoot,
  		WRAPPER_FILE_NAMES,
  		20,
  	);
  	const runDirectory = runDirectories.find(
  		(directory) => directory.relativePath === "run",
  	) ??
  		runDirectories[0] ?? {
  			exists: false,
  			fileCount: 0,
  			jarFiles: [],
  			notableFiles: [],
  			relativePath: "run",
  		};
  	const { detectedApiSymbols, detectedTopics } =
  		detectTopicsAndApis(scannedFiles);
  	const entrypointFiles = detectEntrypointFiles(scannedFiles);
  	const sourceRoots = detectSourceRoots(scannedFiles);
  	const packageNamespaces = detectPackageNamespaces(scannedFiles);
  	const languages = detectLanguages(scannedFiles, buildFiles);
  	const existingLibraries = detectExistingLibraries(scannedFiles);
  	const buildTool = detectBuildTool(buildFiles);
  	const projectRoots = detectProjectRoots(
  		buildFiles,
  		sourceRoots,
  		entrypointFiles,
  		runDirectories,
  	);
  	const jvmProject = summarizeJvmProject(
  		buildFiles,
  		wrapperFiles,
  		languages,
  		sourceRoots,
  		entrypointFiles,
  		detectedTopics,
  	);
  	const notes: string[] = [];
  
  	if (!jvmProject.isLikelyJvmProject) {
  		notes.push(
  			"The inspected directory tree does not yet strongly resemble a JVM project backed by Gradle or Maven.",
  		);
  	} else if (buildTool === "unknown") {
  		notes.push(
  			"JVM-oriented signals were detected, but no Gradle or Maven build file was found in the inspected directory tree.",
  		);
  	}
  
  	if (detectedTopics.length === 0) {
  		notes.push(
  			"No curated Minestom API symbols were detected in the scanned source files.",
  		);
  	}
  
  	if (runDirectories.length === 0) {
  		notes.push(
  			"No `run/` directory was found in the inspected directory or its scanned subdirectories.",
  		);
  	} else if (
  		runDirectories.some((directory) => directory.jarFiles.length > 0)
  	) {
  		notes.push(
  			"At least one detected `run/` directory contains JAR files that may represent local server extensions or supporting artifacts.",
  		);
  	}
  
  	if (entrypointFiles.length === 0) {
  		notes.push(
  			"No clear Minestom bootstrap entrypoint was detected from `MinecraftServer` usage patterns.",
  		);
  	}
  
  	if (projectRoots.length > 1) {
  		notes.push(
  			"Multiple candidate project roots were detected. Treat the inspection results as workspace-wide rather than assuming a single Minestom module.",
  		);
  	}
  
  	return environmentSummarySchema.parse({
  		buildFiles,
  		buildTool,
  		detectedApiSymbols,
  		detectedTopics,
  		entrypointFiles,
  		existingLibraries,
  		jvmProject,
  		languages,
  		notes,
  		packageNamespaces,
  		projectRoots,
  		repoRoot,
  		runDirectory,
  		runDirectories,
  		sourceRoots,
  	});
  }

• src/minestom/environment.ts:693-700 (schema)

  The Zod schema `inspectMinestomEnvironmentInputSchema` defines the expected input parameters (repoRoot) for the tool.

  const inspectMinestomEnvironmentInputSchema = z.object({
  	repoRoot: z
  		.string()
  		.optional()
  		.describe(
  			"Absolute or relative path to the Minestom repository to inspect. Defaults to the current working directory.",
  		),
  });

• src/minestom/environment.ts:702-712 (registration)

  The tool `inspectMinestomEnvironmentTool` is registered with its name, input schema, and handler function, using the `@tanstack/ai` framework.

  export const inspectMinestomEnvironmentTool: TanStackServerTool =
  	toolDefinition({
  		description:
  			"Use this when you want a Minestom workspace scan rooted at the current directory or `repoRoot`, including build files, source patterns, entrypoints, existing libraries, and any detected `run/` subdirectories.",
  		inputSchema: inspectMinestomEnvironmentInputSchema,
  		name: "inspect_minestom_environment",
  		outputSchema: environmentSummarySchema,
  	}).server(async (args) => {
  		const { repoRoot } = inspectMinestomEnvironmentInputSchema.parse(args);
  		return inspectMinestomEnvironment(repoRoot);
  	});