Knyrps/Sitecore-MCP

# SitecoreMCP 一个作为 .NET Framework 程序集运行**在** Sitecore **内部**的 MCP server，而不是一个 通过网络通过 HTTP 与 Sitecore 通信的外部进程。 现有的 Sitecore MCP server（以及 Sitecore CLI、PowerShell Remoting、Item Service、 GraphQL）都位于平台外部并通过网络进行访问。这意味着需要安装和管理第二个 runtime 及其版本，多了一跳，一个偏离真实 item model 的 DTO 层， 以及所选 API 碰巧暴露的任何权限模型。 此模块是实例 `/bin` 目录中的一个 DLL。它通过进程内调用获取 `Sitecore.Data.Database`、 `Sitecore.Context`、真正的安全模型以及发布和索引 pipeline。 工具只是 Kernel API 的轻量级封装。 **目标：** Sitecore XM/XP 10.x, .NET Framework 4.8, IIS。 已在 10.3 (Kernel 18.0.0.0) 和 10.4 (Kernel 19.0.0.0) 上验证。 ## 组合方式 ``` MCP client (Claude Code, Copilot) │ stdio JSON-RPC ▼ SitecoreMcp.Bridge ← optional; only for clients that cannot speak HTTP or local development environments where CA Certs are self-signed and therefore not supported by your calling runtime (e.g. VSCode Node, OpenCode Bun etc.) │ HTTP POST /sitecore/api/mcp ▼ SitecoreMcp.Server (in the Sitecore worker process) │ in-process Kernel API, under the caller's real Sitecore user ▼ Sitecore ``` 支持 Streamable HTTP 的客户端直接连接到 endpoint 并跳过 bridge。 ## 结构 | 路径 | 角色 | |---|---| | `src/SitecoreMcp.Server` | 部署到实例的模块。包含协议、传输和工具。 | | `src/SitecoreMcp.Bridge` | 用于仅支持 stdio 的 MCP 客户端的 stdio-to-HTTP 垫片。 | | `tests/SitecoreMcp.Server.Tests` | 针对无需运行 Sitecore 的部分的单元测试。 | | `docs/` | 设计说明和设置指南。 | ## 安全态势 该 endpoint **默认禁用**。一个 API key 映射到专用的 Sitecore 用户，并且每次 调用都通过 `UserSwitcher` 在该用户下运行，因此 item 和字段的 ACL、workflow 以及审计都会 正常应用。从不使用 `SecurityDisabler`。写入和操作非 `master` 数据库是按客户端选择性启用的。 在本地，映射的用户可以是 admin；但在共享实例上则不应如此。 ## 本地构建与设置 端到端流程：针对您的实例进行构建、部署、验证并连接客户端。 ### 前置条件 - IIS 上的本地 **Sitecore XM/XP 10.x** 实例。Server 会针对*该实例自身的*程序集进行编译， 因此 10.3 和 10.4 每个都需要一个针对它们的构建。 - **.NET SDK**（用于构建 net48 server、net8.0 bridge 和测试）和 **.NET 8 runtime**（用于运行 bridge）。 - 用于部署的**提权的 PowerShell** —— 写入 web 根目录、设置 app-pool 环境变量以及回收 pool 均仅限管理员操作。 ### 1. 将构建指向您的实例 Server 直接从目标 web 根目录引用 `Sitecore.Kernel`、`Newtonsoft.Json` 和 `Sitecore.Logging`， 因此必须针对其将要运行的那个实例进行构建。在仓库根目录下创建一个被 gitignore 忽略的 `Directory.Build.user.props`： ``` C:\inetpub\wwwroot\my-instance ``` ### 2. 构建并测试 ``` dotnet build -c Release dotnet test ``` 普通的构建绝不会写入 web 根目录 —— 部署是一个独立的、选择加入的步骤。 ### 3. 部署到实例（需提权） 在**提权的** PowerShell 中运行： ``` ./deploy/Deploy-SitecoreMcp.ps1 -WebRoot C:\inetpub\wwwroot\my-instance ``` 这将复制 DLL 和 `SitecoreMcp.config`，写入一个本地的 `SitecoreMcp.Dev.config` 以通过 HTTP 启用带有映射到 admin 的客户端的 endpoint，在 app pool 上设置 `SITECORE_MCP_KEY`，并将其回收 —— 同时打印生成的 key。传递 `-Key ` 以固定您自己的 key，使其不会在部署之间轮换。详情和生产环境的安全态势 （真实的证书、专用的受限用户、关闭写入）请参见 [deploy/README.md](deploy/README.md)。 ### 4. 验证 ``` ./deploy/Verify-SitecoreMcp.ps1 -Url https://my-instance/sitecore/api/mcp -Key ``` 预期会得到一个 `initialize` 结果、工具列表和一个 `sitecore_get_context` payload。然后检查 `App_Data/logs/mcp.log..txt` 中的 `AUDIT` 行 —— 所有 MCP 活动都记录在那里，而不是在 主要的 Sitecore 日志中。 ### 5. 连接 MCP 客户端 两种传输方式；根据您的证书情况进行选择。 **直接 HTTP** —— 任何支持 Streamable HTTP 的客户端指向 `https://my-instance/sitecore/api/mcp` 并附带 `Authorization: Bearer ` 请求头。在具有真实（受信任的）证书的实例上效果最好。 **stdio bridge（推荐用于本地开发）** —— 本地实例使用自签名证书，基于 Node/Bun 的客户端（VS Code、opencode）会拒绝这种证书。该 bridge 是一个 .NET 进程，其 `HttpClient` 信任 Windows 证书存储区，因此它可以无需处理证书问题即可连接。只需发布一次： ``` dotnet publish src/SitecoreMcp.Bridge -c Release # -> src/SitecoreMcp.Bridge/bin/Release/net8.0/win-x64/publish/sitecore-mcp-bridge.exe ``` VS Code (`.vscode/mcp.json`): ``` { "servers": { "sitecore": { "type": "stdio", "command": "C:\\path\\to\\sitecore-mcp-bridge.exe", "env": { "SITECORE_MCP_URL": "https://my-instance/sitecore/api/mcp", "SITECORE_MCP_KEY": "" } } } } ``` opencode (`opencode.json`，项目级作用域): ``` { "$schema": "https://opencode.ai/config.json", "mcp": { "sitecore": { "type": "local", "command": ["C:\\path\\to\\sitecore-mcp-bridge.exe"], "environment": { "SITECORE_MCP_URL": "https://my-instance/sitecore/api/mcp", "SITECORE_MCP_KEY": "{file:./.sitecore-mcp-key}" }, "enabled": true } } } ``` 请勿将 key 包含在已提交的配置中 —— 请引用环境变量，或者如上所述，引用一个被 gitignore 的文件 （`{file:./.sitecore-mcp-key}`，同时将 `.sitecore-mcp-key` 添加到 `.gitignore` 中）。 ## 许可证 MIT — 见 [LICENSE](LICENSE)。