Getting started
-Install the server, connect your MCP client, add the bootstrap rule, and run workflows in natural language. You need Node.js 18+ and an MCP client (Cursor, Claude Desktop, Claude Code, or similar). For how the client, server, and workspace fit together, see The pieces on the home page.
+Install the server, set up .engineering in your project, connect your MCP client, add the bootstrap rule, and run workflows in natural language. You need Node.js 18+ and an MCP client (Cursor, Claude Desktop, Claude Code, or similar). For how the client, server, and workspace fit together, see The pieces on the home page.
1. Install and build
# Clone and install
@@ -91,7 +91,14 @@ 1. Install and build
- 2. Configure your MCP client
+ 2. Deploy .engineering to your project
+ Session state lives under your project’s .engineering/artifacts/planning/ tree. From the root of the project you will use as your workspace — not the workflow-server clone — run:
+ curl -O https://raw.githubusercontent.com/m2ux/workflow-server/main/scripts/deploy.sh
+chmod +x deploy.sh
+./deploy.sh
+ The script creates .engineering/ with the artifact directories and workflow submodules the server expects. Commit the submodule entry when it finishes. For deploy modes, options, and updating submodules, see SETUP.md (source).
+
+ 3. Configure your MCP client
Register the server in your client's MCP configuration. For Cursor this is ~/.cursor/mcp.json; for Claude Desktop it is claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\).
{
"mcpServers": {
@@ -105,7 +112,7 @@ 2. Configure your MCP client
}
}
}
- WORKFLOW_WORKSPACE points at the project the server manages sessions for — the repository whose .engineering/artifacts/planning/ folder holds session state. It is required: the server refuses to start without a workspace (you can pass --workspace=PATH as a command-line argument instead). Restart your MCP client after editing the configuration.
+ Set WORKFLOW_WORKSPACE to the project root from step 2. It points at the repository whose .engineering/artifacts/planning/ folder holds session state. It is required: the server refuses to start without a workspace (you can pass --workspace=PATH as a command-line argument instead). Restart your MCP client after editing the configuration.
@@ -120,20 +127,20 @@ 2. Configure your MCP client
- 3. Add the bootstrap rule
+ 4. Add the bootstrap rule
Add this to your IDE's always-applied rule set (a Cursor rule, a Claude Code project rule, or the equivalent in your client):
For any start workflow, create work package, or resume work package request, call the `discover` tool on the workflow-server MCP server to learn the bootstrap procedure. Complete the procedure before any other action.
If the user provides a `session_token`, pass it to subsequent workflow-server calls per their instructions.
Restart your MCP client after adding the rule.
- 4. Verify
+ 5. Verify
Ask your agent:
Use the workflow server to list available workflows
The agent should call list_workflows and return the workflow inventory.
Then ask it to start a work-package workflow. It should call discover first, then proceed through list_workflows, start_session, and get_workflow. If it skips discover, the rule is not applied — recheck your IDE rule configuration.
- 5. Run and resume
+ 6. Run and resume
Drive workflows in natural language — no tool names, no tokens to copy. A work package is the bundled workflow for planning and implementing one unit of work (for example a feature or issue).
Start a workflow by naming the goal:
Start a new work-package workflow for implementing user authentication
@@ -147,7 +154,6 @@ 5. Run and resume
Next steps
- Browse the definitions — a glossary of terms you will encounter across the docs and in workflow runs.
- - Deploying the
.engineering/ pattern into your own project is covered in SETUP.md (source).