feat: add optional lastModified timestamp to Annotated #140

salman1993 · 2025-01-13T17:20:55Z

Adds an optional timestamp field to Annotated interface.

Motivation and Context

It's useful to know when a Resource is created or updated for context truncation.

How Has This Been Tested?

Breaking Changes

None

Types of changes

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 change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

jspahrsummers

Thanks for the suggestion!

Can you share a bit more about how you might use this to truncate context, just so I have a greater understanding of the use case? I think it probably makes sense, but would love more detail.

Also left a couple of minor comments for discussion. 🙏

jspahrsummers · 2025-01-13T17:36:45Z

schema/schema.ts

@@ -832,6 +832,13 @@ export interface Annotated {
     * @maximum 1
     */
    priority?: number;
+
+    /**
+     * The timestamp indicating when this annotation was created or last updated.


Should this be about the annotation (only) or about the thing that the annotation is attached to? I lean toward the latter—maybe we could update the phrasing to reflect this?

jspahrsummers · 2025-01-13T17:37:29Z

schema/schema.ts

+     * 
+     * Should be an ISO 8601 formatted string (e.g., "2025-01-12T15:00:58Z").
+     */
+    timestamp?: string;


We may want to have other timestamps in future, so perhaps a more specific name like:

Suggested change

timestamp?: string;

lastModified?: string;

* upstream/main: docs: update README links chore: add markdown format check workflow and format all docs chore: add prettier and format command for markdown files Move schema files to versioned directory Fix broken links. 2024-11-05 schema.ts/schema.json points to main/schema/2024-11-05/schema.ts in anticipation of PR modelcontextprotocol#145 being merged. update generate json after merge update protocol revision to draft on sampling page updated schema protocol version to reflect draft. change to relative link in spec point documentation changes to "draft" Revert schema/schema.ts to upstream/main, add drafts folder. Update validate and build scripts to build drafts too. fix: update draft page reference and add alias for better navigation fix: incorrect link for "Specification (Draft)" on nav bar Update schema/schema.ts remove spurious semicolon validation, simplify wording. Add optional "size" attribute to Resource, include in Documentation Update docs/specification/client/sampling.md Updated Specification and Docs to support Audio Modality.

salman1993 · 2025-01-28T15:46:22Z

@jspahrsummers sorry for the delay on this one. I updated the name and added some examples to the docstring.

Generally, the idea here is that since resources are application controlled, it's useful to pass in the lastModified timestamp of the attached data especially for truncation when we exceed context limits (eg. evict files that have no recent activity)

jerome3o-anthropic

This seems reasonable to me, thanks for adding this

addressed

dsp-ant · 2025-02-13T09:21:09Z

schema/draft/schema.ts

+
+    /**
+     * The timestamp when the resource was last modified.
+     * Examples: last activity timestamp in an open file, timestamp when resource is attached, etc.
+     * 
+     * Should be an ISO 8601 formatted string (e.g., "2025-01-12T15:00:58Z").
+     */
+    lastModified?: string;


Can we annotate this with a date? https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.7.3.1

Co-authored-by: David Soria Parra <[email protected]>

dsp-ant · 2025-03-14T16:14:02Z

schema/draft/schema.ts

+     * 
+     * Should be an ISO 8601 formatted string (e.g., "2025-01-12T15:00:58Z").
+     */
+    lastModified?: Date;


I like the idea. While this is usually the most intuitive way to express a point in time. However, I assume a client application will want to use this for comparison of the resource has changed. Notable ISO 8601 are not guarantee to be monotonically increasing. The following issues can appear:

Leap Seconds

Clock Adjustment

Daylight Savings

Clock Drift or Time Sync issues between client and server (particularly in a remote scenario)

There are a few ways to go about this:

We can include more metadata (e,g, rsync uses size + mtime, git uses mtime + hashes) and use unix timestamps, to make educated guesses.

We can enforce a monotonically increasing time, e.g. the watchman uses a random "point in time" stamp, that will always increase. It doesn't have to represent time, but for example things like "since the system started'.

We can define lastModified to be purely informational and must not be used for comparision

Open to any suggestions. THrowing it back to you. If it's intended to be purely informational, I am happy to accept as is.

FWIW, unix timestamps + some additional information might be proibably the easiest.

However, I assume a client application will want to use this for comparison of the resource has changed.

Strictly speaking, we could add language cautioning about the nonmonotonic risk and leave it up to the client how they want to use it, rather than insisting that they not use it for comparison. (I think most rsync/watchman-like things actually let you decide what to do if you get a backwards-moving timestamp?)

Thinking about it for the first time, but: I think I'd opt for ^ plus more (optional) metadata: hash and size both seem useful in different situations. I don't know how much value we'd add by being opinionated here.

HTTP MCP servers will also have a Date header in their responses which clients could use to detect if their clock is ergegiously out of sync. Imo that's probably good enough for most use cases.

@connor4312 That's a transport layer information leaking into the data layer.

@connor4312 true, although in this case the client's clock shouldn't enter into the comparison I don't think

I assume that for now we can probably get away with lastModified and add documentation about dealing with non monotone behaviour on the client side if they choose to care.

dsp-ant

@salman1993 mind rebasing this

Add optional timestamp to Annotated

11f0d6c

jspahrsummers previously requested changes Jan 13, 2025

View reviewed changes

salman1993 added 2 commits January 28, 2025 10:35

fix: rename to lastModified, add example

ee4578a

salman1993 changed the title ~~feat: add optional timestamp to Annotated~~ feat: add optional lastModified timestamp to Annotated Jan 28, 2025

salman1993 requested a review from jspahrsummers January 28, 2025 15:46

salman1993 and others added 2 commits January 28, 2025 10:47

checkout upstream/main for schema/2024-11-05/

461630e

Merge branch 'main' into sm/annotated-timestamp

041666b

jerome3o-anthropic previously approved these changes Feb 13, 2025

View reviewed changes

dsp-ant previously approved these changes Feb 13, 2025

View reviewed changes

use Date instead of string

82ab529

salman1993 dismissed stale reviews from dsp-ant and jerome3o-anthropic via 82ab529 February 17, 2025 23:09

Merge branch 'main' into sm/annotated-timestamp

e0458d7

salman1993 requested review from jerome3o-anthropic and dsp-ant February 17, 2025 23:11

jspahrsummers pushed a commit that referenced this pull request Mar 12, 2025

Added Roo Code to the support matrix (#140)

e8a0471

Co-authored-by: David Soria Parra <[email protected]>

jspahrsummers added this to Standards Track Mar 14, 2025

jspahrsummers moved this to In Review in Standards Track Mar 14, 2025

dsp-ant requested changes Mar 14, 2025

View reviewed changes

dsp-ant added this to the DRAFT 2025-06-XX milestone Jun 5, 2025

dsp-ant previously approved these changes Jun 10, 2025

View reviewed changes

merge upstream/main, make lastModified a Unix epoch timestamp

b793f29

salman1993 dismissed dsp-ant’s stale review via b793f29 June 10, 2025 21:02

dsp-ant approved these changes Jun 10, 2025

View reviewed changes

dsp-ant merged commit 0c7ad86 into modelcontextprotocol:main Jun 10, 2025
1 check passed

github-project-automation bot moved this from In Review to Approved in Standards Track Jun 10, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add optional lastModified timestamp to Annotated #140

feat: add optional lastModified timestamp to Annotated #140

Uh oh!

salman1993 commented Jan 13, 2025 •

edited

Loading

Uh oh!

jspahrsummers left a comment

Uh oh!

jspahrsummers Jan 13, 2025

Uh oh!

jspahrsummers Jan 13, 2025

Uh oh!

salman1993 commented Jan 28, 2025

Uh oh!

jerome3o-anthropic left a comment •

edited

Loading

Uh oh!

dsp-ant Feb 13, 2025

Uh oh!

dsp-ant Mar 14, 2025

Uh oh!

dsp-ant Mar 14, 2025

Uh oh!

bhosmer-ant Jun 10, 2025

Uh oh!

connor4312 Jun 10, 2025

Uh oh!

dsp-ant Jun 10, 2025

Uh oh!

bhosmer-ant Jun 10, 2025

Uh oh!

dsp-ant Jun 10, 2025

Uh oh!

dsp-ant left a comment

Uh oh!

Uh oh!

Uh oh!

feat: add optional lastModified timestamp to Annotated #140

feat: add optional lastModified timestamp to Annotated #140

Uh oh!

Conversation

salman1993 commented Jan 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

jspahrsummers left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

salman1993 commented Jan 28, 2025

Uh oh!

jerome3o-anthropic left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dsp-ant left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

salman1993 commented Jan 13, 2025 •

edited

Loading

jerome3o-anthropic left a comment •

edited

Loading