Skip to content

Commit ecb11e6

Browse files
PederHPclaude
andcommitted
Close the neighbouring cases a differential YAML run and a second review pass found
Frontmatter reader, checked against the yaml 2.8 reference parser: a trailing comment on a continuation line ends the plain scalar; plain scalars and keys cannot start with a flow indicator, a block scalar header, or a block indicator followed by white space, and keys are held to the same reserved-start rules as values; empty flow entries are rejected; -0 and -0.0 render as 0; block scalars keep white-space-only lines wider than their indentation and reject a wider leading empty line; tabs are accepted where YAML allows them (blank lines, after ':' and '-', inside block scalars) and rejected only as indentation; a sequence item with a quoted key is a compact mapping; and a flow collection that closes on a later line is valid-but-unsupported YAML rather than malformed, so the explicit frontmatter escape hatch covers it. McpServerSkill keeps a private copy of its entry and ProtocolSkill returns a copy, so the manifest WithSkills registers cannot drift from the served bytes through the caller's objects. Entry validation errors from the directory overloads name directoryPath rather than a frontmatter parameter those overloads do not have. The client rejects a skills/list page without a skills array instead of dereferencing null, and SkillVerifier treats null text contents as a verification failure. Replace a test that compared a value with itself, add tests for the cases above and for invalid and same-named skill directories, root the Skills assembly in the AOT compatibility app, fix the missing using in the docs snippet, and link the docs page to the samples on GitHub so the links work on the published site. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01P6omaTvQiryHtzFHRqUE3b
1 parent 4813b72 commit ecb11e6

12 files changed

Lines changed: 439 additions & 100 deletions

File tree

‎docs/concepts/skills/skills.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ lays them out, and point `WithSkillsFromDirectory` at the parent:
4141

4242
```csharp
4343
using ModelContextProtocol.Extensions.Skills;
44+
using ModelContextProtocol.Protocol;
4445

4546
builder.Services
4647
.AddMcpServer()
@@ -95,8 +96,8 @@ host verifies a skill by parsing the fetched `SKILL.md` itself and comparing fie
9596
entry; a value that one side types as a number and the other as a string is a verification failure. Quote values
9697
such as version numbers that are meant to be strings.
9798

98-
Anchors, aliases, tags, complex keys, nested flow collections, and multi-line quoted scalars are valid YAML the
99-
reader does not support; it rejects them with a <xref:System.FormatException> naming the construct. For such a
99+
Anchors, aliases, tags, complex keys, nested and multi-line flow collections, and multi-line quoted scalars are
100+
valid YAML the reader does not support; it rejects them with a <xref:System.FormatException> naming the construct. For such a
100101
file, the `Create` and `CreateFromDirectory` overloads that take an explicit `JsonObject` supply the frontmatter
101102
directly. That escape hatch covers only valid-but-unsupported YAML: a file with no frontmatter block, malformed
102103
YAML, or invalid UTF-8 is rejected regardless, since no host could parse it either. When the reader can parse the
@@ -217,7 +218,7 @@ Servers built with this package do not declare `directoryRead`, and hosts must n
217218

218219
### Samples
219220

220-
- [SkillsServer](../../../samples/SkillsServer/README.md): a Streamable
221+
- [SkillsServer](https://github.com/modelcontextprotocol/csharp-sdk/tree/main/samples/SkillsServer): a Streamable
221222
HTTP server serving two skills from directories on disk.
222-
- [SkillsClient](../../../samples/SkillsClient/README.md): a client that
223+
- [SkillsClient](https://github.com/modelcontextprotocol/csharp-sdk/tree/main/samples/SkillsClient): a client that
223224
connects to it and discovers, retrieves, and verifies them.

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

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,10 @@ public static async ValueTask<ListSkillsResult> ListSkillsAsync(
106106
JsonRpcResponse response = await client.SendRequestAsync(request, cancellationToken).ConfigureAwait(false);
107107
var result = response.Result?.Deserialize(McpSkillsJsonContext.Default.ListSkillsResult) ??
108108
throw new JsonException($"Unexpected JSON result in the response to '{SkillsProtocol.MethodSkillsList}'.");
109+
if (result.Skills is null)
110+
{
111+
throw new JsonException($"The response to '{SkillsProtocol.MethodSkillsList}' has no 'skills' array.");
112+
}
109113

110114
foreach (var skill in result.Skills)
111115
{
@@ -236,13 +240,6 @@ public static async ValueTask<ReadResourceResult> ReadSkillResourceAsync(
236240
if (uri is null) throw new ArgumentNullException(nameof(uri));
237241
#endif
238242

239-
if (skill.Resources is { IsDynamic: true })
240-
{
241-
throw new InvalidOperationException(
242-
$"Skill '{skill.Uri}' declares dynamic resources, which carry no digests and cannot be verified. " +
243-
$"Use {nameof(McpClient.ReadResourceAsync)} directly if unverifiable content is acceptable.");
244-
}
245-
246243
SkillVerifier.ThrowIfDynamic(skill);
247244
if (SkillVerifier.FindResource(skill, uri) is null)
248245
{

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

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
using ModelContextProtocol.Client;
12
using ModelContextProtocol.Protocol;
23
using System.Security.Cryptography;
34
using System.Text;
@@ -112,6 +113,11 @@ public static void Verify(SkillResource expected, ResourceContents contents)
112113
switch (contents)
113114
{
114115
case TextResourceContents text:
116+
if (text.Text is null)
117+
{
118+
throw new SkillVerificationException($"The text contents of '{contents.Uri}' carry no text and cannot be verified.");
119+
}
120+
115121
Verify(expected, Encoding.UTF8.GetBytes(text.Text));
116122
break;
117123

@@ -240,7 +246,8 @@ internal static void ThrowIfDynamic(Skill skill)
240246
if (skill.Resources.IsDynamic)
241247
{
242248
throw new InvalidOperationException(
243-
$"Skill '{skill.Uri}' declares dynamic resources, which carry no digests and cannot be verified.");
249+
$"Skill '{skill.Uri}' declares dynamic resources, which carry no digests and cannot be verified. " +
250+
$"Use {nameof(McpClient.ReadResourceAsync)} directly if unverifiable content is acceptable.");
244251
}
245252
}
246253

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

Lines changed: 20 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -33,20 +33,25 @@ namespace ModelContextProtocol.Extensions.Skills;
3333
/// </remarks>
3434
public sealed class McpServerSkill
3535
{
36-
private McpServerSkill(Skill protocolSkill, IReadOnlyList<McpServerResource> resources)
36+
private readonly Skill _entry;
37+
38+
private McpServerSkill(Skill entry, IReadOnlyList<McpServerResource> resources)
3739
{
38-
ProtocolSkill = protocolSkill;
40+
// The entry may hold the caller's frontmatter object; keep a private copy so later changes to it do not
41+
// reach the skill.
42+
_entry = SkillValidation.Snapshot(entry);
3943
Resources = resources;
4044
}
4145

4246
/// <summary>
43-
/// Gets the skill's entry, as returned by <c>skills/list</c> and <c>skills/get</c>.
47+
/// Gets a copy of the skill's entry, as returned by <c>skills/list</c> and <c>skills/get</c>.
4448
/// </summary>
4549
/// <remarks>
46-
/// The catalog that <c>WithSkills</c> creates keeps its own copy of this entry, so changes made to this object
47-
/// after registration do not affect what is served.
50+
/// Each access returns a new copy. The entry was computed from the same bytes <see cref="Resources"/> serve,
51+
/// and the skill keeps that entry itself, so changes made to a returned copy affect neither the skill nor
52+
/// what <c>WithSkills</c> registers.
4853
/// </remarks>
49-
public Skill ProtocolSkill { get; }
54+
public Skill ProtocolSkill => SkillValidation.Snapshot(_entry);
5055

5156
/// <summary>
5257
/// Gets the resources serving the skill's files, one per file, each addressable at the URI its manifest entry names.
@@ -263,6 +268,10 @@ internal static McpServerSkill CreateFromDirectory(string directoryPath, string
263268

264269
private static McpServerSkill CreateCore(string? uri, string? uriPrefix, JsonObject? frontmatter, IEnumerable<McpServerSkillFile> files, string filesParamName)
265270
{
271+
// A violation found in the entry is reported against the frontmatter argument when the caller supplied
272+
// one, and against the files (or directory) it was read from otherwise.
273+
string entryParamName = frontmatter is null ? filesParamName : nameof(frontmatter);
274+
266275
// Normalize and order the files: SKILL.md first, then the rest by path, so the manifest is deterministic.
267276
var normalized = new List<(string Path, McpServerSkillFile File)>();
268277
var seenPaths = new HashSet<string>(StringComparer.Ordinal);
@@ -385,7 +394,7 @@ private static McpServerSkill CreateCore(string? uri, string? uriPrefix, JsonObj
385394
Resources = SkillResources.FromResources(manifest),
386395
};
387396

388-
SkillValidation.Validate(skill, nameof(frontmatter));
397+
SkillValidation.Validate(skill, entryParamName);
389398

390399
var resources = new McpServerResource[normalized.Count];
391400
for (int i = 0; i < normalized.Count; i++)
@@ -586,7 +595,11 @@ private static bool TryDecodeUtf8(ReadOnlySpan<byte> bytes, out string? text)
586595
{
587596
try
588597
{
598+
#if NET
599+
text = s_strictUtf8.GetString(bytes);
600+
#else
589601
text = s_strictUtf8.GetString(bytes.ToArray());
602+
#endif
590603
return true;
591604
}
592605
catch (DecoderFallbackException)

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -69,9 +69,10 @@ public static IMcpServerBuilder WithSkills(
6969
throw new ArgumentException("The skills must not contain null entries.", nameof(skills));
7070
}
7171

72-
entries.Add(skill.ProtocolSkill);
72+
var protocolSkill = skill.ProtocolSkill;
73+
entries.Add(protocolSkill);
7374

74-
var manifest = skill.ProtocolSkill.Resources.Resources!;
75+
var manifest = protocolSkill.Resources.Resources!;
7576
for (int i = 0; i < manifest.Count; i++)
7677
{
7778
var entry = manifest[i];

0 commit comments

Comments
 (0)