codeigniter-mcp

Model Context Protocol (MCP) server built for high-velocity AI development on CodeIgniter 4 and modern PHP architectures (MVC + Services/Repository layer).

Eliminates LLM hallucinations, scaffolds complete production-ready modules in <15 milliseconds, and unlocks real-time live database and route introspection directly inside your AI IDE (Claude Code, Cursor, Windsurf, Trae, OpenAI Codex, and Google Project Astra).

Architecture: The "Top 1%" Dual-Engine Design

Most MCP servers are either purely external (blind to running application state) or heavy PHP extensions. codeigniter-mcp uses a Dual-Engine Architecture bridging the best of both worlds:

flowchart TB
    subgraph AI["AI Coding Assistant"]
        Client["Claude Code / Cursor / Windsurf / Trae / Codex / Astra"]
    end

    subgraph Outer["Engine 1: Outer Server (Node/TypeScript)"]
        MCPNode["codeigniter-mcp (stdio / HTTP)"]
        Scaffold["Lightning Scaffolding (<15 ms)\nCRUD, Controllers, Services, Entities"]
        Linter["AST Linter & Conventions\nStrict types, PascalCase, Zero-SQL Controllers"]
        RouteVal["Route Collision Analyzer\nCI4 placeholders, (:segment), $routes->resource()"]
        Migrator["Safe Migration Runner\nExplicit confirmation, interpreted PHP errors"]
    end

    subgraph Inner["Engine 2: Inner In-App Server (PHP Spark Command)"]
        SparkCmd["php spark mcp:serve\n(Generated via scaffold_ci4_mcp_server)"]
        LiveDB["Live DB Introspection\nReal tables, columns, nullability, keys"]
        SafeQuery["Safe SELECT Query Engine\nCapped row limit, mutation blocking"]
        ActiveRoutes["Live Route Reflector\nReads compiled Services::routes()"]
        MigStatus["Migration Version Status\nReads active batch history"]
    end

    Client -->|Local stdio or Streamable HTTP| MCPNode
    MCPNode --> Scaffold
    MCPNode --> Linter
    MCPNode --> RouteVal
    MCPNode --> Migrator
    MCPNode -.->|Generates app/Commands/McpServer.php| SparkCmd
    Client -.->|Direct live introspection| SparkCmd
    SparkCmd --> LiveDB
    SparkCmd --> SafeQuery
    SparkCmd --> ActiveRoutes
    SparkCmd --> MigStatus

1. Outer Engine (codeigniter-mcp): Runs in Node/TypeScript over stdio or http. Handles sub-millisecond code scaffolding, static syntax validation, and route collision checks without touching PHP runtime dependencies.
2. Inner Engine (php spark mcp:serve): Scaffolds a zero-dependency, native CodeIgniter 4 Spark command (app/Commands/McpServer.php) that runs a pure JSON-RPC 2.0 MCP server over stdio for real-time live schema reflection, safe read-only SQL queries, and compiled route inspection.

Highlights

• 8 Production Tools: Complete CRUD scaffolding, modular controllers, services, repositories, route validation, migration runner, AST convention linter, and native CI4 MCP server generator.
• Vibecoding Ready (Zero Hallucinations): The AI assistant never confuses CI3, Laravel, and CI4 syntax. Generates clean BaseController, dependency-injected Services, Query Builder Models, and CSRF-protected forms.
• Enterprise-Grade Security:
  • Symlink Traversal Mitigation: Canonical realpathSync resolution prevents reading or writing outside APP_ROOT.
  • DNS Rebinding Protection: Enforces strict Host header matching (returns 403 Forbidden).
  • HTTP API Key Authentication: Supports Authorization: Bearer <key> or X-API-Key headers.
  • Safe PDO Mutations: Prevents false 404s on unchanged MySQL row updates (rowCount() > 0 || $this->findById($id)).
  • Destructive Operations Guarded: Requires explicit confirm: true or overwrite: true.
• 4 Convention Resources + 3 Token-Saving Prompts: Compact prompt templates save token context and speed up LLM responses.

Quickstart

Run with npx (No installation needed)

npx -y codeigniter-mcp

Install globally

npm install -g codeigniter-mcp

From source (Contributors)

git clone https://github.com/AntigamerISK/codeigniter-mcp.git
cd codeigniter-mcp
npm install
npm run build
npm test
npm run verify

IDE & AI Agent Configuration

1. Claude Code / Claude Desktop

Add to claude_desktop_config.json or run claude mcp add codeigniter-mcp:

{
  "mcpServers": {
    "codeigniter-mcp": {
      "command": "npx",
      "args": ["-y", "codeigniter-mcp"],
      "env": {
        "APP_ROOT": "/absolute/path/to/your/codeigniter4_project",
        "RATE_LIMIT_PER_MINUTE": "30"
      }
    }
  }
}

2. Cursor / Windsurf / Trae

In your project root or global settings (.cursor/mcp.json or settings UI):

{
  "mcpServers": {
    "codeigniter-mcp": {
      "command": "npx",
      "args": ["-y", "codeigniter-mcp"],
      "env": {
        "APP_ROOT": "/absolute/path/to/your/codeigniter4_project"
      }
    }
  }
}

3. Remote Agents / OpenAI Codex / Google Project Astra (Streamable HTTP)

For cloud agents that connect over HTTP instead of spawning local sub-processes:

# Start server in HTTP mode
MCP_TRANSPORT=http MCP_PORT=3000 MCP_BIND_HOST=127.0.0.1 MCP_API_KEY=secret_token APP_ROOT=/path/to/project npx codeigniter-mcp

Configure your remote AI agent:

{
  "mcpServers": {
    "codeigniter-mcp": {
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer secret_token"
      }
    }
  }
}

Available Tools (8 Tools)

In-App Live Introspection (php spark mcp:serve)

Once you run scaffold_ci4_mcp_server, your CodeIgniter 4 application gains its own native MCP server:

php spark mcp:serve

This exposes live runtime tools to your AI assistant:

• ci4_db_tables: Reflects active database schema, columns, data types, and primary keys.
• ci4_db_query: Runs safe, read-only SELECT queries (capped at 50 rows, destructive keywords blocked).
• ci4_routes_list: Reads dynamically compiled routes directly from Services::routes().
• ci4_migration_status: Queries Services::migrations() for active and pending migration batches.

Token-Saving Prompts (3 Prompts)

Compact input templates that minimize token consumption:

Convention Resources (4 Resources)

Read-only context injected into the LLM context window:

• convention://naming: Rules for PascalCase, camelCase, kebab-case, and mandatory suffixes.
• convention://architecture: Explains MVC + Service + Repository separation.
• convention://folder-structure: CodeIgniter 4 directory tree mapping.
• convention://security-rules: Guidelines for CSRF tokens, PDO parameterized statements, and strict typing.

Configuration Variables

Testing & Quality Assurance

# Run complete test suite (165 tests across 17 files)
npm test

# Typecheck with zero warnings
npm run typecheck

# Acceptance checklist against real stdio MCP transport
npm run verify

codeigniter-mcp — acceptance checklist

  ✅  Handshake: serverInfo.name = codeigniter-mcp
  ✅  Exposes 8 tools (found 8)
  ✅  Exposes 4 convention resources (found 4)
  ✅  Exposes 3 token-saving prompts (found 3)
  ✅  scaffold_full_resource creates 8 files on disk (7 ms)
  ✅  php -l passes on all generated files (8 files OK)
  ✅  lint_against_framework_rules → compliant
  ✅  validate_route POST /orders → valid
  ✅  run_migration without confirm → blocked (zero executions)
  ✅  run_migration with confirm=true executes via bin/migrate
  ✅  scaffold again → no overwrite, 8 files skipped
  ✅  Path traversal outside APP_ROOT → ValidationError
  ✅  Runner failure → actionable MigrationFailedError

Result: 13 passed · 0 failed · 0 skipped

Documentation

• docs/tools.md — Comprehensive parameter references for all 8 tools.
• docs/profiles.md — Profiles, auto-detection (ci4 vs spec), and configuration.
• docs/security.md — Deep dive into the security architecture and guardrails.
• docs/testing.md — Testing strategy, E2E fixtures, and CI automation.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting pull requests.

License

Distributed under the MIT License. See LICENSE for more information.