Kss MCP Template

KSS MCP模板-。NET核心MCP服务器，带有示例API

中的完整模型上下文协议（MCP）服务器实现。NET核心，带有用于城市和个人数据的示例REST API。

🎯 概述

该项目演示了如何构建一个MCP服务器，该服务器将来自REST API的数据公开为Claude等人工智能助手可以使用的工具。它包括：

• KSS。MCP。服务器 -MCP服务器实现MCP 2024-11-05协议
• KSS。样本Api -REST API提供示例城市和个人端点

📋 先决条件

• .NET 8.0 SDK或更高版本
• Windows、macOS或Linux

🚀 快速开始

1.克隆和构建

# Restore and build all projects
dotnet restore
dotnet build

2.启动示例API

Windows（PowerShell）：

.\start-api.ps1

Linux/Mac：

chmod +x start-api.sh
./start-api.sh

API将在以下网址提供： http://localhost:5000\ Swagger用户界面： http://localhost:5000/swagger

3.测试API（可选）

在新终端中：

.\test-api.ps1

4.启动MCP服务器

在新终端中（保持API运行）：

dotnet run --project KSS.MCP.Server/KSS.MCP.Server.csproj

5.使用Claude Desktop进行配置

添加到您的Claude Desktop配置文件中：

视窗: %APPDATA%\Claude\claude_desktop_config.json\ macOS: ~/Library/Application Support/Claude/claude_desktop_config.json\ Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "city-person-api": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "C:\\Source Control\\KSS.MCP.Template\\KSS.MCP.Server\\KSS.MCP.Server.csproj"
      ]
    }
  }
}

重新启动Claude Desktop并开始使用工具！

🏗️ 项目结构

KSS.MCP.Template/
│
├── KSS.MCP.Server/           # MCP Server Project
│   ├── Program.cs            # Entry point
│   ├── McpServer.cs          # MCP protocol implementation
│   ├── CityApiService.cs     # API client service
│   ├── appsettings.json      # Configuration
│   └── KSS.MCP.Server.csproj # Project file
│
├── KSS.SampleApi/            # Sample REST API Project
│   ├── Controllers/          # API Controllers
│   │   ├── CityController.cs
│   │   └── PersonController.cs
│   ├── Models/               # Data models
│   │   ├── City.cs
│   │   └── Person.cs
│   ├── Services/             # Business logic
│   │   └── SampleDataService.cs
│   ├── Program.cs            # API entry point
│   ├── appsettings.json      # Configuration
│   ├── README.md             # API documentation
│   └── KSS.SampleApi.csproj  # Project file
│
├── start-api.ps1             # PowerShell script to start API
├── start-api.sh              # Bash script to start API
├── test-api.ps1              # API testing script
├── API_EXAMPLES.md           # API endpoint examples
├── INTEGRATION_GUIDE.md      # Integration documentation
├── QUICKSTART.md             # Quick start guide
├── mcp-config.json           # Sample MCP configuration
├── test-messages.jsonl       # Test MCP messages
├── .gitignore                # Git ignore file
├── KSS.MCP.Template.sln      # Visual Studio solution
└── README.md                 # This file

🛠️ MCP工具

MCP服务器提供3个工具：

🌐 API终点

城市终点

• GET /api/city -获取所有城市
• GET /api/city/{id} -按ID获取城市
• GET /api/city/by-name/{name} -按名称获取城市
• GET /api/city/search?q={term} -搜索城市
• GET /api/city/{id}/persons -在城市里找人

人员端点

• GET /api/person -获取所有人员
• GET /api/person/{id} -按ID获取人员
• GET /api/person/{id}/with-city -获取城市详细信息
• GET /api/person/by-city/{cityName} -按城市名称获取人员
• GET /api/person/by-city-id/{cityId} -按城市ID获取人员
• GET /api/person/search?q={term} -搜索人员

📊 样品数据

API包括样本数据：

• 6城市：纽约、洛杉矶、芝加哥、休斯顿、凤凰城、费城
• 10人：分布在各个职业的城市

📚 文档

• QUICKSTART.md -MCP服务器快速入门指南
• KSS。SampleApi/README.md -API文件示例
• API示例.md -API的详细示例及响应
• 集成_指南.md -将MCP服务器连接到API的指南

🔧 配置

MCP服务器配置(appsettings.json)

{
  "CityApi": {
    "BaseUrl": "http://localhost:5000",
    "Timeout": 30,
    "ApiKey": ""
  }
}

API配置示例(KSS.SampleApi/appsettings.json)

{
  "Urls": "http://localhost:5000"
}

🧪 测试

测试API样品

# Run all API tests
.\test-api.ps1

测试单个端点

# Get all cities
curl http://localhost:5000/api/city

# Get person by ID
curl http://localhost:5000/api/person/1

# Search for engineers
curl http://localhost:5000/api/person/search?q=engineer

测试MCP服务器

# Pipe test messages to the MCP server
cat test-messages.jsonl | dotnet run --project KSS.MCP.Server/KSS.MCP.Server.csproj

🔄 整合

要将MCP服务器连接到示例API：

1. 启动示例API
2. 更新 appsettings.json 在MCP服务器中
3. 修改 CityApiService.cs 调用真正的API端点
4. 启动MCP服务器
5. 配置Claude桌面

看 集成_指南.md 详细说明。

🎨 特性

MCP服务器

• ✅ 完全支持MCP 2024-11-05协议
• ✅ 基于stdio的JSON-RPC 2.0
• ✅ 工具注册和执行
• ✅ 错误处理和日志
• ✅ 可通过应用程序配置

API样本

• ✅ 带有Swagger文档的RESTful API
• ✅ 为跨源请求启用CORS
• ✅ 城市和人的综合终点
• ✅ 搜索和过滤功能
• ✅ 结构化日志记录
• ✅ 使用正确的HTTP状态代码处理错误

🚀 部署

部署示例API

示例API可以部署到：

• Azure应用服务
• AWS Elastic Beanstalk
• Docker容器
• 任何。NET托管平台

更新MCP服务器的 BaseUrl 指向已部署的API。

部署MCP服务器

MCP服务器作为基于stdio的应用程序运行，通常由MCP客户端（例如Claude Desktop）在本地启动。

🔐 安全考虑

用于生产用途：

• 向API添加身份验证（JWT、OAuth、API密钥）
• 将CORS限制到特定的源
• 使用HTTPS进行API通信
• 验证并净化所有输入
• 实施速率限制
• 添加请求日志记录和监控

🛣️ 路线图

• \[\]添加数据库集成（实体框架核心）
• \[\]实现身份验证和授权
• \[\]添加POST/PUT/DELETE端点
• \[\]为大型数据集添加分页
• \[\]实现缓存
• \[\]添加单元和集成测试
• \[\]创建Docker容器
• \[\]添加CI/CD管道

📖 了解更多

• 模型上下文协议文档
• ASP。NET核心文档
• 克劳德桌面MCP指南

🤝 贡献

这是一个模板项目。请随意：

• 根据您的需求进行分叉和定制
• 添加新工具和端点
• 与您自己的API集成
• 分享改进

📄 许可证

这是一个按原样提供的模板项目，用于学习和发展目的。

💡 示例

与克劳德一起使用

一旦配置了Claude Desktop：

你：“你能给我看一下关于ID 1的信息吗？”

克劳德: *使用 get_person_by_id 工具并显示结果*

你：“显示数据库中的所有工程师”

克劳德: *使用 search_persons 以“engineer”为搜索词的工具*

你“谁住在芝加哥？”

克劳德: *使用 get_persons_by_city 以“芝加哥”为城市名称的工具*

🆘 支持

如果您遇到问题：

1. 检查一下。NET 8.0 SDK已安装： dotnet --version
2. 验证两个项目是否构建： dotnet build
3. 检查API是否可访问： http://localhost:5000/swagger
4. 查看MCP服务器stderr中的日志
5. 查阅此存储库中的文档文件

🎓 学习资源

此模板演示：

• 在中构建MCP服务器。NET核心
• 用ASP.NET创建RESTful API。NET核心
• 实现JSON-RPC 2.0协议
• 面向服务的体系结构
• API集成模式
• AI助手的工具设计

非常适合学习如何：

• 将您的API暴露给AI助手
• 构建自定义MCP服务器
• 与Claude Desktop集成
• 创建结构化工具界面