CSLA .NET MCP 服务器

此仓库包含CSLA .NET MCP（模型上下文协议）服务器的源代码。该服务器旨在支持在使用CSLA .NET框架创建.NET C#应用程序时，利用生成式人工智能（大型语言模型）模型。

概述

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

特点/特性

代码示例全面收集的CSLA .NET代码示例，按概念和复杂度组织
语义搜索使用由Azure OpenAI嵌入支持的自然语言查询来查找相关示例
概念浏览浏览可用的CSLA概念和类别
Aspire Integration 可以翻译为“志向集成”或“追求整合”，具体取决于上下文和语境，但通常“志向集成”或类似的表述更能传达出积极向上、追求融合与发展的含义使用.NET Aspire构建，以实现现代云原生开发
HTTP APIRESTful 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设置指南.md 以获取分步指南。

部署一个模型：

首选 Azure OpenAI Studio（可译为“Azure OpenAI 工作室”）
导航至“部署”
使用该模型创建一个新的部署 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"  # Must match deployment name
$env:AZURE_OPENAI_API_VERSION = "2024-02-01"  # Optional, API version

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"  # Must match deployment name
export AZURE_OPENAI_API_VERSION="2024-02-01"  # Optional, API version

如需更详细的配置信息，请参阅 \azure-openai-config.md\ 翻译为中文是：“Azure-OpenAI 配置文件.md”。

向量嵌入

服务器使用 预生成的向量嵌入 用于语义搜索功能。这大大减少了启动时间，并消除了生成嵌入所需的Azure OpenAI API费用。

其工作原理

嵌入生成 （在运行服务器之前）：

- 运行 csla-embeddings-generator 用于为所有代码样本生成嵌入的CLI工具 - 这创建了一个 embeddings.json 包含预计算向量嵌入的文件

服务器启动：

- 服务器从（某个地方）加载预生成的嵌入向量 embeddings.json 在启动时 - 服务器初始化过程中不进行嵌入生成

运行时 （用户查询）：

- 仍需Azure OpenAI凭证来为用户搜索查询生成嵌入向量 - 服务器将用户查询的嵌入表示与预加载的代码样本嵌入表示进行比较

生成嵌入表示

在运行服务器之前，你必须为你的代码样本生成嵌入表示：

# Generate embeddings for the default csla-examples directory
dotnet run --project csla-embeddings-generator

# Or specify custom paths
dotnet run --project csla-embeddings-generator -- --examples-path ./csla-examples --output ./embeddings.json

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

见 \csla-embeddings-generator/README.md\ 翻译成中文为：\csla-嵌入生成器/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

使用默认路径：

# Assumes embeddings.json exists in current directory
dotnet run --project csla-mcp-server

好处

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

MCP 工具

服务器目前提供了两个用（某种语言/技术）实现的MCP工具 CslaMcpServer.Tools.CslaCodeTool：

Search — 搜索代码示例和Markdown片段，查找关键词匹配项，并返回评分结果。
Fetch — 返回名为代码示例或Markdown文件的原始内容。

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

工具：搜索

描述：从提供的输入文本中提取关键词并进行搜索 .cs 并且 .md 在示例文件夹中查找这些单词的出现情况所对应的文件。返回一个JSON数组，其中包含合并了语义（基于向量）和基于单词（关键词）的搜索得分的综合搜索结果。

参数：

message (字符串，必填)：用于搜索的自然语言文本或关键词。工具会忽略长度为4个字符或更短的单词。此外，工具还会搜索相邻单词的2词组合，以查找短语匹配（例如，从“create operation method”中搜索“create operation”和“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个字符）。
该工具从搜索信息中的相邻单词创建双词组合，以查找短语匹配。与单个单词匹配（权重为1）相比，多词短语匹配（权重为2）会获得更高的分数。
词匹配使用词边界来确保精确匹配。例如，搜索“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（可能是指某种特定的开发指南、规范或框架，具体需根据上下文确定，此处直译为“CSLA”）指导

贡献

为仓库创建分支（或“克隆仓库”）
创建一个特性分支
按照既定模式添加您的代码示例
测试你的更改
提交拉取请求

代码示例指南

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

许可证

此项目采用MIT许可证授权 - 详情请参阅LICENSE文件。

支持

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

Docker：构建与运行

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

从源代码构建

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

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

./build.sh

这个脚本将：

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

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

# Step 1: Generate embeddings
dotnet run --project csla-embeddings-generator -- --examples-path ./csla-examples --output ./embeddings.json

# Step 2: Build Docker image
docker build -f csla-mcp-server/Dockerfile -t csla-mcp-server:latest .

使用Docker Hub上的预构建镜像

官方预构建的镜像可在Docker Hub上获取，并且已包含预先生成的嵌入（embeddings）：

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 构建过程包括 embeddings.json 在构建之前，应在仓库根目录中存在该文件。
如果你在开发过程中需要快速调试或迭代，可以考虑在本地运行应用程序，使用 dotnet run --project csla-mcp-server/csla-mcp-server.csproj 而不是每次更改都重建镜像。
重要的为了在运行时（针对用户查询嵌入）启用语义搜索功能，需要设置Azure OpenAI环境变量。

配置代码示例文件夹

MCP服务器从一个可配置的文件夹中读取代码示例和Markdown示例。控制使用哪个文件夹的方法有三种（优先级从高到低）：

命令行标志 -f / --folder 在启动服务器时
环境变量 CSLA_CODE_SAMPLES_PATH
服务器代码使用的内置默认路径

命令行标志总是会覆盖环境变量。如果两者都未提供，则服务器使用默认的示例路径。

示例

运行并使用（某个方法或工具）指向一个文件夹 -f 选项（PowerShell）：

dotnet run --project csla-mcp-server -- -f "S:\src\rdl\csla-mcp\csla-examples"

设置环境变量（PowerShell）并运行（无需 -f（env 将被使用）：

$env:CSLA_CODE_SAMPLES_PATH = 'S:\src\rdl\csla-mcp\csla-examples'
dotnet run --project csla-mcp-server --

在cmd.exe（Windows）中使用环境变量进行一次性启动：

set CSLA_CODE_SAMPLES_PATH=S:\src\rdl\csla-mcp\csla-examples && dotnet run --project csla-mcp-server --

验证与错误

服务器在启动时验证提供的文件夹。如果文件夹不存在或不包含任何内容 .cs 或者 .md 服务器将打印一条有用的错误信息，并以非零代码退出。
用于验证失败的退出代码：

- 2 — CLI 文件夹不存在 - 3 — CLI 文件夹存在，但其中不包含任何内容 .cs 或者 .md 文件 - 4 — ENV文件夹不存在 - 5 — ENV文件夹存在但为空 .cs 或者 .md 文件 - 6 — 无法处理ENV变量（出现意外错误）

csla MCP

快速接入

详细介绍