Add eMCP scaffolding

Author: Dmi3yy

.ci/governance-lock.json

@@ -0,0 +1,19 @@
+{
+    "toolset_version": "1.0",
+    "canonical_tools": [
+        "evo.content.search",
+        "evo.content.get",
+        "evo.content.root_tree",
+        "evo.content.descendants",
+        "evo.content.ancestors",
+        "evo.content.children",
+        "evo.content.siblings",
+        "evo.model.list",
+        "evo.model.get"
+    ],
+    "spec_version": "1.0-contract",
+    "runtime_status": "Gate C baseline implemented (full validation pending)",
+    "spec_public_contract_hash": "752772e83d65c41fe55bd6ddef3359a8ab04f0e3efe67d4901e79870d1967e7b",
+    "model_allowlists_hash": "2e27381b6120a53f4adb6da3649fcc5319530da4f6e41063d7b7b0700d600731",
+    "updated_at": "2026-03-02T14:48:22+00:00"
+}

.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - '**'
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      run_runtime_integration:
+        description: 'Run runtime integration checks against deployed environment'
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          coverage: none
+
+      - name: Validate composer files
+        run: composer validate --strict
+
+      - name: Install dependencies
+        run: composer install --no-interaction --prefer-dist --no-progress
+
+      - name: Run CI checks
+        run: composer run ci:check
+
+  runtime-integration:
+    needs: checks
+    if: ${{ github.event_name == 'workflow_dispatch' && inputs.run_runtime_integration == true }}
+    runs-on: ubuntu-latest
+    env:
+      EMCP_INTEGRATION_ENABLED: '1'
+      EMCP_BASE_URL: ${{ secrets.EMCP_BASE_URL }}
+      EMCP_SERVER_HANDLE: ${{ secrets.EMCP_SERVER_HANDLE }}
+      EMCP_API_PATH: ${{ secrets.EMCP_API_PATH }}
+      EMCP_API_TOKEN: ${{ secrets.EMCP_API_TOKEN }}
+      EMCP_MANAGER_PATH: ${{ secrets.EMCP_MANAGER_PATH }}
+      EMCP_MANAGER_COOKIE: ${{ secrets.EMCP_MANAGER_COOKIE }}
+      EMCP_DISPATCH_CHECK: ${{ secrets.EMCP_DISPATCH_CHECK }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          coverage: none
+
+      - name: Install dependencies
+        run: composer install --no-interaction --prefer-dist --no-progress
+
+      - name: Runtime integration checks
+        run: composer run test:integration:runtime

.gitignore

@@ -1 +1,3 @@
-.idea
+.idea
+.DS_Store
+demo/

ARCHITECTURE_FREEZE_CHECKLIST.md

@@ -3,31 +3,37 @@
 Use this checklist before starting Phase 1 implementation.
 
 ## 1. Contract Completeness
-- [ ] `PRD.md`, `SPEC.md`, `TOOLSET.md` are mutually consistent.
-- [ ] Gate A/B/C boundaries are explicit and conflict-free.
-- [ ] Namespace governance and ecosystem extension rules are finalized.
-- [ ] `initialize` metadata contract is mandatory and versioned.
+- [x] `PRD.md`, `SPEC.md`, `TOOLSET.md` are mutually consistent.
+- [x] Gate A/B/C boundaries are explicit and conflict-free.
+- [x] Namespace governance and ecosystem extension rules are finalized.
+- [x] `initialize` metadata contract is mandatory and versioned.
 
 ## 2. Security Baseline
-- [ ] `THREAT_MODEL.md` attack trees reviewed and approved.
-- [ ] `SECURITY_CHECKLIST.md` mapped to planned tests.
-- [ ] Model field allowlist policy is complete for all allowlisted models.
-- [ ] Error formatter contract (`401/403/409/413/415` + `trace_id`) is fixed.
+- [x] `THREAT_MODEL.md` attack trees reviewed and approved.
+- [x] `SECURITY_CHECKLIST.md` mapped to planned tests.
+- [x] Model field allowlist policy is complete for all allowlisted models.
+- [x] Error formatter contract (`401/403/409/413/415` + `trace_id`) is fixed.
 
 ## 3. Runtime Governance
-- [ ] Tool uniqueness and handle uniqueness rules are frozen.
-- [ ] Rate-limit identity resolver algorithm is frozen.
-- [ ] Idempotency hash and conflict policy is frozen.
-- [ ] Streaming activation policy (`stream.enabled`) is frozen.
+- [x] Tool uniqueness and handle uniqueness rules are frozen.
+- [x] Rate-limit identity resolver algorithm is frozen.
+- [x] Idempotency hash and conflict policy is frozen.
+- [x] Streaming activation policy (`stream.enabled`) is frozen.
 
 ## 4. Release/BC Governance
-- [ ] SemVer and Public Contract Stability sections approved.
-- [ ] Golden fixture governance (version bump + changelog + CI guard) approved.
-- [ ] Deprecation policy for breaking changes approved.
-- [ ] Upstream compatibility policy (`laravel/mcp ^0.5.x`) approved.
+- [x] SemVer and Public Contract Stability sections approved.
+- [x] Golden fixture governance (version bump + changelog + CI guard) approved.
+- [x] Deprecation policy for breaking changes approved.
+- [x] Upstream compatibility policy (`laravel/mcp ^0.5.x`) approved.
 
 ## 5. Process Readiness
-- [ ] Formal platform audit (`PLATFORM_AUDIT.md`) approved.
-- [ ] Ownership assigned for platform, security, and release decisions.
-- [ ] Phase 1 backlog items trace to frozen contracts.
-- [ ] Any open architectural question has owner + resolution date.
+- [x] Formal platform audit (`PLATFORM_AUDIT.md`) approved.
+- [x] Ownership assigned for platform, security, and release decisions.
+- [x] Phase 1 backlog items trace to frozen contracts.
+- [x] Any open architectural question has owner + resolution date.
+
+## Freeze Decision
+- Date: 2026-02-19
+- Status: APPROVED
+- Baseline: architecture contract frozen for Gate B start
+- Change rule: contract updates require explicit SemVer-aware version bump + changelog entry

CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+- Added Gate C baseline async dispatch implementation (`/dispatch`, worker, idempotency, failover).
+- Added minimal security hardening baseline (security policy, redactor, audit logger).
+- Added governance guard tests and golden fixtures bound to `toolsetVersion`.

CONTRIBUTING.md

@@ -8,6 +8,9 @@ This repository defines and implements the official MCP platform layer for Evolu
 - Any change that affects public MCP behavior must include tests and changelog entry.
 - Namespace governance is mandatory: third-party additions must use `vendor.domain.*`.
 - Breaking changes require SemVer-major planning and deprecation note.
+- eMCP core MUST remain orchestration-agnostic.
+- Planner/strategy-specific logic MUST NOT be implemented in eMCP core layer.
+- Orchestration concepts belong in consuming packages (for example `dAi`/`eAi`), not in core transport/policy/runtime.
 
 ## Pull Request Requirements
 - Link issue/problem statement.

DOCS.md

@@ -6,6 +6,11 @@ It is the implementation-oriented guide aligned with `PRD.md` and `SPEC.md`.
 Contract boundary:
 - `SPEC.md` and `TOOLSET.md` are normative.
 - `DOCS.md` describes how to implement and operate those contracts.
+- `OPERATIONS.md` is the day-2 operator runbook (profiles, health checks, triage).
+
+Status marker:
+- Contract target: `SPEC 1.0-contract`.
+- Runtime baseline in current repository: `Gate C baseline implemented (full validation pending)`.
 
 ## 1) Overview
 `eMCP` is a thin Evo-native adapter around `laravel/mcp`.
@@ -32,6 +37,43 @@ Implementation order is mandatory:
 
 Minimal first release is Gate A only.
 
+## 2.1) Laravel MCP Parity Contract
+eMCP keeps upstream `laravel/mcp` behavior as the baseline:
+- `GET` on MCP transport route returns `405`.
+- `POST` processes JSON-RPC messages.
+- `MCP-Session-Id` is passed through request/response.
+- `202` is preserved for no-reply notification flows.
+- SSE transport response uses `text/event-stream` when streaming is enabled.
+- Upstream command surface (`make:mcp-*`, `mcp:start`, `mcp:inspector`) remains available.
+
+eMCP-specific logic is additive (ACL/scopes/policies), not a protocol rewrite.
+
+## 2.2) Ecosystem Interop Map
+- `sApi`: external exposure for MCP endpoints through route providers and JWT scopes.
+- `sTask`: async dispatch for long-running MCP calls (`emcp_dispatch` worker).
+- `eAi`: AI runtime can consume eMCP tools in manager or API mode.
+- `dAi`: manager orchestration UI can consume stable eMCP tool contracts.
+
+Boundary rule:
+- eMCP provides protocol/runtime/policy contracts.
+- orchestration concepts live in consuming packages, not in eMCP core.
+
+## 2.3) Fast Path: One MCP Server, Internal + External
+1. Generate primitives:
+```bash
+php artisan make:mcp-server ContentServer
+php artisan make:mcp-tool HealthTool
+```
+Generated classes are placed under `core/custom/app/Mcp/...`.
+2. Register server entry in `core/custom/config/mcp.php`.
+3. Verify manager/internal call:
+- `POST /{manager_prefix}/{handle}` with manager session and `emcp` permission.
+4. Verify external API call (with `sApi` installed):
+- `POST /{SAPI_BASE_PATH}/{SAPI_VERSION}/mcp/{handle}`
+- `Authorization: Bearer <jwt>` with required `mcp:*` scopes.
+5. Optional async mode:
+- `queue.driver=stask` + dispatch endpoint + task progress tracking.
+
 ## User Guide
 
 ## 3) Requirements
@@ -122,6 +164,8 @@ return [
 
     'limits' => [
         'max_payload_kb' => 256,
+        'max_result_items' => 100,
+        'max_result_bytes' => 1048576,
     ],
 
     'logging' => [
@@ -143,6 +187,7 @@ return [
             'max_offset' => 5000,
         ],
         'models' => [
+            'max_offset' => 5000,
             'allow' => [
                 'SiteTemplate', 'SiteTmplvar', 'SiteTmplvarContentvalue',
                 'SiteSnippet', 'SitePlugin', 'SiteModule', 'Category',
@@ -176,21 +221,25 @@ return [
             'handle' => 'content',
             'transport' => 'web',
             'route' => '/mcp/content',
-            'class' => App\Mcp\Servers\ContentServer::class,
+            'class' => EvolutionCMS\eMCP\Servers\ContentServer::class,
             'enabled' => true,
             'auth' => 'sapi_jwt',
             'scopes' => ['mcp:read', 'mcp:call'],
         ],
         [
             'handle' => 'content-local',
             'transport' => 'local',
-            'class' => App\Mcp\Servers\ContentServer::class,
-            'enabled' => true,
+            'class' => EvolutionCMS\eMCP\Servers\ContentServer::class,
+            'enabled' => false,
         ],
     ],
 ];
 ```
 
+Note:
+- `content-local` is disabled by default to avoid duplicate tool-name registration conflicts with `content`.
+- Enable local transport only when conflicting server entries are disabled or use non-overlapping tool names.
+
 Validation rules:
 - `handle` must be unique
 - `class` must exist and extend `Laravel\Mcp\Server`
@@ -208,6 +257,23 @@ Route semantics:
 - Gate A manager endpoint is `/{manager_prefix}/{handle}`.
 - `servers[*].route` is the web transport route binding and is externally relevant in API mode (Gate B+).
 
+## 6.3 Configuration Presets (Practical)
+Use these presets to reduce setup friction:
+
+- `manager-only`:
+  - `mode.internal=true`, `mode.api=false`
+  - use manager endpoint only (`/{manager_prefix}/{handle}`)
+- `api-only`:
+  - `mode.internal=false`, `mode.api=true`
+  - require `sApi` + JWT scopes
+- `hybrid` (recommended default):
+  - `mode.internal=true`, `mode.api=true`
+  - same tool contract available for manager and API consumers
+
+Async add-on (any preset):
+- `queue.driver=stask` for long-running calls.
+- `queue.failover=sync` for resilient fallback on installations without `sTask`.
+
 ## 7) Server Registration Model
 Upstream Laravel MCP expects `routes/ai.php`.
 `eMCP` replaces this with config-first registration for Evo.
@@ -254,6 +320,16 @@ Safety constraints:
 - allow only approved operators/casts
 - enforce `depth/limit/offset` caps from config
 
+Contract-first execution style:
+- each tool call follows `validate -> authorize -> query -> map -> paginate`
+- one tool should map to one explicit handler/procedure
+- hidden query/policy side effects outside the pipeline are discouraged
+
+Orchestration execution profile (post-MVP):
+- `Intent -> PolicyCheck -> Task(s) -> EvidenceTrace -> ApprovalGate`
+- planner actions should be constrained by policy-valid action sets
+- intent/task/evidence linkage should be auditable end-to-end
+
 Model catalog profile (read-only by default):
 - `evo.model.list`
 - `evo.model.get`
@@ -324,11 +400,13 @@ Via `McpRouteProvider` (`RouteProviderInterface`):
 - `POST /mcp/{server}/dispatch`
 
 Recommended middleware chain:
-- `sapi.jwt`
+- `emcp.jwt`
 - `emcp.scope`
 - `emcp.actor`
 - `emcp.rate`
 
+`McpRouteProvider` removes upstream `sapi.jwt` from MCP routes and uses `emcp.jwt` as the single JWT middleware.
+
 Error handling policy:
 - transport/auth/middleware failures -> HTTP status (`401/403/405/413/415`) with non-JSON-RPC error body.
 - JSON-RPC dispatch failures -> HTTP `200` + JSON-RPC `error` (`-32700`, `-32600`, `-32601`, `-32602`, `-32603`).
@@ -445,12 +523,17 @@ php artisan mcp:start content-local
 php artisan mcp:inspector content-local
 ```
 
-Planned eMCP operational commands:
+Before `mcp:start content-local`, enable `content-local` in `core/custom/config/mcp.php` and disable conflicting server entries if they expose identical tool names.
+
+Available eMCP operational commands:
 
 ```bash
 php artisan emcp:test
-php artisan emcp:sync-workers
 php artisan emcp:list-servers
+php artisan emcp:sync-workers
+composer run governance:update-lock
+composer run ci:check
+EMCP_INTEGRATION_ENABLED=1 EMCP_BASE_URL="https://example.org" EMCP_API_PATH="/api/v1/mcp/{server}" EMCP_API_TOKEN="<jwt>" composer run test:integration:runtime
 ```
 
 ## 16) Troubleshooting