API Tomcp

应用程序编程接口。ToMcp

一个C#源代码生成器，可以自动转换您的ASP。NET核心API端点到 模型上下文协议（MCP） 工具。

这是什么？

应用程序编程接口。ToMcp分析您现有的ASP。NET Core控制器，并生成与MCP兼容的工具类。这允许AI助手（如Claude）通过MCP协议与您的REST API交互，而无需手动编写任何集成代码。

特性

• 自动生成刀具 -在编译时扫描控制器并生成MCP工具
• 属性控制 -使用 [McpExpose] 和 [McpIgnore] 微调暴露的端点
• 灵活选择 -在allowlist之间进行选择(SelectedOnly)或阻止列表(AllExceptExcluded)模式
• 可自定义命名 -通过配置工具命名格式 generator.json
• 环路预防 -当MCP工具回调API时，内置中间件可防止无限递归
• 身份验证转发 -MCP请求的身份验证头转发到API调用

快速开始

1.安装软件包

dotnet add package Kebechet.Api.ToMcp

2.添加发电机配置

创建 Mcp/generator.json 在您的项目中：

{
  "schemaVersion": 1,
  "mode": "SelectedOnly",
  "include": [
    "ProductsController.GetAll",
    "ProductsController.GetById"
  ],
  "exclude": [],
  "naming": {
    "toolNameFormat": "{Controller}_{Action}",
    "removeControllerSuffix": true
  }
}

将其添加到您的 .csproj:

3.在Program.cs中连接

using System.Reflection;
using Api.ToMcp.Runtime;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddMcpTools(Assembly.GetExecutingAssembly());

var app = builder.Build();

app.UseMcpLoopPrevention();
app.MapControllers();
app.MapMcpEndpoint("mcp");

app.Run();

4.使用控制器上的属性

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    public Task GetAll([FromQuery] string? category = null)
    {
        // ...
    }

    [HttpGet("{id:guid}")]
    public Task GetById(Guid id)
    {
        // ...
    }

    [HttpDelete("{id:guid}")]
    [McpIgnore]  // Exclude dangerous operations
    public Task Delete(Guid id)
    {
        // ...
    }
}

配置

选择模式

命名选项

包含/排除模式

• "ProductsController" -包括/排除整个控制器
• "ProductsController.GetById" -包括/排除特定行动

属性

[McpExpose]

强制将端点作为MCP工具公开，而不管配置模式如何。

[McpExpose(Name = "GetProduct", Description = "Retrieves a product by ID")]
public Task
 GetById(Guid id) { ... }

[McpIgnore]

强制将终点排除在MCP暴露之外。

[McpIgnore]
public Task Delete(Guid id) { ... }

基于范围的访问控制

应用程序编程接口。ToMcp支持MCP工具的可选基于作用域的访问控制。作用域从HTTP方法映射而来：

默认行为

默认情况下， 不进行范围检查 -所有生成的工具都是可访问的。

启用范围验证

要启用范围验证，请配置声明到范围映射器：

using Api.ToMcp.Abstractions.Scopes;

builder.Services.AddMcpTools(Assembly.GetExecutingAssembly(), options =>
{
    options.ClaimName = "permissions"; // JWT claim name
    options.ClaimToScopeMapper = claimValue =>
    {
        var scope = McpScope.None;
        if (claimValue.Contains("read")) scope |= McpScope.Read;
        if (claimValue.Contains("write")) scope |= McpScope.Write;
        if (claimValue.Contains("delete")) scope |= McpScope.Delete;
        return scope;
    };
});

运作原理

1. MCP请求与包含索赔的JWT一起到达
2. 已配置 ClaimName 从用户的声明中读取
3. ClaimToScopeMapper 将索赔价值转换为 McpScope
4. 如果未授予工具所需的作用域（基于HTTP方法），则返回错误

JWT索赔示例

{ "permissions": "mcp:read mcp:write" }

这笔赠款 Read 和 Write 范围，但不是 Delete.

运作原理

1. 编译时：源代码生成器扫描您的控制器以查找HTTP操作
2. 代码生成：对于每个选定的端点，都会生成一个工具类，其中包含 [McpServerToolType] 属性
3. 运行时：当MCP客户端调用工具时，它会在内部通过HTTP调用您的API
4. 环路预防：The X-MCP-Internal-Call 标头阻止递归调用MCP端点

生成代码示例

对于 ProductsController.GetById(Guid id)，生成器创建：

[McpServerToolType]
public static class ProductsController_GetByIdTool
{
    [McpServerTool(Name = "Products_GetById")]
    [Description("Invokes ProductsController.GetById")]
    public static async Task InvokeAsync(
        IMcpHttpInvoker invoker,
        [Description("Parameter: id")] Guid id)
    {
        var route = $"/api/products/{Uri.EscapeDataString(id.ToString())}";
        return await invoker.GetAsync(route);
    }
}

需求

• .NET 8.0或更高版本
• ASP。NET核心

许可证

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