diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 3cfebb7..410f934 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.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] diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index fcc216c..d44e6b2 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.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 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 901c723..ee2878b 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 129d324..3600e4d 100644 --- a/CHANGELOG.md +++ b/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`. diff --git a/CLAUDE.md b/CLAUDE.md index 0571299..8ace94e 100644 --- a/CLAUDE.md +++ b/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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a738f30..dcaeaa8 100644 --- a/CONTRIBUTING.md +++ b/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]` diff --git a/README.ja.md b/README.ja.md index 8402415..92a3b75 100644 --- a/README.ja.md +++ b/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 など) diff --git a/README.ko.md b/README.ko.md index e560412..0ef4f79 100644 --- a/README.ko.md +++ b/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 등) diff --git a/README.md b/README.md index 80c40e2..41f0b41 100644 --- a/README.md +++ b/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.) diff --git a/TimeTree-MCP-install.sh b/TimeTree-MCP-install.sh index d992f8a..e629386 100755 --- a/TimeTree-MCP-install.sh +++ b/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 diff --git a/package-lock.json b/package-lock.json index b6f1a20..f54a1b0 100644 --- a/package-lock.json +++ b/package-lock.json @@ -21,7 +21,7 @@ "typescript": "^5.7.2" }, "engines": { - "node": ">=18.0.0" + "node": ">=22" } }, "node_modules/@esbuild/aix-ppc64": { diff --git a/package.json b/package.json index 26613e5..c726d55 100644 --- a/package.json +++ b/package.json @@ -35,6 +35,6 @@ "typescript": "^5.7.2" }, "engines": { - "node": ">=18.0.0" + "node": ">=22" } }