feat: add example tool implementation

Author: Mearman

src/tools/example.test.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Unit tests for the example tool
+ * @module tools/example.test
+ */
+
+import { describe, expect, it } from 'vitest';
+import { exampleTool } from './example.js';
+
+/**
+ * Test suite for the example tool functionality
+ */
+describe('exampleTool', () => {
+	/**
+	 * Test that the tool correctly echoes back the input message
+	 */
+	it('should echo the message', async () => {
+		const result = await exampleTool({ message: 'Hello, world!' });
+		expect(result.content[0]).toEqual({
+			type: 'text',
+			text: 'Echo: Hello, world!',
+		});
+	});
+
+	/**
+	 * Test that the uppercase option works correctly
+	 */
+	it('should convert to uppercase when requested', async () => {
+		const result = await exampleTool({
+			message: 'Hello, world!',
+			uppercase: true,
+		});
+		expect(result.content[0]).toEqual({
+			type: 'text',
+			text: 'Echo: HELLO, WORLD!',
+		});
+	});
+
+	/**
+	 * Test that invalid inputs are properly rejected with validation errors
+	 */
+	it('should validate input', async () => {
+		await expect(exampleTool({})).rejects.toThrow();
+		await expect(exampleTool({ message: 123 })).rejects.toThrow();
+	});
+});

src/tools/example.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Example tool implementation demonstrating MCP tool structure
+ * @module tools/example
+ */
+
+import { z } from 'zod';
+
+/**
+ * Input schema for the example tool
+ * @description Validates input parameters for the echo tool
+ */
+export const ExampleToolSchema = z.object({
+	message: z.string().describe('The message to echo back'),
+	uppercase: z
+		.boolean()
+		.optional()
+		.default(false)
+		.describe('Whether to return the message in uppercase'),
+});
+
+/**
+ * TypeScript type for the example tool input
+ */
+export type ExampleToolInput = z.infer<typeof ExampleToolSchema>;
+
+/**
+ * Example tool that echoes back the input message
+ * @param args - Raw input arguments to be validated against ExampleToolSchema
+ * @returns MCP tool response with the echoed message
+ * @throws {z.ZodError} If input validation fails
+ *
+ * @example
+ * ```typescript
+ * const result = await exampleTool({ message: "Hello", uppercase: true });
+ * // Returns: { content: [{ type: 'text', text: 'Echo: HELLO' }] }
+ * ```
+ */
+export async function exampleTool(args: unknown) {
+	const input = ExampleToolSchema.parse(args);
+
+	let result = input.message;
+	if (input.uppercase) {
+		result = result.toUpperCase();
+	}
+
+	return {
+		content: [
+			{
+				type: 'text',
+				text: `Echo: ${result}`,
+			},
+		],
+	};
+}