docs: refresh contributor docs, add review rules, and require Node 22

.github/ISSUE_TEMPLATE/bug_report.md

@@ -30,7 +30,7 @@ What actually happened.
 
 ## Environment
 
-- **TimeTree MCP Version**: [e.g., 0.1.0]
+- **TimeTree MCP Version**: [e.g., 0.3.0]
 - **Node.js Version**: [run `node --version`]
 - **Operating System**: [e.g., macOS 14.0, Ubuntu 22.04, Windows 11]
 - **Claude Client**: [e.g., Claude Desktop, Claude Code]

.github/PULL_REQUEST_TEMPLATE.md

@@ -31,7 +31,8 @@ Describe how you tested these changes:
 - [ ] Tested with MCP Inspector
 - [ ] Tested with Claude Desktop
 - [ ] Tested with Claude Code
-- [ ] Tested with actual TimeTree account
+- [ ] Tested with actual TimeTree account (dedicated test calendar; no real data committed)
+- [ ] `npm run verify` passes
 - [ ] Added/updated tests (if applicable)
 
 ### Test Environment
@@ -46,8 +47,8 @@ Add screenshots to help explain your changes.
 
 ## Documentation
 
-- [ ] Updated README.md (if needed)
-- [ ] Updated README.ko.md (if needed)
+- [ ] Updated README.md, README.ko.md, and README.ja.md together (if needed)
+- [ ] Updated COMMANDS.md for tool parameter changes (if needed)
 - [ ] Updated CHANGELOG.md under `[Unreleased]`
 - [ ] Added/updated code comments
 - [ ] Updated type definitions
@@ -61,6 +62,7 @@ Add screenshots to help explain your changes.
 - [ ] I have tested that my changes work correctly
 - [ ] No sensitive data (credentials, session IDs) is exposed
 - [ ] Rate limiting is respected (no API abuse)
+- [ ] "Allow edits by maintainers" is checked (for PRs from forks)
 
 ## Breaking Changes
 

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
       # Report every Node version instead of cancelling siblings on the first failure.
       fail-fast: false
       matrix:
-        node-version: [18, 20, 22]
+        node-version: [22, 24]
 
     steps:
       - uses: actions/checkout@v7

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `start_before`, `query`, `label_id`, and `include_memos` filters to `get_events`.
 
 ### Changed
+- Node.js 22 or later is now required. Node.js 18 and 20 are past end-of-life; CI tests Node.js 22 and 24.
 - `get_events` now returns events sorted by start time, so `limit` keeps the earliest matches.
 - Every tool now accepts `calendar_id` as a string or a number, matching the string IDs returned by `list_calendars`.
 

CLAUDE.md

@@ -66,6 +66,8 @@ npm install
 npm run typecheck
 npm test
 npm run build
+# or run all CI checks at once:
+npm run verify
 ```
 
 For manual MCP inspection:
@@ -119,3 +121,17 @@ This is primarily a project guide, not a full contribution handbook. For contrib
 - Do not add dependencies unless the benefit is clear and documented.
 - Make privacy-preserving behavior the default.
 - When uncertain about upstream behavior, document the observation method without storing sensitive captures.
+
+## Code Review Rules
+
+Automated and human reviewers should flag these repository-specific issues. Leave formatting and lint-style nits to CI.
+
+- Any write to stdout in `src/` (`console.log`, `process.stdout.write`). MCP uses stdout for JSON-RPC; logs must go through `src/utils/logger.ts`.
+- Credentials, cookies, CSRF tokens, session IDs, or raw upstream response bodies reaching logs or tool responses without the shared logger's masking.
+- Tool responses that forward raw upstream payloads instead of shaped, documented fields.
+- TimeTree requests that bypass `rateLimiter.executeWithRetry`.
+- Treating the `since` sync cursor as a date filter.
+- User-visible tool changes without matching updates to `README.md`, `README.ko.md`, `README.ja.md`, `COMMANDS.md`, and `CHANGELOG.md` under `[Unreleased]`.
+- Real account data in tests, fixtures, or docs: emails, calendar names, event content, or request captures.
+- Removing `"private": true` from `package.json`, or `package.json` and `package-lock.json` versions drifting apart.
+- New runtime dependencies without a stated reason.

CONTRIBUTING.md

@@ -46,10 +46,9 @@ Feature suggestions are welcome, but keep in mind:
    - Follow the existing code style
    - Add/update tests if applicable
    - Update documentation
-4. **Test your changes**:
+4. **Test your changes** (the same checks CI runs):
    ```bash
-   npm run build
-   npm run dev  # for watch mode
+   npm run verify  # typecheck, tests, and audit
    ```
 5. **Commit** with a clear message:
    ```bash
@@ -59,13 +58,13 @@ Feature suggestions are welcome, but keep in mind:
    ```bash
    git push origin feature/your-feature-name
    ```
-7. **Open a Pull Request** against `main`
+7. **Open a Pull Request** against `main`, and keep **Allow edits by maintainers** checked so maintainers can push small fixes such as docs or merge updates to your branch
 
 ## Development Setup
 
 ### Prerequisites
 
-- Node.js >= 18.0.0
+- Node.js >= 22
 - npm or yarn
 - A TimeTree account (for testing)
 
@@ -100,10 +99,15 @@ TimeTree-MCP/
 │   │   ├── auth.ts               # Authentication + CSRF token manager
 │   │   └── api.ts                # TimeTree API client (read + CRUD)
 │   ├── tools/
-│   │   ├── index.ts              # Tool registration
-│   │   ├── calendar-tools.ts     # list_calendars
-│   │   ├── event-tools.ts        # get_events, get_updated_events
-│   │   └── event-crud-tools.ts   # create_event, update_event, delete_event
+│   │   ├── index.ts                   # Tool registration
+│   │   ├── shared-schemas.ts          # Shared input schemas (calendar_id)
+│   │   ├── calendar-tools.ts          # list_calendars
+│   │   ├── calendar-metadata-tools.ts # labels, members, virtual members
+│   │   ├── event-tools.ts             # get_events, get_updated_events
+│   │   ├── event-crud-tools.ts        # create_event, update_event, delete_event
+│   │   ├── memo-tools.ts              # list/create/update/delete memos
+│   │   ├── comment-tools.ts           # event comments
+│   │   └── holiday-tools.ts           # get_holidays
 │   └── types/
 │       ├── timetree.ts           # TypeScript/Zod schemas
 │       └── label-colors.ts       # Event color mapping (label_id 1-10)
@@ -112,19 +116,29 @@ TimeTree-MCP/
 
 ### Testing
 
-Currently, testing is manual via MCP Inspector:
+Automated tests use mocked HTTP clients and never call TimeTree:
 
 ```bash
-npx @modelcontextprotocol/inspector dist/index.js
+npm test         # build + node:test suites in tests/
+npm run verify   # typecheck + tests + npm audit, as CI runs them
 ```
 
-Set environment variables:
+Add regression tests in `tests/` for parsing, request shape, and tool output changes.
+
+For manual checks against a real account, use MCP Inspector:
+
+```bash
+npm run build
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+Set environment variables in your shell only:
 ```
 TIMETREE_EMAIL=your-email@example.com
 TIMETREE_PASSWORD=your-password
 ```
 
-**Future**: We plan to add automated tests with mocked APIs.
+Use a dedicated test calendar, and never commit real responses, calendar content, or credentials.
 
 ## Code Style
 
@@ -170,7 +184,7 @@ If TimeTree changes their API:
 ## Documentation
 
 When adding features:
-- Update README.md and README.ko.md (both English and Korean)
+- Update README.md, README.ko.md, and README.ja.md together, plus COMMANDS.md for tool parameters
 - Add JSDoc comments to public functions
 - Update CHANGELOG.md under `[Unreleased]`
 

README.ja.md

@@ -29,7 +29,7 @@ Claude、Codex、Cursor、Windsurf などの MCP クライアントから、Time
 
 ### 必要条件
 
-- Node.js >= 18.0.0
+- Node.js >= 22
 - Git（インストール用）
 - TimeTree アカウント
 - MCP 対応クライアント（Claude Desktop、Claude Code、Codex、Antigravity、Cline など）

README.ko.md

@@ -29,7 +29,7 @@ Claude, Codex, Cursor, Windsurf 같은 MCP 클라이언트에서 TimeTree 캘린
 
 ### 요구사항
 
-- Node.js >= 18.0.0
+- Node.js >= 22
 - Git (설치용)
 - TimeTree 계정
 - MCP 호환 클라이언트 (Claude Desktop, Claude Code, Codex, Antigravity, Cline 등)

README.md

@@ -29,7 +29,7 @@ Use Claude, Codex, Cursor, Windsurf, and other MCP clients to read and manage yo
 
 ### Requirements
 
-- Node.js >= 18.0.0
+- Node.js >= 22
 - Git (for installation)
 - A TimeTree account
 - An MCP-compatible client (Claude Desktop, Claude Code, Codex, Antigravity, Cline, etc.)

TimeTree-MCP-install.sh

@@ -13,13 +13,13 @@ fi
 
 if ! command -v node &> /dev/null; then
   echo "❌ ERROR: Node.js is not installed."
-  echo "   Please install Node.js 18 or later: https://nodejs.org"
+  echo "   Please install Node.js 22 or later: https://nodejs.org"
   exit 1
 fi
 
 NODE_MAJOR=$(node -v | sed 's/v//' | cut -d. -f1)
-if [ "$NODE_MAJOR" -lt 18 ]; then
-  echo "❌ ERROR: Node.js 18+ is required (found $(node -v))"
+if [ "$NODE_MAJOR" -lt 22 ]; then
+  echo "❌ ERROR: Node.js 22+ is required (found $(node -v))"
   echo "   Please upgrade: https://nodejs.org"
   exit 1
 fi

package.json

@@ -35,6 +35,6 @@
     "typescript": "^5.7.2"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22"
   }
 }