csla-MCP服务器

Name: csla-MCP服务器
Author: MarimerLLC

作者：MarimerLLC4 星标更新：2025-10-28

安装使用来源：spider==github.com

项目介绍

CSLA .NET MCP 服务器

此仓库包含了 CSLA .NET MCP（模型上下文协议）服务器的源代码。该服务器旨在支持在使用 CSLA .NET 框架创建 .NET C# 应用程序时使用生成式 AI（LLM）模型。

概述

CSLA MCP 服务器为 AI 编码助手提供了访问官方 CSLA .NET 代码示例、模式和最佳实践的途径。它实现了模型上下文协议（MCP），作为 CSLA 开发的知识库。

特性

代码示例：按概念和复杂度组织的全面的 CSLA .NET 代码示例集合
语义搜索：使用 Azure OpenAI 嵌入通过自然语言查询找到相关示例
概念浏览：浏览可用的 CSLA 概念和类别
Aspire 集成：使用 .NET Aspire 进行现代云原生开发
HTTP API：用于轻松集成的 RESTful API 端点

Azure OpenAI 配置

服务器使用 Azure OpenAI 进行向量嵌入以提供语义搜索能力。您必须配置以下环境变量：

必需的环境变量

AZURE_OPENAI_ENDPOINT：您的 Azure OpenAI 服务端点（例如，https://your-resource.openai.azure.com/）
AZURE_OPENAI_API_KEY：您的 Azure OpenAI API 密钥

可选的环境变量

AZURE_OPENAI_EMBEDDING_MODEL：要使用的嵌入模型部署名称（默认：text-embedding-3-small）
AZURE_OPENAI_API_VERSION：要使用的 API 版本（默认：2024-02-01）

⚠️ 重要提示：需要模型部署

在运行服务器之前，您必须在 Azure OpenAI 资源中部署一个嵌入模型。部署名称必须与 AZURE_OPENAI_EMBEDDING_MODEL 环境变量完全匹配。

快速设置：请参阅 azure-openai-setup-guide.md 获取逐步说明。

要部署模型：

访问 Azure OpenAI Studio
导航到“部署”
使用模型 text-embedding-3-small 创建一个新的部署
确保部署名称与您的环境变量匹配

备用模式：如果未配置 Azure OpenAI，服务器将以仅关键词搜索模式运行。

示例配置

PowerShell (Windows)：

$env:AZURE_OPENAI_ENDPOINT = "https://your-resource.openai.azure.com/"
$env:AZURE_OPENAI_API_KEY = "your-api-key-here"
$env:AZURE_OPENAI_EMBEDDING_MODEL = "text-embedding-3-small"  # 必须与部署名称匹配
$env:AZURE_OPENAI_API_VERSION = "2024-02-01"  # 可选，API 版本

Bash (Linux/macOS)：

export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export AZURE_OPENAI_API_KEY="your-api-key-here"
export AZURE_OPENAI_EMBEDDING_MODEL="text-embedding-3-small"  # 必须与部署名称匹配
export AZURE_OPENAI_API_VERSION="2024-02-01"  # 可选，API 版本

有关更详细的配置信息，请参阅 azure-openai-config.md。

向量嵌入

服务器使用预生成的向量嵌入来实现语义搜索功能。这显著减少了启动时间，并消除了生成嵌入时的 Azure OpenAI API 成本。

工作原理

嵌入生成（在运行服务器之前）：
- 运行 csla-embeddings-generator CLI 工具为所有代码示例生成嵌入
- 这会创建一个包含预先计算的向量嵌入的 embeddings.json 文件
服务器启动：
- 服务器在启动时从 embeddings.json 加载预生成的嵌入
- 在服务器初始化期间不会生成嵌入
运行时（用户查询）：
- 仍需要 Azure OpenAI 凭据来为用户查询生成嵌入
- 服务器将用户查询嵌入与预加载的代码样本嵌入进行比较

生成嵌入

在运行服务器之前，您必须为代码示例生成嵌入：

# 为默认的 csla-examples 目录生成嵌入
dotnet run --project csla-embeddings-generator

# 或指定自定义路径
dotnet run --project csla-embeddings-generator -- --examples-path ./csla-examples --output ./embeddings.json

这将在当前目录（或指定的输出路径）中创建一个 embeddings.json 文件。

请参阅 csla-embeddings-generator/README.md 了解更多信息。

配置嵌入路径

服务器需要知道在哪里找到 embeddings.json 文件。有三种方式可以配置这一点（优先级从高到低）：

命令行标志 --embeddings 或 -e
环境变量 CSLA_EMBEDDINGS_PATH
默认路径：./embeddings.json（当前目录）

示例

使用命令行标志：

dotnet run --project csla-mcp-server -- --embeddings ./path/to/embeddings.json

使用环境变量（PowerShell）：

$env:CSLA_EMBEDDINGS_PATH = "S:\src\rdl\csla-mcp\embeddings.json"
dotnet run --project csla-mcp-server

使用环境变量（Bash）：

export CSLA_EMBEDDINGS_PATH="/path/to/embeddings.json"
dotnet run --project csla-mcp-server

使用默认路径：

# 假设 embeddings.json 存在于当前目录
dotnet run --project csla-mcp-server

优点

更快的启动：服务器立即启动，无需等待嵌入生成
减少成本：代码示例嵌入只需生成一次，而不是每次重启服务器时都生成
离线开发：服务器可以在没有 Azure OpenAI 的情况下启动（尽管语义搜索需要它来处理用户查询）
一致的结果：所有服务器实例使用相同的嵌入

MCP 工具

服务器目前暴露了两个在 CslaMcpServer.Tools.CslaCodeTool 中实现的 MCP 工具：

Search — 搜索代码示例和 Markdown 片段中的关键词匹配并返回评分结果。
Fetch — 返回命名代码样本或 Markdown 文件的原始内容。

这两个工具都在包含示例文件的仓库文件夹下操作：csla-examples/（工具在服务器代码中使用绝对路径：s:\src\rdl\csla-mcp\csla-examples\）。

工具：Search

描述：从提供的输入文本中提取重要的单词，并在示例文件夹下的 .cs 和 .md 文件中搜索这些单词的出现情况。返回一个合并了语义（基于向量）和基于词（关键词）搜索得分的 JSON 数组。

参数：

message（字符串，必需）：要搜索的自然语言文本或关键词。长度小于等于 4 的单词会被工具忽略。工具还会搜索相邻单词的两词组合以查找短语匹配（例如，“create operation”和“operation method”来自“create operation method”）。
version（整数，可选）：过滤结果的 CSLA 版本号（例如，9 或 10）。如果没有提供，则默认为通过扫描示例文件夹中的版本子目录（例如，v9/，v10/）获得的最高版本。根目录中的文件（适用于所有版本）无论指定什么版本都会被包括。

输出：具有以下形状的对象的 JSON 数组：

FileName（字符串）：相对于示例文件夹的相对文件路径（例如，v10/ReadOnlyProperty.md 或 CommonFile.cs）
Score（双精度浮点数）：从语义和词搜索合并的标准化综合得分（0.0 到 1.0）
VectorScore（双精度浮点数，可为空）：来自 Azure OpenAI 嵌入的语义相似性得分（如果无法使用语义搜索则为 null）
WordScore（双精度浮点数，可为空）：标准化的关键词匹配得分（如果没有找到关键词匹配则为 null）

示例调用（MCP tools/call）：

{
  "method": "tools/call",
  "params": {
    "name": "Search",
    "arguments": { 
      "message": "data portal authorization business object",
      "version": 10
    }
  }
}

不带版本的示例调用（使用最高可用版本）：

{
  "method": "tools/call",
  "params": {
    "name": "Search",
    "arguments": { 
      "message": "read-write property editable root"
    }
  }
}

注意事项和行为：

工具在构建搜索词时忽略短词（≤ 3 字符）。
工具从搜索消息中的相邻单词创建两词组合以查找短语匹配。多词短语匹配会得到更高的分数（权重为 2），而单词匹配的权重为 1。
单词匹配使用词边界确保精确匹配。例如，搜索“property”不会匹配“ReadProperty”或“GetProperty”。
匹配是大小写不敏感的，并且会在文件中计数多次出现。
结果结合了语义搜索（当配置了 Azure OpenAI 时）和关键词搜索以获得更准确的结果。
结果按 Score 降序排列，然后按文件名排序。
版本过滤：版本子目录中的文件（例如，v9/，v10/）根据指定的版本进行过滤。根目录中的文件被视为适用于所有版本并且始终被包括。

工具：Fetch

描述：根据文件名从 csla-examples/ 文件夹返回特定文件的文本内容。

参数：

fileName（字符串，必需）：要获取的文件名（例如，ReadOnlyProperty.md 或 MyBusinessClass.cs）。工具通过将配置的示例路径与给定的文件名相结合来解析文件。

输出：原始文件内容作为字符串。如果找不到文件，工具将返回简单的错误消息字符串，如 "File 'X' not found."。

示例调用（MCP tools/call）：

{
  "method": "tools/call",
  "params": {
    "name": "Fetch",
    "arguments": { "fileName": "ReadOnlyProperty.md" }
  }
}

安全注意事项：

当前实现直接结合配置的绝对路径和提供的 fileName，而不执行额外的验证以防止路径遍历。当远程暴露这些工具时，考虑添加验证以确保只返回允许的文件。

如果您需要更高层次的工具，如 get_csla_example，list_csla_concepts 或语义搜索包装器，这些工具并未在 CslaCodeTool.cs 中实现，需要单独添加。

与 AI 助手的集成

此 MCP 服务器设计用于由 AI 编码助手使用，以提供准确、最新的 CSLA .NET 示例和指导。当集成时：

AI 助手可以查询特定的 CSLA 模式
服务器返回官方、经过测试的代码示例
AI 助手可以为开发者提供更准确的 CSLA 指导

贡献

分叉仓库
创建功能分支
添加遵循现有模式的代码示例
测试更改
提交拉取请求

代码示例指南

使用清晰、描述性的文件名
包含全面的示例以展示概念
在代码示例中添加解释性注释
为复杂的模式创建配套的 Markdown 文档
遵循 CSLA 最佳实践和惯例

许可证

该项目采用 MIT 许可证 - 详情见 LICENSE 文件。

支持

关于 CSLA .NET 的问题，请访问：

Docker：构建和运行

此项目包含位于 csla-mcp-server/Dockerfile 的多阶段 Dockerfile，用于构建和发布应用程序，然后生成一个小的运行时镜像。

从源代码构建

重要：在构建 Docker 镜像之前，您必须为代码示例生成向量嵌入。

使用 build.sh 脚本自动化整个过程：

./build.sh

此脚本将：

构建嵌入生成器 CLI 工具
为 csla-examples/ 中的所有代码示例生成嵌入
在仓库根目录中创建 embeddings.json
构建包含嵌入的 Docker 镜像

或者，您可以手动执行这些步骤：

# 步骤 1：生成嵌入
dotnet run --project csla-embeddings-generator -- --examples-path ./csla-examples --output ./embeddings.json

# 步骤 2：构建 Docker 镜像
docker build -f csla-mcp-server/Dockerfile -t csla-mcp-server:latest .

使用 Docker Hub 上的预构建镜像

官方预构建镜像已在 Docker Hub 上提供，并已包含预生成的嵌入：

docker pull rockylhotka/csla-mcp-server:latest

此镜像包含：

csla-mcp-server 应用程序
官方 CSLA 代码示例的预生成嵌入
所有必要的运行时依赖项

运行容器

使用 Azure OpenAI 配置运行容器（将容器端口 80 映射到主机端口 8080）：

使用 Docker Hub 镜像：

docker run --rm -p 8080:80 `
  -e AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" `
  -e AZURE_OPENAI_API_KEY="your-api-key-here" `
  -e AZURE_OPENAI_EMBEDDING_MODEL="text-embedding-3-small" `
  -e AZURE_OPENAI_API_VERSION="2024-02-01" `
  --name csla-mcp-server rockylhotka/csla-mcp-server:latest

使用本地构建的镜像：

docker run --rm -p 8080:80 `
  -e AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" `
  -e AZURE_OPENAI_API_KEY="your-api-key-here" `
  -e AZURE_OPENAI_EMBEDDING_MODEL="text-embedding-3-small" `
  -e AZURE_OPENAI_API_VERSION="2024-02-01" `
  --name csla-mcp-server csla-mcp-server:latest

在浏览器中打开 http://localhost:8080 以访问服务器。

使用 Docker 自定义嵌入

如果您想使用自己的嵌入文件与 Docker 容器：

本地生成您的嵌入：

dotnet run --project csla-embeddings-generator -- --examples-path ./my-examples --output ./my-embeddings.json

将嵌入文件挂载到容器中：

docker run --rm -p 8080:80 `
  -v "S:\path\to\my-embeddings.json:/app/embeddings.json" `
  -e CSLA_EMBEDDINGS_PATH="/app/embeddings.json" `
  -e AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" `
  -e AZURE_OPENAI_API_KEY="your-api-key-here" `
  --name csla-mcp-server rockylhotka/csla-mcp-server:latest

Docker：挂载自定义代码示例

您可以将自定义的 csla-examples 文件夹挂载到容器中，并设置 CSLA_CODE_SAMPLES_PATH 环境变量：

Linux/macOS：

docker run --rm -p 8080:80 \
  -v "/path/on/host/csla-examples:/app/examples" \
  -e CSLA_CODE_SAMPLES_PATH="/app/examples" \
  -e AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" \
  -e AZURE_OPENAI_API_KEY="your-api-key-here" \
  --name csla-mcp-server rockylhotka/csla-mcp-server:latest

Windows (PowerShell)：

docker run --rm -p 8080:80 `
  -v "S:\src\rdl\csla-mcp\csla-examples:/app/examples" `
  -e CSLA_CODE_SAMPLES_PATH="/app/examples" `
  -e AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" `
  -e AZURE_OPENAI_API_KEY="your-api-key-here" `
  --name csla-mcp-server rockylhotka/csla-mcp-server:latest

注意：如果您挂载了自定义代码示例，应同时挂载从这些示例生成的自定义嵌入，否则语义搜索结果可能与自定义代码示例不匹配。

Docker 构建注意事项

Dockerfile 使用 .NET 10 SDK 和 ASP.NET 运行时镜像。确保您的 Docker 安装支持所需的基镜像。
Docker 构建包括应在构建