Skip to content

Commit cbd8a58

Browse files
committed
Add SEP-2640 Skills extension package
Adds ModelContextProtocol.Extensions.Skills implementing the skills/list and skills/get methods of SEP-2640, alongside the existing Tasks and Apps extension packages. Declares the io.modelcontextprotocol/skills capability inline and registers both methods through McpServerOptions.RequestHandlers, so Core is unchanged. Skill manifests are modelled as SkillResources, a closed type admitting only an enumerated file list or the dynamic marker, so an invalid manifest cannot be constructed. Pagination uses keyset cursors over URI order. skills/get sets RoutingNameParameter to uri, matching how Core routes resources/read for the Mcp-Name header. ttlMs and cacheScope are gated on the negotiated protocol version by default, which SEP-2640 currently requires, but the gate is configurable while the working group settles whether that condition is removed.
1 parent df11d7d commit cbd8a58

26 files changed

Lines changed: 1664 additions & 3 deletions

‎ModelContextProtocol.slnx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@
6969
<Project Path="src/ModelContextProtocol.AspNetCore/ModelContextProtocol.AspNetCore.csproj" />
7070
<Project Path="src/ModelContextProtocol.Core/ModelContextProtocol.Core.csproj" />
7171
<Project Path="src/ModelContextProtocol.Extensions.Apps/ModelContextProtocol.Extensions.Apps.csproj" />
72+
<Project Path="src/ModelContextProtocol.Extensions.Skills/ModelContextProtocol.Extensions.Skills.csproj" />
7273
<Project Path="src/ModelContextProtocol.Extensions.Tasks/ModelContextProtocol.Extensions.Tasks.csproj" />
7374
<Project Path="src/ModelContextProtocol/ModelContextProtocol.csproj" />
7475
</Folder>

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

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,15 @@ namespace ModelContextProtocol.Protocol;
1010
/// </remarks>
1111
public abstract class PaginatedRequestParams : RequestParams
1212
{
13-
/// <summary>Prevent external derivations.</summary>
14-
private protected PaginatedRequestParams()
13+
/// <summary>
14+
/// Initializes a new instance of the <see cref="PaginatedRequestParams"/> class.
15+
/// </summary>
16+
/// <remarks>
17+
/// This is <see langword="protected"/> rather than <c>private protected</c> so that extension packages
18+
/// implementing paginated methods defined outside the core specification can derive from it. See
19+
/// <see cref="Server.McpServerRequestHandler"/>.
20+
/// </remarks>
21+
protected PaginatedRequestParams()
1522
{
1623
}
1724

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

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,15 @@ namespace ModelContextProtocol.Protocol;
1717
/// </remarks>
1818
public abstract class PaginatedResult : Result
1919
{
20-
private protected PaginatedResult()
20+
/// <summary>
21+
/// Initializes a new instance of the <see cref="PaginatedResult"/> class.
22+
/// </summary>
23+
/// <remarks>
24+
/// This is <see langword="protected"/> rather than <c>private protected</c> so that extension packages
25+
/// implementing paginated methods defined outside the core specification can derive from it. See
26+
/// <see cref="Server.McpServerRequestHandler"/>.
27+
/// </remarks>
28+
protected PaginatedResult()
2129
{
2230
}
2331

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
using System.Text.Json.Serialization;
2+
3+
namespace ModelContextProtocol.Extensions.Skills;
4+
5+
/// <summary>
6+
/// Provides source-generated JSON serialization metadata for MCP Skills extension types.
7+
/// </summary>
8+
[JsonSourceGenerationOptions(
9+
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
10+
PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
11+
[JsonSerializable(typeof(SkillEntry))]
12+
[JsonSerializable(typeof(SkillResource))]
13+
[JsonSerializable(typeof(SkillResources))]
14+
[JsonSerializable(typeof(ListSkillsRequestParams))]
15+
[JsonSerializable(typeof(ListSkillsResult))]
16+
[JsonSerializable(typeof(GetSkillRequestParams))]
17+
[JsonSerializable(typeof(GetSkillResult))]
18+
public sealed partial class McpSkillsJsonContext : JsonSerializerContext
19+
{
20+
}
Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<TargetFrameworks>net10.0;net9.0;net8.0;netstandard2.0</TargetFrameworks>
5+
<GenerateDocumentationFile>true</GenerateDocumentationFile>
6+
<IsPackable>true</IsPackable>
7+
<PackageId>ModelContextProtocol.Extensions.Skills</PackageId>
8+
<Description>MCP Skills extension (SEP-2640) for the .NET Model Context Protocol (MCP) SDK</Description>
9+
<PackageReadmeFile>README.md</PackageReadmeFile>
10+
<!-- Suppress the experimental MCP warnings for internal usage -->
11+
<NoWarn>$(NoWarn);MCPEXP001;MCPEXP002</NoWarn>
12+
<!--
13+
Package validation stays enabled so cross-target-framework API compatibility is checked. The
14+
repo-wide baseline is cleared because this package has no released version to compare against yet;
15+
set it to the first shipped version once this package has been released.
16+
-->
17+
<PackageValidationBaselineVersion />
18+
</PropertyGroup>
19+
20+
<PropertyGroup Condition="'$(TargetFramework)' != 'netstandard2.0'">
21+
<IsAotCompatible>true</IsAotCompatible>
22+
</PropertyGroup>
23+
24+
<PropertyGroup Condition="'$(TargetFramework)' == 'netstandard2.0'">
25+
<!-- CS0436: Allow ObsoleteAttribute to be redefined internally -->
26+
<NoWarn>$(NoWarn);CS0436</NoWarn>
27+
</PropertyGroup>
28+
29+
<ItemGroup>
30+
<Compile Include="..\Common\Experimentals.cs" Link="Experimentals.cs" />
31+
<Compile Include="..\Common\McpProtocolVersions.cs" Link="McpProtocolVersions.cs" />
32+
</ItemGroup>
33+
34+
<!-- Exclude polyfills inherited from Directory.Build.props; this package only needs the ExperimentalAttribute polyfill. -->
35+
<ItemGroup>
36+
<Compile Remove="..\Common\Polyfills\**\*.cs" />
37+
<Compile Include="..\Common\Polyfills\System\Diagnostics\CodeAnalysis\ExperimentalAttribute.cs"
38+
Link="Polyfills\ExperimentalAttribute.cs" />
39+
<Compile Include="..\Common\Polyfills\System\Runtime\CompilerServices\CompilerFeatureRequiredAttribute.cs"
40+
Link="Polyfills\CompilerFeatureRequiredAttribute.cs" />
41+
<Compile Include="..\Common\Polyfills\System\Runtime\CompilerServices\IsExternalInit.cs"
42+
Link="Polyfills\IsExternalInit.cs" />
43+
<Compile Include="..\Common\Polyfills\System\Runtime\CompilerServices\RequiredMemberAttribute.cs"
44+
Link="Polyfills\RequiredMemberAttribute.cs" />
45+
</ItemGroup>
46+
47+
<ItemGroup>
48+
<ProjectReference Include="..\ModelContextProtocol\ModelContextProtocol.csproj" />
49+
</ItemGroup>
50+
51+
<ItemGroup>
52+
<None Include="..\PACKAGE.md" Pack="true" PackagePath="\README.md" />
53+
</ItemGroup>
54+
55+
</Project>
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
using ModelContextProtocol.Protocol;
2+
using System.Text.Json.Serialization;
3+
4+
namespace ModelContextProtocol.Extensions.Skills;
5+
6+
/// <summary>
7+
/// Represents the parameters for a <c>skills/get</c> request retrieving a single skill's entry by URI.
8+
/// </summary>
9+
/// <remarks>
10+
/// See the <see href="https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640">SEP-2640</see>
11+
/// specification for details.
12+
/// </remarks>
13+
public sealed class GetSkillRequestParams : RequestParams
14+
{
15+
/// <summary>
16+
/// Gets or sets the URI of the skill's <c>SKILL.md</c>.
17+
/// </summary>
18+
/// <remarks>
19+
/// If the URI does not identify a skill the server serves, the server returns error -32602
20+
/// (Invalid params), the same code <c>resources/read</c> uses for unknown resources.
21+
/// </remarks>
22+
[JsonPropertyName("uri")]
23+
public required string Uri { get; set; }
24+
}
Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
using ModelContextProtocol.Protocol;
2+
using System.Text.Json.Serialization;
3+
4+
namespace ModelContextProtocol.Extensions.Skills;
5+
6+
/// <summary>
7+
/// Represents a server's response to a <c>skills/get</c> request, containing one skill's entry.
8+
/// </summary>
9+
/// <remarks>
10+
/// <para>
11+
/// A server answers for every skill it serves, whether or not that skill appears in its <c>skills/list</c>
12+
/// result. The result carries no pagination cursor, because a single entry is not a list.
13+
/// </para>
14+
/// <para>
15+
/// See the <see href="https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640">SEP-2640</see>
16+
/// specification for details.
17+
/// </para>
18+
/// </remarks>
19+
public sealed class GetSkillResult : Result
20+
{
21+
/// <summary>
22+
/// Gets or sets the skill's entry, identical in shape and meaning to an entry of <c>skills/list</c>.
23+
/// </summary>
24+
[JsonPropertyName("skill")]
25+
public required SkillEntry Skill { get; set; }
26+
}
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
using ModelContextProtocol.Protocol;
2+
using System.Text.Json.Serialization;
3+
4+
namespace ModelContextProtocol.Extensions.Skills;
5+
6+
/// <summary>
7+
/// Represents the parameters for a <c>skills/list</c> request enumerating the skills a server serves.
8+
/// </summary>
9+
/// <remarks>
10+
/// <para>
11+
/// See the <see href="https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640">SEP-2640</see>
12+
/// specification for details.
13+
/// </para>
14+
/// </remarks>
15+
public sealed class ListSkillsRequestParams : PaginatedRequestParams;
Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
using ModelContextProtocol.Protocol;
2+
using System.Text.Json.Serialization;
3+
4+
namespace ModelContextProtocol.Extensions.Skills;
5+
6+
/// <summary>
7+
/// Represents a server's response to a <c>skills/list</c> request, containing the skills it serves.
8+
/// </summary>
9+
/// <remarks>
10+
/// <para>
11+
/// The result may be empty or partial. A server whose skill catalog is large, generated on demand, or
12+
/// otherwise unenumerable may return fewer skills than it serves, and hosts must not treat an empty
13+
/// listing as proof that a server has no skills. Skills absent from a listing remain retrievable through
14+
/// <c>skills/get</c>.
15+
/// </para>
16+
/// <para>
17+
/// An entry is atomic: a skill's manifest is never split across pages.
18+
/// </para>
19+
/// <para>
20+
/// See the <see href="https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640">SEP-2640</see>
21+
/// specification for details.
22+
/// </para>
23+
/// </remarks>
24+
public sealed class ListSkillsResult : PaginatedResult, ICacheableResult
25+
{
26+
/// <summary>
27+
/// Gets or sets the skill entries.
28+
/// </summary>
29+
[JsonPropertyName("skills")]
30+
public IList<SkillEntry> Skills { get; set; } = [];
31+
32+
/// <inheritdoc />
33+
[JsonPropertyName("ttlMs")]
34+
[JsonConverter(typeof(TimeSpanMillisecondsConverter))]
35+
public TimeSpan? TimeToLive { get; set; }
36+
37+
/// <inheritdoc />
38+
/// <remarks>
39+
/// Core applies its own internal <c>CacheScopeConverter</c> to this property on the built-in result
40+
/// types, which tolerates unrecognized scope strings on read by mapping them to
41+
/// <see langword="null"/>. That converter is not accessible outside the core assembly, so this type
42+
/// relies on the converter declared on the <see cref="Protocol.CacheScope"/> enum instead. The written
43+
/// wire values are identical; only the read-side leniency differs.
44+
/// </remarks>
45+
[JsonPropertyName("cacheScope")]
46+
public CacheScope? CacheScope { get; set; }
47+
}
Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
using System.Text.Json.Nodes;
2+
using System.Text.Json.Serialization;
3+
4+
namespace ModelContextProtocol.Extensions.Skills;
5+
6+
/// <summary>
7+
/// Represents a single skill as returned by <c>skills/list</c> and <c>skills/get</c>.
8+
/// </summary>
9+
/// <remarks>
10+
/// <para>
11+
/// An entry is a complete, point-in-time snapshot of a skill: its <c>SKILL.md</c> URI, the verbatim
12+
/// frontmatter of that file, and the manifest of the skill's files. A host that pages through a listing
13+
/// therefore has everything it needs to build its registry and verify every file it later reads, without
14+
/// a second round-trip per skill.
15+
/// </para>
16+
/// <para>
17+
/// See the <see href="https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640">SEP-2640</see>
18+
/// specification for details.
19+
/// </para>
20+
/// </remarks>
21+
public sealed class SkillEntry
22+
{
23+
/// <summary>
24+
/// Gets or sets the resource URI of the skill's <c>SKILL.md</c>.
25+
/// </summary>
26+
/// <remarks>
27+
/// The final path segment preceding <c>/SKILL.md</c> must equal the <c>name</c> field of
28+
/// <see cref="Frontmatter"/>, so that a skill's name is recoverable from its URI alone.
29+
/// </remarks>
30+
[JsonPropertyName("uri")]
31+
public required string Uri { get; set; }
32+
33+
/// <summary>
34+
/// Gets or sets the skill's <c>SKILL.md</c> YAML frontmatter rendered verbatim as a JSON object.
35+
/// </summary>
36+
/// <remarks>
37+
/// Every field the author wrote is passed through, not a curated subset. Hosts re-parse the fetched
38+
/// <c>SKILL.md</c> and compare it against this object field by field, treating any discrepancy as a
39+
/// verification failure, so this must reproduce the authored frontmatter exactly.
40+
/// </remarks>
41+
[JsonPropertyName("frontmatter")]
42+
public required JsonObject Frontmatter { get; set; }
43+
44+
/// <summary>
45+
/// Gets or sets the skill's file manifest.
46+
/// </summary>
47+
[JsonPropertyName("resources")]
48+
public required SkillResources Resources { get; set; }
49+
}

0 commit comments

Comments
 (0)