codeigniter-mcp

MCP (Model Context Protocol) server that accelerates development of a PHP framework inspired by CodeIgniter: MVC + optional Services/Repository layer (lightweight Ports/Adapters), with native CodeIgniter 4 support (auto- detected from the project structure). Extreme development speed without sacrificing security.

Version: 0.5.0 — Semantic versioning: any input/output schema change breaks compatibility and must be versioned explicitly.

Highlights

• 7 tools + 4 resources + 3 token-saving prompts for an LLM (Claude Code, Cursor, VS Code, Trae) to scaffold, validate and maintain idiomatic framework code without hallucinating structure.
• CodeIgniter 4 native — BaseController + Model (Query Builder) + forge migrations + views; auto-detected, zero config needed.
• Hard security by default: Zod input validation, path-traversal protection, explicit confirm/overwrite for destructive ops, rate limiting, prepared statements, no credential leaks.

Quickstart

npx -y codeigniter-mcp          # run directly over stdio (published package)
npm install -g codeigniter-mcp  # or install globally

From source (contributors): npm install && npm run build && npm test.

Configuration

The server reads environment variables (see mcp.json):

| Variable | Default | Description | |---|---|---| | APP_ROOT | — | Required. Absolute path to the target PHP framework root. All tools operate only inside this directory. | | RATE_LIMIT_PER_MINUTE | 20 | Write operations allowed per minute per session. | | MCP_TRANSPORT | stdio | stdio (local) or http (remote Streamable HTTP). | | MCP_PORT | 3000 | HTTP transport port. |

mcp.json (Claude Code / Cursor / Trae):

{
  "mcpServers": {
    "codeigniter-mcp": {
      "command": "npx",
      "args": ["-y", "codeigniter-mcp"],
      "env": {
        "APP_ROOT": "/path/to/mi-framework",
        "RATE_LIMIT_PER_MINUTE": "20"
      }
    }
  }
}

Project profiles (.codeigniter-mcp.json — optional): an explicit file always wins; without it the profile is auto-detected from the project structure (app/Config/Paths.php or spark → ci4; bin/migrate or app/Repositories → spec; unknown → spec). See docs/profiles.md.

Tools

| Tool | What it does | |---|---| | scaffold_full_resource | Full CRUD: Controller + Service + Repository (interface+impl) + Entity + Migration + tests (8 files, ~15 ms) | | scaffold_controller | Controller only; zero SQL allowed (build-time check) | | scaffold_service | Service: business logic + validation, contract-first DI (ci4: Service that injects the Model) | | scaffold_repository | Repository interface + PDO implementation, always together (ci4: no-op, Models handle data) | | validate_route | Read-only route collision detection against app/Config/Routes.php | | run_migration | Runs the native migration runner (spec: bin/migrate; ci4: spark migrate). Requires explicit confirm; failures are interpreted (no raw stack traces) | | lint_against_framework_rules | Lints PHP files against the profile conventions |

Prompts

Token-saving templates: compact input → exact tool arguments.

| Prompt | What it does | |---|---| | create_full_resource | resource + compact fields → exact scaffold_full_resource arguments | | run_migration | direction + confirm → exact run_migration arguments | | lint_file | filePath → exact lint_against_framework_rules arguments |

Resources

| URI | Content | |---|---| | convention://naming | PascalCase / camelCase / kebab-case, mandatory suffixes | | convention://architecture | MVC + Service + Repository (lightweight Ports/Adapters) | | convention://folder-structure | Framework folder tree | | convention://security-rules | Hard security rules of the tools |

Docs

• docs/tools.md — full tool specs, inputs/outputs and examples
• docs/profiles.md — profiles, .codeigniter-mcp.json, auto-detection, generated contract
• docs/security.md — security model in detail
• docs/testing.md — tests, npm run verify, local development, end-to-end example

Roadmap

• ci3 profile — CodeIgniter 3 (legacy) support behind the same .codeigniter-mcp.json / auto-detection mechanism (CI3 is still active on a large legacy base but is EOL: no security patches).
• Recipe prompts — high-level feature templates (auth, file uploads, REST CRUD) that chain the existing tools.

Contributing

Contributions are welcome! Read CONTRIBUTING.md to set up the development environment, run the tests and open a pull request. Security issues should be reported privately — see SECURITY.md. Release history is tracked in CHANGELOG.md.

License

MIT © 2026 X-Gunner