docs: add JSDoc comments to source files and fix license

- Add comprehensive JSDoc comments to all non-test TypeScript files
- Fix license from MIT back to CC BY-NC-SA 4.0
- Update package.json license field
- Add template repo badges to README
- Add proper license badge and attribution to README

Author: Mearman

LICENSE

@@ -1,21 +1,18 @@
-MIT License
+Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License
 
-Copyright (c) 2025
+Copyright (c) 2025 Joseph Mearman
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+You are free to:
+- Share — copy and redistribute the material in any medium or format
+- Adapt — remix, transform, and build upon the material
+
+Under the following terms:
+- Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
+- NonCommercial — You may not use the material for commercial purposes.
+- ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
+
+No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.

README.md

@@ -2,6 +2,9 @@
 
 A template repository for building Model Context Protocol (MCP) servers with TypeScript.
 
+[![Use this template](https://img.shields.io/badge/Use%20this%20template-2ea44f?style=for-the-badge)](https://github.com/Mearman/mcp-template/generate)
+[![GitHub](https://img.shields.io/github/stars/Mearman/mcp-template?style=for-the-badge)](https://github.com/Mearman/mcp-template)
+
 ## Features
 
 - 🚀 Full TypeScript support with strict mode
@@ -214,7 +217,9 @@ This template includes semantic-release for automated versioning and publishing:
 
 ## License
 
-MIT
+[![CC BY-NC-SA 4.0](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg)](http://creativecommons.org/licenses/by-nc-sa/4.0/)
+
+This work is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](http://creativecommons.org/licenses/by-nc-sa/4.0/).
 
 ## Contributing
 

package.json

@@ -18,7 +18,7 @@
 	},
 	"keywords": ["mcp", "model-context-protocol", "typescript", "template", "mcp-server"],
 	"author": "",
-	"license": "MIT",
+	"license": "CC-BY-NC-SA-4.0",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/Mearman/mcp-template.git"

src/index.test.ts

@@ -1,8 +1,18 @@
+/**
+ * @fileoverview Basic tests for the MCP server entry point
+ * @module index.test
+ */
+
 import { describe, expect, it } from 'vitest';
 
+/**
+ * Test suite for the MCP server module
+ */
 describe('MCP Server', () => {
+	/**
+	 * Test that the server module can be imported as an ES module
+	 */
 	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

@@ -1,11 +1,19 @@
 #!/usr/bin/env node
+/**
+ * @fileoverview MCP server entry point that sets up and starts the server
+ * @module index
+ */
+
 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 { ExampleToolSchema, exampleTool } from './tools/example.js';
 
+/**
+ * Create the MCP server instance with configured capabilities
+ */
 const server = new Server(
 	{
 		name: 'mcp-template',
@@ -18,7 +26,10 @@ const server = new Server(
 	},
 );
 
-// List available tools
+/**
+ * Register handler for listing available tools
+ * @returns List of available tools with their schemas
+ */
 server.setRequestHandler(ListToolsRequestSchema, async () => {
 	return {
 		tools: [
@@ -31,7 +42,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 	};
 });
 
-// Handle tool calls
+/**
+ * Register handler for executing tool calls
+ * @param request - The tool call request containing tool name and arguments
+ * @returns Tool execution result
+ */
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
 	const { name, arguments: args } = request.params;
 
@@ -43,11 +58,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 	}
 });
 
-// Start the server
+/**
+ * Start the MCP server using stdio transport
+ */
 const transport = new StdioServerTransport();
 await server.connect(transport);
 
-// Handle shutdown gracefully
+/**
+ * Handle graceful shutdown on SIGINT (Ctrl+C)
+ */
 process.on('SIGINT', async () => {
 	await server.close();
 	process.exit(0);

src/tools/example.test.ts

@@ -1,7 +1,18 @@
+/**
+ * @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({
@@ -10,6 +21,9 @@ describe('exampleTool', () => {
 		});
 	});
 
+	/**
+	 * Test that the uppercase option works correctly
+	 */
 	it('should convert to uppercase when requested', async () => {
 		const result = await exampleTool({
 			message: 'Hello, world!',
@@ -21,6 +35,9 @@ describe('exampleTool', () => {
 		});
 	});
 
+	/**
+	 * 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

@@ -1,5 +1,14 @@
+/**
+ * @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
@@ -9,8 +18,23 @@ export const ExampleToolSchema = z.object({
 		.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);
 

src/utils/validation.test.ts

@@ -1,7 +1,18 @@
+/**
+ * @fileoverview Unit tests for validation utilities and schemas
+ * @module utils/validation.test
+ */
+
 import { describe, expect, it } from 'vitest';
 import { dateSchema, timestampSchema, urlSchema, validateInput } from './validation.js';
 
+/**
+ * Test suite for validation schemas
+ */
 describe('validation schemas', () => {
+	/**
+	 * Tests for URL validation schema
+	 */
 	describe('urlSchema', () => {
 		it('should accept valid URLs', () => {
 			expect(urlSchema.parse('https://example.com')).toBe('https://example.com');
@@ -14,6 +25,9 @@ describe('validation schemas', () => {
 		});
 	});
 
+	/**
+	 * Tests for date validation schema (YYYY-MM-DD format)
+	 */
 	describe('dateSchema', () => {
 		it('should accept valid dates', () => {
 			expect(dateSchema.parse('2024-01-01')).toBe('2024-01-01');
@@ -27,6 +41,9 @@ describe('validation schemas', () => {
 		});
 	});
 
+	/**
+	 * Tests for timestamp validation schema (YYYYMMDDHHmmss format)
+	 */
 	describe('timestampSchema', () => {
 		it('should accept valid timestamps', () => {
 			expect(timestampSchema.parse('20240101120000')).toBe('20240101120000');
@@ -39,6 +56,9 @@ describe('validation schemas', () => {
 	});
 });
 
+/**
+ * Test suite for the validateInput utility function
+ */
 describe('validateInput', () => {
 	it('should return parsed value for valid input', () => {
 		const result = validateInput(urlSchema, 'https://example.com');

src/utils/validation.ts

@@ -1,24 +1,64 @@
+/**
+ * @fileoverview Common validation schemas and utilities for input validation
+ * @module utils/validation
+ */
+
 import { z } from 'zod';
 
 /**
  * Common validation schemas for reuse across tools
  */
 
-// URL validation
+/**
+ * Schema for validating URL strings
+ * @description Ensures the input is a valid URL format
+ * @example
+ * ```typescript
+ * const validUrl = urlSchema.parse("https://example.com");
+ * // Returns: "https://example.com"
+ * ```
+ */
 export const urlSchema = z.string().url('Invalid URL format');
 
-// Date validation
+/**
+ * Schema for validating date strings in YYYY-MM-DD format
+ * @description Validates that the input matches the YYYY-MM-DD date format
+ * @example
+ * ```typescript
+ * const validDate = dateSchema.parse("2024-01-15");
+ * // Returns: "2024-01-15"
+ * ```
+ */
 export const dateSchema = z
 	.string()
 	.regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in YYYY-MM-DD format');
 
-// Timestamp validation (YYYYMMDDHHmmss)
+/**
+ * Schema for validating timestamp strings in YYYYMMDDHHmmss format
+ * @description Validates 14-digit timestamp strings commonly used by web archives
+ * @example
+ * ```typescript
+ * const validTimestamp = timestampSchema.parse("20240115143022");
+ * // Returns: "20240115143022" (2024-01-15 14:30:22)
+ * ```
+ */
 export const timestampSchema = z
 	.string()
 	.regex(/^\d{14}$/, 'Timestamp must be in YYYYMMDDHHmmss format');
 
 /**
  * Validate and parse input with helpful error messages
+ * @param schema - Zod schema to validate against
+ * @param input - Unknown input to validate
+ * @returns Validated and typed input
+ * @throws {Error} If validation fails, with formatted error messages
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({ name: z.string() });
+ * const validated = validateInput(schema, { name: "test" });
+ * // Returns: { name: "test" } with TypeScript type inference
+ * ```
  */
 export function validateInput<T>(schema: z.ZodSchema<T>, input: unknown): T {
 	try {