feat: add template source code structure

- Add MCP server entry point with example tool registration
- Create example tool implementation with input validation
- Add validation utilities for common patterns (URL, date, timestamp)
- Include comprehensive test coverage for all components

Author: Mearman

src/index.test.ts

@@ -0,0 +1,9 @@
+import { describe, it, expect } from 'vitest';
+
+describe('MCP Server', () => {
+  it('should export as ES module', async () => {
+    // This test verifies the module can be imported
+    const module = await import('./index.js');
+    expect(module).toBeDefined();
+  });
+});

src/index.ts

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { exampleTool, ExampleToolSchema } from './tools/example.js';
+
+const server = new Server(
+  {
+    name: 'mcp-server-template',
+    version: '0.1.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'example_tool',
+        description: 'An example tool that echoes back the input',
+        inputSchema: zodToJsonSchema(ExampleToolSchema),
+      },
+    ],
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  switch (name) {
+    case 'example_tool':
+      return await exampleTool(args);
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+});
+
+// Start the server
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+// Handle shutdown gracefully
+process.on('SIGINT', async () => {
+  await server.close();
+  process.exit(0);
+});

src/tools/example.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'vitest';
+import { exampleTool } from './example.js';
+
+describe('exampleTool', () => {
+  it('should echo the message', async () => {
+    const result = await exampleTool({ message: 'Hello, world!' });
+    expect(result.content[0]).toEqual({
+      type: 'text',
+      text: 'Echo: Hello, world!',
+    });
+  });
+
+  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!',
+    });
+  });
+
+  it('should validate input', async () => {
+    await expect(exampleTool({})).rejects.toThrow();
+    await expect(exampleTool({ message: 123 })).rejects.toThrow();
+  });
+});

src/tools/example.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+
+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'),
+});
+
+export type ExampleToolInput = z.infer<typeof ExampleToolSchema>;
+
+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}`,
+      },
+    ],
+  };
+}

src/utils/validation.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { urlSchema, dateSchema, timestampSchema, validateInput } from './validation.js';
+
+describe('validation schemas', () => {
+  describe('urlSchema', () => {
+    it('should accept valid URLs', () => {
+      expect(urlSchema.parse('https://example.com')).toBe('https://example.com');
+      expect(urlSchema.parse('http://example.com/path')).toBe('http://example.com/path');
+    });
+
+    it('should reject invalid URLs', () => {
+      expect(() => urlSchema.parse('not a url')).toThrow();
+      expect(() => urlSchema.parse('example.com')).toThrow();
+    });
+  });
+
+  describe('dateSchema', () => {
+    it('should accept valid dates', () => {
+      expect(dateSchema.parse('2024-01-01')).toBe('2024-01-01');
+      expect(dateSchema.parse('2024-12-31')).toBe('2024-12-31');
+    });
+
+    it('should reject invalid dates', () => {
+      expect(() => dateSchema.parse('2024-1-1')).toThrow();
+      expect(() => dateSchema.parse('01-01-2024')).toThrow();
+      expect(() => dateSchema.parse('2024/01/01')).toThrow();
+    });
+  });
+
+  describe('timestampSchema', () => {
+    it('should accept valid timestamps', () => {
+      expect(timestampSchema.parse('20240101120000')).toBe('20240101120000');
+    });
+
+    it('should reject invalid timestamps', () => {
+      expect(() => timestampSchema.parse('2024-01-01')).toThrow();
+      expect(() => timestampSchema.parse('202401011200')).toThrow();
+    });
+  });
+});
+
+describe('validateInput', () => {
+  it('should return parsed value for valid input', () => {
+    const result = validateInput(urlSchema, 'https://example.com');
+    expect(result).toBe('https://example.com');
+  });
+
+  it('should throw formatted error for invalid input', () => {
+    expect(() => validateInput(urlSchema, 'invalid')).toThrow('Validation failed');
+  });
+});

src/utils/validation.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+
+/**
+ * Common validation schemas for reuse across tools
+ */
+
+// URL validation
+export const urlSchema = z.string().url('Invalid URL format');
+
+// Date validation
+export const dateSchema = z.string().regex(
+  /^\d{4}-\d{2}-\d{2}$/,
+  'Date must be in YYYY-MM-DD format'
+);
+
+// Timestamp validation (YYYYMMDDHHmmss)
+export const timestampSchema = z.string().regex(
+  /^\d{14}$/,
+  'Timestamp must be in YYYYMMDDHHmmss format'
+);
+
+/**
+ * Validate and parse input with helpful error messages
+ */
+export function validateInput<T>(schema: z.ZodSchema<T>, input: unknown): T {
+  try {
+    return schema.parse(input);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      const issues = error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`);
+      throw new Error(`Validation failed:\n${issues.join('\n')}`);
+    }
+    throw error;
+  }
+}