Zero MCP Net

ZeroMCP.net

](https://www.nuget.org/packages/ZeroMCP/) ](https://www.nuget.org/packages/ZeroMCP/)  ](https://github.com/ZeroMCP/ZeroMCP.net/stargazers)

企业级MCP支持ASP。NET核心API。

ZeroMCP允许团队将现有的控制器和最小API端点公开为MCP（模型上下文协议）工具、资源、模板和提示，而无需创建第二个服务或复制逻辑。

执行摘要

• 它解决了什么： 将LLM客户端连接到已建立的ASP。NET核心API安全快速。
• 它是如何工作的： 注释端点([Mcp], [McpResource], [McpTemplate], [McpPrompt])或使用最少的API元数据(.AsMcp, .AsResource, .AsTemplate, .AsPrompt)，然后绘制一条MCP路线。
• 企业为什么采用它： 保持现有的身份验证、策略、验证、可观察性和发布控制。

核心能力

• 通过您的真实ASP进行进程调度。NET核心管道
• 流式HTTP MCP端点(GET 和 POST)
• 本地/桌面MCP客户端的可选stdio传输
• 流媒体工具结果通过 IAsyncEnumerable
• 一个框架中的工具、资源、模板和提示
• 按工具治理（角色、策略、过滤器）
• 可观察性挂钩（相关性、日志、指标接收器、OpenTetry标签）
• 用于发现和受控测试的检查器端点
• 用于分阶段客户端迁移的版本化MCP路由

建筑概览

1. API启动发现来自控制器和最小API的MCP元数据。
2. ZeroMCP构建模式和端点描述符。
3. MCP客户端呼叫 /mcp 使用JSON-RPC方法。
4. ZeroMCP在进程中调度到您的原始端点。
5. 响应被归一化为MCP兼容的输出。

该模型保留了中间件行为，避免了“影子实现”

快速开始

1） 安装软件包

2） 注册和地图

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();

builder.Services.AddZeroMCP(options =>
{
    options.ServerName = "Orders Platform";
    options.ServerVersion = "1.0.0";
});

var app = builder.Build();

app.MapControllers();
app.MapZeroMCP(); // registers GET+POST /mcp

app.Run();

3） 将端点显示为MCP

[HttpGet("{id:int}")]
[Mcp("get_order", Description = "Retrieves an order by ID.")]
public IActionResult GetOrder(int id) => Ok(new { id });

app.MapGet("/api/health", () => Results.Ok(new { status = "ok" }))
   .AsMcp("health_check", "Returns API health status.");

企业部署指南

安全基线

• 使用现有的身份验证/授权保护MCP端点：

app.MapZeroMCP().RequireAuthorization("McpPolicy");

• 使用强制最小特权 Roles 和 Policy 关于工具元数据。
• 在受信任的环境之外禁用或限制检查器端点。
• 仅通过转发所需的安全标头 ForwardHeaders.

治理

• ToolFilter：按名称/环境排除发现时间。
• ToolVisibilityFilter：基于上下文的每个请求的动态可见性。
• 角色/策略在列表和调用边界处强制执行。
• 使用版本化路由在客户群体中运行受控切换。

可观察性和操作

• 通过可配置的标头传播关联ID。
• 围绕MCP请求生命周期和工具调用的结构化日志记录。
• IMcpMetricsSink 用于自定义遥测输出。
• 可选的OpenTetry痕迹富集功能。
• 基于SSE的长寿命MCP连接的保持活动行为。

可靠性建议

• 在ASP上设置端点身份验证和速率限制策略。NET核心层。
• 对待 /mcp 作为具有正常SLO/SLA控制的生产API表面。
• 将检查器UI置于环境检查或内部访问控制之后。
• 在客户端推出之前，通过集成测试验证关键工具流。

配置示例

builder.Services.AddZeroMCP(options =>
{
    options.ServerName = "Orders Platform";
    options.ServerVersion = "2.3.0";
    options.RoutePrefix = "/mcp";

    // Core behavior
    options.IncludeInputSchemas = true;
    options.ForwardHeaders = ["Authorization"];

    // Governance
    options.ToolFilter = name => !name.StartsWith("internal_");
    options.ToolVisibilityFilter = (name, ctx) =>
        ctx.User.IsInRole("Admin") || !name.StartsWith("admin_");

    // Observability
    options.CorrelationIdHeader = "X-Correlation-ID";
    options.EnableOpenTelemetryEnrichment = true;

    // Optional MCP capabilities
    options.EnableResources = true;
    options.EnablePrompts = true;
    options.EnableToolInspector = false;
    options.EnableToolInspectorUI = false;
});

支持的MCP表面

• initialize
• tools/list, tools/call
• resources/list, resources/templates/list, resources/read
• resources/subscribe, resources/unsubscribe （启用时）
• prompts/list, prompts/get
• 通知流，如列表更改更新（启用时）

运输选项

流式HTTP（默认）

• GET /mcp 用于元数据和SSE场景
• POST /mcp JSON-RPC方法

stdio（可选）

if (args.Contains("--mcp-stdio"))
{
    await app.RunMcpStdioAsync();
    return;
}

对于直接生成服务流程的本地优先MCP客户端很有用。

克劳德桌面stdio示例

{
  "mcpServers": {
    "orders-api": {
      "command": "dotnet",
      "args": ["run", "--project", "ZeroMCP.Sample", "--", "--mcp-stdio"]
    }
  }
}

有关完整的客户端设置选项（stdio和HTTP），请参阅 wiki/Connecting-Clients.md.

检查器端点

• GET /mcp/tools：JSON工具和模式清单
• GET /mcp/ui：基于浏览器的调用UI

建议用法：仅在开发和内部测试环境中启用。

版本控制和兼容性

• 语义版本控制策略在中定义 VERSIONING.md.
• MCP协议行为是通过显式兼容性测试实现的。
• 版本化端点支持允许客户端不中断迁移路径。

解决方案布局

• ZeroMCP/：核心框架包（NuGet工件源）
• ZeroMCP.Sample/：具有实用模式的参考主机
• ZeroMCP.Tests/：集成和模式/兼容性测试
• examples/：重点场景示例：

- Minimal - WithAuth - WithEnrichment - WithStdio - WithRateLimiting - Enterprise

• wiki/：实施和运营文件
• progress.md：持久工程变更日志

[Mcp] 属性快速参考

[Mcp] 支持所需的工具名称以及用于可发现性和治理的可选元数据。

[Mcp(
    "create_order",
    Description = "Creates an order.",
    Tags = new[] { "orders", "write" },
    Category = "orders",
    Examples = new[] { "Create order for Alice, quantity 2" },
    Hints = new[] { "idempotent", "cost=low" },
    Roles = new[] { "Admin" },
    Policy = "RequireEditor",
    Version = 2
)]

详细信息： wiki/The-Mcp-Attribute.md.

其他属性快速参考

在从控制器操作中暴露MCP资源和提示时使用这些：

[McpResource("catalog://info", "catalog_info",
    Description = "Returns catalog metadata.",
    MimeType = "application/json")]

[McpTemplate("catalog://products/{id}", "product_resource",
    Description = "Returns a product by ID.",
    MimeType = "application/json")]

[McpPrompt("restock_recommendation_prompt",
    Description = "Generates a restock recommendation prompt.")]

最低API当量：

app.MapGet("/api/catalog/info", () => Results.Ok(...))
   .AsResource("catalog://info", "catalog_info", "Returns catalog metadata.", mimeType: "application/json");

app.MapGet("/api/catalog/products/{id:int}", (int id) => Results.Ok(...))
   .AsTemplate("catalog://products/{id}", "product_resource", "Returns a product by ID.", mimeType: "application/json");

app.MapGet("/api/catalog/prompts/restock/{productId:int}", (int productId) => Results.Ok(...))
   .AsPrompt("restock_recommendation_prompt", "Generates a restock recommendation prompt.");

详细信息： wiki/Resources-and-Prompts.md.

构建和测试

dotnet build ZeroMCP.slnx -v detailed
dotnet test ZeroMCP.Tests/ZeroMCP.Tests.csproj -v detailed

集成测试包括MCP流式HTTP行为（例如GET /mcp 随着 Accept: text/event-stream 和 Mcp-Session-Id, resources/subscribe 带有会话头，以及 notifications/resources/updated 在SSE频道上）。看 McpResourceSubscriptionTests 和 McpClientCompatibilityTests 在 ZeroMCP.Tests/.

文档地图

• 软件包自述： ZeroMCP/README.md
• 配置： wiki/Configuration.md
• 安全模型： wiki/Security-Model.md
• 企业使用情况： wiki/Enterprise-Usage.md
• 工具版本控制： wiki/Tool-Versioning.md
• 资源和提示： wiki/Resources-and-Prompts.md

贡献

值得欢迎的贡献，尤其是在协议兼容性强化、最小API绑定奇偶性和以生产为重点的样本方面。请在每次功能更改时包括集成测试和文档更新。