All notable changes to the Zolinga framework (system module) will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
- MCP
resources/listandresources/readsupport. The MCP gateway now implements the MCP Resources protocol. Module authors can drop.meta.jsondescriptor files (alongside content files) intomodules/<module>/mcp/resources/to expose them as discoverable, readable resources. TheMcpResourcesListHandlerauto-discovers them and rewrites internalmodule://URIs to the externalmcp-system://<module>/resources/<basename>scheme so internal paths are never leaked. TheMcpResourcesReadHandlerserves text resources as{ text }and binary resources as{ blob }(base64-encoded) based on themimeTypein the.meta.json. McpEvent::validateResponse()β new hook method called by the gateway before producing any output to clients. The base implementation is a no-op; descendant event classes can override it to enforce response-level constraints (e.g. URI scheme whitelisting).Resources\ListEventandResources\ReadEventoverride it to validate that all resource URIs use allowed schemes (mcp-system,http,https).Resources\ListEvent::addResourceJson()andaddResource()β append resource descriptors to theresources/listresponse with validation (non-emptyuriwith allowed scheme, non-emptyname).Resources\ListEvent::validateResponse()β validates all resource URIs in the response against the allowed scheme whitelist.Resources\ReadEvent::validateResponse()β validates the response content URIs against the allowed scheme whitelist.ResourcesEvent::ALLOWED_URI_SCHEMESconstant andisAllowedScheme()method β defines the whitelist of URI schemes allowed in resource responses (mcp-system,http,https).resourcescapability added to theinitializeresponse. Theinstructionstext now mentionsresources/listandresources/read.
Resources\ReadEventconstructor now extracts the URI scheme from theurirequest parameter and appends it to the event type (e.g.mcp:resources/read:mcp-system), enabling per-scheme handler registration.McpServer::buildResponse()now calls$event->validateResponse()before producing output. If validation throws, the event status is set toERRORand an error response is returned.
McpToolsrenamed toMcpToolsListHandler. Thetools/listhandler class is nowZolinga\System\Mcp\McpToolsListHandler(filesrc/Mcp/mcp-tools-list-handler.php), matching the*Handlersuffix convention used byMcpInitializeHandlerandMcpEchoHandler. The system manifestmcp:tools/listlistener class reference was updated. All wiki and skill documentation references updated.
Mcp\Tools\ListEvent::addTool()β appends a tool to thetools/listresponse with validation. Checks the tool name against the MCP character class ([A-Za-z0-9_:-]{1,64}, nomcp:prefix) viaMcpHelper::isValidToolName()and rejects schemas that are not JSON objects (associative arrays), throwingInvalidArgumentExceptionon any violation. Lets customtools/listhandlers build the catalogue programmatically without bypassing the wire contract.
McpTools::collectTools()now populates the response viaListEvent::addTool()instead of building the tool array directly. The name-format and schema-shape validation thataddTool()provides now guards every tool the manifest walk emits; a tool that fails validation is logged and skipped rather than poisoning the response. Behavior (tool set, ordering, schemas) is unchanged.
- MCP event class hierarchy introduced. The single
\Zolinga\System\Events\McpEventclass is now an abstract base under the new\Zolinga\System\Events\Mcpnamespace, with one concrete subclass per JSON-RPC method:InitializeEvent(initialize),Tools\ListEvent(tools/list),Tools\CallEvent(tools/call),Prompts\ListEvent/Prompts\GetEvent(prompts/*), andResources\ListEvent/Resources\ReadEvent(resources/*).McpEvent::fromJsonRpc()resolves the correct subclass via amatchon the JSON-RPCmethod. The system manifest now type-hintsmcp:initializeandmcp:tools/listlisteners with their concrete event classes (InitializeEvent,Tools\ListEvent) instead of the genericMcpEvent.
- Legacy
\Zolinga\System\Events\McpEvent(the old flat class atsrc/Events/McpEvent.php) β replaced by theMcpnamespace hierarchy. Tool handlers now type-hintTools\CallEventinstead ofMcpEvent. McpEvent::$isToolCallflag. The gateway now distinguishestools/callinvocations byinstanceof CallEvent(and wraps the response in the MCP envelope accordingly) instead of a boolean flag set byfromJsonRpc().McpRequestValidatorclass β its validation logic was already moved intoMcpEvent::fromJsonRpc()in 1.6.8; the leftover dead file (src/Mcp/McpRequestValidator.php) is now deleted.
- MCP tool names now allow
:in the character set.McpHelper::TOOL_NAME_CHAR_CLASSchanged from[A-Za-z0-9_-]to[A-Za-z0-9_:-]so that Zolinga event names with colons (e.g.my-module:search) can be exposed as MCP tools verbatim.McpHelper::isValidToolName()now explicitly rejects names starting withmcp:to prevent collision with protocol events, replacing the previous implicit guarantee that relied on:being absent from the allowed charset.
- MCP protocol events are now prefixed with
mcp:. All non-tools/callJSON-RPC methods dispatched by the MCP gateway are prefixed withmcp:and keep their original method path verbatim (e.g.initializeβmcp:initialize,tools/listβmcp:tools/list,notifications/initializedβmcp:notifications/initialized).tools/callstill uses the bare tool name as the event type.McpTools::isReservedEvent()excludes protocol events with a singlestr_starts_with($eventName, 'mcp:')check instead of a hardcoded list β new protocol methods are automatically excluded.
- MCP tools no longer use the
tools:call:event-name prefix. MCP tool events are now distinguished from other MCP events solely by themcporigin and the presence of aschema.response, not by an event-name prefix. The gateway dispatchestools/callusing the bare tool name (params.name) as the event type (e.g.echoinstead oftools:call:echo).McpEventgained anisToolCallflag (set byfromJsonRpc()) that the gateway uses to decide envelope wrapping andisErrormapping, replacing the previousstr_starts_with($event->type, 'tools:call:')check.McpTools::collectTools()now uses the listener's event name verbatim as the tool name and excludes reserved MCP protocol events (initialize,tools:list,notifications:*) instead of matching thetools:call:prefix. Thetools:call:*emit entry was removed from the system manifest.
WWW-Authenticateheader now quotes theresource_metadataURL value per RFC 9728 Section 5.1 (e.g.Bearer resource_metadata="https://..."). Some clients failed to parse the unquoted form correctly.
McpServer::sendHeadersForStatus()now uses$api->url->resolveUrl()to build theWWW-Authenticateheader URL instead of manually concatenatingbaseURL+ path. This ensures the PRM URL is resolved consistently with the rest of the system.
- MCP gateway rewritten from scratch:
McpServerreduced from ~640 to ~250 lines. Clean linear pipeline: parse JSON -> createMcpEvent-> dispatch -> serialize response. Dropped batch support (MCP Streamable HTTP spec is one message per request). DroppedfirstMethod/firstToolNamestate fields,process(),isBatch, and 5 separate send methods. McpEvent::fromJsonRpc(): New static factory onMcpEventthat validates the JSON-RPC 2.0 envelope and resolves the Zolinga event type (tools/call->tools:call:<name>, otherwise/->:). Moves input parsing into the event class where it belongs.McpServerAPI change:run()is the single public entry point (replacesprocess()->send()).sendException()renamed tosendError(). HTTP response status now reflects the event status (401 for UNAUTHORIZED, 404 for NOT_FOUND, etc.) instead of always 200. UNAUTHORIZED responses include aWWW-Authenticate: Bearer resource_metadata=...header pointing to the OAuth Protected Resource Metadata endpoint (RFC 9728).- MCP gateway refactoring:
McpToolsCallEventmerged intoMcpEvent. The gateway now usesstr_starts_with($event->type, 'tools:call:')instead ofinstanceofto decide envelope wrapping. Tool handlers type-hintMcpEventinstead ofMcpToolsCallEvent. - Removed
McpToolsCallEvent: The$contentproperty andaddTextContent()method are gone. The gateway always auto-generatescontentfromjson_encode($response)(or$event->messageon error). No tool in the codebase used them. AuthorizeEvent: AddedrequiresLoginproperty (bool) andrequireLogin()setter. Whentrue, a failed authorization should result in HTTP 401 Unauthorized; whenfalse(default), HTTP 403 Forbidden.
McpRequestValidatorclass β logic moved intoMcpEvent::fromJsonRpc().McpHelper::BATCH_MAX_REQUESTSconstant β batches no longer supported.McpToolsCallEventclass β useMcpEventinstead.McpEvent::$contentproperty andaddTextContent()method β the gateway auto-generates content blocks.
- Content event refactoring:
ContentEventis now an abstract base class with concrete subclasses for HTML, JSON, and plain text content. - Two-phase content dispatch:
PreflightEventdetermines MIME type before the content event, enabling non-HTML responses (JSON, text) from any URL. - New
ContentMimeTypesEnumfor mapping MIME types to content event classes. - MCP server logging improvements.
- Updated all documentation and skills.
- Per-request access log on the MCP gateway (
/mcp/). Every request β POST, GET, DELETE, etc. β produces a shortsystem:mcp:infoline via$api->logwith the request contents (method, tool, size, batch flag, response status). No IP or User-Agent duplication (Apache already records those). McpServer::run()β top-level request entry point that picks POST vs non-POST and returns a spec-compliant 405 withAllow: GET, POST, DELETEfor non-POST (per MCP Streamable HTTP spec Β§2.2 / Β§2.5).McpServer::logAccess(int $status, ?string $method, bool $isBatch, ?string $toolName)β the helper behind the access log. Bounded viaMcpHelper::truncateForEcho().
MCP gateway hardening after a soft penetration test. No protocol or API changes for well-behaved clients.
- 64 KiB request body cap (HTTP 413).
- 50-request batch cap.
- 64-char
idcap, 256-charmethodcap β oversize values are not echoed back. McpHelper::truncateForEcho()β strips control characters, caps at 200 chars, applied to every attacker-controlled field in error responses and log lines.- Top-level scalar JSON is now a parse error (was silent 204).
- Empty batches are an invalid-request error (was silent 204).
- Invalid
Mcp-Session-Idvalues are dropped with a truncated warning. - Non-POST requests are rejected with HTTP 405 (POST is the only method that carries a JSON-RPC message; the spec allows 405 for non-streaming gateways).
McpToolsCallEvent(extendsMcpEvent) β per-tool event dispatched astools:call:<name>. Carries a$contentarray of human-readable blocks and anaddTextContent()helper. Handlers set the raw structured payload on$event->response; the gateway builds the MCP{ content, isError, structuredContent }envelope.McpHelper::envelope(McpToolsCallEvent)β builds the standard MCPtools/callresult envelope. When the handler adds no content blocks, the gateway falls back to a single text block carryingjson_encode($event->response).McpToolsenforcesschema.responseon every exposed tool. Listeners without one are skipped bytools/listand an error is logged via$api->log->error().
- The gateway now wraps
tools/callresponses β handlers no longer build the envelope. Errors surface asresult.isError = true, never as a JSON-RPCerrorblock. - Unknown tools are an MCP error envelope, not a JSON-RPC
errorblock.
- MCP-conformant gateway: separate handlers for
initialize(lifecycle payload only),tools/list(tool discovery) andtools/call(tool invocation). - New
McpToolsclass,McpServerorchestrator,McpRequestValidator,McpHelper, and exception classes (McpException,McpParseErrorException,McpInvalidRequestException,McpMethodNotFoundException,McpInvalidParamsException,McpInternalErrorException). - New
McpEchoHandlerexample tool. tools/listnow excludes reserved MCP protocol methods.- WIKI: new
tools/listandtools/callreference pages; [MCPpage](:Zolinga Core:Running the System:MCP) rewritten.
- MCP (Model Context Protocol) non-streaming HTTP gateway at
public/mcp/index.php. Translates JSON-RPC 2.0 requests into Zolinga events dispatched from the newmcporigin. - New event class
\Zolinga\System\Events\McpEvent(extendsRequestResponseEvent, adds the JSON-RPCid). - New system handler
\Zolinga\System\Mcp\McpInitializeHandlerthat handles the MCPinitializerequest and returns the list of all listeners that opt in to themcporigin, including descriptions and JSON Schema files. - New
mcpvalue in\Zolinga\System\Types\OriginEnumand a matchingEvent::ORIGIN_MCPconstant. - Optional
schemaproperty on listen atoms ({ request?: string, response?: string }) β each value is a Zolinga URI pointing to a JSON Schema file. - Documentation: [MCP (Model Context Protocol)](:Zolinga Core:Running the System:MCP), [MCP Events](:Zolinga Core:Events and Listeners:MCP), and event reference pages for
initializeandmcp:echo.
- MCP (Model Context Protocol) non-streaming HTTP gateway at
public/mcp/index.php. Translates JSON-RPC 2.0 requests into Zolinga events dispatched from the newmcporigin, and serializes responses back as JSON-RPC 2.0 messages. - New event class
\Zolinga\System\Events\McpEvent(extendsRequestResponseEvent, adds the JSON-RPCid). - New system handler
\Zolinga\System\Mcp\McpInitializeHandlerthat handles the MCPinitializerequest and returns the list of all listeners that opt in to themcporigin, including descriptions and JSON Schema files. - New
mcpvalue in\Zolinga\System\Types\OriginEnumand a matchingEvent::ORIGIN_MCPconstant. - Optional
schemaproperty on listen atoms ({ request?: string, response?: string }) β each value is a Zolinga URI pointing to a JSON Schema file (e.g.module://my-module/schema/mcp/tool.json). The MCPinitializehandler embeds the parsed schema asinputSchema/outputSchema. - Documentation: [MCP (Model Context Protocol)](:Zolinga Core:Running the System:MCP), [MCP Events](:Zolinga Core:Events and Listeners:MCP), and event reference pages for
initializeandmcp:echo.
system-changelogskill: guidance for creating and maintaining CHANGELOG.md files per Keep a Changelog and SemVer standards.- Manifest skill now requires updating CHANGELOG.md when bumping module version.