fix: Fix MCP server handling for URI / direct json reference

Author: pomianowski

Dockerfile

@@ -19,6 +19,9 @@ RUN dotnet publish "./src/OpenApi.Client.Mcp/OpenApi.Client.Mcp.csproj" -c Relea
 
 # This stage is used in production or when running from VS in regular mode (Default when not using the Debug configuration)
 FROM base AS final
+EXPOSE 80
+EXPOSE 8080
+EXPOSE 8000
 WORKDIR /app
 COPY --from=publish /app/publish .
 ENTRYPOINT ["dotnet", "OpenApi.Client.Mcp.dll"]

README.md

@@ -1,39 +1,56 @@
 # ☄️ OpenAPI Client
 
-[Created with ❤ in Poland by lepo.co](https://lepo.co/) and [wonderful open-source community](https://github.com/lepoco/openapi.client/graphs/contributors)  
-OpenAPI Client is a toolkit that helps you create HTTP clients for external APIs based on their OpenAPI specifications. It simplifies the process of consuming and interacting with various web services. The project is developed and maintained by lepo.co and other community contributors.
+[Created with ❤ in Poland by lepo.co](https://lepo.co/) and [the awesome open-source community](https://github.com/lepoco/openapi.client/graphs/contributors).  
+OpenAPI Client is a modern toolkit for developers working with OpenAPI/Swagger specifications. It provides multiple tools to simplify the creation, inspection, validation, and integration of OpenAPI clients across .NET projects and MCP (Model Context Protocol) environments.
 
-## 👀 What does this repo contain?
+## 🧰 What's in this repo?
 
-The repository contains NuGet package source code, which uses C# code generators that can be used to generate native C# API clients from YAML or JSON files.
+This repository contains a suite of OpenAPI tools designed to support different workflows:
 
-## MCP Server
+| Tool                     | Description                                                                    |
+| ------------------------ | ------------------------------------------------------------------------------ |
+| 🧠 .NET Source Generator | Generates C# HTTP clients directly from OpenAPI JSON/YAML files at build time. |
+| 💻 .NET CLI Tool         | Command-line tool to generate clients from OpenAPI definitions manually.       |
+| 🛰️ MCP Server            | Containerized server with built-in tools for working with OpenAPI specs.       |
 
-Build for yourself:
+## 🚀 MCP Server Tools
 
-```cmd
-docker buildx build ./ -f ./src/OpenApi.Client.Mcp/Dockerfile -t mcp/openapi --no-cache
-```
+The MCP Server is the central piece of this toolkit. It runs as a standalone container or inside an MCP setup and exposes tools for working with OpenAPI documents.
+
+### 🛠️ Available Server Tools
+
+| Tool                     | Description                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------------ |
+| `get_list_of_operations` | Lists all operation IDs from a given OpenAPI or Swagger JSON document.                     |
+| `get_known_responses`    | Lists all known responses for given operation IDs from a OpenAPI or Swagger JSON document. |
+| `validate_document`      | Validates the structure and syntax of an OpenAPI JSON document.                            |
+| `generate_curl_command`  | Generates a cURL command for a specific operation ID.                                      |
+| `create_csharp_snippet`  | Creates a simple HTTP request for a given operation ID.                                    |
+
+### 🐳 Run the server with Docker
 
-or
+Build the image:
 
-```cmd
-dotnet publish .\src\OpenApi.Client.Mcp\OpenApi.Client.Mcp.csproj -c Release /t:PublishContainer
+```bash
+docker buildx build ./ -t mcp/openapi --no-cache
+# or
+dotnet publish ./src/OpenApi.Client.Mcp/OpenApi.Client.Mcp.csproj -c Release /t:PublishContainer
 ```
 
-Then
+Run the container:
 
-```cmd
-docker run -d --name mcp-openapi mcp/openapi -e MODE=Stdio
-docker run -d --name mcp-openapi mcp/openapi -e MODE=Http -p 64622:8080
+```bash
+docker run -d -i --rm --name mcp-openapi mcp/openapi
+# or for HTTP mode:
+docker run -d -i --rm --name mcp-openapi mcp/openapi -e MODE=Http -p 64622:8080
 ```
 
-You can configure your *mcp.json* file
+Example MCP config (`.mcp.json`):
 
 ```json
 {
   "servers": {
-    "openapi.mcp": {
+    "openapi": {
       "type": "stdio",
       "command": "docker",
       "args": ["run", "-i", "--rm", "mcp/openapi"]
@@ -43,12 +60,12 @@ You can configure your *mcp.json* file
 }
 ```
 
-## Gettings started
+## 📦 NuGet Package (Source Generator)
 
 OpenApiClient is available as NuGet package on NuGet.org:  
 <https://www.nuget.org/packages/OpenApiClient>
 
-You can add it to your project using .NET CLI:
+Install the package to enable automatic OpenAPI client generation:
 
 ```powershell
 dotnet add package OpenApiClient
@@ -60,82 +77,50 @@ dotnet add package OpenApiClient
 NuGet\Install-Package OpenApiClient
 ```
 
-, you can also use the .NET CLI tool to generate the classes using commands
-
-```powershell
-dotnet tool install --global OpenApiClient.Cli
-```
-
-Define an Open API file as content in your **.csproj** file.
+In your .csproj:
 
 ```xml
-<Project Sdk="Microsoft.NET.Sdk">
-
-  <PropertyGroup>
-    <TargetFrameworks>net8.0</TargetFrameworks>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <PackageReference Include="OpenApiClient" Version="1.0.0">
-      <PrivateAssets>all</PrivateAssets>
-      <IncludeAssets>compile; build; analyzers</IncludeAssets>
-    </PackageReference>
-  </ItemGroup>
-
-  <ItemGroup>
-    <OpenApiContract Include="google.youtube.api.json" />
-  </ItemGroup>
-
-</Project>
+<ItemGroup>
+  <AdditionalFiles Include="google.youtube.api.json" />
+</ItemGroup>
 ```
 
-Define your partial class as open api client
+Define a client:
 
 ```csharp
-/// <summary>
-/// My YouTube Client.
-/// </summary>
 [OpenApiClient("google.youtube.api")]
 public partial class YouTubeClient;
 ```
 
-You can now use your generated client!
+Use it:
 
 ```csharp
-IYouTubeClient client = new YouTubeClient(new HttpClient());
-
-var subscribersCount = client.SubscribersCountAsync("mychannel", CancellationToken.None);
+var client = new YouTubeClient(new HttpClient());
+var subs = await client.SubscribersCountAsync("mychannel", CancellationToken.None);
 ```
 
-## Known limitations
+### Known limitations
 
 Since we are using the generated internal `OpenApiAttribute` as a marker, conflicts may occur when we use `InternalsVisibleTo`.
 
 We found the use of nullable essential, so C# 8.0 is required.
 
-## OpenAPI
-
-OpenAPI specification is available at:  
-<https://github.com/OAI/OpenAPI-Specification>
-
-## Community Toolkit
-
-The OpenAPI Client is inspired by the MVVM Community Toolkit:  
-<https://github.com/CommunityToolkit/dotnet>
-
-## Special thanks
+## 💻 .NET CLI Tool
 
-JetBrains was kind enough to lend a license for the open-source **dotUltimate** for Open API Client development. Learn more here:
+Generate OpenAPI clients from the terminal:
 
-- https://www.jetbrains.com/dotnet/
-- https://www.jetbrains.com/opensource/
+```bash
+dotnet tool install --global OpenApiClient.Cli
+```
 
-## Compilation
+```bash
+dotnet openapi generate ./google.youtube.api.json --output ./clients/YouTubeClient.cs --namespace Google.YouTube --classname YouTubeClient
+```
 
-Use Visual Studio 2022 and invoke the .sln.
+## OpenAPI
 
-Visual Studio  
-**OpenAPI Client** is an Open Source project. You are entitled to download and use the freely available Visual Studio Community Edition to build, run or develop for OpenAPI Client. As per the Visual Studio Community Edition license, this applies regardless of whether you are an individual or a corporate user.
+OpenAPI specification is available at:  
+<https://github.com/OAI/OpenAPI-Specification>
 
 ## Code of Conduct
 

ThirdPartyNotices.txt

@@ -5,9 +5,37 @@ Do Not Translate or Localize
 
 This project incorporates components from the projects listed below. The original copyright notices and the licenses under which the .NET Foundation received such components are set forth below.
 
-1.  CommunityToolkit/dotnet version 8.2.2 (https://github.com/CommunityToolkit/dotnet), included in all sources
-2.  Sergio0694/ComputeSharp (https://github.com/Sergio0694/ComputeSharp), contributed by Sergio Pedri to reuse some helpers to support incremental generators in the MVVM Toolkit.
-3.  Sergio0694/PolySharp (https://github.com/Sergio0694/PolySharp), used as inspiration for the implementation of the generators.
+1.  Microsoft/OpenAPI.NET (https://github.com/Microsoft/OpenAPI.NET), used for interaction with OpenAPI documents.
+2.  CommunityToolkit/dotnet version 8.2.2 (https://github.com/CommunityToolkit/dotnet), included in all sources
+3.  Sergio0694/ComputeSharp (https://github.com/Sergio0694/ComputeSharp), contributed by Sergio Pedri to reuse some helpers to support incremental generators in the MVVM Toolkit.
+4.  Sergio0694/PolySharp (https://github.com/Sergio0694/PolySharp), used as inspiration for the implementation of the generators.
+5.  modelcontextprotocol/csharp-sdk (https://github.com/modelcontextprotocol/csharp-sdk), used as foundation of the MCP server.
+
+%% Microsoft/OpenAPI.NET NOTICES AND INFORMATION BEGIN HERE
+=========================================
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+=========================================
+END OF Microsoft/OpenAPI.NET NOTICES AND INFORMATION
 
 %% CommunityToolkit/dotnet NOTICES AND INFORMATION BEGIN HERE
 =========================================
@@ -90,3 +118,29 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 =========================================
 END OF Sergio0694/PolySharp NOTICES AND INFORMATION
+
+%% modelcontextprotocol/csharp-sdk NOTICES AND INFORMATION BEGIN HERE
+=========================================
+MIT License
+
+Copyright (c) Anthropic and Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+=========================================
+END OF modelcontextprotocol/csharp-sdk NOTICES AND INFORMATION

src/OpenApi.Client.Mcp/Dockerfile

@@ -20,5 +20,8 @@ RUN dotnet publish "./src/OpenApi.Client.Mcp/OpenApi.Client.Mcp.csproj" -c Relea
 # This stage is used in production or when running from VS in regular mode (Default when not using the Debug configuration)
 FROM base AS final
 WORKDIR /app
+EXPOSE 80
+EXPOSE 8080
+EXPOSE 8000
 COPY --from=publish /app/publish .
 ENTRYPOINT ["dotnet", "OpenApi.Client.Mcp.dll"]

src/OpenApi.Client.Mcp/Services/IOpenApiService.cs

@@ -8,27 +8,55 @@ namespace OpenApi.Client.Mcp.Services;
 internal interface IOpenApiService
 {
     /// <summary>
-    /// Creates an OpenAPI client from the specified URL address of the OpenAPI JSON file or Swagger-generated JSON.
+    /// Generates an OpenAPI client from a URL pointing to an OpenAPI or Swagger JSON document.
     /// </summary>
-    Task<string> CreateFromFileAsync(string address, CancellationToken cancellationToken = default);
+    Task<string> CreateCsharpClientAsync(
+        string addressOrFileContents,
+        CancellationToken cancellationToken = default
+    );
+
+    /// <summary>
+    /// Generates a C# code snippet for a given operation ID from the specified OpenAPI document or Swagger-generated JSON.
+    /// </summary>
+    Task<string> CreateCsharpSnippetAsync(
+        string addressOrFileContents,
+        string operationId,
+        string? baseAddress,
+        CancellationToken cancellationToken = default
+    );
 
     /// <summary>
-    /// Retrieves a list of operations from the specified OpenAPI JSON file or Swagger-generated JSON.
+    /// Retrieves a list of operations (endpoints) from the specified OpenAPI document or Swagger-generated JSON.
     /// </summary>
-    Task<string> GetOperationsAsync(string address, CancellationToken cancellationToken = default);
+    Task<string> GetOperationsAsync(
+        string addressOrFileContents,
+        CancellationToken cancellationToken = default
+    );
 
     /// <summary>
-    /// Generates a curl command for a given operation ID from the OpenAPI specification.
+    /// Validates the OpenAPI document or Swagger-generated JSON.
     /// </summary>
-    Task<string> GenerateCurlCommandAsync(
-        string address,
+    Task<string> ValidateDocumentAsync(
+        string addressOrFileContents,
+        CancellationToken cancellationToken = default
+    );
+
+    /// <summary>
+    /// Retrieves known responses for the specified OpenAPI document or Swagger-generated JSON.
+    /// </summary>
+    Task<string> GetKnownResponsesAsync(
+        string addressOrFileContents,
         string operationId,
-        string? baseAddress,
         CancellationToken cancellationToken = default
     );
 
     /// <summary>
-    /// Validates the OpenAPI document at the specified address and returns a string indicating the validation result.
+    /// Generates a cURL command for a given operation ID from the specified OpenAPI JSON file or Swagger-generated JSON.
     /// </summary>
-    Task<string> ValidateDocumentAsync(string address, CancellationToken cancellationToken = default);
+    Task<string> GenerateCurlCommandAsync(
+        string addressOrFileContents,
+        string operationId,
+        string? baseAddress,
+        CancellationToken cancellationToken = default
+    );
 }