内容
# TYPO3 变更日志模型上下文协议（MCP）服务器
本 TYPO3 扩展程序编目了官方的 TYPO3 核心变更日志，将它们转换为 Markdown 格式，并通过 **模型上下文协议（MCP）** 提供。这样允许 AI 助手（如 Claude、PhpStorm 或其他 MCP 兼容的客户端）直接从您的 TYPO3 实例访问有关 TYPO3 核心 API、废弃功能、重大更改、功能和重要说明的最新信息。
> [!NOTE]
> **目标受众和使用场景：**
> 大型基于云的语言模型（如 Gemini 或 GPT-4）通常可以直接回答 TYPO3 变更日志问题，因为它们具有预训练的知识。
>
> 此 MCP 服务器主要设计用于：
> - **本地语言模型**：在您的 PC/Mac 上本地运行的小型模型（例如，通过 Ollama/Llama.cpp），缺乏特定 TYPO3 版本的训练数据。
> - **隔离或空气隔离网络**：AI 模型无法访问互联网或外部文档的环境。
> - **确保准确性**：通过强制模型查询确切的官方数据库，防止语言模型产生幻觉。
---
## 功能
- **变更日志解析器和导入器**：将 TYPO3 核心 RST 变更日志转换为 Markdown 格式，并将它们存储在数据库中，以便快速查询。
- **模型上下文协议（MCP）**：
- **标准输入/输出传输**：通过 TYPO3 控制台命令支持。
- **HTTP 传输**：通过 TYPO3 Reactions 扩展程序支持（SSE/GET 用于连接，POST 用于传入请求）。
- **会话持久性**：在 TYPO3 的可写目录（`var/mcp_sessions`）内使用 `FileSessionStore` 来持久化客户端会话，以跨无状态 HTTP 请求。
---
## 安装和设置
1. **要求扩展程序**：
```bash
composer require stefanfroemken/changelog-mcp
```
2. **运行架构迁移**：
通过 TYPO3 安装工具、TYPO3 后台或 CLI 更新您的数据库架构：
```bash
vendor/bin/typo3 extension:setup
```
3. **导入 TYPO3 变更日志**：
处理并导入 RST 文件到 TYPO3 数据库：
```bash
vendor/bin/typo3 changelog:mcp:prepare
```
---
## 使用和集成
### 1. 标准输入/输出传输（例如用于 IDE 集成）
在本地标准输入/输出上运行 MCP 服务器：
```bash
vendor/bin/typo3 changelog:mcp:server
```
### 2. HTTP 传输（通过 TYPO3 Reactions）
扩展程序实现了 `ChangelogMcpReaction`，以通过 TYPO3 Reactions 中的 HTTP 端点公开 MCP 服务器。
要使用 HTTP 传输，您必须在 TYPO3 后台配置一个 Reaction 记录：
1. 进入 **集成** -> **Reactions**，位于后台模块菜单中。
2. 点击创建新的 Reaction 记录。
3. 选择 **TYPO3 变更日志 MCP** Reaction 类型。
4. 提供描述并设置秘密 API 密钥。
5. 保存记录并使用生成的 Reaction ID（UUID，例如 `a7279da8-56c1-4642-8248-74668bd50a82`）用于您的请求。
---
## 开发和测试
您可以使用 `curl` 手动测试 HTTP/JSON-RPC 通信。
### 步骤 1：初始化会话
向 Reaction 端点发送 `initialize` 请求以启动 MCP 会话。确保用实际值替换端点 URL、`API_SECRET` 和 Reaction ID：
```bash
curl -i -X POST "https://typo3143.ddev.site/typo3/reaction/a7279da8-56c1-4642-8248-74668bd50a82" \
-H "x-api-key: API_SECRET" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {
"name": "mcp-test-client",
"version": "1.0.0"
}
},
"id": 1
}'
```
*注意：响应将包含 `Mcp-Session-Id` 头（例如 `Mcp-Session-Id: 250fd04a-9a0c-48d3-b6e2-99e3d9c8ebca`），您必须在后续请求中使用此 ID。*
### 步骤 2：调用 MCP 工具
使用从初始化步骤中检索到的会话 ID 查询 `search_changelogs` 工具，并使用搜索查询：
```bash
curl -X POST "https://typo3143.ddev.site/typo3/reaction/a7279da8-56c1-4642-8248-74668bd50a82" \
-H "x-api-key: API_SECRET" \
-H "Mcp-Session-Id: YOUR_SESSION_ID" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "search_changelogs",
"arguments": {
"query": "encryption"
}
},
"id": 2
}'
```
### 步骤 3：MCP 客户端配置
要通过 HTTP 将 MCP 客户端（例如 Claude Desktop、Windsurf 或 Antigravity）连接到此服务器，您可以添加以下块到您的 `mcp_config.json`：
```json
{
"mcpServers": {
"typo3-changelog-http": {
"serverUrl": "https://typo3143.ddev.site/typo3/reaction/a7279da8-56c1-4642-8248-74668bd50a82",
"headers": {
"x-api-key": "API_SECRET",
"Content-Type": "application/json",
"Accept": "application/json"
}
}
}
}
```
