Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
181 commits
Select commit Hold shift + click to select a range
58996ec
Add a normalizer for optional nullable tool parameters
ajibarra Nov 20, 2026
197ff88
Keep the normalizer within the line length
ajibarra Nov 20, 2026
c1e09f1
Add Mcp.schema.normalize to clean optional nullable parameters in too…
ajibarra Nov 20, 2026
52bdf93
mcp check: warn about tool schemas strict hosts reject
ajibarra Nov 20, 2026
4419feb
mcp check: fail when discovery is configured without symfony/finder
ajibarra Nov 20, 2026
c43a8b5
Changelog: schema defaults and checks
ajibarra Nov 20, 2026
c716b17
Keep null in nullable parameters whose default is another value
ajibarra Nov 20, 2026
1b2e829
Docs: an input schema example whose defaults the schema accepts
ajibarra Nov 20, 2026
e6fbf7b
Add ToolError::message() for errors the model should read
ajibarra Nov 20, 2026
9203233
Docs: what a client receives from a tool, pinned by tests
ajibarra Nov 20, 2026
325db34
Changelog: results docs and ToolError::message()
ajibarra Nov 20, 2026
f058bdb
Add CacheHints to read Mcp.server.cache
ajibarra Nov 20, 2026
769ffd4
Mcp.server.cache sets the cache hints of the 2026-07-28 protocol
ajibarra Nov 20, 2026
10a09b9
Add ToolValidation::check() to validate tool arguments with a Cake Va…
ajibarra Nov 20, 2026
eb61f9d
McpTestTrait: structured content paths and tool lists of another iden…
ajibarra Nov 20, 2026
5c88392
Bake generators for MCP tools, resources and prompts
ajibarra Nov 20, 2026
38b135b
McpConfig: resolve the config of named servers
ajibarra Nov 20, 2026
6a7fad5
Settings and server factory per MCP server
ajibarra Nov 20, 2026
1f4f525
Serve several MCP servers from one application
ajibarra Nov 20, 2026
9b51fb7
Bake: accept the Plugin.Name form
ajibarra Nov 20, 2026
21c2052
Docs: a list is structured content too for 2026-07-28 clients
ajibarra Nov 20, 2026
38747dc
mcp check: warn about public cache hints on per-user results
ajibarra Nov 20, 2026
30913d8
Keep the cache hints check within the line length
ajibarra Nov 20, 2026
2094c86
Commands, test trait and docs for several MCP servers
ajibarra Nov 20, 2026
445563b
#[McpWhen] registers tools, resources and prompts only when a conditi…
ajibarra Nov 20, 2026
b83ea97
McpTestTrait: run tools that notify, and assert their notifications
ajibarra Nov 20, 2026
c9a298a
Docs and tests for progress over HTTP
ajibarra Nov 20, 2026
4b773c4
Named servers: fail closed on empty security sections, slug names, Mc…
ajibarra Nov 20, 2026
5f5be87
Named servers: reverse routing reaches them, mcp check fails on a sha…
ajibarra Nov 20, 2026
6a2c27b
mcp check: warn about partial security sections; named-server securit…
ajibarra Nov 20, 2026
e9718f7
Searchable tool catalog: find_tools and call_tools
ajibarra Nov 20, 2026
e960a93
Tool catalog: inner calls need their scopes, over HTTP and in tests
ajibarra Nov 20, 2026
6c97690
Tool catalog: audit inner calls, mcp check, docs
ajibarra Nov 20, 2026
97e2dd4
MCP Apps: extension, bridge and app resources from Cake views
ajibarra Nov 20, 2026
03d8143
MCP Apps: #[McpApp], app-only tools hidden from clients without Apps,…
ajibarra Nov 20, 2026
143bfb2
MCP Apps: mcp check, bake mcp_app, docs
ajibarra Nov 20, 2026
6bb0910
MCP client: named clients over HTTP and stdio, tool filters
ajibarra Nov 20, 2026
e301459
MCP client: SSRF guard for URLs learned from remote metadata
ajibarra Nov 20, 2026
2ba4f4c
MCP client: encrypted token store and its migration
ajibarra Nov 20, 2026
910b598
MCP client: OAuth sign-in for user mode clients
ajibarra Nov 20, 2026
163147f
MCP client: user mode connections with refresh and revocation
ajibarra Nov 20, 2026
e986bc2
MCP client: mcp check, docs
ajibarra Nov 20, 2026
42e924f
Tool catalog and #[McpWhen]: honour the hook's registry, refuse hook …
ajibarra Nov 20, 2026
7a57056
Prompt argument validation, features overview
ajibarra Nov 20, 2026
67489c5
MCP client and apps: refuse trailing-dot hosts, issuer for configured…
ajibarra Nov 20, 2026
59e6431
Release notes for 2.2.0, client docs page renamed to mcp-client.md
ajibarra Nov 20, 2026
6c12a35
MCP client: one refresh per user grant at a time
ajibarra Nov 20, 2026
b8b02a7
A mistake in one server or client entry stops that entry only, not th…
ajibarra Nov 21, 2026
4c168da
Named servers: own resource when inheriting auth, mode and authorizer…
ajibarra Nov 21, 2026
ea62088
Several servers example with sibling directories, excludeDirs documen…
ajibarra Nov 21, 2026
f275993
A registry of the hook's own works again: the plugin uses only Regist…
ajibarra Nov 21, 2026
f87c29f
call_tools: a tool that asks the user ends its call with a tool error…
ajibarra Nov 21, 2026
0ed9523
One rule for what goes behind the catalog: tools with an app stay in …
ajibarra Nov 21, 2026
be3d22f
tools/list is always private with a per-user authorizer, and a named …
ajibarra Nov 21, 2026
8cbc7c3
MCP client: read the grant again after claiming its refresh, and a re…
ajibarra Nov 21, 2026
697e7a7
MCP client: a configured client secret needs its issuer, and discover…
ajibarra Nov 21, 2026
cb9a93f
MCP client tables keyed by SHA-256 hashes, with client, user id and i…
ajibarra Nov 21, 2026
3cba3ee
MCP client: uncompressed answers only, any HTTP layer failure is a Cl…
ajibarra Nov 21, 2026
67c5ee2
MCP client: challenge metadata on the configured origin is trusted li…
ajibarra Nov 21, 2026
4fb5836
MCP client: ask for offline_access when the authorization server or t…
ajibarra Nov 21, 2026
aba5c09
MCP Apps: empty ui meta left out, app=1 on refused calls, apps enable…
ajibarra Nov 21, 2026
0df4640
#[McpWhen]: strings that mean off are off, and a method condition add…
ajibarra Nov 21, 2026
34c9d95
Docs and release notes in step with 2.2: mcp check lines, defaults, a…
ajibarra Nov 21, 2026
62088f8
Config mistakes: numeric server and client names stop that entry only…
ajibarra Nov 21, 2026
21b291f
Config mistakes reach the skeleton's error log once per process, as w…
ajibarra Nov 21, 2026
b0752d0
mcp check Cache hints reads a policy the hook set; docs on needs-inpu…
ajibarra Nov 21, 2026
084a58e
McpTestTrait gets prompts, reads resources and asks for completions t…
ajibarra Nov 21, 2026
3fd2ec6
Authorizers can decide who reads which resource and gets which prompt…
ajibarra Nov 21, 2026
86cb5c7
MCP client: token can be a callable, called for each request
ajibarra Nov 21, 2026
a2b864d
MCP client: Mcp.client.proxy sends every client request through an ou…
ajibarra Nov 21, 2026
8e26f65
MCP client: allowPrivateNetwork lets one client use an authorization …
ajibarra Nov 21, 2026
67f4331
MCP client: user mode clients serve a Client ID Metadata Document and…
ajibarra Nov 21, 2026
29ac507
MCP client: cache list results for the ttl the server's cache hints g…
ajibarra Nov 21, 2026
a65e902
Docs: resources, templates, prompts, completions and content types, w…
ajibarra Nov 21, 2026
d1cabc3
Mcp.server.icons: icons in the server info clients show
ajibarra Nov 21, 2026
a3645d3
Named servers with route false are served over stdio only
ajibarra Nov 21, 2026
f8483bf
find_tools: words of any language, arguments searched too, a query le…
ajibarra Nov 21, 2026
1cfc32a
Docs: the sandbox domain of an MCP App page, set from the host's docu…
ajibarra Nov 21, 2026
976acf2
McpTestTrait: structuredContent subset, count and type assertions, co…
ajibarra Nov 21, 2026
e6a2aab
Named servers on routes with parameters (/mcp/{tenant}): McpRoute for…
ajibarra Nov 21, 2026
594c886
An Mcp-* header that is not valid UTF-8 answers 400, not 500
ajibarra Nov 21, 2026
6e70467
MCP client: ping(), serverInfo(), capabilities() and instructions()
ajibarra Nov 21, 2026
48e0b4f
MCP client: list limits, one retry after a header mismatch or an expi…
ajibarra Nov 21, 2026
c8690c7
MCP client: dynamic registration sends application_type and scope
ajibarra Nov 21, 2026
cabcc73
MCP client: client_credentials clients get the application's own OAut…
ajibarra Nov 21, 2026
d33a20b
MCP client: a 403 insufficient_scope marks the user's grant, and the …
ajibarra Nov 21, 2026
48bbf65
MCP client: without protected resource metadata, the server's origin …
ajibarra Nov 21, 2026
44319a2
allowPrivateNetwork also lets that client use an authorization server…
ajibarra Nov 21, 2026
24084ad
MCP client: discovery goes on when the probe needs no sign-in, a step…
ajibarra Nov 21, 2026
3e7ee7d
CI: the client side of the MCP conformance suite runs against the plu…
ajibarra Nov 21, 2026
0a6ebef
Release notes and docs for the server and client additions of 2.2
ajibarra Nov 21, 2026
8c99043
Only the server whose route is the request path is served: route para…
ajibarra Nov 21, 2026
7baff54
mcp check fails when a route parameter is missing from a configured r…
ajibarra Nov 21, 2026
3dd432a
client_credentials tokens are stored under a plain user id, which Pos…
ajibarra Nov 21, 2026
aae4008
A denied resource template also denies the concrete URIs it serves on…
ajibarra Nov 21, 2026
fda9fdb
A subscriptions/listen stream carries no update of a resource the cal…
ajibarra Nov 21, 2026
5a56370
A named server whose configured resource or audience lacks a route pa…
ajibarra Nov 21, 2026
fad6f10
The step_up_scope column is created with the client tables, in their …
ajibarra Nov 21, 2026
23cc33a
A stored client_credentials token is only used for the issuer, token …
ajibarra Nov 21, 2026
a1ebd11
The default server is not served when Mcp.route has parameters
ajibarra Nov 21, 2026
22b670f
PHPStan gets 1G of memory in composer stan and in CI
ajibarra Nov 21, 2026
755e0d9
The tool catalog works next to an authorizer for resources and prompt…
ajibarra Nov 21, 2026
f67ab99
mcp check probes a route with parameters with a real value: in oauth …
ajibarra Nov 21, 2026
4f796a2
A route the application connects itself to the plugin's controller, o…
ajibarra Nov 21, 2026
acdf646
A Content-Encoding header with spaces or tabs before its colon stops …
ajibarra Nov 21, 2026
fcc262d
registration auto uses the client metadata document only on a site wh…
ajibarra Nov 21, 2026
c77b807
A private list in the client cache is keyed by the credential it was …
ajibarra Nov 21, 2026
dab69a4
In oauth mode a route value whose resource is not declared answers 40…
ajibarra Nov 21, 2026
fc2154e
A completion for a denied prompt or template, and an unsubscription f…
ajibarra Nov 21, 2026
9bc0eb5
A configured issuer follows the rule of the other configured addresse…
ajibarra Nov 21, 2026
f83e02d
A 401 is retried with a new token only when the server accepted no re…
ajibarra Nov 21, 2026
58c935a
CHANGELOG lists every behaviour change a 2.1 application can notice; …
ajibarra Nov 21, 2026
5605a0c
find_tools scores a tool from a table of each searched field and its …
ajibarra Nov 21, 2026
6c4555a
ContentGuard declares that it only answers errors
ajibarra Nov 21, 2026
81e44c4
Only an accepted tools/call keeps a 401 from being retried: server/di…
ajibarra Nov 21, 2026
56e18ef
isEndpoint() reads the path as the router does and, once routing has …
ajibarra Nov 21, 2026
1ceab79
The iss of a sign-in response is checked before its error, so the err…
ajibarra Nov 21, 2026
21bbf0f
Docs say a resource URI is not canonical, and the test authorizer den…
ajibarra Nov 21, 2026
e1ac0ac
The test suite runs without PHP's memory limit, which a clean run alr…
ajibarra Nov 21, 2026
b5fa2e7
A typo inside discovery, identity or authorization of a named server …
ajibarra Nov 21, 2026
3ab35b7
A discovered tool named find_tools or call_tools stops the build when…
ajibarra Nov 21, 2026
49187d1
mcp check knows a scope set on find_tools or call_tools while the cat…
ajibarra Nov 21, 2026
b842509
mcp check warns about Rbac rules for plugin CakeDC/Mcp that name a co…
ajibarra Nov 21, 2026
fd5ccb1
assertMcpResourceDenied() passes for a denied resource whose handler …
ajibarra Nov 21, 2026
fff4845
With MCP Apps on, McpTestTrait is a host that renders apps, so the Li…
ajibarra Nov 21, 2026
768dd4c
A client token loses the line break a secret file ends with, and one …
ajibarra Nov 21, 2026
7bd5b3d
A cache on a stdio client fails instead of doing nothing
ajibarra Nov 21, 2026
b578e1c
After a header mismatch the client fetches every page of the tool lis…
ajibarra Nov 21, 2026
c2e7746
Any failure of the HTTP layer on a configured URL is a ClientExceptio…
ajibarra Nov 21, 2026
d3a88b7
What an inner call of call_tools throws fails that call only, keeps t…
ajibarra Nov 21, 2026
12a2853
The key check of a named server's section reads the section's default…
ajibarra Nov 21, 2026
2951e5f
A tools/list page the filter empties, or leaves short, is filled from…
ajibarra Nov 21, 2026
610ba0f
A resource read or prompt get the authorizer denied is audited as den…
ajibarra Nov 21, 2026
6de91f8
mcp check knows resources/read is sent private when the authorizer de…
ajibarra Nov 21, 2026
6142468
A registry of the hook's own whose pages are lists serves again: elem…
ajibarra Nov 21, 2026
f2f0543
mcp check fails on two servers whose route patterns have the same sha…
ajibarra Nov 21, 2026
81f3f34
A resource or audience that runs two route parameters together, where…
ajibarra Nov 21, 2026
5d40200
The auth errors of a named server name its own setting, or say that i…
ajibarra Nov 21, 2026
ed40910
The MCP client logs its configured URL without the query, and the doc…
ajibarra Nov 21, 2026
1c7f14a
bake mcp_* refuses a name that is not a class name instead of writing…
ajibarra Nov 21, 2026
d891a12
A call McpTestTrait refuses for a missing scope keeps no notification…
ajibarra Nov 21, 2026
80a3e2e
RecordingTransport lets a tool notify up to a million times, and says…
ajibarra Nov 21, 2026
dba385b
mcp check passes the Resource line of a default server without a rout…
ajibarra Nov 21, 2026
3704e76
The Apps line of mcp check reads each app page and warns about one th…
ajibarra Nov 21, 2026
13d150e
Docs say a #[McpWhen] on a parent class does not reach the classes th…
ajibarra Nov 21, 2026
fb0b512
A name the DNS has no record of is looked up as the system does, so l…
ajibarra Nov 21, 2026
138c626
The step-up mark keeps 50 scopes and 2048 bytes at most, and the docs…
ajibarra Nov 21, 2026
1007c32
The schema lint and the normalizer look into nested objects and array…
ajibarra Nov 21, 2026
d362b79
mcp inspector --http on a route with parameters asks for the URL of o…
ajibarra Nov 21, 2026
43b21a4
Conditions::key() docblock in the coding standard's form
ajibarra Nov 21, 2026
1820c38
CHANGELOG lists the behaviour changes of this round a 2.1 application…
ajibarra Nov 21, 2026
3958d2d
A Mcp.client.route that is not a path connects no sign-in routes, nev…
ajibarra Nov 21, 2026
59fb526
A route value never ends in a line feed, so /mcp/t/acme%0A is not ano…
ajibarra Nov 21, 2026
624a3ee
The request path is decoded as the installed router decodes it, the w…
ajibarra Nov 21, 2026
4a47264
tools/list fills a short page only when the cursor is the registry's …
ajibarra Nov 21, 2026
f27f438
Behind Mcp.client.proxy a url on this machine is reached directly, NO…
ajibarra Nov 21, 2026
6a74bc2
A shared Mcp.client setting of the wrong type, or a key that is not a…
ajibarra Nov 21, 2026
cf193a1
All the requests of one sign-in step share the client's timeout, so a…
ajibarra Nov 21, 2026
5b2f4ff
The token store's writes no longer race: a step-up mark changes only …
ajibarra Nov 21, 2026
b448e93
A step-up is tried once per scope: a challenge for scopes the last si…
ajibarra Nov 21, 2026
0f2f2cb
call_tools runs a tool on the same object as a call by name: the serv…
ajibarra Nov 21, 2026
875e8c3
With MCP Apps on, tools/list is sent private: clients with and withou…
ajibarra Nov 21, 2026
f0fb28a
A route value that the resource puts in its host is served only in lo…
ajibarra Nov 21, 2026
5c796e7
A subscriptions/listen stream filters every update with the identity …
ajibarra Nov 21, 2026
95981c8
A stdio client whose command path has a space starts on Linux and macOS
ajibarra Nov 21, 2026
e774eb0
CHANGELOG: proxy bypass for this machine, socks5h, and the step-up re…
ajibarra Nov 21, 2026
c4efee2
A path ending in a line feed is not served, so /mcp%0A is never the e…
ajibarra Nov 21, 2026
f162ae1
A request with less than a second left of its sign-in step still has …
ajibarra Nov 21, 2026
d5e1608
Every configured address the URL policy takes as this machine bypasse…
ajibarra Nov 21, 2026
d3a89d5
refreshLeeway and maxResponseBytes read with env() are accepted as th…
ajibarra Nov 21, 2026
02972fe
A stdio command that is a bare name with a space is the file in its c…
ajibarra Nov 21, 2026
9eca942
A step-up never asks for offline_access a server named in its challen…
ajibarra Nov 21, 2026
5b61057
MCP client: protocolVersion() says which protocol revision the client…
ajibarra Nov 21, 2026
bd5c0a2
docs/features.md names the four things mcp/sdk 0.9 has no place for yet
ajibarra Nov 21, 2026
2ad9541
MCP client cache: resource reads and the server/discover answer are k…
ajibarra Nov 21, 2026
08703a6
A redirect of a client's MCP endpoint says so, with its status and ta…
ajibarra Nov 21, 2026
bd2878a
Catalog: maxResultBytes caps find_tools and call_tools answers, a res…
ajibarra Nov 21, 2026
9ea1aa4
McpTestTrait: structured content assertions for a missing path, a fra…
ajibarra Nov 21, 2026
36bc1bf
Structured content assertions never depend on the order of an object'…
ajibarra Nov 21, 2026
cd61a49
The client cache is keyed by the client's url too, so a client pointe…
ajibarra Nov 21, 2026
56b38e4
catalog.maxCalls and catalog.maxResultBytes read with env() are accep…
ajibarra Nov 21, 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
6 changes: 5 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ jobs:
working-directory: cakephp-mcp
- run: vendor/bin/phpcs
working-directory: cakephp-mcp
- run: vendor/bin/phpstan analyse --no-progress
- run: vendor/bin/phpstan analyse --no-progress --memory-limit=1G
working-directory: cakephp-mcp

conformance:
Expand Down Expand Up @@ -118,3 +118,7 @@ jobs:
node-version: '22'
- run: tests/Conformance/run.sh
working-directory: cakephp-mcp
# The client side: the plugin's MCP client (tests/Conformance/client.php) against the suite's own servers.
- run: tests/Conformance/run-client.sh
if: ${{ !cancelled() }}
working-directory: cakephp-mcp
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,4 @@
.phpunit.result.cache
/tests/Conformance/tmp/
/tests/Conformance/results/
/tests/Conformance/results-client/
58 changes: 58 additions & 0 deletions CHANGELOG.md

Large diffs are not rendered by default.

5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ Built on the official [`mcp/sdk`](https://github.com/modelcontextprotocol/php-sd
- Per-tool authorization, including `config/permissions.php` rules through `cakedc/auth`.
- `McpTestTrait` to test your tools, and who may call them, from a regular Cake test case.
- An audit log of MCP calls (`Mcp.audit`, off by default): who called which tool, with which arguments, and how it ended, to a log scope or your own table.
- Since 2.2: several MCP servers in one application (`Mcp.servers`), a tool catalog that keeps large tool sets out of `tools/list` (`find_tools` and `call_tools`), MCP Apps rendered from Cake templates, tools registered only when a flag is on (`#[McpWhen]`), cache hints, and an MCP client to call other MCP servers, on behalf of each user after an OAuth sign-in if needed. See the [features overview](docs/features.md).

## Requirements

Expand Down Expand Up @@ -94,15 +95,19 @@ $service->loadAuthenticator('Authentication.Token', [

## Documentation

- [Features](docs/features.md)
- [Installation](docs/installation.md)
- [Configuration](docs/configuration.md)
- [Writing tools](docs/tools.md)
- [Resources and prompts](docs/resources-and-prompts.md)
- [MCP Apps](docs/apps.md)
- [Authentication](docs/authentication.md)
- [OAuth](docs/oauth.md)
- [Authorization](docs/authorization.md)
- [Testing your tools](docs/testing.md)
- [stdio](docs/stdio.md)
- [Connecting clients](docs/clients.md)
- [Calling other MCP servers](docs/mcp-client.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Protocol conformance](docs/conformance.md)

Expand Down
5 changes: 4 additions & 1 deletion composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
"cakedc/cakephp-oauth-server": "^1.0",
"cakedc/oauth-server": "^1.0",
"cakephp/authentication": "^3.3",
"cakephp/bake": "^3.0",
"cakephp/cakephp-codesniffer": "^5.1",
"cakephp/migrations": "^4.0 || ^5.0",
"firebase/php-jwt": "^6.10 || ^7.0",
Expand All @@ -29,6 +30,8 @@
"psr/cache": "^2.0 || ^3.0"
},
"suggest": {
"cakephp/bake": "Generates MCP tools, resources, prompts and apps with their tests (bin/cake bake mcp_tool, mcp_resource, mcp_prompt, mcp_app)",
"cakephp/migrations": "Creates the tables of the MCP client's user mode (bin/cake migrations migrate -p CakeDC/Mcp)",
"cakephp/authentication": "Identifies the caller of the MCP endpoint (for example with a Bearer token authenticator)",
"cakedc/auth": "Enables RbacToolAuthorizer, per-tool permissions in the config/permissions.php format",
"cakedc/cakephp-oauth-server": "OAuth 2.1 sign-in for remote MCP clients with the application's own login (Mcp.auth.mode oauth)",
Expand Down Expand Up @@ -62,7 +65,7 @@
"test": "phpunit",
"cs-check": "phpcs --colors -p",
"cs-fix": "phpcbf --colors -p",
"stan": "phpstan analyse --no-progress"
"stan": "phpstan analyse --no-progress --memory-limit=1G"
},
"config": {
"sort-packages": true,
Expand Down
82 changes: 82 additions & 0 deletions config/Migrations/20261120120000_CreateMcpClientTables.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
<?php
declare(strict_types=1);

// cakephp/migrations 4 (CakePHP 5.0 to 5.2) runs phinx-style AbstractMigration classes, 5 only
// BaseMigration: extend whichever this installation has.
if (!class_exists('CakeDCMcpMigration', false)) {
class_alias(
class_exists('Migrations\\AbstractMigration') ? 'Migrations\\AbstractMigration' : 'Migrations\\BaseMigration',
'CakeDCMcpMigration',
);
}

/**
* The tables of the MCP client's user mode: each user's grant, and the OAuth clients registered at authorization
* servers. Needed only when a client in `Mcp.clients` uses `auth` `user` with the default store:
* `bin/cake migrations migrate -p CakeDC/Mcp`.
*
* Tokens and secrets are stored encrypted (base64 of Security::encrypt()), hence text columns.
*
* Rows are found by a SHA-256 key (`connection_key` of client and user id, `registration_key` of client and
* issuer), never by the plain values: the default collation of some databases (MySQL's utf8mb4_0900_ai_ci) would
* match "alice" with "Alice" or "jose" with "josé", and the plain values can be as long as they need.
*/
class CreateMcpClientTables extends CakeDCMcpMigration
{
/**
* @return void
*/
public function up(): void
{
$this->table('mcp_client_connections')
->addColumn('connection_key', 'string', ['limit' => 64, 'null' => false])
->addColumn('client', 'text', ['null' => false])
->addColumn('user_id', 'text', ['null' => false])
->addColumn('access_token', 'text', ['null' => false])
->addColumn('refresh_token', 'text', ['null' => true])
->addColumn('expires', 'datetime', ['null' => true])
->addColumn('scope', 'text', ['null' => true])
->addColumn('issuer', 'text', ['null' => false])
->addColumn('token_url', 'text', ['null' => false])
->addColumn('revocation_url', 'text', ['null' => true])
->addColumn('oauth_client_id', 'text', ['null' => false])
->addColumn('client_secret', 'text', ['null' => true])
->addColumn('auth_method', 'string', ['limit' => 30, 'null' => false])
->addColumn('resource', 'text', ['null' => false])
// The scopes a server asked this user for with `403 insufficient_scope`, which the next connect asks
// the authorization server for (scope step-up).
->addColumn('step_up_scope', 'text', ['null' => true])
// The scopes the sign-in that made this grant asked for: a step-up never asks again for scopes the
// authorization server was already asked for and did not grant (a retry limit, so no redirect loop).
->addColumn('requested_scope', 'text', ['null' => true])
// The request refreshing the grant, so that two requests never send the same refresh token.
->addColumn('refresh_claim_id', 'string', ['limit' => 36, 'null' => true])
->addColumn('refresh_claimed_at', 'datetime', ['null' => true])
->addColumn('created', 'datetime', ['null' => false])
->addColumn('modified', 'datetime', ['null' => false])
->addIndex(['connection_key'], ['unique' => true])
->create();

$this->table('mcp_client_registrations')
->addColumn('registration_key', 'string', ['limit' => 64, 'null' => false])
->addColumn('client', 'text', ['null' => false])
->addColumn('issuer', 'text', ['null' => false])
->addColumn('redirect_uri', 'text', ['null' => false])
->addColumn('oauth_client_id', 'text', ['null' => false])
->addColumn('client_secret', 'text', ['null' => true])
->addColumn('auth_method', 'string', ['limit' => 30, 'null' => false])
->addColumn('created', 'datetime', ['null' => false])
->addColumn('modified', 'datetime', ['null' => false])
->addIndex(['registration_key'], ['unique' => true])
->create();
}

/**
* @return void
*/
public function down(): void
{
$this->table('mcp_client_registrations')->drop()->save();
$this->table('mcp_client_connections')->drop()->save();
}
}
141 changes: 141 additions & 0 deletions docs/apps.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
# MCP Apps

An MCP App is a small web page a host (Claude, ChatGPT, an IDE) shows in a
frame next to the conversation. The model calls a tool; the host opens the
tool's app and passes it the result; the page can call tools of your server
itself. It is the MCP Apps extension of the protocol
(`io.modelcontextprotocol/ui`). The plugin renders the page from a Cake
template and ships the official MCP Apps client, so the page needs no build
step.

## Turning it on

```php
'Mcp' => ['apps' => ['enabled' => true]],
```

The server then tells clients it serves apps. Clients that do not render apps
ignore it and keep using your tools as before. If `Mcp.server.configure`
already enables the extension (`$builder->enableExtension(new McpApps())`, as
a 2.1 application could), that keeps working, with or without this setting.
Leaving app-only tools out of `tools/list` for clients that do not render apps
happens only with `Mcp.apps.enabled` on.

## An app

An app is a `ui://` resource with the MIME type `text/html;profile=mcp-app`,
plus a tool linked to it with `#[McpApp]`. `bin/cake bake mcp_app Inbox`
creates both, the page template and a test:

```php
namespace App\Mcp;

use CakeDC\Mcp\App\AppView;
use CakeDC\Mcp\Attribute\McpApp;
use Mcp\Capability\Attribute\McpResource;
use Mcp\Capability\Attribute\McpTool;
use Mcp\Schema\Content\TextResourceContents;
use Mcp\Schema\Extension\Apps\McpApps;
use Mcp\Schema\Extension\Apps\UiResourceContentMeta;
use Mcp\Schema\Extension\Apps\UiResourceCsp;

class InboxApp
{
#[McpResource(uri: 'ui://app/inbox', name: 'inbox', mimeType: McpApps::MIME_TYPE)]
public function page(): TextResourceContents
{
return AppView::render('ui://app/inbox', 'Mcp/inbox', [], new UiResourceContentMeta(
csp: new UiResourceCsp(connectDomains: ['https://api.example.com']),
));
}

/**
* The orders waiting to be read.
*/
#[McpApp(resource: 'ui://app/inbox')]
#[McpTool(name: 'show_inbox')]
public function show(): array
{
return ['count' => 3];
}

/**
* The rows of the inbox, for the app only.
*/
#[McpApp(resource: 'ui://app/inbox', visibility: ['app'])]
#[McpTool(name: 'inbox_rows')]
public function rows(): array
{
// ...
}
}
```

`AppView::render()` renders `templates/Mcp/inbox.php` in the plugin's
`CakeDC/Mcp.app` layout and returns the page with the right MIME type. The
layout is a complete HTML document whose first script defines `McpApps`, the
official client (`@modelcontextprotocol/ext-apps`, inlined, so the page needs
no network access to load it). The template uses it:

```php
<ul id="rows"></ul>
<script type="module">
const app = new McpApps.App({name: 'Inbox', version: '1.0.0'});
app.ontoolresult = (result) => { /* the result of show_inbox */ };
await app.connect();
const rows = await app.callServerTool({name: 'inbox_rows', arguments: {}});
</script>
```

The third argument of `render()` holds the view variables. The fourth,
`UiResourceContentMeta`, tells the host what the frame may do: the domains it
may connect to or load from (`UiResourceCsp`), permissions such as the
clipboard (`UiResourcePermissions`), and whether it wants a border. Hosts apply
a strict policy by default, so declare every outside domain the page uses.

`UiResourceContentMeta` also has `domain`, a dedicated origin for the page's
sandbox, for pages that need a stable origin (an OAuth callback, a CORS policy
or an API key allowlist). The MCP Apps extension leaves its format to each host
(a hash-based subdomain of the host's own domain, or one derived from your
URL), so the plugin does not make one up: without `domain` the host uses its
default sandbox origin, usually one per conversation. Set it from the host's
documentation when you need it:

```php
new UiResourceContentMeta(domain: 'a904794854a047f6.claudemcpcontent.com')
```

## Visibility

`#[McpApp]` writes `_meta.ui` into the tool's entry of `tools/list`:
`resourceUri`, and `visibility`, by default `['model', 'app']`. A tool with
`visibility: ['app']` is for the app only: hosts keep it from the model, and
clients that do not render apps do not get it in `tools/list` at all. The tool
catalog leaves every tool with an app out, even when a pattern of
`Mcp.catalog.tools` matches it: `find_tools` does not offer it, `call_tools`
does not run it, and it stays in `tools/list`, where the host reads its
`_meta.ui` (an app-only tool for clients that render apps, a tool that links to
an app for every client). `bin/cake mcp check` names the tools with an app that
a pattern matched on its `Catalog` line.

Visibility is a hint for the host, not access control. An app-only tool can
still be called by anyone who knows its name and holds a valid token, so it is
gated by your authorizer, needs its scopes and is audited like any other tool
(its audit records carry `app=1`). The page itself is a resource: anyone who
may call the endpoint can read it with `resources/read`, unless your authorizer
also implements `ResourceAuthorizerInterface` (see
[Resources and prompts](authorization.md#resources-and-prompts)). Keep data out of the page template
and load it with a tool call from the page, where the authorizer and the scopes
apply. Data an app shows also passes through the host, so the host vendor's
terms apply to it as much as to what the model reads.

## Checking and testing

`bin/cake mcp check` reports apps on its `Apps` line, and fails when a tool
links to a resource that is not a registered app page, or when tools link to
apps while the server does not announce apps (neither `Mcp.apps.enabled` nor
the hook). It also reads each page and warns about one that does not render
(a missing template, a template that throws). In tests, call the resource method directly to check the page (the
test `bake mcp_app` writes loads the plugin for the page's layout), and the
tools with `McpTestTrait` as usual. Empty `_meta.ui`, `csp` and `permissions`
of a page are left out, never sent as empty lists.
8 changes: 6 additions & 2 deletions docs/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,10 @@ in the `identity` attribute, so the plugin reads it unchanged. Two defaults of
permission rule for the endpoint and its protected resource metadata (used
by [OAuth](oauth.md)) in your `config/permissions.php`, with `bypassAuth` so
the request reaches the plugin, which then does its own 401 and per-tool
authorization. `McpConfig::rbacPermissions()` returns that rule:
authorization. `McpConfig::rbacPermissions()` returns that rule (and, with
a user mode client in `Mcp.clients`, two more: one for its sign-in routes,
and one with `bypassAuth` for its `client.json`, which authorization servers
fetch without a session):

```php
// config/permissions.php
Expand All @@ -110,7 +113,8 @@ in the `identity` attribute, so the plugin reads it unchanged. Two defaults of
];
```

It is this rule, which you can also write by hand:
The first is this rule, which you can also write by hand (the client rules
are in [Calling other MCP servers](mcp-client.md)):

```php
[
Expand Down
Loading
Loading