# MCPExample

**Repository Path**: zzyyu/mcpexample

## Basic Information

- **Project Name**: MCPExample
- **Description**: MCP example，基于2025-11-25最新版本
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-14
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCPExample：使用 C# 和 .NET 8 渐进学习 MCP

这是一个与业务无关的 Model Context Protocol（MCP）学习仓库。它使用 C#、.NET 8 和官方 MCP C# SDK 1.4.1，通过同一组示例对比 stdio 与 Streamable HTTP 两种传输方式。

项目不连接大模型，不需要 API Key、数据库或外部服务。控制台客户端直接调用 MCP 协议，因此可以把注意力集中在 MCP 本身。

## 你将学到什么

- MCP Client、Server、Host 和 Capability 分别负责什么。
- MCP 如何使用 JSON-RPC 完成初始化、能力发现和调用。
- 如何用 C# 定义 Tools、Resources 与 Prompts。
- stdio 与 Streamable HTTP 的运行方式和适用场景。
- 如何使用官方 MCP Client 编写不依赖模型的协议客户端。
- 如何通过单元测试与真实传输集成测试验证 MCP 服务。

## 环境要求

- .NET 8 SDK。
- macOS、Linux 或 Windows 终端。
- Git 仅在需要提交练习时使用。

确认环境：

```bash
dotnet --version
```

输出应为 `8.0.*`。如果不是，请先阅读 [常见问题](docs/troubleshooting.md)。

## 五分钟快速开始

```bash
git clone https://gitee.com/zzyyu/mcpexample.git
cd mcpexample
dotnet restore
dotnet build --no-restore
dotnet test --no-build
```

测试覆盖纯功能逻辑、stdio 进程通信和 Streamable HTTP 通信。

## 运行 stdio 演示

先完成一次构建，然后启动客户端：

```bash
dotnet build
dotnet run --no-build --project src/McpExample.Client
```

客户端会启动 `McpExample.Server.Stdio` 子进程，完成初始化，并依次展示 Tools、Resources、Prompts。正常结束时会看到：

```text
服务端：MCPExample 1.0.0
Tools
Resources
Prompts
演示完成
```

stdio 的标准输出承载 JSON-RPC，普通日志只能写入标准错误流。客户端结束后，服务端子进程也会结束。

## 运行 Streamable HTTP 演示

在第一个终端启动服务端：

```bash
dotnet run --no-build --project src/McpExample.Server.Http --urls http://localhost:5000
```

可先检查健康状态：

```bash
curl http://localhost:5000/health
```

在第二个终端启动客户端：

```bash
dotnet run --no-build --project src/McpExample.Client -- \
  --transport http \
  --url http://localhost:5000/mcp
```

MCP 端点是 `/mcp`。本示例使用无状态 Streamable HTTP，不启用旧版 SSE 端点。

## 示例能力

| 类型 | 名称或 URI | 用途 |
| --- | --- | --- |
| Tool | `add_numbers` | 学习参数 schema 与结构化结果 |
| Tool | `analyze_text` | 学习输入校验与多字段结果 |
| Tool | `delayed_echo` | 学习异步调用与取消 |
| Resource | `learning://overview` | 学习固定资源 |
| Resource Template | `learning://topics/{topic}` | 学习 URI 模板 |
| Prompt | `explain_mcp_concept` | 学习参数化提示模板 |
| Prompt | `review_code` | 学习多角色消息 |

Prompt 只生成消息模板。客户端会显示结果，但不会将结果发送给任何模型。

## 项目结构

```text
src/
├── McpExample.Features/       # 共享 Tools、Resources、Prompts
├── McpExample.Server.Stdio/   # stdio 宿主
├── McpExample.Server.Http/    # Streamable HTTP 宿主
└── McpExample.Client/         # 纯 MCP 控制台客户端
tests/
└── McpExample.Tests/          # 单元测试与集成测试
docs/                          # 中文专题文档
LEARNING_PATH.md               # 八阶段渐进式学习入口
```

## 文档导航

建议先打开 [渐进式学习路线](LEARNING_PATH.md)，再按顺序阅读：

1. [MCP 基础概念](docs/01-mcp-foundations.md)
2. [stdio 服务端](docs/02-stdio-server.md)
3. [Tools](docs/03-tools.md)
4. [Resources](docs/04-resources.md)
5. [Prompts](docs/05-prompts.md)
6. [Streamable HTTP](docs/06-streamable-http.md)
7. [控制台客户端](docs/07-client.md)
8. [测试与调试](docs/08-testing-and-debugging.md)
9. [常见问题](docs/troubleshooting.md)

## 测试与格式检查

```bash
dotnet restore
dotnet build --no-restore
dotnet test --no-build
dotnet format --verify-no-changes
git diff --check
```

只运行某一组测试：

```bash
dotnet test --filter FullyQualifiedName~LearningToolsTests
dotnet test --filter FullyQualifiedName~StdioServerTests
dotnet test --filter FullyQualifiedName~HttpServerTests
```

## 官方参考资料

- [Model Context Protocol 官方文档](https://modelcontextprotocol.io/)
- [MCP C# SDK 官方文档](https://csharp.sdk.modelcontextprotocol.io/)
- [MCP C# SDK 源码](https://github.com/modelcontextprotocol/csharp-sdk)
- [MCP 规范](https://modelcontextprotocol.io/specification/)

## 许可证说明

本仓库用于学习和演示。依赖的官方 MCP C# SDK 使用其自身许可证；使用前请同时查阅对应上游项目的许可证。