Add Annotation Support on Resources

[pushpak1300]

This PR adds support for resource annotations as defined in the MCP Specs.

Usage

Three annotation types are now available for use with Resource classes.

1. Audience.

use Laravel\Mcp\Enums\Role;
use Laravel\Mcp\Server\Annotations\Audience;
use Laravel\Mcp\Server\Resource;

#[Audience(Role::ASSISTANT)]
class SystemLogsResource extends Resource
{
    protected string $description = 'System logs for debugging';

    public function handle(): Response
    {
        return Response::text($this->getSystemLogs());
    }
}

Accepted values: Role::USER, Role::ASSISTANT, or an array of both.

#[Audience([Role::USER, Role::ASSISTANT])]
class DocumentationResource extends Resource { }

2. Priority.

A numerical score between 0.0 and 1.0 indicating resource importance.

use Laravel\Mcp\Server\Annotations\Priority;

#[Priority(1.0)]
class CriticalConfigResource extends Resource
{
    protected string $description = 'Critical application configuration';

    public function handle(): Response
    {
        return Response::text(config('app'));
    }
}

Validation. Throws InvalidArgumentException if value is outside the 0.0 to 1.0 range.

3. LastModified

An ISO 8601 timestamp showing when the resource was last updated.

use Laravel\Mcp\Server\Annotations\LastModified;

#[LastModified('2025-01-12T15:00:58Z')]
class CachedDataResource extends Resource
{
    protected string $description = 'Cached analytics data';

    public function handle(): Response
    {
        return Response::text($this->getCachedData());
    }
}

Accepted formats:

• 2025-01-12T15:00:58Z
• 2025-01-12T15:00:58+00:00
• Any other ISO 8601 compliant format

Validation. Throws InvalidArgumentException if the timestamp format is invalid.

Combining Multiple Annotations

All three annotations can be combined on a single resource.

use Laravel\Mcp\Enums\Role;
use Laravel\Mcp\Server\Annotations\Audience;
use Laravel\Mcp\Server\Annotations\LastModified;
use Laravel\Mcp\Server\Annotations\Priority;

#[Audience(Role::USER)]
#[Priority(0.9)]
#[LastModified('2025-01-12T15:00:58Z')]
class UserDashboardResource extends Resource
{
    protected string $description = 'User-facing dashboard data';

    public function handle(): Response
    {
        return Response::text($this->getDashboardData());
    }
}

How It Works

Annotations are automatically included in resource listings via the resources/list method.

{
  "uri": "file://resources/user-dashboard",
  "name": "UserDashboard",
  "description": "User-facing dashboard data",
  "mimeType": "text/plain",
  "annotations": {
    "audience": ["user"],
    "priority": 0.9,
    "lastModified": "2025-01-12T15:00:58Z"
  }
}

If no annotations are present, the annotations field is omitted entirely from the response.

Important

This implementation throw error if Invalid Annotations are added on the Tool::class or Resource::class

[taylorotwell]

Should this just be an annotations method on the resource that returns an array?

[pushpak1300]

@taylorotwell It could be, and it already works since the user can override the annotations method and return an array. But for defining tool annotations we already use attributes, so it would be better if the codebase supported this in a consistent way instead of having two completely different approaches.