dotnet-campus · walterlv · Apr 3, 2026 · Apr 3, 2026 · Apr 3, 2026 · Apr 3, 2026
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -42,7 +42,7 @@ src/DotNetCampus.ModelContextProtocol/
   - 代码主要以最新版本协议进行编写
   - 遇到需要兼容旧协议的部分，用 `Legacy` 命名相关代码并尽量减少代码量
 - **协议消息类型规范**：详见 [/docs/knowledge/protocol-messages-guide.md](../docs/knowledge/protocol-messages-guide.md)
-  - 所有 Protocol 消息类型必须添加中英双语注释
+  - **仅** `Protocol/` 文件夹下的消息类型必须添加中英双语注释；其他所有代码（接口、实现类、传输层等）一律使用**纯中文注释**（注：当前存在一些遗留非协议代码仍使用双语注释，如果改到了相关代码，请顺手改为纯中文注释）
   - 英文注释必须使用 MCP 官方 Schema 原文
   - 当前使用协议版本：**2025-11-25**
   - Schema 文件：[schema.ts](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-11-25/schema.ts)
@@ -75,8 +75,9 @@ src/DotNetCampus.ModelContextProtocol/
 
 ## 参考资源
 
-- [MCP 官方规范 (2025-06-18)](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports) - **当前使用版本**
-- [MCP Schema (2025-06-18)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-06-18/schema.ts) - **官方消息类型定义**
+- [MCP 官方规范 (2025-11-25)](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) - **当前使用版本**
+- [MCP Schema (2025-11-25)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-11-25/schema.ts) - **官方消息类型定义**
+- [MCP 官方规范 (2025-06-18)](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports) - 旧版本（兼容支持）
 - [MCP 官方规范 (2024-11-05)](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports) - 旧版本（兼容支持）
 - [JSON-RPC 2.0 规范](https://www.jsonrpc.org/specification)
 - [SSE 标准](https://html.spec.whatwg.org/multipage/server-sent-events.html)

diff --git a/README.md b/README.md
@@ -1,12 +1,13 @@
 # DotNetCampus.ModelContextProtocol
 
-[![.NET Build and Test](https://github.com/dotnet-campus/DotNetCampus.ModelContextProtocol/actions/workflows/dotnet-build.yml/badge.svg)](https://github.com/dotnet-campus/DotNetCampus.ModelContextProtocol/actions/workflows/dotnet-build.yml) [![NuGet](https://img.shields.io/nuget/v/DotNetCampus.ModelContextProtocol.svg?label=DotNetCampus.ModelContextProtocol)](https://www.nuget.org/packages/DotNetCampus.ModelContextProtocol)
+[![.NET Build and Test](https://github.com/dotnet-campus/DotNetCampus.ModelContextProtocol/actions/workflows/dotnet-build.yml/badge.svg)](https://github.com/dotnet-campus/DotNetCampus.ModelContextProtocol/actions/workflows/dotnet-build.yml) [![NuGet](https://img.shields.io/nuget/v/DotNetCampus.ModelContextProtocol.svg?label=DotNetCampus.ModelContextProtocol)](https://www.nuget.org/packages/DotNetCampus.ModelContextProtocol) [![NuGet](https://img.shields.io/nuget/v/DotNetCampus.ModelContextProtocol.Ipc.svg?label=DotNetCampus.ModelContextProtocol.Ipc)](https://www.nuget.org/packages/DotNetCampus.ModelContextProtocol.Ipc) [![NuGet](https://img.shields.io/nuget/v/DotNetCampus.ModelContextProtocol.TouchSocket.Http.svg?label=DotNetCampus.ModelContextProtocol.TouchSocket.Http)](https://www.nuget.org/packages/DotNetCampus.ModelContextProtocol.TouchSocket.Http)
 
-| [English][en] | [简体中文][zh-hans] |
-| ------------- | ------------------- |
+| [English][en] | [简体中文][zh-hans] | [繁體中文][zh-hant] |
+| ------------- | ------------------- | ------------------- |
 
-[en]: /docs/en/QuickStart.md
-[zh-hans]: /docs/zh-hans/QuickStart.md
+[en]: /docs/en/README.md
+[zh-hans]: /docs/zh-hans/README.md
+[zh-hant]: /docs/zh-hant/README.md
 
 A lightweight, zero-dependency yet full-featured MCP protocol implementation built with .NET. It can be easily integrated into your application, regardless of its architecture.
 
@@ -25,87 +26,56 @@ A lightweight, zero-dependency yet full-featured MCP protocol implementation bui
 dotnet add package DotNetCampus.ModelContextProtocol
 ```
 
-### Quick Start
+## Quick Start
 
-A typical MCP server program looks like this:
+### Server
 
 ```csharp
-internal class Program
-{
-    private static async Task Main(string[] args)
-    {
-        // The server name and version will be sent to clients via the MCP protocol
-        var mcpServer = new McpServerBuilder("Sample Server", "1.0.0")
-            // If your MCP tool parameters and return values use custom types, you need to provide a JSON serialization context
-            .WithJsonSerializer(McpToolJsonContext.Default)
-            .WithTools(t => t
-                // Register various MCP tools
-                .WithTool(() => new SampleTools())
-                .WithTool(() => new SampleTools2())
-            )
-            // Use Streamable HTTP transport, listening on http://localhost:5943/mcp
-            // Also compatible with SSE, listening on http://localhost:5943/mcp/sse
-            .WithLocalHostHttp(5943, "mcp")
-            // You can also use stdio (standard input/output) transport, which is recommended by the MCP protocol for all MCP servers
-            // However, it's generally not recommended to enable both http and stdio simultaneously,
-            // as the former typically requires singleton execution while the latter must support multiple instances
-            // .WithStdio()
-            .Build();
-#if DEBUG
-        // Enable debug mode so that when the MCP server encounters exceptions, it returns exception information to clients for easier debugging
-        // It's generally not recommended to enable this mode in production, as it would expose internal implementation details of the server
-        mcpServer.EnableDebugMode();
-#endif
-        // Run the MCP server
-        await mcpServer.RunAsync();
-    }
-}
+var mcpServer = new McpServerBuilder("Sample Mcp Server", "1.0.0")
+    .WithTools(tools => tools.WithTool(() => new SampleTools()))
+    .WithLocalHostHttp(5943, "mcp")
+    .Build();
 
-[JsonSerializable(typeof(Foo))]
-[JsonSerializable(typeof(Bar))]
-[JsonSourceGenerationOptions(
-    // Recommended: Most MCP protocol implementations use camelCase naming
-    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
-    // Recommended: Most MCP protocol implementations use string enums
-    UseStringEnumConverter = true,
-    // Recommended: Cannot guarantee AI will always put metadata properties first
-    AllowOutOfOrderMetadataProperties = true
-    // If you plan to use less capable models, you can also enable the following options
-    // PropertyNameCaseInsensitive = true,
-    // NumberHandling = JsonNumberHandling.AllowReadingFromString
-    )]
-internal partial class McpToolJsonContext : JsonSerializerContext;
-```
-
-### Declaring MCP Tool Methods
+await mcpServer.RunAsync();
 
-```csharp
 public class SampleTools
 {
     /// <summary>
-    /// A tool for AI debugging that echoes back information as-is
+    /// 原样返回输入文本。
     /// </summary>
-    /// <param name="text">The string to echo back</param>
-    /// <returns>The echoed string</returns>
+    /// <param name="text">要原样返回的字符串</param>
     [McpServerTool(ReadOnly = true)]
-    public string Echo(string text)
+    public string EchoTool(string text)
     {
         return text;
     }
 }
 ```
 
-### Advanced Usage
+### Client
+
+```csharp
+var client = new McpClientBuilder("Sample Mcp Client", "1.0.0")
+    .WithHttp("http://localhost:5943/mcp")
+    .Build();
+
+var arguments = JsonSerializer.SerializeToElement(new { text = "Hello, MCP!" });
+var result = await client.CallToolAsync("echo_tool", arguments);
+
+Console.WriteLine(result.Content);
+```
+
+## Documentation
 
-For advanced usage including supported types for parameters and return values, type polymorphism, and more, please refer to the [Quick Start Guide](docs/quickstart/README.md)
+See [docs/en/README.md](docs/en/README.md) for the full documentation index.
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome. Please feel free to submit a pull request.
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
 
 ## About dotnet-campus
 

diff --git a/build/Version.props b/build/Version.props
@@ -1,5 +1,5 @@
 <Project>
   <PropertyGroup>
-    <Version>0.1.0</Version>
+    <Version>0.0.0</Version>
   </PropertyGroup>
 </Project>
diff --git a/docs/McpClient设计方案.md b/docs/McpClient设计方案.md
diff --git a/docs/en/Authorization.md b/docs/en/Authorization.md
@@ -0,0 +1,5 @@
+# Authorization
+
+MCP Authorization enables the client and server to complete authentication and authorization before or during a connection.
+
+> The current version does not yet provide built-in Authorization support (planned). In the meantime, you can implement authentication logic yourself using custom HTTP headers (via `HttpClientTransportOptions`'s `HttpClient`) or `WithRequestHandlers` interceptors.
diff --git a/docs/en/DependencyInjection.md b/docs/en/DependencyInjection.md
@@ -0,0 +1,128 @@
+# Dependency Injection
+
+The MCP library's dependency injection is entirely implemented by **compile-time source generators**, with **zero runtime reflection**. This document explains how it works, how to use it, and how it differs from conventional DI containers.
+
+## Core Principle
+
+When you write:
+
+```csharp
+var mcpServer = new McpServerBuilder("Example Server", "1.0.0")
+    .WithServices(appServiceProvider)
+    .WithTools(tools => tools
+        .WithTool<MyTool>()
+        .WithTool<MyOtherTool>())
+    .Build();
+```
+
+What actually happens at compile time:
+
+1. **`WithServices(IServiceProvider)`** merely stores your `IServiceProvider` reference — **no service registration or container scanning** occurs.
+2. **`WithTool<MyTool>()`** has a method body that is literally `throw new InvalidOperationException()` (never executed). The C# 12 **Interceptors** feature intercepts this call at compile time.
+3. **The compile-time generated interceptor code** uses Roslyn to analyze `MyTool`'s constructor signature and generates explicit `serviceProvider.GetService(typeof(TParam))` calls for each constructor parameter.
+
+> **Key takeaway: Tool classes do NOT need to be registered in the DI container.** The `IServiceProvider` is only used to resolve the **parameter types** of the tool's constructor (such as `ILogger`, `HttpClient`, etc.).
+
+## Two Injection Approaches
+
+### Approach 1: Constructor Injection (`WithTool<T>()`, Recommended)
+
+Best for tool classes with multiple shared dependencies. The source generator (`WithToolInterceptorGenerator`) finds the constructor at compile time and generates `GetService` calls for each parameter:
+
+```csharp
+// User code
+public class MyTool
+{
+    private readonly ILogger _logger;
+    private readonly IDataService _dataService;
+
+    public MyTool(ILogger logger, IDataService dataService)
+    {
+        _logger = logger;
+        _dataService = dataService;
+    }
+
+    /// <summary>
+    /// Process input and return result.
+    /// </summary>
+    [McpServerTool]
+    public string DoSomething(string input)
+    {
+        _logger.Info($"processing: {input}");
+        return _dataService.Process(input);
+    }
+}
+
+// Registration — no factory needed
+builder.WithServices(appServiceProvider);
+builder.WithTool<MyTool>();  // Interceptor auto-generates DI code
+```
+
+Equivalent code generated at compile time (simplified):
+
+```csharp
+// Generated by interceptor at compile time, zero runtime reflection
+var factory = () => new MyTool(
+    (ILogger?)serviceProvider.GetService(typeof(ILogger))
+        ?? throw new InvalidOperationException("Unable to resolve ILogger."),
+    (IDataService?)serviceProvider.GetService(typeof(IDataService))
+        ?? throw new InvalidOperationException("Unable to resolve IDataService."));
+```
+
+### Approach 2: Parameter Injection (`[ToolParameter(Type = ToolParameterType.Injected)]`)
+
+Best when only a few parameters need DI. The source generator (`McpServerToolSourceBuilder`) generates independent `GetService` calls for each injected parameter:
+
+```csharp
+public class SampleTools
+{
+    [McpServerTool]
+    public string FormatMessage(
+        string text,
+        [ToolParameter(Type = ToolParameterType.Injected)] ILogger logger)
+    {
+        logger.Info($"formatting: {text}");
+        return text.ToUpper();
+    }
+}
+```
+
+Equivalent code generated at compile time:
+
+```csharp
+// Nullable types → TryGetService, returns null on resolution failure
+var logger = context.TryGetService<ILogger>();
+
+// Non-nullable types → EnsureGetService, throws on resolution failure
+var requiredService = context.EnsureGetService<IRequiredService>("IRequiredService");
+```
+
+## What You Need to Configure
+
+| Action | Required? | Notes |
+|--------|-----------|-------|
+| Register tool types in DI container | **No** | Source generator has already analyzed constructors; `new` is used directly at runtime |
+| Register constructor parameter types in DI container | **Yes** | Types like `ILogger`, `IDataService` must be resolvable from `IServiceProvider` |
+| Call `WithServices()` | **Yes** | Passes your `IServiceProvider` to the MCP server |
+| Call `WithTool<T>()` (without factory) | **Yes** | Triggers the source generator to emit DI code for this type |
+| Call `WithTool(() => new MyTool(dep1))` | Optional | Manual instantiation; no `IServiceProvider` needed |
+
+## Comparison with Conventional DI Containers
+
+| | Conventional DI (e.g. `Microsoft.Extensions.DI`) | MCP Library |
+|---|---|---|
+| Service discovery | Runtime assembly scanning | Compile-time Roslyn source analysis |
+| Instance creation | Runtime `Activator.CreateInstance` | Compile-time `new T(...)` expressions |
+| Tool registration | `services.AddTransient<MyTool>()` | **Not needed** |
+| Parameter injection | Container recursive type-tree resolution | Compile-time generated `serviceProvider.GetService(typeof(T))` |
+| Resolution failure | Runtime exception | Nullable params return `null`; non-nullable throw |
+
+## Safety
+
+If the `WithTool<T>()` interceptor is missing (e.g., forgot to reference the Analyzer NuGet package), the actual method body is `throw new InvalidOperationException` — the application fails immediately at startup with a clear error, rather than silently using the wrong resolution mechanism.
+
+## Why Not Reflection
+
+1. **AOT-compatible**: No `Activator.CreateInstance` or assembly scanning; fully compatible with NativeAOT compilation.
+2. **Compile-time error detection**: Unresolvable constructor parameters produce `#error` at compile time, no need to wait until runtime.
+3. **Zero overhead**: Generated code performs identically to hand-written `new MyTool(dep1, dep2)`.
diff --git a/docs/en/Elicitation.md b/docs/en/Elicitation.md
@@ -0,0 +1,5 @@
+# Elicitation
+
+MCP Elicitation allows the server to request additional information from the client, which the client then collects from the user.
+
+> The current version has not yet implemented Elicitation (planned).