Open API MCP Net

OpenApiMcpNet

A.NET库，自动生成 模型上下文协议（MCP） OpenAPI规范中的工具。这允许AI助手和LLM与任何具有OpenAPI（Swagger）规范的REST API交互。

特性

• 自动生成刀具：自动将OpenAPI操作转换为MCP兼容工具
• 完全支持OpenAPI：处理路径、查询、标头和cookie参数，以及请求正文
• 身份验证支持：内置对OAuth 1.0a和OAuth 2.0的支持（客户端凭据流）
• 可扩展架构：可以注入自定义身份验证处理程序和web API调用程序
• 流利的API：通过简单、可链接的配置 IMcpServerBuilder 扩展

安装

dotnet add package OpenApiMcpNet

快速开始

基本用法

using Microsoft.Extensions.DependencyInjection;
using ModelContextProtocol.Server;
using OpenApiMcpNet;

var builder = Host.CreateApplicationBuilder(args);

// Add MCP server with tools from OpenAPI spec
builder.Services.AddMcpServer()
    .WithToolsFromOpenApi(openApiSpecJson, "https://api.example.com");

var host = builder.Build();
await host.RunAsync();

从文件或URL加载OpenAPI规范

// From a string
builder.Services.AddMcpServer()
    .WithToolsFromOpenApi(openApiSpecJsonOrYaml, "https://api.example.com");

// From a stream
using var stream = File.OpenRead("openapi.yaml");
builder.Services.AddMcpServer()
    .WithToolsFromOpenApi(stream, "https://api.example.com");

// From an OpenApiDocument
var reader = new OpenApiStringReader();
var document = reader.Read(openApiSpec, out var diagnostic);
builder.Services.AddMcpServer()
    .WithToolsFromOpenApi(document, "https://api.example.com");

认证

OAuth 2.0（客户端凭据）

var authHandler = new OAuth2AuthenticationHandler(
    httpClient,
    tokenEndpoint: "https://auth.example.com/oauth/token",
    consumerKey: "your-client-id",
    consumerSecret: "your-client-secret",
    scope: "read write" // optional
);

// Authenticate before making requests
await authHandler.AuthenticateAsync();

// Register with DI
builder.Services.AddSingleton(authHandler);

OAuth 1.0a

var authHandler = new OAuth1AuthenticationHandler(
    httpClient,
    requestTokenUrl: "https://api.example.com/oauth/request_token",
    accessTokenUrl: "https://api.example.com/oauth/access_token",
    consumerKey: "your-consumer-key",
    consumerSecret: "your-consumer-secret",
    signatureMethod: "HMAC-SHA1"
);

await authHandler.AuthenticateAsync();

builder.Services.AddSingleton(authHandler);

自定义身份验证

实施 IAuthenticationHandler 或 IRequestAuthenticationHandler 对于自定义身份验证：

public class ApiKeyAuthenticationHandler : IAuthenticationHandler
{
    private readonly string _apiKey;

    public bool IsAuthenticated => true;

    public ApiKeyAuthenticationHandler(string apiKey)
    {
        _apiKey = apiKey;
    }

    public Task AuthenticateAsync() => Task.CompletedTask;

    public void AuthenticateRequest(
        HttpRequestMessage request,
        IEnumerable> queryParameters,
        IEnumerable> bodyParameters)
    {
        request.Headers.Add("X-API-Key", _apiKey);
    }
}

运作原理

1. 解析OpenAPI规范：库读取您的OpenAPI规范（JSON或YAML）
2. 生成工具：规范中的每个操作都成为MCP工具，具有：

- 名字：源自 operationId 或由方法+路径生成 - 描述：来自 summary 或 description 在规范中 - 输入模式：根据参数和请求正文模式自动生成

1. 处理请求：当AI调用工具时，库：

- 将参数映射到正确的位置（路径、查询、标头、正文） - 应用身份验证 - 发出HTTP请求 - 以结构化JSON返回响应

API 参考

扩展方法

WithToolsFromOpenApi(string openApiSpec, string baseUrl)

从OpenAPI规范字符串中注册MCP工具。

WithToolsFromOpenApi(Stream openApiSpecStream, string baseUrl)

从OpenAPI规范流中注册MCP工具。

WithToolsFromOpenApi(OpenApiDocument openApiDocument, string baseUrl)

从解析的OpenAPI文档中注册MCP工具。

接口

IAuthenticationHandler

在发出请求之前需要进行身份验证的身份验证处理程序的接口。

public interface IAuthenticationHandler
{
    bool IsAuthenticated { get; }
    Task AuthenticateAsync();
    void AuthenticateRequest(HttpRequestMessage request, ...);
}

IWebApiCaller

用于向web API发出HTTP请求的接口。

public interface IWebApiCaller
{
    Task CallApiAsync(WebApiMetadata apiMetadata, IDictionary parameters, CancellationToken cancellationToken);
}

示例

给定这个OpenAPI操作：

paths:
  /users/{id}:
    get:
      operationId: GetUser
      summary: Gets a user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        200:
          description: The user

库生成一个MCP工具：

• 名字: GetUser
• 描述: Gets a user by ID
• 输入模式: { "id": { "type": "integer" } }

当被呼叫时 { "id": 123 }，它使a GET 请求 /users/123.

需求

• .NET 8.0或更高版本
• 模型上下文协议 0.5.0-复习.1或更高版本
• 微软。OpenApi。读者 1.6.28或更高版本

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

贡献

欢迎投稿！请随时提交拉取请求。