diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4f6f3019b..f3a799fc0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -8,28 +8,28 @@ on: jobs: build: - - runs-on: ${{ matrix.os }} - strategy: matrix: os: [ubuntu-latest, windows-latest, macos-latest] configuration: [Debug, Release] fail-fast: false - steps: - - uses: actions/checkout@v4 + runs-on: ${{ matrix.os }} + + steps: + - name: Clone the repo + uses: actions/checkout@v4 with: fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis - - - name: Setup .NET + + - name: Set up .NET uses: actions/setup-dotnet@v4 with: - dotnet-version: | + dotnet-version: | 9.0.x 8.0.x - # Netfx testing on non-Windows requires mono + # NetFX testing on non-Windows requires mono - name: Setup Mono if: runner.os == 'Linux' run: sudo apt-get install -y mono-devel @@ -38,7 +38,7 @@ jobs: uses: actions/setup-node@v3 with: node-version: '20' - + - name: Install dependencies for tests run: npm install @modelcontextprotocol/server-everything @@ -48,6 +48,9 @@ jobs: - name: Build run: dotnet build --configuration ${{ matrix.configuration }} + - name: Pack + run: dotnet pack --configuration ${{ matrix.configuration }} + - name: Test run: >- dotnet test diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index fe8763935..04259a54b 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -16,9 +16,11 @@ permissions: concurrency: group: "pages" cancel-in-progress: false - + jobs: publish-docs: + # Only publish from the modelcontextprotocol/csharp-sdk repository + if: ${{ github.repository == 'modelcontextprotocol/csharp-sdk' }} environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} @@ -42,4 +44,4 @@ jobs: - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v4 \ No newline at end of file + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/release.md b/.github/workflows/release.md new file mode 100644 index 000000000..4077944f9 --- /dev/null +++ b/.github/workflows/release.md @@ -0,0 +1,37 @@ +# Release Process + +The following process is used when publishing new releases to NuGet.org: + +1. **Ensure the CI workflow is fully green** + - Some of the integration tests are flaky and require re-running + - Once the state of the branch is known to be good, a release can proceed + - **The release workflow _does not_ run tests** + +2. **Create a new Release in GitHub** + - Use the link on the repo home page to [Create a new release](https://github.com/modelcontextprotocol/csharp-sdk/releases/new) + - Click the 'Choose a tag' dropdown button + - Type the name using the `v{major}.{minor}.{patch}-{suffix}` pattern + - Click 'Create new tag: ... on publish' + - Click the 'Target' dropdown button + - Choose the 'Recent Commits' tab + - Select the commit to use for the release, ensuring it's one from above where CI is known to be green + - Click the 'Previous tag' dropdown button + - Choose the previous release to use for generating release notes + - Click the 'Generate release notes button' + - This will add release notes into the Release description + - The generated release notes include what has changed and the list of new contributors + - Verify the Release title + - It will be populated to match the tag name to be created + - This should be retained, using the release title format matching the `v{major}.{minor}.{patch}-{suffix}` format + - Augment the Release description as desired + - This content is presented used on GitHub and is not persisted into any artifacts + - Check the 'Set as a pre-release' button under the release description if appropriate + - Click 'Public release' + +3. **Monitor the Release workflow** + - After publishing the release, a workflow will begin for producing the release's build artifacts and publishing the NuGet package to NuGet.org + - If the job fails, troubleshoot and re-run the workflow as needed + - Verify the package version becomes listed on at [https://nuget.org/packages/ModelContextProtocol](https://nuget.org/packages/ModelContextProtocol) + +4. **Update the source to increment the version number** + - Immediately after publishing a new release, the [`/src/Directory.Build.Props`](../../src/Directory.Build.props) file needs to be updated to bump the version to the next expected release version diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 22140a161..35d6053f6 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,20 +1,71 @@ -# This workflow is triggered by new releases -# It builds, tests, and publishes to the GitHub NuGet package registry -name: Release package +# Publish new package versions of ModelContextProtocol +# +# Daily and Manual Runs +# - Triggered automatically at 07:00 UTC daily +# - Triggered manually using GitHub Actions workflow_dispatch event +# - Version prefix applied from /src/Directory.Build.props +# - Version suffix set to `ci.{github.run_number}` +# - Package published to GitHub package registry +# +# Official Releases +# - Triggered after a GitHub Release is created +# - Version prefix applied from /src/Directory.Build.props +# - Version suffix applied from /src/Directory.Build.props +# - Package published to GitHub package registry +# - Package published to NuGet.org +# - Version prefix and/or suffix should be updated after each release + +name: Release Publishing on: + schedule: + - cron: '0 7 * * *' + + workflow_dispatch: + inputs: + version_suffix_override: + description: Version suffix override + type: string + release: types: [published] jobs: - build: + build-all-configs: + strategy: + matrix: + os: [ubuntu-latest, windows-latest, macos-latest] + configuration: [Debug, Release] + fail-fast: false + + runs-on: ${{ matrix.os }} + + steps: + - name: Clone the repo + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis + + - name: Set up .NET + uses: actions/setup-dotnet@v4 + with: + dotnet-version: 9.0.x + - name: Build + run: dotnet build --configuration ${{ matrix.configuration }} + + - name: Pack + run: dotnet pack --configuration ${{ matrix.configuration }} + + build-package: runs-on: windows-latest + needs: build-all-configs + + env: + version_suffix_args: ${{ github.event_name != 'release' && format('--version-suffix "{0}"', inputs.version_suffix_override || format('ci.{0}', github.run_number)) || '' }} steps: - uses: actions/checkout@v4 - with: - fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis - name: Setup .NET uses: actions/setup-dotnet@v2 @@ -23,25 +74,11 @@ jobs: 9.0.x 8.0.x - - name: Set up Node.js - uses: actions/setup-node@v3 - with: - node-version: '20' - - - name: Install dependencies for tests - run: npm install @modelcontextprotocol/server-everything - - - name: Install dependencies for tests - run: npm install @modelcontextprotocol/server-memory - - - name: Build - run: dotnet build --configuration Release - - - name: Test - run: dotnet test --configuration Release --no-build --filter '(Execution!=Manual)' - - name: Pack - run: dotnet pack --configuration Release --output "${{ github.workspace }}/artifacts/packages" + run: dotnet pack + ${{ env.version_suffix_args }} + --configuration Release + --output "${{ github.workspace }}/artifacts/packages" - name: Upload artifact uses: actions/upload-artifact@v4 @@ -50,20 +87,16 @@ jobs: name: build-artifacts path: ${{ github.workspace }}/artifacts - publish: - name: Publish Package - needs: build + publish-package: + needs: build-package runs-on: ubuntu-latest steps: - - name: Checkout code - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - name: Setup .NET uses: actions/setup-dotnet@v2 with: - dotnet-version: | - 9.0.x - 8.0.x + dotnet-version: 9.0.x - name: Download build artifacts uses: actions/download-artifact@v4 @@ -75,7 +108,7 @@ jobs: env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - name: NuGet authentication for GitHub + - name: Authenticate to GitHub registry run: dotnet nuget add source "https://nuget.pkg.github.com/${{ github.repository_owner }}/index.json" --name "github" @@ -89,3 +122,12 @@ jobs: --source "github" --api-key ${{ secrets.GITHUB_TOKEN }} --skip-duplicate + + - name: Publish to NuGet.org (Releases only) + # Only publish to NuGet.org from the modelcontextprotocol/csharp-sdk repository + if: ${{ github.event_name == 'release' && github.repository == 'modelcontextprotocol/csharp-sdk' }} + run: dotnet nuget push + ${{github.workspace}}/build-artifacts/packages/*.nupkg + --source https://api.nuget.org/v3/index.json + --api-key ${{ secrets.NUGET_KEY_MODELCONTEXTPROTOCOL }} + --skip-duplicate diff --git a/Directory.Build.props b/Directory.Build.props index 8746e9aad..159c4a8f0 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -5,15 +5,32 @@ enable enable false - 0.1.0-preview - Microsoft - © Microsoft Corporation. All rights reserved. - $([System.IO.Path]::GetFullPath('$(MSBuildThisFileDirectory)')) - trx%3bLogFileName=$(MSBuildProjectName).$(TargetFramework).$(OS).trx - $(RepoRoot)/artifacts/TestResults false + + $([System.IO.Path]::GetFullPath('$(MSBuildThisFileDirectory)')) + $([MSBuild]::NormalizeDirectory('$(RepoRoot)', 'artifacts')) + $([MSBuild]::NormalizeDirectory('$(ArtifactsDir)', 'obj')) + $([MSBuild]::NormalizeDirectory('$(ArtifactsDir)', 'bin')) + $([MSBuild]::NormalizeDirectory('$(ArtifactsDir)', 'TestResults', '$(Configuration)')) + $([MSBuild]::NormalizeDirectory('$(ArtifactsDir)', 'packages', '$(Configuration)')) + $(MSBuildProjectName) + + $([System.IO.Path]::GetFullPath('$(ArtifactsObjDir)$(OutDirName)\')) + $(BaseIntermediateOutputPath)$(Configuration)\ + + $([System.IO.Path]::GetFullPath('$(ArtifactsBinDir)$(OutDirName)\')) + $(BaseOutputPath)$(Configuration)\ + + $(ArtifactsPackagesDir) + + + + trx%3bLogFileName=$(MSBuildProjectName).$(TargetFramework).$(OS).trx + $(ArtifactsTestResultsDir) + + true diff --git a/README.MD b/README.md similarity index 98% rename from README.MD rename to README.md index 1997a962d..63784d6e2 100644 --- a/README.MD +++ b/README.md @@ -5,7 +5,7 @@ The official C# SDK for the [Model Context Protocol](https://modelcontextprotocol.io/), enabling .NET applications, services, and libraries to implement and interact with MCP clients and servers. Please visit our [API documentation](https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.html) for more details on available functionality. > [!NOTE] -> This repo is still in preview, breaking changes can be introduced without prior notice. +> This project is in preview; breaking changes can be introduced without prior notice. ## About MCP diff --git a/src/Directory.Build.props b/src/Directory.Build.props index 9227624cf..55e48939f 100644 --- a/src/Directory.Build.props +++ b/src/Directory.Build.props @@ -5,12 +5,15 @@ https://github.com/modelcontextprotocol/csharp-sdk https://github.com/modelcontextprotocol/csharp-sdk git + 0.1.0 + preview.2 + ModelContextProtocolOfficial + © Anthropic and Contributors. ModelContextProtocol;mcp;ai;llm MIT logo.png true snupkg - $(RepoRoot)artifacts/ true $(RepoRoot)\Open.snk true @@ -23,4 +26,4 @@ - \ No newline at end of file + diff --git a/src/ModelContextProtocol/ModelContextProtocol.csproj b/src/ModelContextProtocol/ModelContextProtocol.csproj index 0e677692e..dcee6278f 100644 --- a/src/ModelContextProtocol/ModelContextProtocol.csproj +++ b/src/ModelContextProtocol/ModelContextProtocol.csproj @@ -29,7 +29,7 @@ - + diff --git a/src/ModelContextProtocol/README.md b/src/ModelContextProtocol/README.md deleted file mode 100644 index 90a39907c..000000000 --- a/src/ModelContextProtocol/README.md +++ /dev/null @@ -1,181 +0,0 @@ -# MCP C# SDK - -The official C# SDK for the [Model Context Protocol](https://modelcontextprotocol.io/), enabling .NET applications to connect to and interact with MCP clients and servers. - -> [!NOTE] -> This repo is still in preview, breaking changes can be introduced without prior notice. - -## About MCP - -The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). It enables secure integration between LLMs and various data sources and tools. - -For more information about MCP: - -- [Official Documentation](https://modelcontextprotocol.io/) -- [Protocol Specification](https://spec.modelcontextprotocol.io/) -- [GitHub Organization](https://github.com/modelcontextprotocol) - -## Getting Started (Client) - -Then create a client and start using tools, or other capabilities, from the servers you configure: - -```csharp -McpClientOptions options = new() -{ - ClientInfo = new() { Name = "TestClient", Version = "1.0.0" } -}; - -McpServerConfig config = new() -{ - Id = "everything", - Name = "Everything", - TransportType = TransportTypes.StdIo, - TransportOptions = new() - { - ["command"] = "npx", - ["arguments"] = "-y @modelcontextprotocol/server-everything", - } -}; - -var client = await McpClientFactory.CreateAsync(config, options); - -// Print the list of tools available from the server. -await foreach (var tool in client.ListToolsAsync()) -{ - Console.WriteLine($"{tool.Name} ({tool.Description})"); -} - -// Execute a tool (this would normally be driven by LLM tool invocations). -var result = await client.CallToolAsync( - "echo", - new() { ["message"] = "Hello MCP!" }, - CancellationToken.None); - -// echo always returns one and only one text content object -Console.WriteLine(result.Content.First(c => c.Type == "text").Text); -``` - -Note that you should pass CancellationToken objects suitable for your use case, to enable proper error handling, timeouts, etc. This example also does not paginate the tools list, which may be necessary for large tool sets. See the IntegrationTests project for an example of pagination, as well as examples of how to handle Prompts and Resources. - -It is also highly recommended that you pass a proper LoggerFactory instance to the factory constructor, to enable logging of MCP client operations. - -You can find samples demonstrating how to use ModelContextProtocol with an LLM SDK in the [samples](https://github.com/modelcontextprotocol/csharp-sdk/tree/main/samples) directory, and also refer to the [tests](https://github.com/modelcontextprotocol/csharp-sdk/tree/main/tests/ModelContextProtocol.Tests) project for more examples. - -Additional examples and documentation will be added as in the near future. - -Remember you can connect to any MCP server, not just ones created using ModelContextProtocol. The protocol is designed to be server-agnostic, so you can use this library to connect to any compliant server. - -Tools can be exposed easily as `AIFunction` instances so that they are immediately usable with `IChatClient`s. - -```csharp -// Get available functions. -IList tools = await client.GetAIFunctionsAsync(); - -// Call the chat client using the tools. -IChatClient chatClient = ...; -var response = await chatClient.GetResponseAsync( - "your prompt here", - new() - { - Tools = [.. tools], - }); -``` - -## Getting Started (Server) - -Here is an example of how to create an MCP server and register all tools from the current application. -It includes a simple echo tool as an example (this is included in the same file here for easy of copy and paste, but it needn't be in the same file... -the employed overload of `WithTools` examines the current assembly for classes with the `McpServerToolType` attribute, and registers all methods with the -`McpTool` attribute as tools.) - -```csharp -using ModelContextProtocol; -using ModelContextProtocol.Server; -using Microsoft.Extensions.Hosting; -using System.ComponentModel; - -var builder = Host.CreateEmptyApplicationBuilder(settings: null); -builder.Services - .AddMcpServer() - .WithStdioServerTransport() - .WithTools(); -await builder.Build().RunAsync(); - -[McpServerToolType] -public static class EchoTool -{ - [McpTool, Description("Echoes the message back to the client.")] - public static string Echo(string message) => $"hello {message}"; -} -``` - -More control is also available, with fine-grained control over configuring the server and how it should handle client requests. For example: - -```csharp -using ModelContextProtocol.Protocol.Transport; -using ModelContextProtocol.Protocol.Types; -using ModelContextProtocol.Server; -using Microsoft.Extensions.Logging.Abstractions; - -McpServerOptions options = new() -{ - ServerInfo = new() { Name = "MyServer", Version = "1.0.0" }, - Capabilities = new() - { - Tools = new() - { - ListToolsHandler = async (request, cancellationToken) => - { - return new ListToolsResult() - { - Tools = - [ - new Tool() - { - Name = "echo", - Description = "Echoes the input back to the client.", - InputSchema = new JsonSchema() - { - Type = "object", - Properties = new Dictionary() - { - ["message"] = new JsonSchemaProperty() { Type = "string", Description = "The input to echo back." } - } - }, - } - ] - }; - }, - - CallToolHandler = async (request, cancellationToken) => - { - if (request.Params?.Name == "echo") - { - if (request.Params.Arguments?.TryGetValue("message", out var message) is not true) - { - throw new McpServerException("Missing required argument 'message'"); - } - - return new CallToolResponse() - { - Content = [new Content() { Text = $"Echo: {message}", Type = "text" }] - }; - } - - throw new McpServerException($"Unknown tool: '{request.Params?.Name}'"); - }, - } - }, -}; - -await using IMcpServer server = McpServerFactory.Create(new StdioServerTransport("MyServer"), options); - -await server.StartAsync(); - -// Run until process is stopped by the client (parent process) -await Task.Delay(Timeout.Infinite); -``` - -## License - -This project is licensed under the [MIT License](https://github.com/modelcontextprotocol/csharp-sdk/blob/main/LICENSE). diff --git a/tests/ModelContextProtocol.Tests/ModelContextProtocol.Tests.csproj b/tests/ModelContextProtocol.Tests/ModelContextProtocol.Tests.csproj index 479dbf571..7a239ef29 100644 --- a/tests/ModelContextProtocol.Tests/ModelContextProtocol.Tests.csproj +++ b/tests/ModelContextProtocol.Tests/ModelContextProtocol.Tests.csproj @@ -40,10 +40,10 @@ - + PreserveNewest - + PreserveNewest