API - CODEX AGENTS: MCP transport and real e2e smoke

README.md

@@ -27,7 +27,9 @@ All writes go through NODE.DC Agent Gateway, are scoped by agent grants, and are
 - Opaque agent tokens are generated once and stored only as SHA-256 hashes.
 - Authenticated agent-session endpoint returns effective grants/scopes for future MCP calls.
 - Product tool endpoints validate agent token, scopes, and project grants before calling Tasker internal adapter.
-- MCP and Tasker write execution are documented but not implemented yet.
+- MCP JSON-RPC endpoint `/mcp` exposes the same tool runtime as REST product endpoints.
+- Tool execution calls the real Tasker internal adapter; no fake Tasker storage exists in Gateway.
+- Local real e2e smoke verifies Gateway -> MCP -> Tasker runtime writes.
 
 ## Local development
 
@@ -44,6 +46,7 @@ Useful checks:
 ```bash
 npm run check
 npm run build
+npm run smoke:mcp
 npm run smoke:gateway
 curl http://127.0.0.1:4100/readyz
 curl http://127.0.0.1:4100/api/v1/meta/capabilities
@@ -70,15 +73,52 @@ curl http://127.0.0.1:4100/api/v1/agent-session \
 
 Do not expose these lifecycle endpoints publicly before the Launcher/internal auth layer is added.
 
+Call MCP tools through the JSON-RPC endpoint:
+
+```bash
+curl -sS http://127.0.0.1:4100/mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -H 'MCP-Protocol-Version: 2025-06-18' \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"jsonrpc":"2.0","id":"tools","method":"tools/list","params":{}}' | jq
+```
+
 ## Local testing strategy
 
 No fake Tasker storage is embedded into Agent Gateway.
 
 Local verification is split into product layers:
 
-1. `npm run smoke:gateway` verifies real Agent Gateway persistence, bearer token auth, scope checks, grant checks, and the boundary before Tasker calls.
-2. Full localhost e2e starts after Tasker implements `/api/internal/nodedc/agent/...` adapter. Then the same Gateway tool endpoints call the real local Tasker runtime.
-3. External-machine testing uses the same token and endpoint shape against staging HTTPS; no extra protocol or fake environment should be introduced.
+1. `npm run smoke:mcp` verifies MCP initialize, tool listing, bearer token auth, scope checks, grant checks, and the Tasker boundary.
+2. `npm run smoke:gateway` verifies the REST compatibility boundary over the same tool execution path.
+3. `npm run smoke:e2e` verifies REST tool endpoints against the real local Tasker runtime.
+4. `npm run smoke:mcp:e2e` verifies MCP tool calls against the real local Tasker runtime.
+5. External-machine testing uses the same token and endpoint shape against staging HTTPS; no extra protocol or fake environment should be introduced.
+
+Example real localhost MCP e2e:
+
+```bash
+TOKEN=$(python3 - <<'PY'
+from pathlib import Path
+for line in Path('/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/plane-app/plane.env').read_text().splitlines():
+    if line.startswith('NODEDC_INTERNAL_ACCESS_TOKEN=') or line.startswith('PLANE_NODEDC_ACCESS_TOKEN='):
+        value = line.split('=', 1)[1].strip().strip('"').strip("'")
+        if value:
+            print(value)
+            break
+PY
+)
+
+DATABASE_URL='postgres://nodedc_agent_gateway:replace-with-local-postgres-password@localhost:54100/nodedc_agent_gateway' \
+NODE_ENV=development \
+LOG_LEVEL=silent \
+NODEDC_TASKER_INTERNAL_URL='http://localhost:8090' \
+NODEDC_INTERNAL_ACCESS_TOKEN="$TOKEN" \
+SMOKE_WORKSPACE_SLUG='nodedc' \
+SMOKE_PROJECT_ID='<project-id>' \
+npm run smoke:mcp:e2e
+```
 
 Current Tasker internal adapter contract expected by Gateway: