[itTkm]

Pull Request

Description

Images attached to event comments are currently unavailable to MCP clients, and image-only comments appear empty.

This adds image metadata to comment results and a read-only tool to retrieve individual images as standard MCP image content over stdio. Images posted by free accounts are supported, without requiring shared filesystem access between the server and client.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Dependency update

Related Issue

None.

Changes Made

• Include image indices, filenames, and dimensions in comment results, including image-only comments.
• Add get_event_comment_image to return one selected image with structured metadata and an MCP image content block.
• Recognize JPEG, PNG, GIF, and WebP, with a 5 MiB download limit and a 30-second timeout.
• Resolve images through the event's current comments before downloading. Restrict downloads to TimeTree's attachment host, reject redirects, and omit session cookies and CSRF tokens.
• Update tool registration, output schemas, the extension manifest, and documentation. No dependencies added.

Testing

• Tested with MCP Inspector
• Tested with Claude Desktop
• Tested with Claude Code
• Tested with actual TimeTree account (synthetic test events in a personal calendar; no private calendar data committed)
• npm run verify passes
• Added/updated tests (if applicable)
• Tested with Codex
• npm run build:mcpb passes

All 120 automated tests pass on Node.js 22.23.3 and 24.13.0. The 14 new image tests cover image selection, access failures, MCP output shape, format detection, size limits, download timeouts, and safe error responses.

Both the normal build and the extension bundle were checked over stdio on both Node versions using mocked HTTP responses: initialization, tool listing, image transfer, and invalid input handling. Automated tests do not call TimeTree.

Live verification retrieved all 33 images described below through MCP and confirmed their case IDs and expected Japanese date/time and item text in Codex. Decoded byte counts, image formats, dimensions, and SHA-256 hashes were also checked.

Test Environment

• Node.js Version: 22.23.3 and 24.13.0 for automated and build checks
• Operating System: macOS 26.7.1
• TimeTree Account: Personal account with synthetic test events
• Upload Client: TimeTree iOS app; app and iOS versions were not recorded
• MCP Client for Live Verification: Codex

Screenshots (if applicable)

Not applicable. Downloaded images and local validation artifacts are not included in this PR.

Documentation

• 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

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings
• 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

None. Existing comment results gain an images array. No client configuration changes are required.

Additional Notes

Live observations from iOS uploads

Synthetic images were posted to three test events through the TimeTree iOS app, then retrieved through MCP.

Test	Images retrieved	Observed result
Format variants	12/12	All delivered as JPEG at 1200 × 800
File size variants	11/11	All delivered as JPEG at 1920 × 1536
One batch of 10 images	10/10	Returned as 10 comments with one image each; no missing or duplicate cases

• The original format samples covered JPEG (.jpg and .jpeg), PNG, GIF, WebP, HEIC, HEIF, AVIF, BMP, and TIFF, including transparent PNG and animated GIF.
• The transparent PNG was delivered with a white background. The animated GIF was delivered as a still image of its first frame.
• Size-test originals were 2560 × 2048. The largest original was 12,583,041 bytes (about 12 MiB); its delivered image was 1,466,209 bytes (about 1.40 MiB).
• All returned filenames were null, so the original filenames and extensions were not available through the comment metadata.
• All 10 batch-uploaded images matched their individually uploaded counterparts byte-for-byte by SHA-256.
• Case IDs and the expected Japanese date/time and item text were readable in all 33 images.

The MCP server does not convert or resize images. These transformations occurred before MCP retrieval. The tests did not isolate whether conversion happened in the iOS photo library, the app, or TimeTree's backend.

Scope and limits

• The 5 MiB limit is this MCP server's download policy, not a documented TimeTree upload limit or an MCP protocol limit.
• The largest delivered image in these tests was about 1.40 MiB. Uploading an original larger than 5 MiB does not demonstrate retrieval of a delivered image larger than 5 MiB.
• Live tests covered JPEG delivery through the iOS upload path. Other recognized formats and download size enforcement are covered by mocked tests.
• Web/Android upload paths, SVG uploads, and multiple images within a single comment were not tested live. These observations do not establish TimeTree's complete format support or maximum upload size.
• Clients must support MCP image tool results to inspect returned images.
• The MCP server holds images in memory without saving files or returning download URLs.
• Image uploads and Premium files attached directly to events are outside this PR's scope.

[itTkm]

@codex review

[Copilot]

🟢 Approval recommended

No blocking issues were identified in access checks, download safeguards, MCP integration, or regression coverage.

No open issues 🎉

What changed in this PR

Adds event-comment image reading to TimeTree MCP, allowing clients to receive images directly without shared filesystem access.

Changes:

• Adds comment image metadata and the read-only get_event_comment_image tool.
• Restricts downloads to TimeTree’s attachment host with size limits, timeouts, and no authentication material.
• Updates tests, extension registration, and multilingual documentation.

File	Description
tests/​tools.test.mjs	Checks new tool registration.
tests/​tool-metadata.test.mjs	Adds image-tool output validation.
tests/​comment-images.test.mjs	Covers retrieval, safeguards, and MCP results.
src/​utils/​comment-image.ts	Implements bounded image downloads and format detection.
src/​types/​timetree.ts	Defines comment image metadata.
src/​tools/​index.ts	Registers the tool and supports mixed content.
src/​tools/​comment-tools.ts	Exposes image metadata and retrieval.
src/​config/​config.ts	Defines the attachment host.
src/​client/​api.ts	Resolves images through current event comments.
README.md	Documents image support in English.
README.ko.md	Documents image support in Korean.
README.ja.md	Documents image support in Japanese.
mcpb/​manifest.json	Registers the extension’s image tool.
docs/​FEATURE_CANDIDATES.md	Distinguishes supported reading from future uploads.
COMMANDS.md	Documents parameters, results, and limits.
CHANGELOG.md	Records the new image capabilities.

_{Review effort: Balanced}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-21T15:45:50.989120Z	2c26310	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Delightful!

Reviewed commit: 2c26310e04

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".