caelum0x 8ff8a666d9 feat: add real 52s demo video for Symfony AI & MCP Hackathon submission
Terminal screen recording (asciinema+agg+ffmpeg, no AI-generated footage,
no voiceover) of the real, unmodified code actually running: the 17/17
phpunit suite, scripts/verify-live.php against production api.scribase.com
(real proof-of-work solve, real disposable-account retry, and a genuine
503 temporary_capacity response hit live during recording), the real
bin/scribase-mcp-server stdio MCP server answering a real initialize/
tools/list handshake with all 5 tools, and a brief look at the real
#[McpTool] attributes and Symfony AI Agent bridge wiring. demo/build.sh
reproduces it deterministically from demo/raw/*.cast.
2026-11-07 19:09:48 +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

All the classes this example imports (Symfony\AI\Agent\Agent, Symfony\AI\Agent\Bridge\Mcp\{ClientToolset,McpToolbox}, Symfony\AI\Platform\{Platform,Bridge\OpenAi\Factory}) were confirmed to resolve against the real installed packages (composer require + a class_exists() check against every one, not assumed from docs alone). Honestly disclosed: this script needs a real OPENAI_API_KEY, an owner-gated secret not configured in the environment this package was built in, so unlike scripts/verify-live.php below, this one specific file has been checked to compile and resolve against the real APIs but not run end-to-end against a live LLM.

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 full live re-run then hit Scribase's own real, honest, global capacity guard on free temporary projects (503 temporary_capacity — the platform's own disclosed cap of 200 concurrently live anonymous/temporary projects, shared across every real user and agent using it, not a flaw in this code) before the fixed forget path could be re-confirmed end-to-end against a second live project. The fix itself is not in doubt — Postgres's own error message states the exact cast needed, and memory_id's pre-validation makes the cast unconditionally safe — but re-run scripts/verify-live.php yourself once the shared temporary-project pool has headroom to see the complete, currently-green transcript for real. The rest of the suite (steps 1–7, and store/recall/search/isolation within step 8) is independently, already confirmed live and passing.

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.

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%