diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1a923fad..96c72ef0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,13 +2,9 @@ name: CI on: pull_request: - paths-ignore: - - 'docs/**' push: branches: - main - paths-ignore: - - 'docs/**' jobs: tests: diff --git a/README.md b/README.md index 9346e18b..3308dc20 100644 --- a/README.md +++ b/README.md @@ -55,13 +55,14 @@ Assuming you have an MCP-compatible client ([Claude](https://docs.planexe.org/mc The Tool workflow (tools-only, not MCP tasks protocol) -1. `prompt_examples` -2. `model_profiles` (optional, helps choose `model_profile`) -3. non-tool step: draft/approve prompt -4. `plan_create` -5. `plan_status` (poll every 5 minutes until done) -6. optional if failed: `plan_retry` -7. download the result via `plan_download` or via `plan_file_info` +1. `example_plans` (optional, preview what PlanExe output looks like) +2. `example_prompts` +3. `model_profiles` (optional, helps choose `model_profile`) +4. non-tool step: draft/approve prompt +5. `plan_create` +6. `plan_status` (poll every 5 minutes until done) +7. optional if failed: `plan_retry` +8. download the result via `plan_download` or via `plan_file_info` Concurrency note: each `plan_create` call returns a new `plan_id`; server-side global per-client concurrency is not capped, so clients should track their own parallel plans. diff --git a/docs/mcp/codex.md b/docs/mcp/codex.md index 92c1e6ac..83aeab9d 100644 --- a/docs/mcp/codex.md +++ b/docs/mcp/codex.md @@ -15,7 +15,7 @@ Guide for connecting [codex](https://openai.com/codex/) with PlanExe via MCP. 1. Start Codex. 2. Ask for MCP tools. -3. Call `prompt_examples` to get examples. +3. Call `example_prompts` to get examples. 4. Call `plan_create` to start a plan. ## Sample prompt diff --git a/docs/mcp/inspector.md b/docs/mcp/inspector.md index ef303fe5..882ad0f4 100644 --- a/docs/mcp/inspector.md +++ b/docs/mcp/inspector.md @@ -69,7 +69,8 @@ When connected follow these steps: Now there should be a list with tool names and descriptions: ``` -prompt_examples +example_plans +example_prompts model_profiles plan_create plan_status @@ -83,9 +84,9 @@ When you inspect `plan_create`, the visible input schema includes `prompt` and o Follow these steps: ![screenshot of mcp inspector invoke tool](inspector_step5_mcp_planexe_org.webp) -1. In the `Tools` panel; Click on the `prompt_examples` tool. -2. In the `prompt_examples` right sidepanel; Click on `Run Tool`. -3. The MCP server should respond with a list of example prompts. +1. In the `Tools` panel; Click on the `example_plans` tool to preview example output, or `example_prompts` to see prompt examples. +2. In the right sidepanel; Click on `Run Tool`. +3. The MCP server should respond with example plans or example prompts. 4. Optionally run `model_profiles` to inspect available `model_profile` choices before `plan_create`. ## Approach 2. MCP server inside docker @@ -121,7 +122,7 @@ Then open the `Tools` tab, click `List Tools`. ![Screenshot list tools](inspector_step3_docker.webp) -Click `prompt_examples`, click `Run Tool`. +Click `example_prompts`, click `Run Tool`. ![Screenshot example prompts](inspector_step4_docker.webp) @@ -173,6 +174,6 @@ Then open the `Tools` tab, click `List Tools`. ![Screenshot example prompts](inspector_step3_local.webp) -Click `prompt_examples`, click `Run Tool`. +Click `example_prompts`, click `Run Tool`. ![Screenshot example prompts](inspector_step4_local.webp) diff --git a/docs/mcp/mcp_details.md b/docs/mcp/mcp_details.md index c6649a9a..9344a342 100644 --- a/docs/mcp/mcp_details.md +++ b/docs/mcp/mcp_details.md @@ -14,9 +14,25 @@ This document lists the MCP tools exposed by PlanExe and example prompts for age ## Tool Catalog, `mcp_cloud` -### prompt_examples +### example_plans + +Returns a curated list of example plans with download links for reports and zip bundles. Use this to preview what PlanExe output looks like before creating your own plan. No API key required. + +Example prompt: +``` +Show me example plans. +``` + +Example call: +```json +{} +``` + +Response includes `plans` (array of objects with `title`, `report_url`, `zip_url`) and `message`. + +### example_prompts -Returns around five example prompts that show what good prompts look like. Each sample is typically 300-800 words. Usually the AI does the heavy lifting: the user has a vague idea, the agent calls `prompt_examples`, then expands that idea into a high-quality prompt (300-800 words). A compact prompt shape works best: objective, scope, constraints, timeline, stakeholders, budget/resources, and success criteria. The prompt is shown to the user, who can ask for further changes or confirm it’s good to go. When the user confirms, the agent then calls `plan_create`. Shorter or vaguer prompts produce lower-quality plans. +Returns around five example prompts that show what good prompts look like. Each sample is typically 300-800 words. Usually the AI does the heavy lifting: the user has a vague idea, the agent calls `example_prompts`, then expands that idea into a high-quality prompt (300-800 words). A compact prompt shape works best: objective, scope, constraints, timeline, stakeholders, budget/resources, and success criteria. The prompt is shown to the user, who can ask for further changes or confirm it’s good to go. When the user confirms, the agent then calls `plan_create`. Shorter or vaguer prompts produce lower-quality plans. Example prompt: ``` @@ -56,22 +72,6 @@ Response includes: - `model_count` - `models[]` (`key`, `provider_class`, `model`, `priority`) -### example_plans - -Returns a curated list of example plans with download links for reports and zip bundles. Use this to preview what PlanExe output looks like before creating your own plan. No API key required. - -Example prompt: -``` -Show me example plans. -``` - -Example call: -```json -{} -``` - -Response includes `plans` (array of objects with `title`, `report_url`, `zip_url`) and `message`. - ### plan_create Create a new plan. @@ -266,9 +266,23 @@ Special case: ## Typical Flow -### 1. Get example prompts +### 1. Preview example plans (optional) + +Call `example_plans` to see curated example plans with download links, so you can preview what PlanExe output looks like before creating your own plan. + +Prompt: +``` +Show me example plans. +``` + +Tool call: +```json +{} +``` + +### 2. Get example prompts -The user often starts with a vague idea. The AI calls `prompt_examples` first to see what good prompts look like (around five samples, typically 300-800 words each), then expands the user’s idea into a high-quality prompt using this compact shape: objective, scope, constraints, timeline, stakeholders, budget/resources, and success criteria. +The user often starts with a vague idea. The AI calls `example_prompts` first to see what good prompts look like (around five samples, typically 300-800 words each), then expands the user’s idea into a high-quality prompt using this compact shape: objective, scope, constraints, timeline, stakeholders, budget/resources, and success criteria. Prompt: ``` @@ -280,7 +294,7 @@ Tool call: {} ``` -### 2. Inspect model profiles (optional but recommended) +### 3. Inspect model profiles (optional but recommended) Prompt: ``` @@ -292,11 +306,11 @@ Tool call: {} ``` -### 3. Draft and approve the prompt (non-tool step) +### 4. Draft and approve the prompt (non-tool step) At this step, the agent writes a high-quality prompt draft (typically 300-800 words, with objective, scope, constraints, timeline, stakeholders, budget/resources, and success criteria), shows it to the user, and waits for approval. -### 4. Create a plan +### 5. Create a plan The user reviews the prompt and either asks for further changes or confirms it’s good to go. When the user confirms, the agent calls `plan_create` with that prompt. @@ -305,7 +319,7 @@ Tool call: {"prompt": "..."} ``` -### 5. Get status +### 6. Get status Prompt: ``` @@ -324,7 +338,7 @@ Tool call: {"plan_id": "", "model_profile": "baseline"} ``` -### 6. Download the report +### 7. Download the report Prompt: ``` diff --git a/docs/mcp/mcp_setup.md b/docs/mcp/mcp_setup.md index 82662912..03dac784 100644 --- a/docs/mcp/mcp_setup.md +++ b/docs/mcp/mcp_setup.md @@ -23,12 +23,13 @@ This is the shortest path to a working PlanExe MCP integration. ## 2. Minimal tool usage -1. `prompt_examples` -2. `model_profiles` -3. `plan_create` -4. `plan_status` -5. `plan_retry` (optional, only for failed plans) -6. `plan_file_info` +1. `example_plans` (optional, preview example output) +2. `example_prompts` +3. `model_profiles` +4. `plan_create` +5. `plan_status` +6. `plan_retry` (optional, only for failed plans) +7. `plan_file_info` Optional local helper: - `plan_download` (provided by `mcp_local`, not `mcp_cloud`) diff --git a/docs/mcp/planexe_mcp_interface.md b/docs/mcp/planexe_mcp_interface.md index 2a4b42c1..6f020d79 100644 --- a/docs/mcp/planexe_mcp_interface.md +++ b/docs/mcp/planexe_mcp_interface.md @@ -8,14 +8,14 @@ PlanExe is a service that generates **strategic project-plan drafts** from a nat ### 1.2 What kind of plan does it create -The plan is a **project plan**: a DAG of steps (Luigi pipeline stages) that produce artifacts including a Gantt chart, risk analysis, and other project management deliverables. The main output is a self-contained interactive HTML report (~700KB) with collapsible sections, interactive Gantt charts, and embedded JavaScript. The report contains 20+ sections including executive summary, investor pitch, project plan with SMART criteria, strategic decision analysis, scenario comparison, assumptions with expert review, governance structure, SWOT analysis, team role profiles, simulated expert criticism, work breakdown structure, plan review, Q&A, premortem with failure scenarios, self-audit checklist, and adversarial premise attacks. There is also a zip file containing all intermediary pipeline files (md, json, csv) that fed the report. Plan quality depends on prompt quality; use the prompt_examples tool to see the baseline before calling plan_create. +The plan is a **project plan**: a DAG of steps (Luigi pipeline stages) that produce artifacts including a Gantt chart, risk analysis, and other project management deliverables. The main output is a self-contained interactive HTML report (~700KB) with collapsible sections, interactive Gantt charts, and embedded JavaScript. The report contains 20+ sections including executive summary, investor pitch, project plan with SMART criteria, strategic decision analysis, scenario comparison, assumptions with expert review, governance structure, SWOT analysis, team role profiles, simulated expert criticism, work breakdown structure, plan review, Q&A, premortem with failure scenarios, self-audit checklist, and adversarial premise attacks. There is also a zip file containing all intermediary pipeline files (md, json, csv) that fed the report. Plan quality depends on prompt quality; use the example_prompts tool to see the baseline before calling plan_create. #### 1.2.1 Agent-facing summary (for server instructions / tool descriptions) Implementors should expose the following to agents so they understand what PlanExe does: - **What:** PlanExe turns a plain-English goal into a strategic project-plan draft (20+ sections) in ~10–20 min. Sections include executive summary, interactive Gantt charts, investor pitch, SWOT, governance, team profiles, work breakdown, scenario comparison, expert criticism, and adversarial sections (premortem, self-audit, premise attacks) that stress-test the plan. The output is a draft to refine, not an executable or final document — but it surfaces hard questions the prompter may not have considered. -- **Required interaction order:** Call `prompt_examples` first. Optional before `plan_create`: call `model_profiles` to inspect profile guidance and available models in each profile. Then complete a non-tool step: formulate a detailed prompt as flowing prose (not structured markdown), typically ~300-800 words, using the examples as a baseline; include objective, scope, constraints, timeline, stakeholders, budget/resources, and success criteria; get user approval. Only after approval, call `plan_create`. Then poll `plan_status` (about every 5 minutes); use `plan_download` (mcp_local helper) or `plan_file_info` (mcp_cloud tool) when complete (`pending`/`processing` = keep polling, `completed` = download now, `failed` = terminal). If a plan fails and the caller wants another attempt for the same `plan_id`, call `plan_retry` (optional `model_profile`, default `baseline`). To stop, call `plan_stop` with the `plan_id` from `plan_create`. +- **Required interaction order:** Call `example_plans` (optional) and `example_prompts` first. Optional before `plan_create`: call `model_profiles` to inspect profile guidance and available models in each profile. Then complete a non-tool step: formulate a detailed prompt as flowing prose (not structured markdown), typically ~300-800 words, using the examples as a baseline; include objective, scope, constraints, timeline, stakeholders, budget/resources, and success criteria; get user approval. Only after approval, call `plan_create`. Then poll `plan_status` (about every 5 minutes); use `plan_download` (mcp_local helper) or `plan_file_info` (mcp_cloud tool) when complete (`pending`/`processing` = keep polling, `completed` = download now, `failed` = terminal). If a plan fails and the caller wants another attempt for the same `plan_id`, call `plan_retry` (optional `model_profile`, default `baseline`). To stop, call `plan_stop` with the `plan_id` from `plan_create`. - **Output:** Self-contained interactive HTML report (~700KB) with collapsible sections and interactive Gantt charts — open in a browser. The zip contains the intermediary pipeline files (md, json, csv) that fed the report. ### 1.3 Scope of this document @@ -73,7 +73,7 @@ The MCP specification defines two different mechanisms: - **MCP tools** (e.g. plan_create, plan_status, plan_stop, plan_retry): the server exposes named tools; the client calls them and receives a response. PlanExe's interface is **tool-based**: the agent calls plan_create → receives plan_id → polls plan_status → optionally calls plan_retry on failed → uses plan_file_info (and optionally plan_download via mcp_local). This document specifies those tools. - **MCP tasks protocol** ("Run as task" in some UIs): a separate mechanism where the client can run a tool "as a task" using RPC methods such as tasks/run, tasks/get, tasks/result, tasks/cancel, tasks/list, so the tool runs in the background and the client polls for results. -PlanExe **does not** use or advertise the MCP tasks protocol. Implementors and clients should use the **tools only**. Do not enable "Run as task" for PlanExe; many clients (e.g. Cursor) and the Python MCP SDK do not support the tasks protocol properly. Intended flow: call `prompt_examples`; optionally call `model_profiles`; perform the non-tool prompt drafting/approval step; call `plan_create`; poll `plan_status`; if failed call `plan_retry` (optional); then call `plan_file_info` (or `plan_download` via mcp_local) when completed. +PlanExe **does not** use or advertise the MCP tasks protocol. Implementors and clients should use the **tools only**. Do not enable "Run as task" for PlanExe; many clients (e.g. Cursor) and the Python MCP SDK do not support the tasks protocol properly. Intended flow: optionally call `example_plans`; call `example_prompts`; optionally call `model_profiles`; perform the non-tool prompt drafting/approval step; call `plan_create`; poll `plan_status`; if failed call `plan_retry` (optional); then call `plan_file_info` (or `plan_download` via mcp_local) when completed. --- @@ -155,9 +155,9 @@ The public MCP `state` field is aligned with `PlanItem.state`: All tool names below are normative. -### 6.1 prompt_examples +### 6.1 example_prompts -**Call this first.** Returns example prompts that define the baseline for what a good prompt looks like. Do not call plan_create yet. Correct flow: call this tool; optionally call `model_profiles`; then complete a non-tool step (draft and approve a detailed prompt, typically ~300-800 words); only then call `plan_create`. If you call `plan_create` before formulating and approving a prompt, the resulting plan will be lower quality than it could be. +**Call this first.** Returns example prompts that define the baseline for what a good prompt looks like. Do not call plan_create yet. Correct flow: optionally call `example_plans`; call this tool; optionally call `model_profiles`; then complete a non-tool step (draft and approve a detailed prompt, typically ~300-800 words); only then call `plan_create`. If you call `plan_create` before formulating and approving a prompt, the resulting plan will be lower quality than it could be. Write the prompt as flowing prose, not structured markdown with headers or bullet lists. Weave technical specs, constraints, and targets naturally into sentences. Include banned words/approaches and governance structure inline. Typical length: 300–800 words. The examples demonstrate this prose style — match their tone and density. @@ -213,7 +213,7 @@ Use the returned `profile` values directly in `plan_create.model_profile`. ### 6.2 plan_create -**Call only after prompt_examples and after the non-tool drafting/approval step.** Start creating a new plan with the approved prompt. +**Call only after example_prompts and after the non-tool drafting/approval step.** Start creating a new plan with the approved prompt. **Request** @@ -282,7 +282,7 @@ Use a normal single LLM response (not PlanExe) for one-shot micro-tasks. PlanExe - model_profile: LLM profile (`baseline` | `premium` | `frontier` | `custom`). If unsure, call `model_profiles` first. - user_api_key: user API key for credits and attribution (if your deployment requires it). -Clients can call the MCP tool **prompt_examples** to retrieve example prompts. Use these as examples for plan_create; they can also call plan_create with any prompt—short prompts produce less detailed plans. +Clients can call the MCP tool **example_prompts** to retrieve example prompts. Use these as examples for plan_create; they can also call plan_create with any prompt—short prompts produce less detailed plans. For the full catalog file: diff --git a/docs/proposals/47-openclaw-agent-skill-integration.md b/docs/proposals/47-openclaw-agent-skill-integration.md index 84be3f65..99be3ae6 100644 --- a/docs/proposals/47-openclaw-agent-skill-integration.md +++ b/docs/proposals/47-openclaw-agent-skill-integration.md @@ -55,7 +55,7 @@ OpenClaw Agent "description": "Gives the agent the ability to plan, budget, and track complex projects via the PlanExe Cloud.", "permissions": ["network_access"], "mcp_tools": [ - "prompt_examples", + "example_prompts", "task_create", "task_status", "task_stop", @@ -68,7 +68,7 @@ OpenClaw Agent The PlanExe MCP exposes the following real tools via `https://mcp.planexe.org/mcp`: -### `prompt_examples()` — Get example prompts +### `example_prompts()` — Get example prompts - Input: none - Output: List of example planning prompts @@ -143,7 +143,7 @@ The PlanExe MCP exposes the following real tools via `https://mcp.planexe.org/mc ### Phase A — Skill Packaging and Contracts (1–2 weeks) 1. Define skill manifest and MCP tool bindings: - - `prompt_examples` — Provide example planning prompts + - `example_prompts` — 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 diff --git a/docs/proposals/58-boost-initial-prompt.md b/docs/proposals/58-boost-initial-prompt.md index 4bfd09b2..c511f36c 100644 --- a/docs/proposals/58-boost-initial-prompt.md +++ b/docs/proposals/58-boost-initial-prompt.md @@ -35,7 +35,7 @@ When this happens, later stages can look polished but still be impractical becau There is already a quality gap between two prompt sources: -- MCP tool-driven prompt assembly that follows `prompt_examples` (high structure, better constraints). +- MCP tool-driven prompt assembly that follows `example_prompts` (high structure, better constraints). - Direct human input that is often shorter, incomplete, or inconsistent. This proposal targets that gap by lifting weak human prompts toward the same baseline used in MCP flows. @@ -47,7 +47,7 @@ Why now: - We already have high-quality prompt examples in `worker_plan/worker_plan_api/prompt/data/simple_plan_prompts.jsonl`. - We already document strong prompt shape in `docs/prompt_writing_guide.md`. -- MCP usage already enforces prompt-quality workflow via `docs/mcp/planexe_mcp_interface.md` (`prompt_examples` -> formulate -> `task_create`). +- MCP usage already enforces prompt-quality workflow via `docs/mcp/planexe_mcp_interface.md` (`example_prompts` -> formulate -> `task_create`). - PlanExe already contains assumption-oriented components (`assume/*`) that can consume cleaner input. - The rewrite stage can be bounded, deterministic in structure, and audited with artifacts. @@ -170,7 +170,7 @@ Decision rule: - `worker_plan/worker_plan_api/prompt/data/simple_plan_prompts.jsonl` (including MCP-curated examples) ## MCP Baseline Alignment -Use MCP `prompt_examples` as the reference quality target for rewritten human prompts. +Use MCP `example_prompts` as the reference quality target for rewritten human prompts. Concretely: diff --git a/docs/proposals/62-agent-first-frontend-discoverability.md b/docs/proposals/62-agent-first-frontend-discoverability.md index 857896ae..2a95872e 100644 --- a/docs/proposals/62-agent-first-frontend-discoverability.md +++ b/docs/proposals/62-agent-first-frontend-discoverability.md @@ -32,7 +32,7 @@ This section records what is currently implemented in the repository and what st - `public/llms.txt` now reflects current production guidance: - MCP endpoint is `/mcp` (not `/sse`) - MCP auth uses `X-API-Key` - - Tool names match current MCP tools (`prompt_examples`, `task_create`, `task_status`, `task_stop`, `task_file_info`) + - Tool names match current MCP tools (`example_prompts`, `task_create`, `task_status`, `task_stop`, `task_file_info`) - Pricing/cost docs point to `https://docs.planexe.org/costs_and_models/` - Support contact includes Discord: `https://planexe.org/discord` - Current positioning is documented: @@ -88,14 +88,14 @@ PlanExe turns broad goals into structured strategic-plan drafts and downloadable ## MCP Tools -- prompt_examples +- example_prompts - task_create - task_status - task_stop - task_file_info Recommended flow: -1) prompt_examples +1) example_prompts 2) task_create 3) task_status (poll every 5 minutes) 4) task_file_info @@ -289,7 +289,7 @@ Recommended flow: "name": "PlanExe", "description": "Strategic plan generation via MCP tools", "tools": [ - {"name": "prompt_examples"}, + {"name": "example_prompts"}, {"name": "task_create"}, {"name": "task_status"}, {"name": "task_stop"}, @@ -494,7 +494,7 @@ print(response.output_text) | Tool | Input | Output | Use Case | |------|-------|--------|----------| -| `prompt_examples` | none | prompt samples | Bootstrap high-quality prompts | +| `example_prompts` | none | prompt samples | Bootstrap high-quality prompts | | `task_create` | prompt, speed_vs_detail | task_id | Start plan generation | | `task_status` | task_id | state, progress | Poll long-running execution | | `task_file_info` | task_id, artifact | download metadata/url | Retrieve output files | diff --git a/docs/proposals/70-mcp-interface-evaluation-and-roadmap.md b/docs/proposals/70-mcp-interface-evaluation-and-roadmap.md index 70b495ce..41a834d6 100644 --- a/docs/proposals/70-mcp-interface-evaluation-and-roadmap.md +++ b/docs/proposals/70-mcp-interface-evaluation-and-roadmap.md @@ -25,7 +25,7 @@ Nine tools, split across two transports: | Tool | Cloud (`mcp_cloud`) | Local (`mcp_local`) | Auth | Annotations | | ----------------- | ------------------- | ------------------- | -------- | ----------------------- | -| `prompt_examples` | yes | yes | Public | readOnly, idempotent | +| `example_prompts` | yes | yes | Public | readOnly, idempotent | | `model_profiles` | yes | yes | Public | readOnly, idempotent | | `plan_create` | yes | yes | Required | openWorld | | `plan_status` | yes | yes | Required | readOnly, idempotent | @@ -46,7 +46,7 @@ Nine tools, split across two transports: **Dual transport.** `mcp_cloud` (stateless HTTP / Railway) and `mcp_local` (stdio proxy) cover the two major deployment patterns. Most users can pick one without reading source code. -**Clean module structure.** `mcp_cloud/app.py` is now a thin re-export facade (~195 lines). Logic lives in focused modules: `handlers.py` (tool handlers), `schemas.py` (tool definitions), `tool_models.py` (Pydantic models), `db_queries.py` (DB operations), `auth.py` (key hashing/user resolution), `download_tokens.py` (signed tokens), `model_profiles.py`, `worker_fetchers.py`, `zip_utils.py`, `prompt_examples.py`. This makes PRs reviewable and bugs easy to isolate. +**Clean module structure.** `mcp_cloud/app.py` is now a thin re-export facade (~195 lines). Logic lives in focused modules: `handlers.py` (tool handlers), `schemas.py` (tool definitions), `tool_models.py` (Pydantic models), `db_queries.py` (DB operations), `auth.py` (key hashing/user resolution), `download_tokens.py` (signed tokens), `model_profiles.py`, `worker_fetchers.py`, `zip_utils.py`, `example_prompts.py`. This makes PRs reviewable and bugs easy to isolate. **Consistent `plan_`* naming throughout.** The rename from `task_`* to `plan_*` covers the full stack: external tool names, handler functions, request classes (`PlanCreateRequest`, etc.), DB query helpers (`_create_plan_sync`, `get_plan_by_id`, etc.), local variable names, and test file names. No backward-compat aliases remain. @@ -227,7 +227,7 @@ Outstanding issues: ### 6.4 Example prompt gallery -Add 10–15 high-quality example prompts (startup, research paper, home renovation, hiring plan, …) to `prompt_examples`. Agents and users copy-paste these; each successful use is a social proof data point. +Add 10–15 high-quality example prompts (startup, research paper, home renovation, hiring plan, …) to `example_prompts`. Agents and users copy-paste these; each successful use is a social proof data point. ### 6.5 Observability / social proof diff --git a/mcp_cloud/AGENTS.md b/mcp_cloud/AGENTS.md index 46e4a688..e29473e0 100644 --- a/mcp_cloud/AGENTS.md +++ b/mcp_cloud/AGENTS.md @@ -59,9 +59,9 @@ for AI agents and developer tools to interact with PlanExe. Communicates with - MCP methods: `initialize`, `notifications/initialized`, `tools/list`, `prompts/list`, `resources/list`, `resources/templates/list`, `ping` - Probe compatibility: `GET/HEAD/POST /mcp`, `GET/HEAD /mcp/`, and `GET /mcp/tools` - `tools/call` without API key is allowed **only** for free setup tools: - - `model_profiles` - - `prompt_examples` - `example_plans` + - `example_prompts` + - `model_profiles` - All other tool invocations (for example `plan_create`) must remain API-key protected. - Keep auth-denial logging explicit (`Auth rejected: ...`) with method/path/user-agent and parsed JSON-RPC methods to make Railway debugging easier. diff --git a/mcp_cloud/README.md b/mcp_cloud/README.md index 1928d886..7ca0cfdd 100644 --- a/mcp_cloud/README.md +++ b/mcp_cloud/README.md @@ -14,7 +14,7 @@ mcp_cloud provides a standardized MCP interface for PlanExe's plan generation wo ## Run as task (MCP tasks protocol) -MCP has two ways to run long-running work: **tools** (what we use) and the **tasks** protocol ("Run as task" in some UIs). PlanExe uses **tools only**: `prompt_examples`, `model_profiles`, `plan_create`, `plan_status`, `plan_stop`, `plan_retry`, `plan_file_info` (or `plan_download` via `mcp_local`). The agent creates a task, polls status, retries on failed when needed, then downloads; that is the intended flow per `docs/mcp/planexe_mcp_interface.md`. We do not advertise or implement the MCP tasks protocol (tasks/get, tasks/result, etc.). Clients like Cursor do not support it properly—use the tools directly. +MCP has two ways to run long-running work: **tools** (what we use) and the **tasks** protocol ("Run as task" in some UIs). PlanExe uses **tools only**: `example_plans`, `example_prompts`, `model_profiles`, `plan_create`, `plan_status`, `plan_stop`, `plan_retry`, `plan_file_info` (or `plan_download` via `mcp_local`). The agent creates a task, polls status, retries on failed when needed, then downloads; that is the intended flow per `docs/mcp/planexe_mcp_interface.md`. We do not advertise or implement the MCP tasks protocol (tasks/get, tasks/result, etc.). Clients like Cursor do not support it properly—use the tools directly. Workflow clarity: prompt drafting + user approval is a non-tool step between setup tools and `plan_create`. ## Client Choice Guide @@ -42,7 +42,7 @@ mcp_cloud exposes HTTP endpoints on port `8001` (or `${PLANEXE_MCP_HTTP_PORT}`). - `true`: provide a valid `X-API-Key`. Accepted keys are (1) UserApiKey from home.planexe.org (`pex_...`), or (2) `PLANEXE_MCP_API_KEY` if set (for dev or shared secret). OAuth is not supported for the MCP API. -When auth is enabled, MCP handshake/discovery calls (`initialize`, `notifications/initialized`, `tools/list`, `prompts/list`, `resources/list`, `resources/templates/list`, `ping`, `GET /mcp/tools`, and probe traffic to `/mcp` for redirect/handshake compatibility) are intentionally allowed without API key for connector health checks. In addition, `tools/call` is open without API key only for `model_profiles` and `prompt_examples`; all other tool calls remain protected. +When auth is enabled, MCP handshake/discovery calls (`initialize`, `notifications/initialized`, `tools/list`, `prompts/list`, `resources/list`, `resources/templates/list`, `ping`, `GET /mcp/tools`, and probe traffic to `/mcp` for redirect/handshake compatibility) are intentionally allowed without API key for connector health checks. In addition, `tools/call` is open without API key only for `example_plans`, `example_prompts`, and `model_profiles`; all other tool calls remain protected. ### Connecting via HTTP/URL @@ -138,7 +138,8 @@ mcp_cloud uses the same database configuration as other PlanExe services: See `docs/mcp/planexe_mcp_interface.md` for full specification. Available tools: -- `prompt_examples` - Return example prompts. Use these as examples for plan_create. +- `example_plans` - Return curated example plans with download links for reports and zip bundles. +- `example_prompts` - Return example prompts. Use these as examples for plan_create. - `model_profiles` - List profile options and currently available models in each profile. - `plan_create` - Create a new plan (returns plan_id as UUID; may require user_api_key for credits) - `plan_status` - Get plan status and progress @@ -167,7 +168,7 @@ Note: `plan_download` is a synthetic tool provided by `mcp_local`, not by this s > **Breaking change (v2026-02-26):** External-facing field names were renamed from `task_id` → `plan_id`, `tasks` → `plans`, and error codes from `TASK_NOT_FOUND` → `PLAN_NOT_FOUND`, `TASK_NOT_FAILED` → `PLAN_NOT_FAILED`. -**Tip**: Call `prompt_examples` to get example prompts to use with plan_create, then call `model_profiles` to choose `model_profile` based on current runtime availability. The prompt catalog is the same as in the frontends (`worker_plan.worker_plan_api.PromptCatalog`). When running with `PYTHONPATH` set to the repo root (e.g. stdio setup), the catalog is loaded automatically; otherwise built-in examples are returned. +**Tip**: Call `example_plans` to preview example output, then call `example_prompts` to get example prompts to use with plan_create, then call `model_profiles` to choose `model_profile` based on current runtime availability. The prompt catalog is the same as in the frontends (`worker_plan.worker_plan_api.PromptCatalog`). When running with `PYTHONPATH` set to the repo root (e.g. stdio setup), the catalog is loaded automatically; otherwise built-in examples are returned. Download flow: call `plan_file_info` to obtain the `download_url`, then fetch the report via `GET /download/{plan_id}/030-report.html` (API key required if configured). diff --git a/mcp_cloud/app.py b/mcp_cloud/app.py index 55a517da..b40464eb 100644 --- a/mcp_cloud/app.py +++ b/mcp_cloud/app.py @@ -110,8 +110,8 @@ build_zip_download_path, ) -# -- prompt_examples: example prompt loading ----------------------------------- -from mcp_cloud.prompt_examples import ( # noqa: F401 +# -- example_prompts: example prompt loading ----------------------------------- +from mcp_cloud.example_prompts import ( # noqa: F401 _load_mcp_example_prompts, _builtin_mcp_example_prompts, ) @@ -131,8 +131,8 @@ PLAN_STOP_INPUT_SCHEMA, PLAN_RETRY_INPUT_SCHEMA, PLAN_FILE_INFO_INPUT_SCHEMA, - PROMPT_EXAMPLES_INPUT_SCHEMA, - PROMPT_EXAMPLES_OUTPUT_SCHEMA, + EXAMPLE_PROMPTS_INPUT_SCHEMA, + EXAMPLE_PROMPTS_OUTPUT_SCHEMA, MODEL_PROFILES_INPUT_SCHEMA, MODEL_PROFILES_OUTPUT_SCHEMA, EXAMPLE_PLANS_INPUT_SCHEMA, @@ -147,10 +147,10 @@ from mcp_cloud.handlers import ( # noqa: F401 handle_list_tools, handle_call_tool, - handle_plan_create, - handle_prompt_examples, - handle_model_profiles, handle_example_plans, + handle_example_prompts, + handle_model_profiles, + handle_plan_create, handle_plan_status, handle_plan_stop, handle_plan_retry, diff --git a/mcp_cloud/db_setup.py b/mcp_cloud/db_setup.py index c948da97..78879be8 100644 --- a/mcp_cloud/db_setup.py +++ b/mcp_cloud/db_setup.py @@ -87,9 +87,9 @@ def ensure_planitem_stop_columns() -> None: "Use PlanExe for substantial multi-phase projects with constraints, stakeholders, budgets, and timelines. " "Do not use PlanExe for tiny one-shot outputs (for example: 'give me a 5-point checklist'); use a normal LLM response for that. " "The planning pipeline is fixed end-to-end; callers cannot select individual internal pipeline steps to run. " - "Required interaction order: call prompt_examples first. " + "Required interaction order: call example_plans first (optional, to preview what PlanExe output looks like — curated example reports and zip bundles). " + "Then call example_prompts. " "Optional before plan_create: call model_profiles to see profile guidance and available models in each profile. " - "Optional: call example_plans to preview what PlanExe output looks like (curated example reports and zip bundles). " "Then perform a non-tool step: draft a strong prompt as flowing prose (not structured markdown with headers or bullets), " "typically ~300-800 words, and get user approval. " "Good prompt shape: objective, scope, constraints, timeline, stakeholders, budget/resources, and success criteria. " diff --git a/mcp_cloud/prompt_examples.py b/mcp_cloud/example_prompts.py similarity index 100% rename from mcp_cloud/prompt_examples.py rename to mcp_cloud/example_prompts.py diff --git a/mcp_cloud/handlers.py b/mcp_cloud/handlers.py index 5daad106..2e1766f5 100644 --- a/mcp_cloud/handlers.py +++ b/mcp_cloud/handlers.py @@ -48,7 +48,7 @@ ) from mcp_cloud.model_profiles import _get_model_profiles_sync from mcp_cloud.download_tokens import build_report_download_url, build_zip_download_url -from mcp_cloud.prompt_examples import _load_mcp_example_prompts +from mcp_cloud.example_prompts import _load_mcp_example_prompts from mcp_cloud.schemas import TOOL_DEFINITIONS logger = logging.getLogger(__name__) @@ -162,7 +162,7 @@ async def handle_plan_create(arguments: dict[str, Any]) -> CallToolResult: ) -async def handle_prompt_examples(arguments: dict[str, Any]) -> CallToolResult: +async def handle_example_prompts(arguments: dict[str, Any]) -> CallToolResult: """Return curated prompts from the catalog (mcp_example true) so LLMs can see example detail.""" samples = _load_mcp_example_prompts() payload = { @@ -572,13 +572,13 @@ async def handle_plan_list(arguments: dict[str, Any]) -> CallToolResult: TOOL_HANDLERS = { + "example_plans": handle_example_plans, + "example_prompts": handle_example_prompts, + "model_profiles": handle_model_profiles, "plan_create": handle_plan_create, "plan_status": handle_plan_status, "plan_stop": handle_plan_stop, "plan_retry": handle_plan_retry, "plan_file_info": handle_plan_file_info, "plan_list": handle_plan_list, - "prompt_examples": handle_prompt_examples, - "model_profiles": handle_model_profiles, - "example_plans": handle_example_plans, } diff --git a/mcp_cloud/http_server.py b/mcp_cloud/http_server.py index 3ee22055..9d0f8896 100644 --- a/mcp_cloud/http_server.py +++ b/mcp_cloud/http_server.py @@ -66,7 +66,7 @@ handle_plan_retry, handle_plan_stop, handle_plan_file_info, - handle_prompt_examples, + handle_example_prompts, handle_example_plans, resolve_plan_by_id, set_download_base_url, @@ -170,9 +170,9 @@ def _split_csv_env(value: Optional[str]) -> list[str]: "ping", } PUBLIC_TOOL_CALLS_NO_AUTH = { - "model_profiles", - "prompt_examples", "example_plans", + "example_prompts", + "model_profiles", } @@ -637,7 +637,7 @@ async def plan_create( Field(description="Model profile: baseline, premium, frontier, custom. Call model_profiles to inspect options."), ] = "baseline", ) -> Annotated[CallToolResult, PlanCreateOutput]: - """Create a new PlanExe task. Use prompt_examples first for example prompts.""" + """Create a new PlanExe task. Use example_prompts first for example prompts.""" authenticated_user_api_key = _get_authenticated_user_api_key() arguments: dict[str, Any] = { "prompt": prompt, @@ -682,9 +682,9 @@ async def plan_file_info( return await handle_plan_file_info({"plan_id": plan_id, "artifact": artifact}) -async def prompt_examples() -> CallToolResult: +async def example_prompts() -> CallToolResult: """Return curated example prompts from the catalog (no arguments).""" - return await handle_prompt_examples({}) + return await handle_example_prompts({}) async def model_profiles() -> Annotated[CallToolResult, ModelProfilesOutput]: @@ -710,15 +710,15 @@ async def plan_list( def _register_tools(server: FastMCP) -> None: handler_map = { + "example_plans": example_plans, + "example_prompts": example_prompts, + "model_profiles": model_profiles, "plan_create": plan_create, "plan_status": plan_status, "plan_stop": plan_stop, "plan_retry": plan_retry, "plan_file_info": plan_file_info, "plan_list": plan_list, - "prompt_examples": prompt_examples, - "model_profiles": model_profiles, - "example_plans": example_plans, } for tool in TOOL_DEFINITIONS: handler = handler_map.get(tool.name) diff --git a/mcp_cloud/schemas.py b/mcp_cloud/schemas.py index 44afd001..87e93e0b 100644 --- a/mcp_cloud/schemas.py +++ b/mcp_cloud/schemas.py @@ -5,8 +5,8 @@ from mcp_cloud.tool_models import ( ModelProfilesInput, ModelProfilesOutput, - PromptExamplesInput, - PromptExamplesOutput, + ExamplePromptsInput, + ExamplePromptsOutput, ExamplePlansInput, ExamplePlansOutput, PlanCreateInput, @@ -58,8 +58,8 @@ PLAN_RETRY_INPUT_SCHEMA = PlanRetryInput.model_json_schema() PLAN_FILE_INFO_INPUT_SCHEMA = PlanFileInfoInput.model_json_schema() -PROMPT_EXAMPLES_INPUT_SCHEMA = PromptExamplesInput.model_json_schema() -PROMPT_EXAMPLES_OUTPUT_SCHEMA = PromptExamplesOutput.model_json_schema() +EXAMPLE_PROMPTS_INPUT_SCHEMA = ExamplePromptsInput.model_json_schema() +EXAMPLE_PROMPTS_OUTPUT_SCHEMA = ExamplePromptsOutput.model_json_schema() MODEL_PROFILES_INPUT_SCHEMA = ModelProfilesInput.model_json_schema() MODEL_PROFILES_OUTPUT_SCHEMA = ModelProfilesOutput.model_json_schema() EXAMPLE_PLANS_INPUT_SCHEMA = ExamplePlansInput.model_json_schema() @@ -78,7 +78,24 @@ class ToolDefinition: TOOL_DEFINITIONS = [ ToolDefinition( - name="prompt_examples", + name="example_plans", + description=( + "Returns a curated list of example plans with download links for reports and zip bundles. " + "Use this to preview what PlanExe output looks like before creating your own plan. " + "Especially useful when the user asks what the output looks like before committing to a plan. " + "No API key required." + ), + input_schema=EXAMPLE_PLANS_INPUT_SCHEMA, + output_schema=EXAMPLE_PLANS_OUTPUT_SCHEMA, + annotations={ + "readOnlyHint": True, + "destructiveHint": False, + "idempotentHint": True, + "openWorldHint": False, + }, + ), + ToolDefinition( + name="example_prompts", description=( "Call this first. Returns example prompts that define what a good prompt looks like. " "Do NOT call plan_create yet. Optional before plan_create: call model_profiles to choose model_profile. " @@ -90,8 +107,8 @@ class ToolDefinition: "Then call plan_create. " "PlanExe is not for tiny one-shot outputs like a 5-point checklist; and it does not support selecting only some internal pipeline steps." ), - input_schema=PROMPT_EXAMPLES_INPUT_SCHEMA, - output_schema=PROMPT_EXAMPLES_OUTPUT_SCHEMA, + input_schema=EXAMPLE_PROMPTS_INPUT_SCHEMA, + output_schema=EXAMPLE_PROMPTS_OUTPUT_SCHEMA, annotations={ "readOnlyHint": True, "destructiveHint": False, @@ -115,27 +132,10 @@ class ToolDefinition: "openWorldHint": False, }, ), - ToolDefinition( - name="example_plans", - description=( - "Returns a curated list of example plans with download links for reports and zip bundles. " - "Use this to preview what PlanExe output looks like before creating your own plan. " - "Especially useful when the user asks what the output looks like before committing to a plan. " - "No API key required." - ), - input_schema=EXAMPLE_PLANS_INPUT_SCHEMA, - output_schema=EXAMPLE_PLANS_OUTPUT_SCHEMA, - annotations={ - "readOnlyHint": True, - "destructiveHint": False, - "idempotentHint": True, - "openWorldHint": False, - }, - ), ToolDefinition( name="plan_create", description=( - "Call only after prompt_examples and after you have completed prompt drafting/approval (non-tool step). " + "Call only after example_prompts and after you have completed prompt drafting/approval (non-tool step). " "PlanExe turns the approved prompt into a strategic project-plan draft (20+ sections) in ~10-20 min. " "Sections include: executive summary, interactive Gantt charts, investor pitch, project plan with SMART criteria, " "strategic decision analysis, scenario comparison, assumptions with expert review, governance structure, " diff --git a/mcp_cloud/tests/test_cors_config.py b/mcp_cloud/tests/test_cors_config.py index 998e0f43..7fd3a11b 100644 --- a/mcp_cloud/tests/test_cors_config.py +++ b/mcp_cloud/tests/test_cors_config.py @@ -170,12 +170,12 @@ def test_public_streamable_tools_call_model_profiles(self): result = asyncio.run(http_server._is_public_mcp_request_without_auth(request)) self.assertTrue(result) - def test_public_streamable_tools_call_prompt_examples(self): + def test_public_streamable_tools_call_example_prompts(self): request = _RequestStub( headers={}, method="POST", path="/mcp/", - body=b'{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"prompt_examples","arguments":{}}}', + body=b'{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"example_prompts","arguments":{}}}', ) result = asyncio.run(http_server._is_public_mcp_request_without_auth(request)) self.assertTrue(result) diff --git a/mcp_cloud/tests/test_tool_surface_consistency.py b/mcp_cloud/tests/test_tool_surface_consistency.py index b4c01647..faaaf0d7 100644 --- a/mcp_cloud/tests/test_tool_surface_consistency.py +++ b/mcp_cloud/tests/test_tool_surface_consistency.py @@ -80,17 +80,17 @@ def test_local_plan_retry_schema_defaults_model_profile(self): self.assertEqual(model_profile.get("default"), "baseline") -class TestPromptExamplesAnnotations(unittest.TestCase): - def test_cloud_prompt_examples_annotations(self): - definition = _tool_def(cloud_app.TOOL_DEFINITIONS, "prompt_examples") +class TestExamplePromptsAnnotations(unittest.TestCase): + def test_cloud_example_prompts_annotations(self): + definition = _tool_def(cloud_app.TOOL_DEFINITIONS, "example_prompts") annotations = definition.annotations or {} self.assertTrue(annotations.get("readOnlyHint")) self.assertFalse(annotations.get("destructiveHint")) self.assertTrue(annotations.get("idempotentHint")) self.assertFalse(annotations.get("openWorldHint")) - def test_local_prompt_examples_annotations(self): - definition = _tool_def(local_app.TOOL_DEFINITIONS, "prompt_examples") + def test_local_example_prompts_annotations(self): + definition = _tool_def(local_app.TOOL_DEFINITIONS, "example_prompts") annotations = definition.annotations or {} self.assertTrue(annotations.get("readOnlyHint")) self.assertFalse(annotations.get("destructiveHint")) diff --git a/mcp_cloud/tool_models.py b/mcp_cloud/tool_models.py index b22da7e8..36462f70 100644 --- a/mcp_cloud/tool_models.py +++ b/mcp_cloud/tool_models.py @@ -9,7 +9,7 @@ class ErrorDetail(BaseModel): details: dict[str, Any] | None = None -class PromptExamplesOutput(BaseModel): +class ExamplePromptsOutput(BaseModel): samples: list[str] = Field( ..., description=( @@ -22,7 +22,7 @@ class PromptExamplesOutput(BaseModel): message: str -class PromptExamplesInput(BaseModel): +class ExamplePromptsInput(BaseModel): """No input parameters.""" pass @@ -293,7 +293,7 @@ class PlanCreateInput(BaseModel): ..., description=( "What the plan should cover (goal, context, constraints). " - "Use prompt_examples to get example prompts; use these as examples for plan_create. " + "Use example_prompts to get example prompts; use these as examples for plan_create. " "For best results, provide a detailed prompt (typically ~300-800 words). " "Good prompt shape: objective, scope, constraints, timeline, stakeholders, " "budget/resources, and success criteria. " diff --git a/mcp_local/AGENTS.md b/mcp_local/AGENTS.md index f4e3499c..b7cad61f 100644 --- a/mcp_local/AGENTS.md +++ b/mcp_local/AGENTS.md @@ -6,7 +6,7 @@ to mcp_cloud, a MCP server running in the cloud, over HTTP. ## Interaction model - The local proxy exposes MCP tools over stdio and forwards requests to mcp_cloud using `PLANEXE_URL` (defaults to the hosted `/mcp` endpoint). -- Supported tools: `prompt_examples`, `model_profiles`, `example_plans`, `plan_create`, `plan_status`, `plan_stop`, `plan_retry`, `plan_download`. +- Supported tools: `example_plans`, `example_prompts`, `model_profiles`, `plan_create`, `plan_status`, `plan_stop`, `plan_retry`, `plan_download`. - `plan_download` calls the remote `plan_file_info` tool to obtain a download URL, then downloads the artifact to `PLANEXE_PATH` on the local machine. - `plan_create` visible input schema includes `prompt`, optional `model_profile`, and optional `user_api_key`. diff --git a/mcp_local/README.md b/mcp_local/README.md index f332d976..1d4e39b4 100644 --- a/mcp_local/README.md +++ b/mcp_local/README.md @@ -8,7 +8,8 @@ proxy forwards tool calls over HTTP and downloads artifacts from `/download/{pla ## Tools -`prompt_examples` - Return example prompts. Use these as examples for plan_create. You can also call `plan_create` with any prompt—short prompts produce less detailed plans. +`example_plans` - Return curated example plans with download links for reports and zip bundles. +`example_prompts` - Return example prompts. Use these as examples for plan_create. You can also call `plan_create` with any prompt—short prompts produce less detailed plans. `model_profiles` - Show model_profile options and currently available models in each profile. `plan_create` - Initiate creation of a plan. `plan_status` - Get status and progress about the creation of a plan. @@ -34,7 +35,7 @@ Minimal error contract: - Local proxy specific codes: `REMOTE_ERROR`, `DOWNLOAD_FAILED`. - `plan_file_info` (called under the hood by plan_download) may return `{}` while output is not ready. -**Tip**: Call `prompt_examples` to get example prompts to use with plan_create. The full catalog lives at `worker_plan/worker_plan_api/prompt/data/simple_plan_prompts.jsonl`. +**Tip**: Call `example_plans` to preview example output, then call `example_prompts` to get example prompts to use with plan_create. The full catalog lives at `worker_plan/worker_plan_api/prompt/data/simple_plan_prompts.jsonl`. `plan_download` is a synthetic tool provided by the local proxy. It calls the remote MCP tool `plan_file_info` to obtain a download URL, then downloads the @@ -51,7 +52,7 @@ file locally into `PLANEXE_PATH`. Some MCP clients (e.g. the MCP Inspector) show a **"Run as task"** option for tools. That refers to the MCP **tasks** protocol: a separate mechanism where the client runs a tool in the background using RPC methods like `tasks/run`, `tasks/get`, `tasks/result`, and `tasks/cancel`, instead of a single blocking tool call. -**PlanExe does not use or advertise the MCP tasks protocol.** Our interface is **tool-based** only: the agent calls `prompt_examples` and `model_profiles` for setup, completes a non-tool prompt drafting/approval step, then `plan_create` → gets a `plan_id` → polls `plan_status` → optionally calls `plan_retry` if failed → uses `plan_download`. That flow is defined in `docs/mcp/planexe_mcp_interface.md` and is the intended design. +**PlanExe does not use or advertise the MCP tasks protocol.** Our interface is **tool-based** only: the agent calls `example_plans`, `example_prompts`, and `model_profiles` for setup, completes a non-tool prompt drafting/approval step, then `plan_create` → gets a `plan_id` → polls `plan_status` → optionally calls `plan_retry` if failed → uses `plan_download`. That flow is defined in `docs/mcp/planexe_mcp_interface.md` and is the intended design. You should **not** enable "Run as task" for PlanExe. The Python MCP SDK and clients like Cursor do not properly support the tasks protocol (method registration and initialization fail). Use the tools directly: create a task, poll status, then download when done. diff --git a/mcp_local/planexe_mcp_local.py b/mcp_local/planexe_mcp_local.py index 5b7f8eeb..bad6c613 100644 --- a/mcp_local/planexe_mcp_local.py +++ b/mcp_local/planexe_mcp_local.py @@ -335,7 +335,7 @@ class ToolDefinition: "type": "string", "description": ( "What the plan should cover. Good prompts are often 300–800 words. " - "Use prompt_examples to get example prompts; use these as examples for plan_create. " + "Use example_prompts to get example prompts; use these as examples for plan_create. " "Good prompt shape: objective, scope, constraints, timeline, stakeholders, " "budget/resources, and success criteria. " "Write as flowing prose, not structured markdown. Include banned approaches, " @@ -418,12 +418,12 @@ class ToolDefinition: "required": ["plan_id"], } -PROMPT_EXAMPLES_INPUT_SCHEMA = { +EXAMPLE_PROMPTS_INPUT_SCHEMA = { "type": "object", "properties": {}, "required": [], } -PROMPT_EXAMPLES_OUTPUT_SCHEMA = { +EXAMPLE_PROMPTS_OUTPUT_SCHEMA = { "type": "object", "properties": { "samples": { @@ -634,7 +634,24 @@ class ToolDefinition: TOOL_DEFINITIONS = [ ToolDefinition( - name="prompt_examples", + name="example_plans", + description=( + "Returns a curated list of example plans with download links for reports and zip bundles. " + "Use this to preview what PlanExe output looks like before creating your own plan. " + "Especially useful when the user asks what the output looks like before committing to a plan. " + "No API key required." + ), + input_schema=EXAMPLE_PLANS_INPUT_SCHEMA, + output_schema=EXAMPLE_PLANS_OUTPUT_SCHEMA, + annotations={ + "readOnlyHint": True, + "destructiveHint": False, + "idempotentHint": True, + "openWorldHint": False, + }, + ), + ToolDefinition( + name="example_prompts", description=( "Call this first. Returns example prompts that define what a good prompt looks like. " "Do NOT call plan_create yet. Optional before plan_create: call model_profiles to choose model_profile. " @@ -646,8 +663,8 @@ class ToolDefinition: "Then call plan_create. " "PlanExe is not for tiny one-shot outputs like a 5-point checklist; and it does not support selecting only some internal pipeline steps." ), - input_schema=PROMPT_EXAMPLES_INPUT_SCHEMA, - output_schema=PROMPT_EXAMPLES_OUTPUT_SCHEMA, + input_schema=EXAMPLE_PROMPTS_INPUT_SCHEMA, + output_schema=EXAMPLE_PROMPTS_OUTPUT_SCHEMA, annotations={ "readOnlyHint": True, "destructiveHint": False, @@ -671,27 +688,10 @@ class ToolDefinition: "openWorldHint": False, }, ), - ToolDefinition( - name="example_plans", - description=( - "Returns a curated list of example plans with download links for reports and zip bundles. " - "Use this to preview what PlanExe output looks like before creating your own plan. " - "Especially useful when the user asks what the output looks like before committing to a plan. " - "No API key required." - ), - input_schema=EXAMPLE_PLANS_INPUT_SCHEMA, - output_schema=EXAMPLE_PLANS_OUTPUT_SCHEMA, - annotations={ - "readOnlyHint": True, - "destructiveHint": False, - "idempotentHint": True, - "openWorldHint": False, - }, - ), ToolDefinition( name="plan_create", description=( - "Call only after prompt_examples and after you have completed prompt drafting/approval (non-tool step). " + "Call only after example_prompts and after you have completed prompt drafting/approval (non-tool step). " "PlanExe turns the approved prompt into a strategic project-plan draft (20+ sections) in ~10-20 min. " "Sections include: executive summary, interactive Gantt charts, investor pitch, project plan with SMART criteria, " "strategic decision analysis, scenario comparison, assumptions with expert review, governance structure, " @@ -823,9 +823,9 @@ class ToolDefinition: "Use PlanExe for substantial multi-phase projects with constraints, stakeholders, budgets, and timelines. " "Do not use PlanExe for tiny one-shot outputs (for example: 'give me a 5-point checklist'); use a normal LLM response for that. " "The planning pipeline is fixed end-to-end; callers cannot select individual internal pipeline steps to run. " - "Required interaction order: call prompt_examples first. " + "Required interaction order: call example_plans first (optional, to preview what PlanExe output looks like — curated example reports and zip bundles). " + "Then call example_prompts. " "Optional before plan_create: call model_profiles to see profile guidance and available models in each profile. " - "Optional: call example_plans to preview what PlanExe output looks like (curated example reports and zip bundles). " "Then perform a non-tool step: draft a strong prompt as flowing prose (not structured markdown with headers or bullets), " "typically ~300-800 words, and get user approval. " "Good prompt shape: objective, scope, constraints, timeline, stakeholders, budget/resources, and success criteria. " @@ -923,9 +923,9 @@ async def handle_plan_create(arguments: dict[str, Any]) -> CallToolResult: return _wrap_response(payload) -async def handle_prompt_examples(arguments: dict[str, Any]) -> CallToolResult: +async def handle_example_prompts(arguments: dict[str, Any]) -> CallToolResult: """Return curated prompts from mcp_cloud so LLMs can see example detail.""" - payload, error = _call_remote_tool("prompt_examples", arguments or {}) + payload, error = _call_remote_tool("example_prompts", arguments or {}) if error: return _wrap_response({"error": error}, is_error=True) return _wrap_response(payload) @@ -1083,15 +1083,15 @@ async def handle_plan_list(arguments: dict[str, Any]) -> CallToolResult: TOOL_HANDLERS = { + "example_plans": handle_example_plans, + "example_prompts": handle_example_prompts, + "model_profiles": handle_model_profiles, "plan_create": handle_plan_create, "plan_status": handle_plan_status, "plan_stop": handle_plan_stop, "plan_retry": handle_plan_retry, "plan_download": handle_plan_download, "plan_list": handle_plan_list, - "prompt_examples": handle_prompt_examples, - "model_profiles": handle_model_profiles, - "example_plans": handle_example_plans, } diff --git a/public/llms.txt b/public/llms.txt index 82292579..5c388490 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -63,9 +63,9 @@ MCP Inspector setup guide: ### MCP Tools (Current) The MCP server exposes tool-based workflows (not MCP tasks protocol): -- prompt_examples -- model_profiles - example_plans +- example_prompts +- model_profiles - plan_create - plan_status - plan_stop @@ -97,14 +97,15 @@ Minimal error-handling contract: - `plan_file_info` may return `{}` while artifact output is not ready yet. Recommended interaction order: -1. Call prompt_examples. -2. Optionally call model_profiles to choose model_profile based on current availability. -3. Non-tool step: prepare and approve a strong prompt as flowing prose (not structured markdown), typically ~300-800 words, with objective, scope, constraints, timeline, stakeholders, budget/resources, and success criteria. -4. Call plan_create. -5. Poll plan_status until complete (repeat every 5 minutes). -6. If failed, optionally call plan_retry (defaults to baseline model_profile). -7. Use plan_file_info to get download URLs. -8. Use plan_stop if the run must be cancelled. +1. Optionally call example_plans to preview what PlanExe output looks like. +2. Call example_prompts. +3. Optionally call model_profiles to choose model_profile based on current availability. +4. Non-tool step: prepare and approve a strong prompt as flowing prose (not structured markdown), typically ~300-800 words, with objective, scope, constraints, timeline, stakeholders, budget/resources, and success criteria. +5. Call plan_create. +6. Poll plan_status until complete (repeat every 5 minutes). +7. If failed, optionally call plan_retry (defaults to baseline model_profile). +8. Use plan_file_info to get download URLs. +9. Use plan_stop if the run must be cancelled. Concurrency semantics: - Each plan_create call creates a new task_id. diff --git a/skills/planexe-mcp/SKILL.md b/skills/planexe-mcp/SKILL.md index 13ea108a..d73972aa 100644 --- a/skills/planexe-mcp/SKILL.md +++ b/skills/planexe-mcp/SKILL.md @@ -83,9 +83,30 @@ PLANEXE_API_KEY=your_api_key ## Invoking PlanExe Tools -The PlanExe MCP exposes eight core tools via the `/mcp` endpoint: +The PlanExe MCP exposes nine core tools via the `/mcp` endpoint: -### Tool 1: `prompt_examples` +### Tool 1: `example_plans` + +Preview curated example plans with download links for reports and zip bundles. + +**No parameters required:** + +```json +{ + "jsonrpc": "2.0", + "method": "tools/call", + "params": { + "name": "example_plans", + "arguments": {} + } +} +``` + +**Returns:** List of example plans with `title`, `report_url`, and `zip_url`. + +--- + +### Tool 2: `example_prompts` Get example prompts to understand what PlanExe can do. @@ -96,7 +117,7 @@ Get example prompts to understand what PlanExe can do. "jsonrpc": "2.0", "method": "tools/call", "params": { - "name": "prompt_examples", + "name": "example_prompts", "arguments": {} } } @@ -106,7 +127,7 @@ Get example prompts to understand what PlanExe can do. --- -### Tool 2: `plan_create` +### Tool 3: `plan_create` Create a new planning task. This is the main entry point for generating plans. @@ -136,7 +157,7 @@ Create a new planning task. This is the main entry point for generating plans. --- -### Tool 3: `plan_status` +### Tool 4: `plan_status` Poll the status of a running planning task. @@ -161,7 +182,7 @@ Poll the status of a running planning task. --- -### Tool 4: `plan_stop` +### Tool 5: `plan_stop` Stop a running planning task. @@ -184,7 +205,7 @@ Stop a running planning task. --- -### Tool 5: `model_profiles` +### Tool 6: `model_profiles` Return available model profiles and their guidance before calling `plan_create`. @@ -205,7 +226,7 @@ Return available model profiles and their guidance before calling `plan_create`. --- -### Tool 6: `plan_file_info` +### Tool 7: `plan_file_info` Retrieve download information for completed plan artifacts. @@ -233,7 +254,7 @@ Retrieve download information for completed plan artifacts. --- -### Tool 7: `plan_list` +### Tool 8: `plan_list` List recent tasks for an authenticated user. Useful for recovering a lost `task_id`. @@ -257,7 +278,7 @@ List recent tasks for an authenticated user. Useful for recovering a lost `task_ --- -### Tool 8: `plan_retry` +### Tool 9: `plan_retry` Retry a failed task with an optional upgraded model profile. @@ -283,16 +304,17 @@ Retry a failed task with an optional upgraded model profile. ## Typical Workflow -1. Call `prompt_examples` to understand available planning scenarios -2. Optionally call `model_profiles` to choose an appropriate `model_profile` -3. Formulate your planning prompt -4. Get user approval for the request -5. Call `plan_create` with your prompt and parameters → receives `task_id` -6. Poll `plan_status` every 5+ minutes until status is `completed` or `failed` -7. If `failed`, optionally call `plan_retry` to requeue with a stronger model -8. Call `plan_file_info` with completed `task_id` to get download link -9. Download and use the generated plan -10. If you lose a `task_id`, call `plan_list` with your `user_api_key` to recover it +1. Optionally call `example_plans` to preview what PlanExe output looks like +2. Call `example_prompts` to understand available planning scenarios +3. Optionally call `model_profiles` to choose an appropriate `model_profile` +4. Formulate your planning prompt +5. Get user approval for the request +6. Call `plan_create` with your prompt and parameters → receives `task_id` +7. Poll `plan_status` every 5+ minutes until status is `completed` or `failed` +8. If `failed`, optionally call `plan_retry` to requeue with a stronger model +9. Call `plan_file_info` with completed `task_id` to get download link +10. Download and use the generated plan +11. If you lose a `task_id`, call `plan_list` with your `user_api_key` to recover it Refer to the [PlanExe API documentation](https://planexe.org/docs) for extended examples and advanced use cases.