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>
298 lines
17 KiB
Markdown
298 lines
17 KiB
Markdown
# 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
|
||
[`caelum0x/scribase-hermes-plugin`](https://git.ereboslab.com/caelum0x/scribase-hermes-plugin)
|
||
— 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
|
||
```
|
||
|
||
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.
|
||
|
||
## 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).
|
||
|
||
**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.
|
||
|
||
## 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.
|
||
## 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)
|