PromptCraft

PromptCraft is an MCP-first, stage-aware prompt engineering assistant.

It is not a Python string-concatenation prompt generator, an executor model, or a full Agent framework. PromptCraft provides Skill rules, stage memory, context compression, and routing guidance to the MCP host model. The host model then uses that instruction bundle to write the final prompt.

Primary Usage: MCP

Install the package from this repository:

pip install .

Configure your MCP host with the stdio server:

{
  "mcpServers": {
    "promptcraft": {
      "command": "python",
      "args": ["-m", "promptcraft.mcp_server"]
    }
  }
}

After that, use natural language in Codex, Cursor, Claude Code, Windsurf, or another MCP host:

Please call PromptCraft and generate a stage-level advanced prompt for the current task.

PromptCraft will detect the stage event, select a Skill, read compact memory, hydrate only business-relevant context, and return a prompt generation instruction bundle for the host model.

MCP Tools

PromptCraft exposes eight public tools:

promptcraft_generate_prompt: generate a stage-level prompt instruction bundle.
promptcraft_generate_repair_prompt: generate a lightweight in-stage repair bundle.
promptcraft_select_skill: select the best Skill without generating a bundle.
promptcraft_start_stage: archive the previous stage and start a new one.
promptcraft_compact_context: return a host compaction instruction bundle for raw stage text, or normalize already structured StageMemory.
promptcraft_get_memory: read task and stage memory.
promptcraft_update_memory: update task-level or stage-level memory.
promptcraft_list_skills: list the bundled Skills and use cases.

Typical input:

{
  "task_id": "demo",
  "user_request": "Generate an advanced prompt for the experiment-analysis stage.",
  "output_format": "Chinese academic experiment-analysis section",
  "stage_hint": "auto",
  "skill": "auto"
}

To save MCP-generated prompt bundles into task-specific folders, pass save_prompt and optionally output_dir:

{
  "task_id": "router-audit",
  "user_request": "Audit router edge cases",
  "save_prompt": true,
  "output_dir": "outputs"
}

This writes to outputs/router-audit/prompt.md and saves task state beside it as outputs/router-audit/state.json. If output_dir is omitted while save_prompt is true, outputs is used by default. Repeated generations for the same task create timestamped prompt files in the same task folder.

Typical response shape:

{
  "event": "NEW_STAGE",
  "selected_skill": "step-back",
  "memory_summary": {},
  "visible_context": {},
  "instruction_bundle": {},
  "host_generation_guidance": "..."
}

Generation responses do not expose raw routing metadata or the full internal context packet. Only the business context needed by the host model is returned.

Core Design

User interaction is natural language through MCP.
Python is the implementation language, not the primary user interface.
PromptCraft does not call an external model by default in v1.
The final prompt is generated by the MCP host model from the instruction bundle.
Stage memory stores compact summaries, not full chat history.
Advanced Skills are used for task starts and stage switches; in-stage repair stays lightweight.

Skills

PromptCraft includes seven prompt-engineering Skills:

zero-shot
few-shot
zero-shot-cot
few-shot-cot
step-back
least-to-most
tree-of-thought

Developer CLI

The CLI is kept for local debugging and tests. It is not the primary user experience.

python -m promptcraft generate --task "Extract action items" --output-format "JSON" --json
python -m promptcraft compress examples\minimal_task.json

For cleaner multi-task runs, write prompts into task-specific folders:

python -m promptcraft generate --task "Audit router edge cases" --task-id router-audit --out-dir outputs

This writes to outputs/router-audit/prompt.md. If the same task is generated again without --append, PromptCraft creates a timestamped prompt file in the same task folder instead of overwriting the existing prompt. When --out-dir is used with a task id and no explicit --state-store, the task state is saved beside the prompt as outputs/router-audit/state.json.

Generated scratch artifacts can be removed after a prompt is produced by passing explicit cleanup paths:

python -m promptcraft generate --task "Extract action items" --cleanup-after-generate --cleanup-path generated_tests --cleanup-path draft_skill\SKILL.md

The same behavior is available through MCP with cleanup_after_generate: true and cleanup_paths: [...]. Cleanup is skipped when no prompt is generated.

The generated prompt in CLI output is a developer-facing MCP instruction bundle preview, not a guarantee that PromptCraft executed the user task.

Windows Development

PowerShell, Python, and JSON tooling can disagree about encodings when the project path contains Chinese characters or spaces. Before running ad hoc local debugging commands, set the current PowerShell session to UTF-8:

chcp 65001
$env:PYTHONIOENCODING="utf-8"
$env:PYTHONUTF8="1"

You can also dot-source the helper script from the repository root:

. .\scripts\windows_dev_env.ps1

Avoid pasting long multi-line python -c "..." snippets from web pages or chat tools into PowerShell. They can contain hidden non-breaking spaces (\xa0) that PowerShell and Python do not parse as normal spaces. Prefer putting temporary debugging code in a small .py file and running python temp_debug.py.

For the least surprising Windows development experience, use a short ASCII workspace path such as C:\workspace\PromptCraft.

See examples/mcp_usage.md for a short MCP integration note.

Compact Context Flow

promptcraft_compact_context keeps the v1 boundary honest: PromptCraft does not do semantic summarization with local Python rules. If the tool receives raw stage notes or conversation text, it returns NEEDS_HOST_COMPACTION plus a compaction instruction bundle. The MCP host model should use that bundle to produce clean stage_memory JSON, then call promptcraft_update_memory.

If the tool receives already structured stage fields, it returns READY_FOR_MEMORY_UPDATE with normalized and deduplicated stage_memory plus a ready-to-use next_tool_call.

MCP Servers