README

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

Note

Target Audience & Use Case: Large cloud-based LLMs (such as Gemini or GPT-4) can often answer TYPO3 changelog questions out of the box using their pre-trained knowledge.

This MCP server is primarily designed for:

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

Features

Changelog Parser & Importer: Converts TYPO3 Core RST 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/mcp_sessions) to persist client sessions across stateless HTTP requests.

Installation & Setup

Require the Extension:

composer require stefanfroemken/changelog-mcp

Run Schema Migration: Update your database schema via the TYPO3 Install Tool, TYPO3 Backend, or CLI:
```
vendor/bin/typo3 extension:setup
```
Import TYPO3 Changelogs: Process and import the RST files into the TYPO3 database:
```
vendor/bin/typo3 changelog:mcp:prepare
```

Usage & Integration

1. STDIO Transport (e.g. for IDE integrations)

Run the MCP server locally over standard input/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, you must configure a Reaction record in the TYPO3 Backend:

Go to Integrations -> Reactions in the backend module menu.
Click to create a new Reaction record.
Select the TYPO3 Changelog MCP reaction type.
Provide a description and set up the secret API key.
Save the record and use the generated Reaction ID (UUID, e.g., a7279da8-56c1-4642-8248-74668bd50a82) for your requests.

Development & Testing

You can manually 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. Make sure to replace the endpoint URL, API_SECRET, and reaction ID with your actual values:

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 (e.g., Mcp-Session-Id: 250fd04a-9a0c-48d3-b6e2-99e3d9c8ebca), which you must use 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, you can 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"
      }
    }
  }
}

stefanfroemken / changelog-mcp

Maintainers

Package info

Statistics

Security