PHPackages                             wazobia/nexus-mcp-laravel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. wazobia/nexus-mcp-laravel

ActiveLibrary[Authentication & Authorization](/categories/authentication)

wazobia/nexus-mcp-laravel
=========================

Laravel HMAC middleware and MCP server helpers for the Nexus MCP ecosystem

v1.0.1(1mo ago)0142MITPHPPHP ^8.1

Since Jun 11Pushed 1mo agoCompare

[ Source](https://github.com/wazobiatech/nexus-mcp-laravel)[ Packagist](https://packagist.org/packages/wazobia/nexus-mcp-laravel)[ RSS](/packages/wazobia-nexus-mcp-laravel/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (12)Versions (3)Used By (0)

wazobia/nexus-mcp-laravel
=========================

[](#wazobianexus-mcp-laravel)

Laravel HMAC middleware and MCP server helpers for the [Nexus MCP](https://github.com/wazobiatech/nexus-mcp-contract) ecosystem.

The PHP/Laravel equivalent of the TypeScript (`@wazobiatech/nexus-mcp`), Python (`wazobiatech-nexus-mcp`), and Go (`github.com/wazobiatech/nexus-mcp-go`) SDKs. All four SDKs produce byte-identical HMAC-SHA256 signatures, verified by the shared [contract test vectors](https://github.com/wazobiatech/nexus-mcp-contract).

---

Requirements
------------

[](#requirements)

- PHP `^8.1`
- Laravel `^10.0` or `^11.0`
- Guzzle `^7.0`

---

Installation
------------

[](#installation)

```
composer require wazobia/nexus-mcp-laravel
```

The `McpServiceProvider` is auto-discovered — no manual registration needed.

---

Quick Start
-----------

[](#quick-start)

Create a route file `routes/mcp.php` and register it in your `RouteServiceProvider` (or `bootstrap/app.php` in Laravel 11):

```
use Wazobia\NexusMcp\Manifest;
use Wazobia\NexusMcp\ManifestContext;
use Wazobia\NexusMcp\McpRouter;
use Wazobia\NexusMcp\McpToolDefinition;

$manifest = new Manifest(
    namespace: 'my-service',
    description: 'My service MCP manifest',
    version: '1.0.0',
    context: new ManifestContext(
        boundedContext: 'my-service',
        description: 'Handles ...',
        capabilities: ['...'],
        knownGaps: [],
    ),
    tools: [],
);

$tools = [
    new McpToolDefinition(
        name: 'my_tool',
        description: 'Does something useful',
        inputSchema: [
            'type' => 'object',
            'properties' => [
                'message' => ['type' => 'string', 'description' => 'Input message'],
            ],
            'required' => ['message'],
        ],
        handler: function (array $args): array {
            return ['result' => 'Hello, ' . $args['message']];
        },
    ),
];

McpRouter::register(
    manifest: $manifest,
    tools:    $tools,
    secret:   env('MCP_HMAC_SECRET'),
    healthExtra: [
        'server'    => 'my-service-mcp-server',
        'version'   => '1.0.0',
        'timestamp' => now()->toISOString(),
    ],
);
```

This registers three routes:

MethodPathAuthDescription`GET``/health`NoneK8s liveness probe`GET``/mcp/manifest`HMACReturns service manifest JSON`POST``/mcp/call`HMACInvokes a named tool---

Environment Variables
---------------------

[](#environment-variables)

VariableRequiredDescription`MCP_HMAC_SECRET`✅Shared HMAC-SHA256 secret (min 16 chars)---

Classes
-------

[](#classes)

### `Hmac`

[](#hmac)

Core signing utilities.

```
use Wazobia\NexusMcp\Hmac;

// Compute a signature
$sig = Hmac::computeSignature('POST', '/mcp/call', '1718000000', $secret);

// Sign a request — returns [signature, timestamp]
[$sig, $ts] = Hmac::signRequest('GET', '/mcp/manifest', $secret);

// Check if a timestamp is stale (> 300s from now)
$stale = Hmac::isStale(1718000000);
```

### `HmacMiddleware`

[](#hmacmiddleware)

Laravel HTTP middleware that validates incoming HMAC signatures on MCP routes. Automatically exempts `/health`, `/health/live`, and `/health/ready` for K8s probes.

```
// Recommended — via McpRouter::register() (secret bound through container)
McpRouter::register($manifest, $tools, env('MCP_HMAC_SECRET'));

// Direct usage
app()->singleton('nexus-mcp.hmac_secret', fn () => env('MCP_HMAC_SECRET'));
Route::middleware(\Wazobia\NexusMcp\HmacMiddleware::class)->group(function () {
    // your HMAC-protected routes
});
```

> **Note:** Do not pass the secret as a middleware string parameter (`HmacMiddleware::class . ':' . $secret`). Laravel's param parser splits on commas, which would silently truncate any secret containing one. The container binding avoids this entirely.

### `HmacClient`

[](#hmacclient)

Guzzle-based HTTP client that automatically signs every outbound request.

```
use Wazobia\NexusMcp\HmacClient;

$client = new HmacClient('http://mercury:4001', env('MERCURY_HMAC_SECRET'));

// GET /mcp/manifest
$response = $client->get('/mcp/manifest');
$manifest = json_decode($response->getBody(), true);

// POST /mcp/call
$response = $client->post('/mcp/call', [
    'json' => ['tool' => 'login', 'arguments' => ['email' => 'a@b.com']],
]);

// Query strings are signed correctly (ksorted, RFC3986-encoded)
$response = $client->get('/mcp/manifest', ['query' => ['version' => '1', 'format' => 'full']]);
```

### `McpRouter`

[](#mcprouter)

Registers the three standard MCP endpoints on the Laravel router.

```
McpRouter::register(
    manifest:    $manifest,       // Manifest DTO
    tools:       $tools,          // McpToolDefinition[]
    secret:      $secret,         // HMAC secret
    prefix:      'api',           // Optional route prefix (default: empty)
    healthExtra: [                // Optional extra fields in /health response
        'server'    => 'my-service',
        'version'   => '1.0.0',
        'timestamp' => now()->toISOString(),
        'endpoints' => ['POST /mcp/call' => 'Tool invocation'],
    ],
);
```

### `McpToolDefinition`

[](#mcptooldefinition)

DTO for a tool definition. The `handler` is excluded from manifest JSON serialisation.

```
use Wazobia\NexusMcp\McpToolDefinition;

$tool = new McpToolDefinition(
    name:        'create_post',
    description: 'Create a new blog post',
    inputSchema: [
        'type'       => 'object',
        'properties' => [
            'title'   => ['type' => 'string'],
            'content' => ['type' => 'string'],
        ],
        'required' => ['title', 'content'],
    ],
    handler: function (array $args, array $context): array {
        // $args    — tool arguments from the MCP call
        // $context — ['headers' => [...], 'method' => 'POST', 'path' => '/mcp/call']
        return ['id' => '123', 'title' => $args['title']];
    },
);
```

### `Manifest` / `ManifestContext`

[](#manifest--manifestcontext)

DTOs that serialise to the Nexus MCP manifest schema.

```
use Wazobia\NexusMcp\Manifest;
use Wazobia\NexusMcp\ManifestContext;

$manifest = new Manifest(
    namespace:   'my-service',
    description: 'My service tools',
    version:     '1.0.0',
    context: new ManifestContext(
        boundedContext: 'my-service',
        description:    'Handles blog management',
        capabilities:   ['create posts', 'manage tags'],
        knownGaps:      ['no draft support yet'],
    ),
    tools: $tools, // McpToolDefinition[] — handlers stripped automatically
);
```

---

HMAC Contract
-------------

[](#hmac-contract)

All Nexus MCP SDKs use the same signing spec:

```
payload = METHOD.upper() + path + timestamp
          where path includes query string, no fragment, no host
          timestamp = Unix epoch, whole seconds, decimal string
digest  = HMAC-SHA256(secret_utf8, payload_utf8), lowercase hex
headers = x-signature: {digest}
          x-timestamp: {timestamp}
reject if |now - timestamp| > 300

```

Cross-language correctness is verified by [16 contract test vectors](https://github.com/wazobiatech/nexus-mcp-contract/blob/v1.0.0/vectors.json) shared across all four SDKs.

---

Testing
-------

[](#testing)

```
composer install
./vendor/bin/phpunit
```

- `tests/Unit/HmacTest.php` — 8 unit tests (signature format, method normalisation, staleness window)
- `tests/Contract/VectorTest.php` — 16 cross-language contract vectors (vendored, hermetic — no network required)

---

License
-------

[](#license)

MIT

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance90

Actively maintained with recent releases

Popularity15

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

45d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/74bef2d8a21069354833c101455ec2a2f197d8bef923e808c31d35576260ddb0?d=identicon)[wazobiatech](/maintainers/wazobiatech)

---

Top Contributors

[![cuzoechi](https://avatars.githubusercontent.com/u/169653298?v=4)](https://github.com/cuzoechi "cuzoechi (7 commits)")

---

Tags

laravelmcphmacnexuswazobia

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/wazobia-nexus-mcp-laravel/health.svg)

```
[![Health](https://phpackages.com/badges/wazobia-nexus-mcp-laravel/health.svg)](https://phpackages.com/packages/wazobia-nexus-mcp-laravel)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.3M347](/packages/psalm-plugin-laravel)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

77922.3M186](/packages/laravel-mcp)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M133](/packages/roots-acorn)[api-platform/laravel

API Platform support for Laravel

58174.6k17](/packages/api-platform-laravel)[fleetbase/core-api

Core Framework and Resources for Fleetbase API

1235.9k21](/packages/fleetbase-core-api)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5022.6k](/packages/simplestats-io-laravel-client)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)