Skill freshness, self-introspection, and skill-in-instructions#28
Merged
Merged
Conversation
Addresses four pieces of Claude Desktop feedback:
* Skill freshness detection: capture a fingerprint (SHA-256 over sorted
tool+prompt names) and the downstream RemoteVersion when update_skill
is called, then compare against the live surface area on every
list_services / get_service_details to emit
skillFreshness=fresh|stale|unknown plus skillRecordedVersion and
skillRecordedAt. Skill docs are operator-authored, so the aggregator
detects rather than auto-rewrites drift.
* Aggregator self-introspection: populate remoteName / remoteTitle /
remoteVersion on the aggregator's own row in list_services from the
configured McpServerOptions.ServerInfo, instead of leaving them null.
* Skill in initialize handshake: read data/skills/{SelfName}.md at
server startup and append it (capped at 16KB) to
McpServerOptions.ServerInstructions, so MCP clients get aggregator
orientation during the initialize handshake without needing to know
to call get_service_skill.
* refresh_service semantics: tighten the tool description to spell out
that it clears the cached connection, ServerInfo, tools, and prompts,
and that it does NOT modify the skill document (admin-authored via
update_skill).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Addresses four pieces of feedback from a Claude Desktop session about the aggregator's metadata surface area:
update_skillnow snapshots a SHA-256 fingerprint over the downstream's sorted tool + prompt names, plus itsRemoteVersion, at the moment the skill is authored.list_servicesandget_service_detailsrecompute the fingerprint against the live downstream and emitskillFreshness(fresh|stale|unknown),skillRecordedVersion, andskillRecordedAt. Drift is detected rather than auto-rewritten, since skill docs are operator-authored.list_servicesnow populatesremoteName/remoteTitle/remoteVersionfrom the configuredMcpServerOptions.ServerInfoinstead of leaving them null — so clients can identify what version of the aggregator they're talking to.data/skills/{SelfName}.mdis read at server start and appended toMcpServerOptions.ServerInstructions(capped at 16 KB). MCP clients now receive aggregator orientation during the initialize handshake without having to know to callget_service_skill. Skill changes require a server restart to re-embed.refresh_servicesemantics. Description now spells out exactly what is invalidated (connection,ServerInfo, tool list, prompt list) and what is not (the skill document — that is admin-authored viaupdate_skill).New / changed types
RegisteredServer.SkillRecordedVersion/SkillRecordedFingerprint/SkillRecordedAtServiceIndex+ServiceDetails:SkillFreshness,SkillRecordedVersion,SkillRecordedAtServerRegistry.UpdateSkillSnapshotAsync(...)SkillFingerprint.Compute(tools, prompts)utility (Core/Services)SkillSnapshot.CaptureAsync(...)helper shared byAdminTools.UpdateSkillandAdminController.UpdateSkillTest plan
dotnet build— cleandotnet test— 89 passed, 0 failed (13 new tests covering fingerprint determinism / order-independence / drift, and registry snapshot persistence)update_skill, observeskillFreshness: freshinlist_services; then add a tool to the downstream and observeskillFreshness: stalelist_servicesnow reportsremoteName/remoteVersioninstructionsincludes both the discovery flow and the aggregator skill doc