CLAUDE.md•2.63 kB
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
**mcp-datetime** is a minimal TypeScript MCP (Model Context Protocol) server built with Bun that provides current local datetime information. This serves as a blueprint for simple, single-purpose MCP servers.
## Development Commands
### Core Commands
- `bun install` - Install dependencies
- `bun run src/index.ts` - Run the MCP server
- `bun test` - Run test suite (uses Bun's built-in test runner)
- `bun build src/index.ts --outdir=dist` - Build for production
### Development Workflow
- `bun --hot src/index.ts` - Run with hot reload during development
## Architecture
### Technology Stack
- **Runtime**: Bun (all-in-one JavaScript runtime)
- **Language**: TypeScript with ESNext features
- **Protocol**: Model Context Protocol (MCP)
- **Dependencies**: `@modelcontextprotocol/sdk`, `date-fns`, `date-fns-tz`
### File Structure
```
src/
├── index.ts # Main entry point (server startup)
├── server/
│ └── datetime-server.ts # MCP server configuration
├── tools/
│ ├── current-time.ts # Single MCP tool - current datetime
│ └── current-time.test.ts # Unit tests for current-time tool
├── types/
│ └── datetime.types.ts # Minimal type definitions
└── utils/
└── datetime-utils.ts # Empty file for future extension
```
### Key Components
- **MCP Server**: Uses `@modelcontextprotocol/sdk` for MCP protocol implementation
- **Single Tool**: `current-time` tool returns comprehensive datetime info (weekday, date, time, timezone)
- **Testing**: Bun's native test runner with mock capabilities
- **Timezone Support**: Uses `date-fns-tz` for timezone handling
### Configuration Details
- **TypeScript**: ESNext target, ESM modules, strict mode enabled
- **Entry Point**: `src/index.ts` (TypeScript file run directly with Bun)
- **Module System**: ES modules (`"type": "module"` in package.json)
## Extension Patterns
This blueprint is designed for easy extension:
1. **Add new tools**: Create `src/tools/new-tool.ts` and register in `datetime-server.ts`
2. **Add resources**: Create `src/resources/` directory and register in `datetime-server.ts`
3. **Input validation**: Use Zod schemas for tool input validation
4. **Testing**: Create `.test.ts` files alongside source files
## MCP Configuration
### Claude Desktop Setup
```json
{
"mcpServers": {
"datetime": {
"command": "bun",
"args": ["/absolute/path/to/mcp-datetime/src/index.ts"]
}
}
}
```