TinaCMS MCP Server (C#)

TinaCMS MCP 服务（C#）

本项目使用官方 C# SDK（modelcontextprotocol/csharp-sdk）实现了一个独立的模型上下文协议（MCP）服务。它旨在提供一组工具，用于与 TinaCMS 项目仓库管理的内容文件进行交互。

借助标准化的 MCP，AI 模型或其他 MCP 客户端可以在 TinaCMS 站点中列出、读取、创建、更新和删除内容文件。

功能

• 连接本地 TinaCMS 项目目录。
• 使用标准 MCP Stdio 传输进行通信。
• 提供用于基本内容管理操作的工具：
  • 列出集合（/content 下的目录）。
  • 列出集合中的文档（非递归和递归）。
  • 读取文档内容。
  • 读取文档 frontmatter（元数据）。
  • 创建新文档。
  • 更新现有文档（完整替换内容）。
  • 更新文档 frontmatter（合并元数据）。
  • 删除文档。
  • 移动/重命名文档。
  • 复制文档。
  • 读取 TinaCMS 生成的架构（.tina/schema.json）。
• 包含基本的路径验证和安全检查。

前提条件

• .NET 8 SDK（或更高版本）：用于构建和运行 C# 服务。
• Node.js 和 npm/npx： 用于运行 MCP Inspector 工具进行测试。
• TinaCMS 项目： 需要一个本地 TinaCMS 项目，其内容将由此服务管理。

设置

1. 克隆/下载： 获取本项目的源代码。
2. 配置根路径：
   • 打开 appsettings.json 文件。
   • 找到 TinaProject 部分。
   • 重要： 将 RootPath 提供的示例路径替换为目标 TinaCMS 项目根目录的完整绝对路径（该目录中包含 .tina 文件夹）。
   • 路径分隔符建议使用正斜杠（/），以便跨平台兼容；在 Windows 上也可以根据需要使用双反斜杠（\\）。

   {
     "Logging": { ... },
     "TinaProject": {
       "RootPath": "/path/to/your/tina-project" 
     }
   }
   

3. 还原依赖项： 在 TinaMcpServer 项目目录中打开终端并运行：

   dotnet restore
   

开发

• 构建： 编译项目：

  dotnet build
  

• 在本地运行（用于测试）： 本服务设计为由 MCP 客户端（如 Inspector）运行。直接运行用处不大，但你可以使用以下命令启动：

  dotnet run 
  

  或运行编译后的 DLL：

  dotnet bin/Debug/net8.0/TinaMcpServer.dll
  

  服务将启动并等待 MCP 客户端通过标准输入/输出进行连接。如果在没有客户端的情况下运行，服务可能会立即退出或显示 JSON 错误。

使用 MCP Inspector 进行测试

推荐使用官方 MCP Inspector 测试此服务及其工具。

1. 确保项目已构建： 如果尚未运行，请执行 dotnet build。
2. 运行 Inspector： 在终端中（位于 TinaMcpServer 项目目录）运行以下命令。该命令会指示 Inspector 使用 dotnet 启动已编译的服务 DLL：

   npx @modelcontextprotocol/inspector dotnet bin/Debug/net8.0/TinaMcpServer.dll
   

3. 打开 Inspector UI： 命令会输出一个 URL（例如，http://127.0.0.1:6274）。在 Web 浏览器中打开此 URL。
4. 连接： 点击已检测到的 TinaMcpServer 对应的“Connect”按钮。
5. 使用工具：
   • 前往“Tools”标签页。
   • 点击“List Tools”查看所有可用工具。
   • 点击特定工具，查看其说明和参数。
   • 填写必需参数并点击“Run Tool”。
   • 查看结果，并检查运行 Inspector 的终端中来自 C# 服务的日志。

可用工具

（此处简要介绍工具；完整详情请参阅代码中的工具属性）

• ListTinaCollections()：列出 /content 下的集合目录。
• ListCollectionDocuments(collection)：列出集合目录中的文件。
• ListDocumentsRecursive(collection)：列出集合中的所有文件，包括子目录中的文件。
• GetTinaDocument(collection, relativePath)：获取文档的完整文本内容。
• CreateTinaDocument(collection, relativePath, content)：创建新文档；如果文档已存在则失败。
• UpdateTinaDocument(collection, relativePath, content)：覆盖现有文档；如果文档不存在则失败。
• DeleteTinaDocument(collection, relativePath)：删除现有文档；如果文档不存在则失败。
• MoveDocument(collection, oldRelativePath, newRelativePath)：移动或重命名文档。
• CopyDocument(collection, sourceRelativePath, destinationRelativePath)：复制文档。
• GetDocumentMetadata(collection, relativePath)：以 JSON 字符串形式获取 YAML frontmatter。
• UpdateDocumentMetadata(collection, relativePath, metadataUpdatesJson)：根据 JSON 对象添加或更新 frontmatter 字段。
• GetCollectionSchemaInfo(collection)：读取 .tina/schema.json 文件内容。

未来可能的增强

• 支持配置假定的 /content 目录名称。
• 提供更精细的更新操作（例如，支持部分更新，而非完全替换）。
• 根据需要支持不同的 frontmatter 格式（例如 JSON、TOML）。
• 增强架构解析和交互能力。
• 支持不同的传输选项（例如 HTTP/SSE）。