From 6748e6cd843739436f4af9a38e65679b2ed741cc Mon Sep 17 00:00:00 2001 From: darbs-claude Date: Mon, 23 Feb 2026 11:28:32 +0000 Subject: [PATCH] fix: improve workspace context error messages (closes #28) Updated workspace_id error messages in all MCP tools to include actionable guidance and a documentation link. Affected tools: PlanCreate, PlanGet, PlanList, StateSet, StateGet, StateList, SessionStart. Resolves DX-001 from TODO.md. Co-Authored-By: Claude Sonnet 4.6 --- Mcp/Tools/Agent/Plan/PlanCreate.php | 2 +- Mcp/Tools/Agent/Plan/PlanGet.php | 2 +- Mcp/Tools/Agent/Plan/PlanList.php | 2 +- Mcp/Tools/Agent/Session/SessionStart.php | 2 +- Mcp/Tools/Agent/State/StateGet.php | 2 +- Mcp/Tools/Agent/State/StateList.php | 2 +- Mcp/Tools/Agent/State/StateSet.php | 2 +- TODO.md | 6 +++--- 8 files changed, 10 insertions(+), 10 deletions(-) diff --git a/Mcp/Tools/Agent/Plan/PlanCreate.php b/Mcp/Tools/Agent/Plan/PlanCreate.php index ff3076d..3e74189 100644 --- a/Mcp/Tools/Agent/Plan/PlanCreate.php +++ b/Mcp/Tools/Agent/Plan/PlanCreate.php @@ -99,7 +99,7 @@ class PlanCreate extends AgentTool // Determine workspace_id - never fall back to hardcoded value in multi-tenant environment $workspaceId = $context['workspace_id'] ?? null; if ($workspaceId === null) { - return $this->error('workspace_id is required but could not be determined from context'); + return $this->error('workspace_id is required. Ensure you have authenticated with a valid API key and started a session. See: https://host.uk.com/ai'); } $plan = AgentPlan::create([ diff --git a/Mcp/Tools/Agent/Plan/PlanGet.php b/Mcp/Tools/Agent/Plan/PlanGet.php index ed71bb4..2929bc7 100644 --- a/Mcp/Tools/Agent/Plan/PlanGet.php +++ b/Mcp/Tools/Agent/Plan/PlanGet.php @@ -71,7 +71,7 @@ class PlanGet extends AgentTool // Validate workspace context for tenant isolation $workspaceId = $context['workspace_id'] ?? null; if ($workspaceId === null) { - return $this->error('workspace_id is required for plan operations'); + return $this->error('workspace_id is required. Ensure you have authenticated with a valid API key and started a session. See: https://host.uk.com/ai'); } $format = $this->optional($args, 'format', 'json'); diff --git a/Mcp/Tools/Agent/Plan/PlanList.php b/Mcp/Tools/Agent/Plan/PlanList.php index 22d7423..68e0250 100644 --- a/Mcp/Tools/Agent/Plan/PlanList.php +++ b/Mcp/Tools/Agent/Plan/PlanList.php @@ -71,7 +71,7 @@ class PlanList extends AgentTool // Validate workspace context for tenant isolation $workspaceId = $context['workspace_id'] ?? null; if ($workspaceId === null) { - return $this->error('workspace_id is required for plan operations'); + return $this->error('workspace_id is required. Ensure you have authenticated with a valid API key and started a session. See: https://host.uk.com/ai'); } // Query plans with workspace scope to prevent cross-tenant access diff --git a/Mcp/Tools/Agent/Session/SessionStart.php b/Mcp/Tools/Agent/Session/SessionStart.php index ce0b723..3e3458f 100644 --- a/Mcp/Tools/Agent/Session/SessionStart.php +++ b/Mcp/Tools/Agent/Session/SessionStart.php @@ -88,7 +88,7 @@ class SessionStart extends AgentTool // Determine workspace_id - never fall back to hardcoded value in multi-tenant environment $workspaceId = $context['workspace_id'] ?? $plan?->workspace_id ?? null; if ($workspaceId === null) { - return $this->error('workspace_id is required but could not be determined from context or plan'); + return $this->error('workspace_id is required. Ensure you have authenticated with a valid API key and started a session, or provide a valid plan_slug to infer workspace context. See: https://host.uk.com/ai'); } $session = AgentSession::create([ diff --git a/Mcp/Tools/Agent/State/StateGet.php b/Mcp/Tools/Agent/State/StateGet.php index 9a06898..590043f 100644 --- a/Mcp/Tools/Agent/State/StateGet.php +++ b/Mcp/Tools/Agent/State/StateGet.php @@ -71,7 +71,7 @@ class StateGet extends AgentTool // Validate workspace context for tenant isolation $workspaceId = $context['workspace_id'] ?? null; if ($workspaceId === null) { - return $this->error('workspace_id is required for state operations'); + return $this->error('workspace_id is required. Ensure you have authenticated with a valid API key and started a session. See: https://host.uk.com/ai'); } // Query plan with workspace scope to prevent cross-tenant access diff --git a/Mcp/Tools/Agent/State/StateList.php b/Mcp/Tools/Agent/State/StateList.php index 199b56d..694ab61 100644 --- a/Mcp/Tools/Agent/State/StateList.php +++ b/Mcp/Tools/Agent/State/StateList.php @@ -70,7 +70,7 @@ class StateList extends AgentTool // Validate workspace context for tenant isolation $workspaceId = $context['workspace_id'] ?? null; if ($workspaceId === null) { - return $this->error('workspace_id is required for state operations'); + return $this->error('workspace_id is required. Ensure you have authenticated with a valid API key and started a session. See: https://host.uk.com/ai'); } // Query plan with workspace scope to prevent cross-tenant access diff --git a/Mcp/Tools/Agent/State/StateSet.php b/Mcp/Tools/Agent/State/StateSet.php index e8e15b7..702edb3 100644 --- a/Mcp/Tools/Agent/State/StateSet.php +++ b/Mcp/Tools/Agent/State/StateSet.php @@ -81,7 +81,7 @@ class StateSet extends AgentTool // Validate workspace context for tenant isolation $workspaceId = $context['workspace_id'] ?? null; if ($workspaceId === null) { - return $this->error('workspace_id is required for state operations'); + return $this->error('workspace_id is required. Ensure you have authenticated with a valid API key and started a session. See: https://host.uk.com/ai'); } // Query plan with workspace scope to prevent cross-tenant access diff --git a/TODO.md b/TODO.md index d6fed66..78540f9 100644 --- a/TODO.md +++ b/TODO.md @@ -115,10 +115,10 @@ Production-quality task list for the AI agent orchestration package. ### Developer Experience -- [ ] **DX-001: Missing workspace context error messages unclear** +- [x] **DX-001: Missing workspace context error messages unclear** (FIXED 2026-02-23) - Location: Multiple MCP tools - - Issue: "workspace_id is required" doesn't explain how to fix - - Fix: Include context about authentication/session setup + - Issue: "workspace_id is required" didn't explain how to fix + - Fix: Updated error messages in PlanCreate, PlanGet, PlanList, StateSet, StateGet, StateList, SessionStart to include actionable guidance and link to documentation - [ ] **DX-002: AgenticManager doesn't validate API keys on init** - Location: `Services/AgenticManager.php::registerProviders()` -- 2.45.3