README

An MCP server for CodeIgniter 4, in the spirit of Laravel Boost.

It stops your AI coding agent guessing. Instead of inventing column names and inferring routes from filenames, the agent asks your running application: real schema, real routes, real models, real filters, real migration state — plus always-loaded conventions and on-demand skills for CodeIgniter 4 and MariaDB.

Works with Claude Code, Cursor, Codex CLI, Windsurf, Zed, GitHub Copilot and Antigravity.

Status: pre-1.0. The protocol layer, SQL guard, redaction and installers are covered by 142 automated tests. The tools that read framework internals are written against CodeIgniter's documented APIs and verified against its source, but need a run of php spark boost:doctor on your project to confirm — see Production readiness for an honest account.

Why

Ask an agent to "add a status column to orders" without this, and it will guess a migration, guess your model's $allowedFields, and guess whether status already exists. With it, the agent reads your actual schema and migration history first.

Zero runtime dependencies beyond PHP and CodeIgniter — no ReactPHP, no MCP SDK, nothing to conflict with your app's dependency tree.

Install

composer require --dev codeigniter-ps/ci4-boost
php spark boost:install
php spark boost:doctor     # verify it works

boost:install detects which agents your project already uses (.claude/, .cursor/, .codex/, …) and for each one registers the MCP server, writes a guidelines block, and installs skills. It also publishes app/Config/Boost.php.

Useful flags:

Flag	Effect
`--agents=claude_code,cursor`	Configure specific agents, skipping detection
`--all`	Configure every supported agent
`--list`	Show supported agent names and their config paths

Then restart your editor (or reload its MCP servers).

--no-header is not optional. CodeIgniter prints a CLI banner to stdout before any command runs, which lands in front of the first JSON-RPC message and breaks the handshake. boost:install writes the flag into your MCP config, boost:mcp refuses to start without it, and boost:doctor fails if it's missing from a config file. If you register the server by hand, the command is php /path/to/spark boost:mcp --no-header.

Commands

Command	Purpose
`boost:install`	Configure agents: MCP server, guidelines, skills
`boost:update`	Refresh guidelines and skills after an upgrade or edit
`boost:doctor`	Diagnose an install; `--verbose` also runs every read-only tool
`boost:mcp`	Start the server (your editor runs this, not you)

boost:doctor is the first thing to reach for when an editor reports the server as disconnected. It checks the environment, config, tool registry, a real initialize → tools/list handshake, every agent config file, and database connectivity — and tells you which one is broken.

Tools

Tool	What the agent gets
`application_info`	PHP/CI4 versions, environment, DB driver, all Composer packages
`database_connections`	Configured DB groups (credentials redacted)
`database_schema`	Tables, columns, indexes, foreign keys — summary or detailed, filterable
`database_query`	Read-only SQL against a real connection; `EXPLAIN` for tuning
`route_list`	Every defined route: method, URI, name, handler
`migration_status`	Which migrations are applied vs pending, with batch and timestamp
`model_inspector`	Every model's table, keys, allowed fields, validation rules, callbacks
`filter_list`	Filter aliases, globals, per-method and per-URI bindings
`event_list`	Registered events and their listeners
`validation_rule_list`	Named rule groups and custom rule-set methods
`shield_info`	Shield auth config and groups/permissions, if installed
`service_list`	Every `service()` factory, including app-specific ones
`config_dump`	Any `app/Config/*.php` class, with secrets redacted
`read_log_entries`	Recent log lines, filterable by level
`last_error`	Most recent ERROR+ entry with its stack trace
`get_absolute_url`	Relative path or route name → real absolute URL
`search_docs`	Keyword search over a bundled CodeIgniter 4 user guide index
`evaluate_code`	Tinker-style PHP eval — off by default, see Security

Six of these have no Laravel Boost equivalent (filter_list, event_list, validation_rule_list, shield_info, service_list, config_dump) because they map CodeIgniter-specific concepts.

search_docs is a local counterpart to Laravel Boost's hosted semantic search-docs, not a clone of it: it scores a bundled snapshot of the user guide's table of contents (title, keywords, a short summary) against your query and returns a link to the real page, entirely offline and without an embeddings model. Coarser than semantic search, but it needs nothing beyond PHP and never sends your query anywhere.

route_list and migration_status read the framework's services directly rather than shelling out to spark routes/migrate:status. That's deliberate: CLI::write() writes straight to the stdout handle, bypassing output buffering, so running those commands in-process would dump an ASCII table into the protocol stream. Reading the services also gives the agent structured JSON instead of a table it has to parse.

Guidelines and skills

Two distinct ways of giving the agent context, mirroring Laravel Boost:

Aspect	Guidelines	Skills
Loaded	Upfront, always in context	On demand, when relevant
Scope	Broad conventions	Focused task recipes
Bundled	CI4 core, MariaDB, models, routing/filters, validation, migrations, Shield, testing	`ci4-model-development`, `ci4-restful-api`, `ci4-migration-authoring`, `shield-auth-setup`, `mariadb-query-tuning`

Customizing

Add your own without forking:

.ai/guidelines/our-conventions.md        # appended to the bundled guidelines
.ai/skills/invoice-generation/SKILL.md   # installed alongside the bundled skills

Overriding

A file with the same name as a bundled one replaces it, keeping its position:

.ai/guidelines/10-database.md            # replaces the bundled database section
.ai/skills/ci4-restful-api/SKILL.md      # replaces the bundled skill

Run php spark boost:update after adding or editing either. Boost only ever rewrites content between its own markers in CLAUDE.md/AGENTS.md, and never touches a skill folder whose .boost-managed marker you've deleted — so your edits survive upgrades.

To keep resources fresh automatically, add to your app's composer.json:

{
    "scripts": {
        "post-update-cmd": ["@php spark boost:update"]
    }
}

For package authors

If you maintain a CodeIgniter 4 package, you can teach every user's AI agent how to use it. Add either or both of:

your-package/
└── resources/boost/
    ├── guidelines/acme-payments.md          # merged into users' guidelines
    └── skills/acme-payments/SKILL.md        # installed into users' skills

When a project that requires your package runs boost:install or boost:update, these are discovered from vendor/ automatically (via Composer's installed.json, with a directory-scan fallback) and merged in. Precedence is: bundled → vendor packages → the project's own .ai/ files, later winning on filename/skill-name conflicts — so end users can always override you.

Keep guidelines short and actionable: what the package does, its conventions, and one or two code samples. Skills follow the Agent Skills format: a folder with a SKILL.md containing name and description frontmatter plus Markdown instructions.

Configuration

app/Config/Boost.php:

public bool    $enabled             = true;
public bool    $enableDatabaseQuery = true;   // false = no row data leaves the machine
public bool    $enableEvaluateCode  = false;  // arbitrary PHP; local dev only
public int     $maxRows             = 200;    // cap query result size
public int     $maxLogLines         = 200;
public ?string $phpBinary           = null;   // null = PHP_BINARY
public array   $additionalTools     = [];     // your own ToolInterface classes
public array   $agents              = [];     // per-agent path overrides

A disabled tool isn't advertised in tools/list at all, rather than being offered and then refusing every call.

Supported agents

Agent	MCP config	Guidelines	Skills
Claude Code	`.mcp.json`	`CLAUDE.md`	`.claude/skills`
Cursor	`.cursor/mcp.json`	`AGENTS.md`	`.cursor/skills`
Codex CLI	`.codex/config.toml`	`AGENTS.md`	`.agents/skills`
Windsurf	`.windsurf/mcp.json`	`.windsurf/rules/…`	`.windsurf/skills`
Zed	`.zed/settings.json`	`AGENTS.md`	`.zed/skills`
GitHub Copilot (VS Code)	`.vscode/mcp.json`	`AGENTS.md`	`.github/skills`
Antigravity	(register manually in the IDE)	`AGENTS.md`	`.agents/skills`

Config files are merged, never overwritten: other MCP servers and unrelated settings are preserved. Add another editor by extending Install\Agents\Agent and calling Boost::registerAgent(MyAgent::class).

Production readiness

An honest summary, because "it runs" and "it's safe to publish" aren't the same claim.

Well covered (142 tests, 697 assertions):

The MCP protocol layer, end-to-end over real stream handles: handshake, version negotiation, tools/list, tools/call, notifications, batches, malformed input, error codes, and the guarantee that stdout carries nothing but one JSON object per line.
The read-only SQL guard, tested adversarially against ~35 mutation, stacking, comment-obscuring and file-exfiltration attempts.
Secret redaction, including the case that a plain password match misses (CodeIgniter's own SMTPPass).
The JSON and TOML config writers: merging, idempotency, preserving other servers and unrelated keys, Windows path escaping.
The installers: guideline block replacement, preservation of hand-written content, user-customized skills left alone, and MCP config landing in the project root rather than public/.
Every tool's metadata and JSON-encodability, and a check that no tool leaks a seeded credential through the server.

Verified by reading CodeIgniter's source, not by execution: the framework APIs the tools call (listTables, getFieldData, getIndexData, getForeignKeyData, DefinedRouteCollector, MigrationRunner, Events::listeners, Config\Services). Reading the source is how four fatal bugs in the first draft were found — including the stdout-corrupting banner and the command() helper silently returning nothing — but it is not a substitute for running against a real app.

Not covered here: no test boots a real CodeIgniter application or connects to a real MariaDB server, because neither was available in the environment this was built in. boost:doctor --verbose exists precisely to close that gap on your machine in one command.

Recommended before you rely on it: run boost:install and boost:doctor --verbose on a real project and read the output. If it's all green, the framework-facing assumptions hold for your setup.

Publishing

To list on Packagist: push to GitHub, submit the repository URL at packagist.org/packages/submit, enable the GitHub webhook, then tag v0.2.0. See RELEASE-CHECKLIST.md for the full pre-flight list — including the note that the Packagist vendor in composer.json must be one your account controls.

License

MIT — see LICENSE.md.

codeigniter-ps / ci4-boost

Maintainers

Package info

Statistics

Security