caelum0x 0e106c09bb docs: re-record demo video with the now fully-green verify-live.php run
The 2026-11-07 video honestly showed scripts/verify-live.php hitting a real, disclosed production capacity limit mid-run (503 temporary_capacity) before scribase_memory_task's forget path could be captured green. That path is now fixed (previous commit) and re-confirmed live on 4 separate fresh production runs, so re-recorded demo/raw/02-verify-live.cast against a fresh run showing the full 9-step suite passing end-to-end, including store/recall/search/scope-isolation/forget and a real copy-on-write branch create+discard.

Also fixed the end card's stale github.com/caelum0x URL to the real Rithub URL, and replaced the "hit a real production limit" caption with "3 real bugs found live, fixed, re-verified" to match what the new footage actually shows. Old partial-capacity-hit cast kept as a .bak rather than deleted. New video: 60.3s (was 52s), same 1920x1080 H.264 pipeline (demo/build.sh, ffmpeg-skill + asciinema/agg), no AI-generated or staged footage.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-11-17 15:59:22 +03:00

scribase-mcp-php

A real Model Context Protocol server for Scribase — 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 Agent via symfony/ai-mcp-tool.

Built for the Symfony AI & MCP 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 — 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

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:

$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:

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:

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:

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

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 stack — one hosted Postgres backend (Supabase/Neon-compatible API, auth, storage) instead of stitching Supabase + Neon + Clerk + Resend together.

  • Scribase — hosted Postgres, Supabase/Neon alternative, free tier, 14 days Pro trial, no card required
  • Toolgate — one key for agent tools, pay only for what you call
  • Scribase Mail — Resend-compatible email API
  • More open-source projects from this account: git.ereboslab.com/caelum0x
Description
Real MCP server for Scribase (hosted Postgres, Supabase/Neon alternative) on the official PHP MCP SDK, wired into a real Symfony AI Agent. Built for the Symfony AI & MCP Hackathon.
Readme MIT 2.9 MiB
Languages
PHP 100%