From efd8fb3534bc6b2d3ac3f4dec8746d6367355a79 Mon Sep 17 00:00:00 2001 From: Larry the Laptop Lobster Date: Fri, 20 Feb 2026 21:45:39 -0500 Subject: [PATCH] fix: replace hallucinated MCP tool names with real ones (task_create/task_status/task_stop/task_file_info/prompt_examples) --- .../47-openclaw-agent-skill-integration.md | 72 +++++--- skills/planexe-mcp/SKILL.md | 155 +++++++++++++++--- 2 files changed, 185 insertions(+), 42 deletions(-) diff --git a/docs/proposals/47-openclaw-agent-skill-integration.md b/docs/proposals/47-openclaw-agent-skill-integration.md index cf10df2b1..84be3f65c 100644 --- a/docs/proposals/47-openclaw-agent-skill-integration.md +++ b/docs/proposals/47-openclaw-agent-skill-integration.md @@ -54,38 +54,65 @@ OpenClaw Agent "version": "1.0.0", "description": "Gives the agent the ability to plan, budget, and track complex projects via the PlanExe Cloud.", "permissions": ["network_access"], - "tools": [ - "create_plan", - "check_plan_status", - "get_next_action_item", - "report_result" + "mcp_tools": [ + "prompt_examples", + "task_create", + "task_status", + "task_stop", + "task_file_info" ] } ``` -## Skill Capabilities (Tools) +## Skill Capabilities (MCP Tools) -### `create_plan(goal: str, constraints: list)` +The PlanExe MCP exposes the following real tools via `https://mcp.planexe.org/mcp`: -- Input: goal + constraints -- Output: `plan_id` + plan summary +### `prompt_examples()` — Get example prompts -### `get_next_action_item(plan_id: str)` +- Input: none +- Output: List of example planning prompts +- Used in: Skill initialization and user guidance -- Input: plan ID -- Output: atomic next task +### `task_create(prompt, speed_vs_detail, model_profile, user_api_key?)` — Start a planning task -### `report_result(plan_id: str, task_id: str, output: str)` +- Input: + - `prompt` (string): Natural language planning request + - `speed_vs_detail` (enum): `"ping"` | `"fast"` | `"all"` + - `model_profile` (enum): `"baseline"` | `"premium"` | `"frontier"` | `"custom"` + - `user_api_key` (optional string): Override environment API key +- Output: `task_id` for polling and result retrieval +- Used in: Step 1 of planning workflow -- Input: task output -- Output: plan updated, progress logged +### `task_status(task_id)` — Poll planning progress + +- Input: `task_id` (string) +- Output: status (queued|running|completed|failed), progress %, estimated time remaining +- Used in: Polling loop every 5+ minutes (plans take 15-20+ min) + +### `task_stop(task_id)` — Cancel a running task + +- Input: `task_id` (string) +- Output: Confirmation of cancellation +- Used in: Early termination / user interruption + +### `task_file_info(task_id, artifact)` — Get download link for results + +- Input: + - `task_id` (string) + - `artifact` (enum): `"report"` | `"zip"` +- Output: `download_url` +- Used in: Retrieving completed plans after task finishes ## Agent-to-Agent Protocol - **EdgeBot** detects a local issue (low water). - **EdgeBot** requests a plan from **CloudBot**. -- **CloudBot** generates the plan and sends `plan_id`. -- **EdgeBot** executes local steps and reports back. +- **CloudBot** calls `task_create()` via PlanExe MCP and receives `task_id`. +- **CloudBot** polls `task_status(task_id)` every 5+ minutes. +- **CloudBot** calls `task_file_info(task_id, "report")` to get download URL when complete. +- **EdgeBot** executes local steps from the plan and reports back. +- **CloudBot** can call `task_stop(task_id)` if execution is cancelled. ## Integration Points @@ -115,11 +142,12 @@ OpenClaw Agent ### Phase A — Skill Packaging and Contracts (1–2 weeks) -1. Define skill manifest and tool contracts: - - `create_plan` - - `check_plan_status` - - `get_next_action_item` - - `report_result` +1. Define skill manifest and MCP tool bindings: + - `prompt_examples` — Provide example planning prompts + - `task_create` — Initiate planning task with goal and parameters + - `task_status` — Poll task progress (required for async workflows) + - `task_stop` — Cancel long-running tasks + - `task_file_info` — Retrieve generated plan artifacts 2. Add JSON schema validation for tool inputs/outputs. 3. Version the skill API separately from PlanExe core API. diff --git a/skills/planexe-mcp/SKILL.md b/skills/planexe-mcp/SKILL.md index bb351f19a..1519301ed 100644 --- a/skills/planexe-mcp/SKILL.md +++ b/skills/planexe-mcp/SKILL.md @@ -83,36 +83,151 @@ PLANEXE_API_KEY=your_api_key ## Invoking PlanExe Tools -Once configured, you can invoke PlanExe tools within your OpenClaw workflows: +The PlanExe MCP exposes five core tools via the `/mcp` endpoint: -### Example: Create a Plan +### Tool 1: `prompt_examples` -```openclaw -planexe.create_plan( - title="Project Launch", - description="Q2 product launch planning", - deadline="2026-06-30" -) +Get example prompts to understand what PlanExe can do. + +**No parameters required:** + +```json +{ + "jsonrpc": "2.0", + "method": "tools/call", + "params": { + "name": "prompt_examples", + "arguments": {} + } +} ``` -### Example: Analyze an Existing Plan +**Returns:** List of example prompts for planning tasks. -```openclaw -planexe.analyze_plan( - plan_id="plan_123abc" -) +--- + +### Tool 2: `task_create` + +Create a new planning task. This is the main entry point for generating plans. + +**Parameters:** + +```json +{ + "jsonrpc": "2.0", + "method": "tools/call", + "params": { + "name": "task_create", + "arguments": { + "prompt": "Create a project launch plan for Q2 2026", + "speed_vs_detail": "all", + "model_profile": "premium", + "user_api_key": "your_optional_api_key" + } + } +} ``` -### Example: Run Plan Simulation +**Parameter Guide:** +- `prompt` (required): Your planning request in natural language +- `speed_vs_detail` (required): One of `"ping"`, `"fast"`, or `"all"` + - `"ping"`: Quick outline (~2-5 min) + - `"fast"`: Standard plan (~10-15 min) + - `"all"`: Comprehensive analysis (~20-30+ min) +- `model_profile` (required): One of `"baseline"`, `"premium"`, `"frontier"`, or `"custom"` +- `user_api_key` (optional): Your PlanExe API key (if not set in environment) + +**Returns:** `task_id` for polling status and retrieving results. + +--- + +### Tool 3: `task_status` + +Poll the status of a running planning task. -```openclaw -planexe.simulate_plan( - plan_id="plan_123abc", - iterations=100 -) +**Parameters:** + +```json +{ + "jsonrpc": "2.0", + "method": "tools/call", + "params": { + "name": "task_status", + "arguments": { + "task_id": "task_abc123def456" + } + } +} ``` -Refer to the complete [PlanExe API documentation](https://planexe.org/docs) for all available tools and parameters. +**Usage:** Planning tasks take 15-20+ minutes. Poll every 5+ minutes to check progress. + +**Returns:** Current status (`queued`, `running`, `completed`, `failed`), progress percentage, and estimated time remaining. + +--- + +### Tool 4: `task_stop` + +Stop a running planning task. + +**Parameters:** + +```json +{ + "jsonrpc": "2.0", + "method": "tools/call", + "params": { + "name": "task_stop", + "arguments": { + "task_id": "task_abc123def456" + } + } +} +``` + +**Returns:** Confirmation that the task has been stopped. + +--- + +### Tool 5: `task_file_info` + +Retrieve download information for completed plan artifacts. + +**Parameters:** + +```json +{ + "jsonrpc": "2.0", + "method": "tools/call", + "params": { + "name": "task_file_info", + "arguments": { + "task_id": "task_abc123def456", + "artifact": "report" + } + } +} +``` + +**Artifact Options:** +- `"report"`: Markdown/PDF plan document +- `"zip"`: Complete deliverables package + +**Returns:** `download_url` for accessing the artifact. + +--- + +## Typical Workflow + +1. Call `prompt_examples` to understand available planning scenarios +2. Formulate your planning prompt +3. Get user approval for the request +4. Call `task_create` with your prompt and parameters → receives `task_id` +5. Poll `task_status` every 5+ minutes until status is `completed` or `failed` +6. Call `task_file_info` with completed `task_id` to get download link +7. Download and use the generated plan + +Refer to the [PlanExe API documentation](https://planexe.org/docs) for extended examples and advanced use cases. ## Configuration Reference