Template MCP (Mcprunner)

模板MCP服务器

用于创建模型上下文协议（MCP）服务器的基本C#API模板，基于 mssqlMCP 架构和使用相同的包和版本。

概述

此模板为在C#中构建可以与VS Code和GitHub Copilot集成的MCP服务器提供了一个起点。它包括核心基础设施、依赖注入设置以及遵循与mssqlMCP项目相同模式的示例工具。

特性

• MCP服务器实现：使用ModelContextProtocol构建。AspNetCore（v0.1.0-review.13）
• 双重运输支持：HTTP和Stdio传输
• 结构化日志记录：使用Serilog进行控制台和文件输出
• 依赖注入：干净的架构，关注点分离
• CORS支持：可配置的跨源资源共享
• 示例工具：演示模式的MCP工具示例

先决条件

• .NET 9.0 SDK或更高版本
• Visual Studio代码（可选，用于Copilot集成）

项目结构

templateMCP/
├── Configuration/          # Configuration providers
├── Extensions/            # Service collection extensions
├── Interfaces/            # Service interfaces
├── Models/               # Data models
├── Tools/                # MCP tool implementations
├── Logs/                 # Log files (generated at runtime)
├── appsettings.json      # Application configuration
├── appsettings.Development.json  # Development configuration
├── Program.cs            # Application entry point
└── templateMCP.csproj    # Project file

入门指南

1.安装

将此模板克隆或下载到本地计算机。

2.配置

在中配置您的设置 appsettings.json:

• 连接串：如果需要，更新数据库连接字符串
• CORS设置：配置允许的源、方法和标头
• 日志记录：根据需要调整Serilog设置

3.环境变量

使用环境变量设置传输类型：

# For HTTP transport (default)
$env:TEMPLATE_MCP_TRANSPORT = "Http"

# For Stdio transport (for VS Code integration)
$env:TEMPLATE_MCP_TRANSPORT = "Stdio"

备注：传输类型决定了日志记录的配置方式：

• HTTP模式：从读取日志配置 appsettings.json
• 标准模式：通过编程将日志记录配置到stderr，以防止JSON-RPC干扰

4.构建和运行

# Restore dependencies
dotnet restore

# Build the project
dotnet build

# Run the application
dotnet run

服务器将于启动 http://localhost:5000 默认情况下（HTTP模式）。

可用的MCP工具

此模板包括三个示例工具：

1. 模板初始化连接：初始化连接
2. 模板_样本_数据：返回示例数据
3. 模板执行操作：执行示例操作

示例用法

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "template_get_sample_data",
    "arguments": {
      "connectionName": "DefaultConnection"
    }
  }
}

创建自己的工具

要创建自己的MCP工具：

1. 创建工具类 在 Tools/ 文件夹：

[McpServerToolType]
public class MyCustomTools
{
    [McpServerTool(Name = "my_custom_tool"), Description("Description of my tool.")]
    public async Task MyCustomTool(string parameter)
    {
        // Your implementation here
        return JsonSerializer.Serialize(result);
    }
}

1. 注册工具 在 Program.cs:

builder.Services.AddMcpServer().WithHttpTransport()
    .WithTools()
    .WithTools();  // Add your tool

包的依赖

此模板使用与mssqlMCP相同的包和版本：

• 模型上下文协议。AspNetCore：0.1.0-审查13
• 微软。数据。Sql客户端: 6.0.2
• 微软。数据。SQLite: 9.0.5
• Serilog。AspNetCore: 9.0.0
• 潇洒: 2.1.66
• 测试：xUnit 2.6.6，第4.20.70季度，微软。网。测试。私人股本17.9.0

建筑

graph TD
    A[VS Code/Copilot] -->|MCP Protocol| B[MCP Server]
    B --> C[Tools Layer]
    C --> D[SampleTools]
    D --> E[Service Layer]
    E --> F[SampleService]
    E --> G[ConfigurationProvider]
    E --> H[LoggingConfigurationService]

    style A fill:#e1f5ff
    style B fill:#fff4e1
    style C fill:#e8f5e9
    style D fill:#e8f5e9
    style E fill:#f3e5f5
    style F fill:#f3e5f5
    style G fill:#f3e5f5
    style H fill:#f3e5f5

此模板遵循干净的架构模式：

• 程序cs：具有DI配置和传输感知日志记录的应用程序入口点
• 工具/：MCP工具实现装饰有 [McpServerToolType]
• 服务项目/：业务逻辑与MCP协议处理分离
• 接口/：服务合同
• 配置/：配置提供程序
• 扩展/：服务注册扩展
• 型号/：数据模型

关键设计决策

1. 传输感知日志记录：应用程序在配置Serilog之前检测传输模式（HTTP/Stdio），确保正确的stdout/stderr分离
2. 错误处理：具有优雅处理的全局异常中间件 OperationCanceledException 用于清洁停机
3. 中间件订购：首先放置错误处理中间件，以便在启动响应之前捕获所有异常

与VS代码集成

要将此MCP服务器与VS Code和Copilot一起使用：

1. 先构建项目：

   dotnet build

1. 创建一个 .vscode/mcp.json 工作区中的文件：

   {
     "servers": {
       "templateMCP": {
         "command": "dotnet",
         "args": [
           "c:\\path\\to\\templateMCP\\bin\\Debug\\net9.0\\templateMCP.dll"
         ],
         "env": {
           "TEMPLATE_MCP_TRANSPORT": "Stdio"
         }
       }
     }
   }

重要：使用预构建的DLL路径，而不是 dotnet run 以避免构建输出干扰MCP协议。

1. 重新启动VS Code以加载MCP服务器

标准模式故障排除

如果在输出窗口中看到“解析消息失败”警告：

• 确保您正在运行构建的DLL（不是 dotnet run)
• 模板在Stdio模式下自动将日志路由到stderr
• 构建警告和stdout消息将干扰JSON-RPC通信
• 检查 Logs/ 详细应用程序日志文件夹

日志记录

日志将写入：

• 控制台/Stderr：实时日志输出

- 在 HTTP模式：日志到stdout（控制台） - 在 标准模式：仅记录到stderr（以避免干扰stdout上的JSON-RPC）

• 文件: Logs/templateMCP-YYYY-MM-DD.txt （每日滚动文件，保留30天）

日志级别可以在中配置 appsettings.json 在...之下 Serilog 部分。在Stdio模式下，模板以编程方式配置日志记录，以防止stdout污染。

CORS配置

CORS设置 appsettings.json 可以定制生产：

{
  "Cors": {
    "AllowedOrigins": ["https://your-domain.com"],
    "AllowedMethods": ["GET", "POST"],
    "AllowedHeaders": ["Content-Type", "Authorization"],
    "AllowCredentials": true
  }
}

后续步骤

1. 自定义工具：修改 Tools/SampleTools.cs 或创建新的工具类
2. 添加服务：在中创建服务 Services/ 业务逻辑文件夹
3. 添加模型：在中定义数据模型 Models/ 文件夹
4. 配置数据库：更新数据库的连接字符串
5. 添加身份验证：按照mssqlMCP模式实现API密钥身份验证

参考实现

此模板基于 mssqlMCP 该项目提供了一个全面的例子：

• 多次API密钥验证
• 连接字符串加密
• 数据库元数据检索
• SQL Server集成
• 高级安全功能

有关高级模式和实现，请参阅mssqlMCP存储库。

许可证

此模板遵循MIT许可证模式。

贡献

欢迎贡献和改进！请随时提交pull请求或未决问题。