# ZeroMCP.net

**Repository Path**: yanzhengyu/ZeroMCP.net

## Basic Information

- **Project Name**: ZeroMCP.net
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-07
- **Last Updated**: 2026-04-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ZeroMCP.net

[![NuGet 版本](https://img.shields.io/nuget/v/ZeroMCP.svg)](https://www.nuget.org/packages/ZeroMCP/)
[![NuGet 下载量](https://img.shields.io/nuget/dt/ZeroMCP.svg)](https://www.nuget.org/packages/ZeroMCP/)
[![许可证: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ZeroMCP/ZeroMCP.net/blob/main/LICENSE)
[![GitHub Stars](https://img.shields.io/github/stars/ZeroMCP/ZeroMCP.net?style=social)](https://github.com/ZeroMCP/ZeroMCP.net/stargazers)

面向 ASP.NET Core API 的企业级 MCP 赋能方案。

ZeroMCP 让团队能够将现有的控制器和最小化 API 端点暴露为 MCP(模型上下文协议)工具、资源、模板和提示词,无需创建第二个服务或复制逻辑。

## 执行摘要

- **解决的问题:** 安全快速地将 LLM 客户端连接到已建立的 ASP.NET Core API。
- **工作原理:** 为端点添加注解(`[Mcp]`、`[McpResource]`、`[McpTemplate]`、`[McpPrompt]`)或使用最小化 API 元数据(`.AsMcp`、`.AsResource`、`.AsTemplate`、`.AsPrompt`),然后映射一个 MCP 路由。
- **企业采用的原因:** 保持现有的身份验证、策略、验证、可观测性和发布控制到位。

## 核心能力

- 通过真实的 ASP.NET Core 管道进行进程内调度
- 可流式传输的 HTTP MCP 端点(`GET` 和 `POST`)
- 可选的 stdio 传输层,用于本地/桌面 MCP 客户端
- 通过 `IAsyncEnumerable<T>` 实现流式工具结果
- 在一个框架中支持工具、资源、模板和提示词
- 每个工具的治理(角色、策略、过滤器)
- 可观测性钩子(关联 ID、日志、指标接收器、OpenTelemetry 标签)
- 用于发现和受控测试的检查器端点
- 版本化的 MCP 路由,支持分阶段客户端迁移

## 架构概览

1. API 启动时从控制器和最小化 API 发现 MCP 元数据。
2. ZeroMCP 构建模式和端点描述符。
3. MCP 客户端使用 JSON-RPC 方法调用 `/mcp`。
4. ZeroMCP 在进程内调度到原始端点。
5. 响应被规范化回 MCP 兼容输出。

此模型保留了中间件行为,避免了"影子实现"。

## 快速开始

### 1) 安装 NuGet 包

```xml
<PackageReference Include="ZeroMCP" Version="1.*" />
```

### 2) 注册和映射

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

builder.Services.AddZeroMCP(options =>
{
    options.ServerName = "订单平台";
    options.ServerVersion = "1.0.0";
});

var app = builder.Build();

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

app.Run();
```

### 3) 将端点暴露为 MCP

```csharp
[HttpGet("{id:int}")]
[Mcp("get_order", Description = "根据 ID 检索订单。")]
public IActionResult GetOrder(int id) => Ok(new { id });

app.MapGet("/api/health", () => Results.Ok(new { status = "ok" }))
   .AsMcp("health_check", "返回 API 健康状态。");
```

## 企业部署指南

### 安全基线

- 使用现有身份验证/授权保护 MCP 端点:

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

- 通过工具元数据上的 `Roles` 和 `Policy` 实施最小权限原则。
- 在非受信环境外禁用或限制检查器端点。
- 仅通过 `ForwardHeaders` 转发所需的安全标头。

### 治理

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

### 可观测性和运维

- 通过可配置的标头传播实现关联 ID。
- 围绕 MCP 请求生命周期和工具调用的结构化日志。
- `IMcpMetricsSink` 用于自定义遥测导出。
- 可选的 OpenTelemetry 丰富功能用于追踪。
- 基于 SSE 的保活行为,用于长寿命 MCP 连接。

### 可靠性建议

- 在 ASP.NET Core 层设置端点身份验证和速率限制策略。
- 将 `/mcp` 视为具有正常 SLO/SLA 控制的生产 API 表面。
- 将检查器 UI 置于环境检查或内部访问控制之后。
- 在客户端推出之前,使用集成测试验证关键工具流程。

## 配置示例

```csharp
builder.Services.AddZeroMCP(options =>
{
    options.ServerName = "订单平台";
    options.ServerVersion = "2.3.0";
    options.RoutePrefix = "/mcp";

    // 核心行为
    options.IncludeInputSchemas = true;
    options.ForwardHeaders = ["Authorization"];

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

    // 可观测性
    options.CorrelationIdHeader = "X-Correlation-ID";
    options.EnableOpenTelemetryEnrichment = true;

    // 可选 MCP 功能
    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(可选)

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

适用于直接生成服务进程的本地优先 MCP 客户端。

#### Claude Desktop stdio 示例

```json
{
  "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]` 支持必需的工具名称以及用于可发现性和治理的可选元数据。

```csharp
[Mcp(
    "create_order",
    Description = "创建订单。",
    Tags = new[] { "orders", "write" },
    Category = "orders",
    Examples = new[] { "为 Alice 创建订单,数量 2" },
    Hints = new[] { "idempotent", "cost=low" },
    Roles = new[] { "Admin" },
    Policy = "RequireEditor",
    Version = 2
)]
```

完整详情: `wiki/The-Mcp-Attribute.md`。

## 其他属性快速参考

当从控制器操作暴露 MCP 资源和提示词时使用这些:

```csharp
[McpResource("catalog://info", "catalog_info",
    Description = "返回目录元数据。",
    MimeType = "application/json")]

[McpTemplate("catalog://products/{id}", "product_resource",
    Description = "根据 ID 返回产品。",
    MimeType = "application/json")]

[McpPrompt("restock_recommendation_prompt",
    Description = "生成补货建议提示词。")]
```

最小化 API 等效项:

```csharp
app.MapGet("/api/catalog/info", () => Results.Ok(...))
   .AsResource("catalog://info", "catalog_info", "返回目录元数据。", mimeType: "application/json");

app.MapGet("/api/catalog/products/{id:int}", (int id) => Results.Ok(...))
   .AsTemplate("catalog://products/{id}", "product_resource", "根据 ID 返回产品。", mimeType: "application/json");

app.MapGet("/api/catalog/prompts/restock/{productId:int}", (int productId) => Results.Ok(...))
   .AsPrompt("restock_recommendation_prompt", "生成补货建议提示词。");
```

完整详情: `wiki/Resources-and-Prompts.md`。

## 构建和测试

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

## 文档地图

- 包自述文件: `ZeroMCP/README.md`
- 配置: `wiki/Configuration.md`
- 安全模型: `wiki/Security-Model.md`
- 企业用法: `wiki/Enterprise-Usage.md`
- 工具版本控制: `wiki/Tool-Versioning.md`
- 资源和提示词: `wiki/Resources-and-Prompts.md`

## 贡献

欢迎贡献,特别是在协议兼容性强化、最小化 API 绑定对等性和面向生产的示例方面。请在每次功能更改时包含集成测试和文档更新。