time-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Time MCP Server is a Model Context Protocol (MCP) server implementation that provides time awareness capabilities to LLMs. It exposes 6 time-related tools through the MCP protocol: current_time, relative_time, get_timestamp, days_in_month, convert_time, and get_week_year.

Development Commands

# Development (run server locally)
npm run dev

# Build (creates dist/ with both CJS and ESM formats)
npm run build

# Lint
npm run lint
npm run lint:fix

Architecture

Core Structure

The codebase consists of two main files:

• src/tools.ts: Tool definitions exported as cohesive objects. Each tool object contains:
  • name: Tool identifier
  • description: Tool description
  • schema: Zod schema for input validation
• src/index.ts: MCP server implementation that:
  1. Initializes the McpServer with stdio transport
  2. Registers tools using server.registerTool() with Zod schemas
  3. Implements business logic for each tool using dayjs
  4. Uses Zod for automatic runtime validation (no manual type guards needed)

MCP Server Pattern

The server uses the modern MCP SDK pattern (v1.25+):

1. Create a McpServer instance from @modelcontextprotocol/sdk/server/mcp.js
2. Register tools using server.registerTool(name, config, handler)
3. Connect to stdio transport for communication with MCP clients
4. Zod schemas provide automatic validation and type safety

Tool Implementation Pattern

Each tool follows this pattern:

1. Tool definition in tools.ts as a cohesive object with Zod schema:

   export const TOOL_NAME = {
     name: 'tool_name',
     description: 'Tool description',
     schema: z.object({ /* Zod schema */ }),
   } as const;
   

2. Business logic function in index.ts (e.g., getCurrentTime)

3. Tool registration using server.registerTool() with inline handler: