Skip to content

Commit fe89998

Browse files
PederHPclaude
andcommitted
Address review feedback from the author of modelcontextprotocol#1856
Make CacheScopeConverter public in Core instead of compiling its source into the Skills package, which was the only package doing so. Adding a public type passes package validation against the 2.0.0 baseline. Validate only what the Agent Skills specification states as requirements beyond name and description: compatibility is 1 to 500 characters if provided, and metadata is a mapping. license, allowed-tools, and the values inside metadata pass through verbatim. Hosts compare frontmatter against the file and ignore allowed-tools for MCP-origin skills, so rejecting a whole skill over the shape of such a field would help nobody. Repeat the authorization caveat on WithSkills(IEnumerable<McpServerSkill>) and WithSkillsFromDirectory, whose in-memory catalog serves every caller, and explain why a directory without SKILL.md is skipped while an invalid skill is an error. Guard the public verifier and client read path against a Skill whose required Resources property was assigned null, and document SkillVerificationException on the remaining GetSkillAsync overload. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01P6omaTvQiryHtzFHRqUE3b
1 parent 82f0943 commit fe89998

9 files changed

Lines changed: 94 additions & 41 deletions

File tree

‎docs/concepts/skills/skills.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -76,8 +76,10 @@ builder.Services.AddMcpServer().WithHttpTransport().WithSkills([gitWorkflow, ref
7676

7777
All of these validate the skill against the specification and throw <xref:System.ArgumentException> with a
7878
specific message when, for example, the frontmatter `name` does not match the URI, `description` exceeds the
79-
Agent Skills limit of 1024 characters, `metadata` is not a map of strings, a resource URI escapes the skill's
80-
directory, `SKILL.md` is missing, or the skill exceeds the per-skill limits of 512 files or 16 MiB. File contents are copied when the skill is created, so
79+
Agent Skills limit of 1024 characters, a resource URI escapes the skill's directory, `SKILL.md` is missing, or
80+
the skill exceeds the per-skill limits of 512 files or 16 MiB. Frontmatter fields beyond `name`, `description`,
81+
`compatibility`, and the shape of `metadata` pass through verbatim, as the specification requires; hosts compare
82+
them against the file and ignore fields such as `allowed-tools` for MCP-origin skills. File contents are copied when the skill is created, so
8183
later changes to a caller's buffer or to files on disk do not affect what is served. `CreateFromDirectory` does not
8284
follow symbolic links, since a link can point outside the skill directory; it throws if it encounters one. File
8385
names containing characters with URI syntax (such as `{`, `?`, or a space) are percent-encoded in the resource URIs.

‎src/ModelContextProtocol.Core/Protocol/CacheScopeConverter.cs‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,14 @@ namespace ModelContextProtocol.Protocol;
1616
/// <see cref="CacheScope.Public"/>.
1717
/// </para>
1818
/// <para>
19-
/// This converter is applied per-property on the cacheable result types. The <see cref="CacheScope"/>
20-
/// enum itself retains a standard string converter for any standalone serialization.
19+
/// This converter is applied per-property on the cacheable result types, and is public so that extension
20+
/// packages defining their own <see cref="ICacheableResult"/> types can apply the same read-side leniency. The
21+
/// <see cref="CacheScope"/> enum itself retains a standard string converter for any standalone serialization.
2122
/// </para>
2223
/// </remarks>
23-
internal sealed class CacheScopeConverter : JsonConverter<CacheScope?>
24+
public sealed class CacheScopeConverter : JsonConverter<CacheScope?>
2425
{
26+
/// <inheritdoc />
2527
public override CacheScope? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
2628
{
2729
if (reader.TokenType is JsonTokenType.String)
@@ -52,6 +54,7 @@ internal sealed class CacheScopeConverter : JsonConverter<CacheScope?>
5254
return null;
5355
}
5456

57+
/// <inheritdoc />
5558
public override void Write(Utf8JsonWriter writer, CacheScope? value, JsonSerializerOptions options)
5659
{
5760
if (value is null)

‎src/ModelContextProtocol.Extensions.Skills/Client/McpSkillsClientExtensions.cs‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -154,9 +154,12 @@ public static async ValueTask<Skill> GetSkillAsync(this McpClient client, string
154154
/// <param name="client">The client.</param>
155155
/// <param name="requestParams">The request parameters.</param>
156156
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
157-
/// <returns>The result, as returned by the server.</returns>
157+
/// <returns>The result, as returned by the server, with the entry validated against the specification.</returns>
158158
/// <exception cref="ArgumentNullException"><paramref name="client"/> or <paramref name="requestParams"/> is <see langword="null"/>.</exception>
159159
/// <exception cref="InvalidOperationException">The server did not declare the MCP Skills extension.</exception>
160+
/// <exception cref="SkillVerificationException">
161+
/// The server returned an entry that violates the specification, or an entry for a different URI than the one requested.
162+
/// </exception>
160163
/// <exception cref="McpException">The request failed or the server returned an error response.</exception>
161164
public static async ValueTask<GetSkillResult> GetSkillAsync(
162165
this McpClient client,
@@ -233,13 +236,14 @@ public static async ValueTask<ReadResourceResult> ReadSkillResourceAsync(
233236
if (uri is null) throw new ArgumentNullException(nameof(uri));
234237
#endif
235238

236-
if (skill.Resources.IsDynamic)
239+
if (skill.Resources is { IsDynamic: true })
237240
{
238241
throw new InvalidOperationException(
239242
$"Skill '{skill.Uri}' declares dynamic resources, which carry no digests and cannot be verified. " +
240243
$"Use {nameof(McpClient.ReadResourceAsync)} directly if unverifiable content is acceptable.");
241244
}
242245

246+
SkillVerifier.ThrowIfDynamic(skill);
243247
if (SkillVerifier.FindResource(skill, uri) is null)
244248
{
245249
throw new SkillVerificationException(

‎src/ModelContextProtocol.Extensions.Skills/Client/SkillVerifier.cs‎

Lines changed: 22 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -155,11 +155,7 @@ public static void Verify(Skill skill, ReadResourceResult result)
155155
if (result is null) throw new ArgumentNullException(nameof(result));
156156
#endif
157157

158-
if (skill.Resources.IsDynamic)
159-
{
160-
throw new InvalidOperationException(
161-
$"Skill '{skill.Uri}' declares dynamic resources, which carry no digests and cannot be verified.");
162-
}
158+
ThrowIfDynamic(skill);
163159

164160
if (result.Contents is not { Count: > 0 })
165161
{
@@ -207,7 +203,8 @@ public static void Verify(Skill skill, string uri, ReadResourceResult result)
207203
if (result is null) throw new ArgumentNullException(nameof(result));
208204
#endif
209205

210-
if (!skill.Resources.IsDynamic && FindResource(skill, uri) is null)
206+
ThrowIfDynamic(skill);
207+
if (FindResource(skill, uri) is null)
211208
{
212209
throw new SkillVerificationException(
213210
$"'{uri}' is not listed in the manifest of skill '{skill.Uri}'. An unlisted file is a change to the skill; " +
@@ -229,9 +226,27 @@ public static void Verify(Skill skill, string uri, ReadResourceResult result)
229226
}
230227
}
231228

229+
/// <summary>
230+
/// Rejects a skill whose manifest is missing (the property is <c>required</c> but can still be assigned
231+
/// <see langword="null"/>) or dynamic, neither of which can be verified.
232+
/// </summary>
233+
internal static void ThrowIfDynamic(Skill skill)
234+
{
235+
if (skill.Resources is null)
236+
{
237+
throw new ArgumentException($"Skill '{skill.Uri}' has no resources manifest.", nameof(skill));
238+
}
239+
240+
if (skill.Resources.IsDynamic)
241+
{
242+
throw new InvalidOperationException(
243+
$"Skill '{skill.Uri}' declares dynamic resources, which carry no digests and cannot be verified.");
244+
}
245+
}
246+
232247
internal static SkillResource? FindResource(Skill skill, string uri)
233248
{
234-
var resources = skill.Resources.Resources;
249+
var resources = skill.Resources?.Resources;
235250
if (resources is null)
236251
{
237252
return null;

‎src/ModelContextProtocol.Extensions.Skills/ModelContextProtocol.Extensions.Skills.csproj‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -29,12 +29,6 @@
2929
<ItemGroup>
3030
<Compile Include="..\Common\Experimentals.cs" Link="Experimentals.cs" />
3131
<Compile Include="..\Common\McpProtocolVersions.cs" Link="McpProtocolVersions.cs" />
32-
<!--
33-
Core's CacheScopeConverter tolerates unknown cacheScope values on read so a single unexpected hint
34-
cannot break deserialization of a whole listing. It is internal to Core, so it is compiled into this
35-
assembly as well to give ListSkillsResult the same read-side leniency as the built-in list results.
36-
-->
37-
<Compile Include="..\ModelContextProtocol.Core\Protocol\CacheScopeConverter.cs" Link="Protocol\CacheScopeConverter.cs" />
3832
</ItemGroup>
3933

4034
<!-- Exclude polyfills inherited from Directory.Build.props; this package only needs a handful of them. -->

‎src/ModelContextProtocol.Extensions.Skills/Server/McpSkillsBuilderExtensions.cs‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,13 @@ public static class McpSkillsBuilderExtensions
3434
/// Nested skills may legitimately list the same file. A file URI shared by several skills is registered once,
3535
/// provided every skill lists it with the same digest.
3636
/// </para>
37+
/// <para>
38+
/// Every caller sees every skill. <c>skills/list</c> and <c>skills/get</c> are raw request handlers and do not
39+
/// pass through the request filters that guard the built-in resource methods, such as the ASP.NET Core
40+
/// authorization filters. When some callers must not see some skills, implement <see cref="IMcpSkillCatalog"/>
41+
/// and use <see cref="WithSkills(IMcpServerBuilder, IMcpSkillCatalog, Action{McpSkillsOptions})"/>, and guard
42+
/// the corresponding file resources separately.
43+
/// </para>
3744
/// </remarks>
3845
public static IMcpServerBuilder WithSkills(
3946
this IMcpServerBuilder builder,
@@ -113,9 +120,24 @@ public static IMcpServerBuilder WithSkills(
113120
/// <see cref="McpServerSkill.CreateFromDirectory(string)"/>), or two skills declare the same name.
114121
/// </exception>
115122
/// <remarks>
123+
/// <para>
116124
/// Each skill is built with <see cref="McpServerSkill.CreateFromDirectory(string)"/>: files are read once,
117125
/// digests are computed from the bytes served, and symbolic links are rejected. Only immediate subdirectories
118126
/// are considered skills; a <c>SKILL.md</c> nested deeper inside a skill is one of that skill's files.
127+
/// </para>
128+
/// <para>
129+
/// A subdirectory without a <c>SKILL.md</c> is not a skill and is ignored, so shared assets or documentation can
130+
/// live alongside skills. A subdirectory with a <c>SKILL.md</c> is a skill, and a skill that fails validation is
131+
/// an error rather than a skipped entry, so that a broken skill is noticed at startup instead of being silently
132+
/// absent from the catalog.
133+
/// </para>
134+
/// <para>
135+
/// Every caller sees every skill. <c>skills/list</c> and <c>skills/get</c> are raw request handlers and do not
136+
/// pass through the request filters that guard the built-in resource methods, such as the ASP.NET Core
137+
/// authorization filters. When some callers must not see some skills, implement <see cref="IMcpSkillCatalog"/>
138+
/// and use <see cref="WithSkills(IMcpServerBuilder, IMcpSkillCatalog, Action{McpSkillsOptions})"/>, and guard
139+
/// the corresponding file resources separately.
140+
/// </para>
119141
/// </remarks>
120142
public static IMcpServerBuilder WithSkillsFromDirectory(
121143
this IMcpServerBuilder builder,

‎src/ModelContextProtocol.Extensions.Skills/SkillValidation.cs‎

Lines changed: 9 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -207,26 +207,18 @@ public static void Validate(Skill skill, string paramName)
207207
paramName);
208208
}
209209

210-
ValidateOptionalString(skill, "license", maxLength: null, paramName);
210+
// Beyond name and description, only the constraints the Agent Skills specification states as requirements
211+
// are enforced: compatibility is 1 to 500 characters if provided, and metadata is a mapping. Other fields,
212+
// and the values inside metadata, pass through verbatim. Hosts compare frontmatter field by field against
213+
// the file and ignore fields such as allowed-tools for MCP-origin skills, so rejecting a whole skill over
214+
// the shape of a field no host acts on would help nobody.
211215
ValidateOptionalString(skill, "compatibility", MaxCompatibilityLength, paramName);
212-
ValidateOptionalString(skill, "allowed-tools", maxLength: null, paramName);
213216

214-
if (skill.Frontmatter.TryGetPropertyValue("metadata", out var metadataNode))
217+
if (skill.Frontmatter.TryGetPropertyValue("metadata", out var metadataNode) && metadataNode is not JsonObject)
215218
{
216-
if (metadataNode is not JsonObject metadata)
217-
{
218-
throw new ArgumentException($"Skill '{skill.Uri}' has a 'metadata' frontmatter field that is not a mapping; the Agent Skills specification requires a map from string keys to string values.", paramName);
219-
}
220-
221-
foreach (var entry in metadata)
222-
{
223-
if (entry.Value is not JsonValue value || !value.TryGetValue(out string? _))
224-
{
225-
throw new ArgumentException(
226-
$"Skill '{skill.Uri}' has a 'metadata.{entry.Key}' frontmatter value that is not a string; the Agent Skills specification requires string values. Quote it in SKILL.md if it is meant literally.",
227-
paramName);
228-
}
229-
}
219+
throw new ArgumentException(
220+
$"Skill '{skill.Uri}' has a 'metadata' frontmatter field that is not a mapping. Give it key-value entries, or remove the key if it is not needed.",
221+
paramName);
230222
}
231223

232224
if (skill.Resources is null)

‎tests/ModelContextProtocol.Tests/Client/SkillVerifierTests.cs‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,18 @@ public void Verify_Skill_RejectsEmptyResult()
123123
Assert.Throws<SkillVerificationException>(() => SkillVerifier.Verify(skill, new ReadResourceResult()));
124124
}
125125

126+
[Fact]
127+
public void Verify_Skill_RejectsMissingManifestWithoutCrashing()
128+
{
129+
var skill = CreateSkill(Encoding.UTF8.GetBytes("x"));
130+
skill.Resources = null!;
131+
132+
Assert.Throws<ArgumentException>(() => SkillVerifier.Verify(skill,
133+
new ReadResourceResult { Contents = [new TextResourceContents { Uri = Uri, Text = "x" }] }));
134+
Assert.Throws<ArgumentException>(() => SkillVerifier.Verify(skill, Uri,
135+
new ReadResourceResult { Contents = [new TextResourceContents { Uri = Uri, Text = "x" }] }));
136+
}
137+
126138
[Fact]
127139
public void Verify_Skill_ThrowsForDynamicSkill()
128140
{

‎tests/ModelContextProtocol.Tests/Server/InMemoryMcpSkillCatalogTests.cs‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -187,6 +187,19 @@ public void Constructor_AcceptsFullAgentSkillsFrontmatter()
187187
Assert.Equal(1, new InMemoryMcpSkillCatalog([skill]).Count);
188188
}
189189

190+
[Fact]
191+
public void Constructor_PassesThroughFieldsHostsDoNotActOn()
192+
{
193+
// allowed-tools is experimental and hosts ignore it for MCP-origin skills; license is free-form; metadata
194+
// values are whatever the author wrote. None of these should cost a skill its listing.
195+
var skill = CreateSkill("alpha");
196+
skill.Frontmatter["allowed-tools"] = new JsonArray("Read", "Write");
197+
skill.Frontmatter["license"] = null;
198+
skill.Frontmatter["metadata"] = new JsonObject { ["version"] = 2.1, ["tags"] = new JsonArray("a") };
199+
200+
Assert.Equal(1, new InMemoryMcpSkillCatalog([skill]).Count);
201+
}
202+
190203
[Fact]
191204
public void Constructor_AcceptsEmptyAuthority()
192205
{
@@ -234,7 +247,6 @@ static object[] Case(string reason, Action<Skill> mutate)
234247
});
235248
yield return Case("metadata present but null", s => s.Frontmatter["metadata"] = null);
236249
yield return Case("compatibility present but null", s => s.Frontmatter["compatibility"] = null);
237-
yield return Case("license present but null", s => s.Frontmatter["license"] = null);
238250
yield return Case("relative uri", s =>
239251
{
240252
s.Uri = "alpha/SKILL.md";
@@ -268,10 +280,7 @@ static object[] Case(string reason, Action<Skill> mutate)
268280
yield return Case("description over 1024 characters", s => s.Frontmatter["description"] = new string('d', 1025));
269281
yield return Case("compatibility over 500 characters", s => s.Frontmatter["compatibility"] = new string('c', 501));
270282
yield return Case("compatibility empty", s => s.Frontmatter["compatibility"] = "");
271-
yield return Case("license not a string", s => s.Frontmatter["license"] = 1);
272-
yield return Case("allowed-tools not a string", s => s.Frontmatter["allowed-tools"] = new JsonArray("Bash"));
273283
yield return Case("metadata not a mapping", s => s.Frontmatter["metadata"] = "x");
274-
yield return Case("metadata value not a string", s => s.Frontmatter["metadata"] = new JsonObject { ["version"] = 2.1 });
275284
yield return Case("name missing", s => s.Frontmatter.Remove("name"));
276285
yield return Case("name not a string", s => s.Frontmatter["name"] = 1);
277286
yield return Case("name does not match uri segment", s => s.Frontmatter["name"] = "beta");

0 commit comments

Comments
 (0)