2026-11-07 04:20:26 +03:00
# scribase-mcp-php
A real [Model Context Protocol ](https://modelcontextprotocol.io ) server for
[Scribase ](https://scribase.com ) — a hosted Postgres backend (Supabase/Neon
alternative) — built on the **official PHP MCP SDK** (`mcp/sdk` , a PHP
Foundation + Symfony collaboration) and wired into a real
**[Symfony AI ](https://ai.symfony.com ) `Agent` ** via `symfony/ai-mcp-tool` .
Built for the ** [Symfony AI & MCP Hackathon ](https://symfony.com/hackathon )**
(26 Oct – 22 Nov 2026). Every tool here calls Scribase's real, live,
production management API (`api.scribase.com` ) — nothing is mocked in the
shipped code, and the "Real, live verification" section below is a genuine
transcript from running this exact code against production, including one
real bug it found and fixed.
## What it gives an agent
Five tools, each backed by a distinct, real `api.scribase.com` endpoint:
| Tool | What it does | Endpoint |
|---|---|---|
| `scribase_create_project` | Provisions a real hosted-Postgres project + environment, returns the connection string and API keys. | `PUT .../projects/{id}` + `POST /v1/environments` |
| `scribase_lint_migration` | Runs Scribase's real migration-safety linter (missing RLS, permissive policy, `GRANT` to `PUBLIC` , `SECURITY DEFINER` , missing `WITH CHECK` , …). `apply` is hardcoded `false` in this client — it can only ever lint, never apply. | `POST .../migrations` |
| `scribase_query` | One read-only SQL statement. The control plane enforces read-only twice, server-side (a static keyword check, then a Postgres `READ ONLY` transaction) — this client adds no write-guard of its own because none is needed. | `POST .../database/query` |
| `scribase_branch_task` | A real copy-on-write Postgres branch per task: `create` (cut a branch from a parent environment), `promote` (three-way merge its schema back), `discard` (delete it). | `POST /v1/environments` (`kind: preview` ), `POST .../branches/merge` , `DELETE .../environments/{id}` |
| `scribase_memory_task` | Real, persistent agent memory — `store` /`recall` /`search` /`forget` — backed by a dedicated Postgres table (`hermes_agent_memories` ) this tool creates on first use. Not a context window: a real row in the user's own database that survives across sessions. | `POST .../database/execute` (write-mode SQL) + `POST .../database/query` |
This is the PHP/Symfony-native sibling of
2026-11-17 03:52:26 +03:00
[`caelum0x/scribase-hermes-plugin` ](https://git.ereboslab.com/caelum0x/scribase-hermes-plugin )
2026-11-07 04:20:26 +03:00
— the same five tools, against the same production endpoints, built for Nous
Research's Hermes Agent instead. Both clients wrap one real control plane;
neither invents behavior the other doesn't have. The `hermes_agent_memories`
table name is shared on purpose, so a project's stored memories are readable
from either client.
## Architecture
```
┌─────────────────────┐ tools/list, tools/call (JSON-RPC over stdio)
│ MCP host │ ───────────────────────────────────────────┐
│ (Symfony AI Agent, │ │
│ MCP Inspector, │ ▼
│ Claude Desktop, …) │ ┌──────────────────────┐
└─────────────────────┘ │ bin/scribase-mcp-server│
│ Mcp\Server (mcp/sdk) │
└──────────┬───────────┘
│ addTool([$tools, 'method'])
▼
┌──────────────────────┐
│ ScribaseTools │
│ (5 #[McpTool] methods) │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ ScribaseClient │
│ (Symfony HttpClient) │
└──────────┬───────────┘
│ HTTPS
▼
api.scribase.com (real, live, production)
```
- **`src/ScribaseClient.php` ** — the HTTP layer: request/response, bounded
operation polling (an unattended tool call can never hang forever), and
reading back a ready environment's connection URI + API keys. Uses
`symfony/http-client` .
- **`src/SqlLiteral.php` ** — encodes the handful of model-supplied strings
`scribase_memory_task` ever interpolates into SQL as a hex-encoded
`convert_from(decode('...', 'hex'), 'UTF8')` expression, never a classic
quoted-and-escaped literal. See "Real, live verification" below for why,
and for the one real bug this choice's `uuid` column needed fixing.
- **`src/ScribaseTools.php` ** — the five `#[McpTool]` -attributed methods.
Every parameter uses a native PHP type (`string` , `?int` , `bool` , …), so
`mcp/sdk` 's schema generator builds each tool's real JSON Schema straight
from the method signature and docblock — no hand-written schema to drift
from the code.
- **`bin/scribase-mcp-server` ** — the stdio entrypoint, wiring all five tools
via `Server::builder()->addTool(...)` .
## Running the MCP server
```bash
composer install
SCRIBASE_API_KEY=sbk_... php bin/scribase-mcp-server
```
Point any MCP client at `php /absolute/path/to/bin/scribase-mcp-server` over
stdio — the MCP Inspector, Claude Desktop's `mcpServers` config, or (below)
a real Symfony AI `Agent` .
### Getting a real API key with zero login
Scribase ships a genuinely free, no-account, no-card path for exactly this
situation (an agent that needs a real project to test against):
`POST /v1/temporary-projects` — solve a small proof-of-work, get a real
org + project + production Postgres environment, and a real agent token
scoped to just that project. It lives 72 hours unless claimed. This is the
exact mechanism `scripts/verify-live.php` (below) uses.
## Using it from a real Symfony AI `Agent`
`examples/symfony-ai-agent-demo.php` wires this server into a real
`Symfony\AI\Agent\Agent` , using the official `symfony/ai-mcp-tool` bridge
(`ClientToolset` + `McpToolbox` ) — not a hand-rolled tool-calling loop:
```php
$toolset = new ClientToolset(
'scribase',
Client::builder()->setClientInfo('scribase-mcp-php-demo', '0.1.0')->build(),
new StdioTransport(command: PHP_BINARY, args: [__DIR__.'/../bin/scribase-mcp-server'], env: ['SCRIBASE_API_KEY' => $scribaseKey]),
);
$toolbox = new McpToolbox($toolset);
$platform = new Platform([OpenAiFactory::createProvider($openAiKey)]);
$agent = new Agent($platform, 'gpt-4o-mini', toolbox: $toolbox);
$execution = $agent->call("Run a read-only query reporting the server time and database name.");
echo $execution->asText();
```
Run it:
```bash
OPENAI_API_KEY=sk-... SCRIBASE_API_KEY=sbk_... \
SCRIBASE_ORG=tmp-... SCRIBASE_PROJECT=my-app \
php examples/symfony-ai-agent-demo.php
```
fix: scribase_memory_task was fully broken — lint-invisible policy, permissive-policy anti-pattern, silently-ignored destructive-confirm gate
Three real bugs found live against production api.scribase.com (`scripts/verify-live.php`), all blocking `scribase_memory_task` end-to-end:
1. `ensureMemoryTable()` hid `CREATE POLICY` inside a `DO $$ ... $$` block for idempotency; Scribase's own migration linter only scans top-level statements for `ENABLE ROW LEVEL SECURITY` + `CREATE POLICY`, so every bootstrap tripped `missing_rls` and `store` failed with `sql_blocked_by_lint` before a single memory was ever written.
2. Making the policy literal then tripped the linter's separate `permissive_policy` rule on `USING (true) WITH CHECK (true)` — correctly, since that predicate would authorise Supabase's `anon`/`authenticated` roles too if this table were ever exposed via PostgREST. Fixed by denying those two roles by name instead.
3. A `DROP POLICY IF EXISTS` (added for idempotency) and `memoryForget()`'s plain `DELETE` are both classified destructive by `database/execute` and silently no-op with `{"status":"confirmation_required"}`, HTTP 200, no `error` key — this client checked only the HTTP status, so `forget` always reported `not_found` while deleting nothing. Fixed: `ensureMemoryTable()` now does a cheap read-only existence check and only ever runs its one-time bootstrap script once (no `DROP` needed at all); `memoryForget()` now sends `confirm: true` (safe — its `DELETE` is already scoped to one caller-supplied id + the current scope, exactly the explicit single-purpose action `confirm` exists for). Both paths also now check for `confirmation_required` explicitly instead of inferring success from HTTP status alone.
Full 9-step `scripts/verify-live.php` suite (every tool, store/recall/search/isolation/forget, a real copy-on-write branch) now passes end-to-end against a fresh production temporary project — re-confirmed on two separate runs.
Also added `scripts/toolbox-check.php`: a live, zero-setup verification that the official Symfony AI MCP bridge (`ClientToolset`+`McpToolbox`) really spawns this package's MCP server and lists its real tools — closing half of the previous `class_exists()`-only verification gap on `examples/symfony-ai-agent-demo.php`. It also surfaces a real, confirmed-live naming quirk: `McpToolbox`'s `prefix: ''` is its own default sentinel for `<toolset-name>_`, not a "no prefix" override, so tools list as `scribase_scribase_<tool>`. The other half — the Agent loop actually calling a tool via a live LLM — still needs an owner-gated `OPENAI_API_KEY` not available in this environment; every constructor/method call in that demo was instead checked against the real installed symfony/ai-* source (exact signature matches, not just class_exists()), and this is disclosed plainly in the script and README rather than faked.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-11-17 15:45:42 +03:00
Verification status, precisely — two halves, checked to two different
depths:
- **The bridge half (no LLM needed)** — `ClientToolset` + `McpToolbox`
spawning this package's real MCP stdio server and listing its real
tools over real MCP JSON-RPC — **has been run live** , not just
`class_exists()` : `php scripts/toolbox-check.php` provisions its own
free temporary project and prints all 5 real tools, fetched from the
real subprocess. It also surfaces a real, confirmed-live naming quirk:
`McpToolbox` 's `$prefix` parameter has no "disable prefixing" value —
passing `''` (its own default) is the *sentinel* for `<toolset-name>_` ,
not an override — so every tool is listed as `scribase_scribase_<tool>` ,
doubled, since this package's own MCP tool names already start with
`scribase_` . Harmless, but real.
- **The agent-loop half (needs a real LLM)** — every constructor
argument, named parameter and method call in
`examples/symfony-ai-agent-demo.php` (`Symfony\AI\Agent\Agent` ,
`Symfony\AI\Agent\Bridge\Mcp\{ClientToolset,McpToolbox}` ,
`Symfony\AI\Platform\{Platform,Bridge\OpenAi\Factory}` , `Mcp\Client` )
was checked against the real installed package source — not
`class_exists()` alone, actual signature matches — but has **not**
itself been run end-to-end against a live LLM call. **Honestly
disclosed**: it needs a real `OPENAI_API_KEY` , an owner-gated secret
not configured in the environment this package was built in.
2026-11-07 04:20:26 +03:00
## Real, live verification (not mocked)
`scripts/verify-live.php` is not a unit test — it (1) solves Scribase's real
proof-of-work challenge and provisions a real, free, no-login temporary
project on **production** `api.scribase.com` , then (2) runs every one of
this package's five tools — the literal, unmodified `ScribaseTools` class,
zero monkeypatching — directly against it. Run it yourself:
```bash
php scripts/verify-live.php
```
**A real run, 2026-11-07, found and fixed a real bug.** The first full run
got through project provisioning, both migration-lint checks (blocked →
clean), the read-only query, the rejected write, and four of
`scribase_memory_task` 's five checks (`store` × 2, `recall` , `search` , scope
isolation) — then `forget` failed with a genuine, reproducible Postgres
error:
```
operator does not exist: uuid = text
HINT: No operator matches the given name and argument types. You might need to add explicit type casts.
LINE 2: delete from public.hermes_agent_memories where id = convert_from(decode('...', 'hex'), 'UTF8') and scope = ...
```
`hermes_agent_memories.id` is a real `uuid` column; `SqlLiteral::encode()`
builds a `text` -typed expression (by design — see its docblock for why a
hex-encoded literal is used instead of a quoted-and-escaped one), and
Postgres has no implicit `uuid = text` comparison operator. **Fix** : cast
the literal explicitly — `where id = (<literal>)::uuid` — safe here because
`memory_id` is already validated against a strict UUID regex before this
code path runs, so the cast itself can never fail on malformed input. Fixed
in `ScribaseTools::memoryForget()` , covered by a regression test
(`tests/ScribaseToolsTest.php::testMemoryForgetSendsAnExplicitUuidCastOnTheIdComparison` ),
and the real adversarial/non-ASCII test for `SqlLiteral` itself
(`tests/SqlLiteralTest.php` ) — ported from the same real re-verification
methodology the companion Python plugin used to find its own, different,
hex-encoding motivation (a backslash false-positive on ordinary non-English
content, not an injection hole).
fix: scribase_memory_task was fully broken — lint-invisible policy, permissive-policy anti-pattern, silently-ignored destructive-confirm gate
Three real bugs found live against production api.scribase.com (`scripts/verify-live.php`), all blocking `scribase_memory_task` end-to-end:
1. `ensureMemoryTable()` hid `CREATE POLICY` inside a `DO $$ ... $$` block for idempotency; Scribase's own migration linter only scans top-level statements for `ENABLE ROW LEVEL SECURITY` + `CREATE POLICY`, so every bootstrap tripped `missing_rls` and `store` failed with `sql_blocked_by_lint` before a single memory was ever written.
2. Making the policy literal then tripped the linter's separate `permissive_policy` rule on `USING (true) WITH CHECK (true)` — correctly, since that predicate would authorise Supabase's `anon`/`authenticated` roles too if this table were ever exposed via PostgREST. Fixed by denying those two roles by name instead.
3. A `DROP POLICY IF EXISTS` (added for idempotency) and `memoryForget()`'s plain `DELETE` are both classified destructive by `database/execute` and silently no-op with `{"status":"confirmation_required"}`, HTTP 200, no `error` key — this client checked only the HTTP status, so `forget` always reported `not_found` while deleting nothing. Fixed: `ensureMemoryTable()` now does a cheap read-only existence check and only ever runs its one-time bootstrap script once (no `DROP` needed at all); `memoryForget()` now sends `confirm: true` (safe — its `DELETE` is already scoped to one caller-supplied id + the current scope, exactly the explicit single-purpose action `confirm` exists for). Both paths also now check for `confirmation_required` explicitly instead of inferring success from HTTP status alone.
Full 9-step `scripts/verify-live.php` suite (every tool, store/recall/search/isolation/forget, a real copy-on-write branch) now passes end-to-end against a fresh production temporary project — re-confirmed on two separate runs.
Also added `scripts/toolbox-check.php`: a live, zero-setup verification that the official Symfony AI MCP bridge (`ClientToolset`+`McpToolbox`) really spawns this package's MCP server and lists its real tools — closing half of the previous `class_exists()`-only verification gap on `examples/symfony-ai-agent-demo.php`. It also surfaces a real, confirmed-live naming quirk: `McpToolbox`'s `prefix: ''` is its own default sentinel for `<toolset-name>_`, not a "no prefix" override, so tools list as `scribase_scribase_<tool>`. The other half — the Agent loop actually calling a tool via a live LLM — still needs an owner-gated `OPENAI_API_KEY` not available in this environment; every constructor/method call in that demo was instead checked against the real installed symfony/ai-* source (exact signature matches, not just class_exists()), and this is disclosed plainly in the script and README rather than faked.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-11-17 15:45:42 +03:00
**A second real run, 2026-11-17, found and fixed three more real bugs**, all
in `scribase_memory_task` 's table-bootstrap and `forget` path, each only
reachable once the `uuid` cast fix above let the suite get further than
before. All three are fixed, and the full 9-step suite — every tool,
`store` /`recall` /`search` /isolation/`forget` , a real copy-on-write branch
create+discard — now passes end-to-end, live, against a fresh production
temporary project:
1. **A `CREATE POLICY` hidden inside a `DO $$ ... $$` block is invisible to
Scribase's own migration linter.** `ensureMemoryTable()` 's original DDL
wrapped the RLS policy in a `DO` block to make it idempotent
(`IF NOT EXISTS (SELECT ... pg_policies)` ). The linter — the same one
`scribase_lint_migration` (tool #2 ) exposes, and which `database/execute`
runs too — statically scans only a script's *top-level* statements for
`ENABLE ROW LEVEL SECURITY` paired with a `CREATE POLICY` ; it never looks
inside a `DO` block. So every memory-table bootstrap tripped the linter's
own `missing_rls` rule and `scribase_memory_task` failed with
`sql_blocked_by_lint` before a single memory could ever be stored, on
every project. **Fix** : make `CREATE POLICY` a literal top-level
statement.
2. ** `USING (true) WITH CHECK (true)` trips the linter's own
`permissive_policy` rule — correctly.** Once the policy was visible, the
literal predicate `true` /`true` tripped a second, legitimate rule: that
predicate would authorise Supabase's public-facing `anon` /`authenticated`
roles too, were this table ever exposed through PostgREST (it is not —
only this package's own direct, privileged connection ever touches it —
but the policy should say that, not rely on it). **Fix** : deny those two
roles by name (`USING (current_user NOT IN ('anon', 'authenticated'))` ),
allow everything else.
3. **A `DROP POLICY IF EXISTS` , added to make fix #1 idempotent, was
silently never executed at all.** `POST .../database/execute` classifies
any `DROP ...` /`DELETE ...` statement as destructive and, without a
`confirm: true` flag, replies `{"status": "confirmation_required", ...}`
with HTTP 200 and no `error` key — this client's original code checked
only the HTTP status, so it read that as success and moved on, while the
entire script (table creation included) had silently never run. This hit
twice: once in `ensureMemoryTable()` 's own idempotency DROP, and
independently in `memoryForget()` 's plain `DELETE` — meaning every real
`forget` call "succeeded" while deleting nothing, always reporting
`not_found` even for a memory that genuinely existed. **Fix** :
`ensureMemoryTable()` now runs a cheap read-only `pg_policies` existence
check first and only ever submits the create/RLS/policy script once per
project (so it needs no `DROP` at all); `memoryForget()` 's `DELETE` —
already strictly scoped to one caller-supplied `id` *and* the current
`scope` , the one case where auto-confirming a destructive statement is
correct, since the caller's whole intent in calling `forget` *is* that
one delete — now sends `confirm: true` . Both paths also now check for
`confirmation_required` explicitly rather than inferring success from
the HTTP status alone, so this class of bug cannot hide silently again.
Run it yourself:
```bash
php scripts/verify-live.php
```
The rest of the suite (steps 1– 7, the real copy-on-write branch in step 9)
was independently confirmed live and passing before, during, and after this
second round of fixes.
2026-11-07 04:20:26 +03:00
## Tests
```bash
composer install
composer test
```
17 tests, 37 assertions, all passing: tool-argument validation (no network),
real-response-shape replay tests (bodies captured verbatim from the live run
above, including the `not_read_only` rejection and the `missing_rls` block),
and two regression tests pinned directly to the real bugs found while
building this package — the `uuid` cast above, and the pre-existing
`ttl_hours: null` schema-validator rejection already known from the Python
sibling's own history (this client omits the key entirely, never sends an
explicit JSON `null` ).
## Security notes
- `SCRIBASE_API_KEY` is read once from the environment at server boot
(`ScribaseClient::fromEnvironment()` ) — never accepted as a tool argument,
so a model can never read, exfiltrate, or rotate it through a tool call.
- `scribase_query` cannot write: the control plane rejects writes/DDL both
lexically and inside a Postgres `READ ONLY` transaction, independent of
this client.
- `scribase_lint_migration` hardcodes `apply: false` in this client's own
code — never read from tool arguments — so this tool can only ever lint.
- `scribase_memory_task` never passes raw model-supplied SQL. Every
interpolated value goes through `SqlLiteral::encode()` , a hex-encoded
`decode(...)` expression that can only ever contain the ASCII characters
`0-9a-f` inside a plain single-quoted string — no quote, backslash, or
comment sequence is representable, independent of the server's
`standard_conforming_strings` setting either way.
## License
MIT.
2026-11-16 14:35:19 +00:00
## Ecosystem
Part of the [Scribase ](https://scribase.com ) stack — one hosted Postgres backend (Supabase/Neon-compatible API, auth, storage) instead of stitching Supabase + Neon + Clerk + Resend together.
- [Scribase ](https://scribase.com ) — hosted Postgres, Supabase/Neon alternative, free tier, 14 days Pro trial, no card required
- [Toolgate ](https://toolgate.scribase.com ) — one key for agent tools, pay only for what you call
- [Scribase Mail ](https://mail.scribase.com ) — Resend-compatible email API
- More open-source projects from this account: [git.ereboslab.com/caelum0x ](https://git.ereboslab.com/caelum0x )