README

This TYPO3 extension catalogues official TYPO3 Core changelogs, converts them to Markdown, and provides them via the Model Context Protocol (MCP). AI assistants such as Claude, PhpStorm, or other MCP-compatible clients can access up-to-date information directly from your TYPO3 instance. Supported topics include Core APIs, deprecations, and breaking changes along with features and important notes.

Note

Target Audience & Use Case: Large cloud-based LLMs often answer TYPO3 questions using pre-trained knowledge.

This MCP server is primarily designed for:

• Local LLMs: Small models running locally (via Ollama or Llama.cpp) that lack training data on specific TYPO3 versions.
• Isolated Networks: Air-gapped environments where AI models cannot access external documentation.
• Guaranteed Accuracy: Preventing LLM hallucinations by forcing models to query the exact, official database.

Features

• Changelog Parser and Importer: Converts TYPO3 Core ReST changelogs into Markdown format and stores them in a database for fast querying.
• Model Context Protocol (MCP):
  • STDIO Transport: Supported via a TYPO3 console command.
  • HTTP Transport: Supported via the TYPO3 Reactions extension (SSE/GET for connections, POST for incoming requests).
• Session Persistence: Utilizes FileSessionStore inside TYPO3's writeable directory (var/changelog_mcp_sessions) to persist client sessions across stateless HTTP requests.

Requirements and Prerequisites

• PHP 8.2 or higher with ext-mbstring
• TYPO3 v14.0 or higher
• System extension typo3/cms-reactions
• TYPO3 Core changelog ReST files (included in vendor/typo3/cms-core/Documentation/Changelog/)

Installation and Setup

1. Require the Extension:

   composer require stefanfroemken/changelog-mcp

2. Run Schema Migration: Update your database schema via CLI, Install Tool, or Backend:

   vendor/bin/typo3 extension:setup

3. Import TYPO3 Changelogs: Process and import the ReST files into the TYPO3 database:

   vendor/bin/typo3 changelog:mcp:prepare

Usage and Integration

1. STDIO Transport (IDE integrations)

Run the MCP server locally over standard input and output:

vendor/bin/typo3 changelog:mcp:server

2. HTTP Transport (via TYPO3 Reactions)

The extension implements ChangelogMcpReaction to expose the MCP server over an HTTP endpoint under TYPO3 Reactions.

To use the HTTP transport, configure a Reaction record in the TYPO3 Backend:

1. Navigate to Integrations > Reactions in the backend module menu.
2. Click to create a new Reaction record.
3. Select the TYPO3 Changelog MCP reaction type.
4. Provide a description and set up the secret API key.
5. Save the record and use the generated Reaction ID (UUID) for your requests.

Development and Testing

You can test the HTTP JSON-RPC communication using curl.

Step 1: Initialize Session

Send an initialize request to the reaction endpoint to start an MCP session:

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
      }'

Note: The response will contain the Mcp-Session-Id header, which you must supply in subsequent requests.

Step 2: Call MCP Tool

Query the search_changelogs tool with a search query using the session ID retrieved from the initialization step:

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
      }'

Step 3: MCP Client Configuration

To connect an MCP client (such as Claude Desktop, Windsurf, or Antigravity) to this server over HTTP, add this block to your mcp_config.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"
      }
    }
  }
}