Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
eb903a7
Declare the never return type on a throwing MCP test closure
binaryfire Nov 20, 2026
f180f97
Return protocol errors for malformed MCP requests and headers
binaryfire Nov 20, 2026
238749b
Add MCP conformance fixtures and pin the conformance suite
binaryfire Nov 20, 2026
b0aaf42
Refuse MCP client redirects and validate request origins
binaryfire Nov 20, 2026
2aeae53
Run OpenAI-compatible tool calls sent without an index
binaryfire Nov 20, 2026
8cf1563
Hint at a missing or invalid API key when a provider rejects it
binaryfire Nov 20, 2026
dc5ae43
Add Gemini classification and port AI provider and broadcasting fixes
binaryfire Nov 20, 2026
e43537f
Forward attachment provider options to Anthropic requests
binaryfire Nov 20, 2026
fe8df37
Decode structured output from a code fence with unpaired backticks
binaryfire Nov 20, 2026
e0fe0b9
Keep the text of every step in a stored prompted response
binaryfire Nov 20, 2026
1944d2d
Keep every tool call of a streamed Ollama reply
binaryfire Nov 20, 2026
ea7dc97
Classify provider errors when default JSON decoding throws
binaryfire Nov 20, 2026
fd3af4a
Decode a fence closed with a lone or longer backtick run
binaryfire Nov 20, 2026
c38b5b8
Keep streamed Anthropic citations on their text blocks
binaryfire Nov 20, 2026
a747a7e
Report rejected MCP notifications and keep the session
binaryfire Nov 20, 2026
5562433
Trim the legacy MCP protocol version header
binaryfire Nov 20, 2026
869a3e9
Only match configured MCP origins without a path
binaryfire Nov 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions dogfood/mcp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,15 @@ bash conformance/run.sh client

Use `bash conformance/run.sh all` to run both. The server command starts an isolated Testbench application on `127.0.0.1:8001` and stops it when finished. The client command runs against mock servers started by the conformance runner.

The runner downloads `@modelcontextprotocol/conformance@alpha` through `npx`. Set `CONFORMANCE_PACKAGE` to select a particular package version, `CONFORMANCE_PORT` to change the server port, or `CONFORMANCE_REVISION` to select the requirements revision (default `2026-07-28`). The server readiness probe uses modern discovery.
The runner downloads `@modelcontextprotocol/conformance@0.2.0-alpha.12` through `npx`. Set `CONFORMANCE_PACKAGE` to select a particular package version, `CONFORMANCE_PORT` to change the server port, or `CONFORMANCE_REVISION` to select the requirements revision (default `2026-07-28`). The server readiness probe uses modern discovery.

Each run prints its output directory. Logs, raw results and summary badges go into a new OS temporary directory. Set `CONFORMANCE_OUTPUT_DIR` to choose a different, empty output directory; reusing one mixes its results with previous runs.

## Expected failures

`conformance/conformance-baseline.yml` lists known failures. A successful command means no unexpected failures or stale baseline entries were reported; it does not mean every protocol check passed. The score includes passing and failing checks, excluding warnings and skipped checks.

The server fixtures exercise the package's supported tools, prompts, resources, completions and progress notifications. Several runner scenarios require optional features the package does not implement, such as Tasks, multi-round input requests and embedded-resource content. Swoole's trailing HTTP header whitespace defect also remains an expected failure until fixed upstream.
The server fixtures exercise the package's supported tools, prompts, resources, completions and progress notifications. Several runner scenarios require optional features the package does not implement, such as Tasks, multi-round input requests and embedded-resource content.

The client fixture exercises discovery, tool calls, schema preservation, HTTP header mirroring and OAuth against the runner's local servers. Authorization runs headlessly: the mock authorization endpoint redirects directly to a callback, which the fixture passes to the package's OAuth client. An array session holds the pending exchange. The fixture allows initial authorization and one reauthorization, including scope step-up and authorization-server migration.

Expand Down
8 changes: 8 additions & 0 deletions dogfood/mcp/conformance/ConformanceServer.php
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,16 @@
use Hypervel\Dogfood\Mcp\Conformance\Resources\TemplateResource;
use Hypervel\Dogfood\Mcp\Conformance\Resources\WatchedResource;
use Hypervel\Dogfood\Mcp\Conformance\Tools\AudioContentTool;
use Hypervel\Dogfood\Mcp\Conformance\Tools\CustomHeaderTool;
use Hypervel\Dogfood\Mcp\Conformance\Tools\EmbeddedResourceTool;
use Hypervel\Dogfood\Mcp\Conformance\Tools\ErrorHandlingTool;
use Hypervel\Dogfood\Mcp\Conformance\Tools\ImageContentTool;
use Hypervel\Dogfood\Mcp\Conformance\Tools\JsonSchema202012Tool;
use Hypervel\Dogfood\Mcp\Conformance\Tools\LoggingTool;
use Hypervel\Dogfood\Mcp\Conformance\Tools\MultipleContentTypesTool;
use Hypervel\Dogfood\Mcp\Conformance\Tools\ProgressTool;
use Hypervel\Dogfood\Mcp\Conformance\Tools\SimpleTextTool;
use Hypervel\Dogfood\Mcp\Conformance\Tools\StreamingElicitationTool;
use Hypervel\Mcp\Server;

class ConformanceServer extends Server
Expand All @@ -41,6 +45,10 @@ class ConformanceServer extends Server
MultipleContentTypesTool::class,
ErrorHandlingTool::class,
ProgressTool::class,
JsonSchema202012Tool::class,
CustomHeaderTool::class,
LoggingTool::class,
StreamingElicitationTool::class,
];

public array $resources = [
Expand Down
7 changes: 4 additions & 3 deletions dogfood/mcp/conformance/Prompts/PromptWithArguments.php
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,9 @@ public function arguments(): array
*/
public function complete(string $argument, string $value, array $context): CompletionResponse
{
return $argument === 'arg1'
? CompletionResponse::match(['test', 'testing', 'testable'])
: CompletionResponse::empty();
return match ($argument) {
'arg1' => CompletionResponse::match(['paris', 'park', 'party']),
default => CompletionResponse::empty(),
};
}
}
47 changes: 47 additions & 0 deletions dogfood/mcp/conformance/Tools/CustomHeaderTool.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
<?php

declare(strict_types=1);

namespace Hypervel\Dogfood\Mcp\Conformance\Tools;

use Hypervel\Contracts\JsonSchema\JsonSchema;
use Hypervel\Mcp\Request;
use Hypervel\Mcp\Response;
use Hypervel\Mcp\Server\Tool;

class CustomHeaderTool extends Tool
{
protected string $name = 'test_custom_header';

protected string $description = 'Tests custom Mcp-Param header mirroring';

/**
* Return the mirrored region.
*/
public function handle(Request $request): Response
{
return Response::text("Region: {$request->get('region')}");
}

/**
* Get the tool's input schema.
*/
public function schema(JsonSchema $schema): array
{
return [
'region' => $schema->string()->description('Deployment region')->required(),
];
}

/**
* Mark the region parameter for header mirroring.
*/
public function toArray(): array
{
$tool = parent::toArray();

$tool['inputSchema']['properties']['region']['x-mcp-header'] = 'Region';

return $tool;
}
}
65 changes: 65 additions & 0 deletions dogfood/mcp/conformance/Tools/JsonSchema202012Tool.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
<?php

declare(strict_types=1);

namespace Hypervel\Dogfood\Mcp\Conformance\Tools;

use Hypervel\Mcp\Request;
use Hypervel\Mcp\Response;
use Hypervel\Mcp\Server\Tool;

class JsonSchema202012Tool extends Tool
{
protected string $name = 'json_schema_2020_12_tool';

protected string $description = 'Tool with JSON Schema 2020-12 features';

/**
* Acknowledge the call.
*/
public function handle(Request $request): Response
{
return Response::text('ok');
}

/**
* Advertise an input schema using JSON Schema 2020-12 keywords.
*/
public function toArray(): array
{
return [
...parent::toArray(),
'inputSchema' => [
'$schema' => 'https://json-schema.org/draft/2020-12/schema',
'type' => 'object',
'$defs' => [
'address' => [
'$anchor' => 'addressDef',
'type' => 'object',
'properties' => [
'street' => ['type' => 'string'],
'city' => ['type' => 'string'],
],
],
],
'properties' => [
'name' => ['type' => 'string'],
'address' => ['$ref' => '#/$defs/address'],
'contactMethod' => ['type' => 'string', 'enum' => ['phone', 'email']],
'phone' => ['type' => 'string'],
'email' => ['type' => 'string'],
],
'allOf' => [
['anyOf' => [['required' => ['phone']], ['required' => ['email']]]],
],
'if' => [
'properties' => ['contactMethod' => ['const' => 'phone']],
'required' => ['contactMethod'],
],
'then' => ['required' => ['phone']],
'else' => ['required' => ['email']],
'additionalProperties' => false,
],
];
}
}
24 changes: 24 additions & 0 deletions dogfood/mcp/conformance/Tools/LoggingTool.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<?php

declare(strict_types=1);

namespace Hypervel\Dogfood\Mcp\Conformance\Tools;

use Hypervel\Mcp\Request;
use Hypervel\Mcp\Response;
use Hypervel\Mcp\Server\Tool;

class LoggingTool extends Tool
{
protected string $name = 'test_logging_tool';

protected string $description = 'Tests that no log notifications are sent without a requested log level';

/**
* Complete without sending log notifications.
*/
public function handle(Request $request): Response
{
return Response::text('Logging tool completed.');
}
}
24 changes: 24 additions & 0 deletions dogfood/mcp/conformance/Tools/StreamingElicitationTool.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<?php

declare(strict_types=1);

namespace Hypervel\Dogfood\Mcp\Conformance\Tools;

use Hypervel\Mcp\Request;
use Hypervel\Mcp\Response;
use Hypervel\Mcp\Server\Tool;

class StreamingElicitationTool extends Tool
{
protected string $name = 'test_streaming_elicitation';

protected string $description = 'Tests that the response stream never carries independent requests';

/**
* Complete without sending requests on the response stream.
*/
public function handle(Request $request): Response
{
return Response::text('Streaming elicitation tool completed.');
}
}
31 changes: 15 additions & 16 deletions dogfood/mcp/conformance/client.php
Original file line number Diff line number Diff line change
Expand Up @@ -104,22 +104,21 @@

$log(sprintf('listed %d tools', $tools->count()));

if ($scenario === 'http-custom-headers') {
foreach ($context['toolCalls'] as $call) {
$execute(fn () => $client->callTool($tools->get($call['name']), $call['arguments']));
}
} elseif ($scenario === 'json-schema-2020-12-preservation') {
$execute(fn () => $client->callTool($tools->get('json_schema_echo'), [
'schema' => $tools->get('json_schema_2020_12_tool')->inputSchema,
]));
} elseif ($scenario !== 'initialize') {
$tool = $tools->first();

if ($tool !== null) {
$execute(fn () => $client->callTool($tool, $scenario === 'tools_call' ? ['a' => 2, 'b' => 3] : []));

$log(sprintf('called tool %s', $tool->name));
}
$calls = match (true) {
isset($context['toolCalls']) => $context['toolCalls'],
$scenario === 'tools_call' => [['name' => 'add_numbers', 'arguments' => ['a' => 1, 'b' => 2]]],
$scenario === 'json-schema-2020-12-preservation' => [[
'name' => 'json_schema_echo',
'arguments' => ['schema' => $tools->get('json_schema_2020_12_tool')?->inputSchema],
]],
$scenario === 'initialize' || $tools->isEmpty() => [],
default => [['name' => $tools->first()->name, 'arguments' => []]],
};

foreach ($calls as $call) {
$execute(fn () => $client->callTool($tools->get($call['name']) ?? $call['name'], $call['arguments'] ?? []));

$log(sprintf('called tool %s', $call['name']));
}

$client->disconnect();
Expand Down
7 changes: 2 additions & 5 deletions dogfood/mcp/conformance/conformance-baseline.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,13 +25,10 @@ server:
- tools-call-embedded-resource
- tools-call-mixed-content
- prompts-get-embedded-resource
# Diagnostic tools for capability requests, elicitation and logging are not implemented.
# The diagnostic tool for requests needing an undeclared client capability is not implemented.
- server-stateless
# TODO: Remove once Swoole strips trailing HTTP/1 header whitespace upstream.
- http-header-validation
# Server schemas do not expose custom header annotations or arbitrary JSON Schema keywords.
# The server does not validate mirrored Mcp-Param headers against the request body.
- http-custom-header-server-validation
- json-schema-2020-12

client:
# Multi-round input requests are not implemented.
Expand Down
2 changes: 1 addition & 1 deletion dogfood/mcp/conformance/run.sh
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
#!/usr/bin/env bash
set -uo pipefail

CONFORMANCE="${CONFORMANCE_PACKAGE:-@modelcontextprotocol/conformance@alpha}"
CONFORMANCE="${CONFORMANCE_PACKAGE:-@modelcontextprotocol/conformance@0.2.0-alpha.12}"
REVISION="${CONFORMANCE_REVISION:-2026-07-28}"
PORT="${CONFORMANCE_PORT:-8001}"

Expand Down
27 changes: 27 additions & 0 deletions src/ai/src/Exceptions/InvalidApiKeyException.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<?php

declare(strict_types=1);

namespace Hypervel\Ai\Exceptions;

use Hypervel\Http\Client\RequestException;
use Hypervel\Http\Client\Response;

class InvalidApiKeyException extends RequestException
{
/**
* Create a new invalid API key exception.
*/
public function __construct(public string $provider, Response $response, false|int|null $truncateExceptionsAt = null)
{
parent::__construct($response, $truncateExceptionsAt);
}

/**
* Prepare the exception message.
*/
protected function prepareMessage(Response $response): string
{
return "Missing or invalid API key for AI provider [{$this->provider}]. " . parent::prepareMessage($response);
}
}
42 changes: 28 additions & 14 deletions src/ai/src/Gateway/Anthropic/Concerns/HandlesTextStreaming.php
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,7 @@ protected function processTextStream(
$messageUsage = [];
$usage = null;
$stopReason = '';
$citedUrls = [];

$emitTextStart = function () use (&$textStartEmitted, $messageId, $invocationId): ?StreamEvent {
if ($textStartEmitted) {
Expand Down Expand Up @@ -121,6 +122,21 @@ protected function processTextStream(
))->withInvocationId($invocationId);
};

$emitCitation = function (UrlCitation $citation) use (&$citedUrls, $messageId, $invocationId): ?StreamEvent {
if (in_array($citation->url, $citedUrls, true)) {
return null;
}

$citedUrls[] = $citation->url;

return (new CitationEvent(
$this->generateEventId(),
$messageId,
$citation,
time(),
))->withInvocationId($invocationId);
};

foreach ($this->parseServerSentEvents($streamBody) as $data) {
$type = $data['type'] ?? '';

Expand Down Expand Up @@ -196,13 +212,9 @@ protected function processTextStream(
} elseif ($this->isProviderToolResultBlock($blockType)) {
$fetchResult = $data['content_block']['content'] ?? [];

if ($blockType === 'web_fetch_tool_result' && ($fetchResult['type'] ?? '') === 'web_fetch_result' && filled($fetchResult['url'] ?? null)) {
yield (new CitationEvent(
$this->generateEventId(),
$messageId,
new UrlCitation($fetchResult['url'], $fetchResult['content']['title'] ?? null),
time(),
))->withInvocationId($invocationId);
if ($blockType === 'web_fetch_tool_result' && ($fetchResult['type'] ?? '') === 'web_fetch_result' && filled($fetchResult['url'] ?? null)
&& ($event = $emitCitation(new UrlCitation($fetchResult['url'], $fetchResult['content']['title'] ?? null))) instanceof StreamEvent) {
yield $event;
}

yield (new ProviderToolEvent(
Expand Down Expand Up @@ -270,13 +282,15 @@ protected function processTextStream(
} elseif ($deltaType === 'citations_delta' && $currentBlockType === 'text') {
$citationData = $data['delta']['citation'] ?? null;

if ($citationData && ($citationData['type'] ?? '') === 'web_search_result_location') {
yield (new CitationEvent(
$this->generateEventId(),
$messageId,
new UrlCitation($citationData['url'] ?? '', $citationData['title'] ?? null),
time(),
))->withInvocationId($invocationId);
// Unlike upstream, the citation is kept on its block, as in a buffered response,
// so the step's citations and replay content include it.
if ($citationData && isset($responseContent[$currentBlockIndex])) {
$responseContent[$currentBlockIndex]['citations'][] = $citationData;
}

if ($citationData && ($citationData['type'] ?? '') === 'web_search_result_location'
&& ($event = $emitCitation(new UrlCitation($citationData['url'] ?? '', $citationData['title'] ?? null))) instanceof StreamEvent) {
yield $event;
}
} elseif ($deltaType === 'input_json_delta') {
$partial = (string) ($data['delta']['partial_json'] ?? '');
Expand Down
Loading