{"_id":"@eenlars/alive-mcp","name":"@eenlars/alive-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@eenlars/alive-mcp","version":"1.0.0","description":"MCP server for workflow management and execution. Execute Lucky workflows programmatically with status tracking, cancellation, and async/sync execution modes.","type":"module","bin":{"lucky-mcp":"dist/index.js"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc && node -e \"require('fs').chmodSync('dist/index.js', '755')\"","test":"vitest run","test:watch":"vitest","test:endpoints":"node test-endpoints.js","start":"node dist/index.js","start:cloud":"CLOUD_SERVICE=true node dist/index.js","lint":"eslint src/**/*.ts","lint:fix":"eslint src/**/*.ts --fix","format":"prettier --write .","prepare":"npm run build","publish":"npm run build && npm publish","publish-beta":"npm run build && npm publish --tag beta"},"license":"MIT","dependencies":{"dotenv":"^17.2.2","fastmcp":"^3.20.0","typescript":"^5.9.2","zod":"^4.1.5"},"engines":{"node":">=18.0.0"},"keywords":["mcp","workflows","automation","lucky","agent-execution"],"author":{"name":"eenlars"},"bugs":{"url":"https://github.com/eenlars/alive-mcp/issues"},"homepage":"https://github.com/eenlars/alive-mcp#readme","devDependencies":{"@types/node":"^24.3.1","vitest":"^2.1.8"},"_id":"@eenlars/alive-mcp@1.0.0","gitHead":"b5816c9faeb26e74528abafa789c4419f969ed30","_nodeVersion":"20.19.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-yUcc45UOAamWFSCYKo3/q3iLh3usqA5y5HcRGZ45WTcTxznEEsXNEYKUhvmbJfiDCIWNgHjVsby7BAwcbQngUQ==","shasum":"6a8caa5a7d64d3d6ae123ff08ec7f9f7c5ac1f27","tarball":"https://registry.npmjs.org/@eenlars/alive-mcp/-/alive-mcp-1.0.0.tgz","fileCount":5,"unpackedSize":27013,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEIpqzWB5fKOQ72P6tu3waXYyDzNQso91TbEpvjMxTgIAiEA2QY+B5cS4xSx6AzLfCi4ii3SZv8pTAcp1FmO8B9aSmE="}]},"_npmUser":{"name":"eenlars","email":"eedenlars@gmail.com"},"directories":{},"maintainers":[{"name":"eenlars","email":"eedenlars@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/alive-mcp_1.0.0_1760837394627_0.7625189014861233"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-19T01:29:54.505Z","1.0.0":"2025-10-19T01:29:54.851Z","modified":"2025-10-19T01:29:55.161Z"},"maintainers":[{"name":"eenlars","email":"eedenlars@gmail.com"}],"description":"MCP server for workflow management and execution. Execute Lucky workflows programmatically with status tracking, cancellation, and async/sync execution modes.","homepage":"https://github.com/eenlars/alive-mcp#readme","keywords":["mcp","workflows","automation","lucky","agent-execution"],"author":{"name":"eenlars"},"bugs":{"url":"https://github.com/eenlars/alive-mcp/issues"},"license":"MIT","readme":"<div align=\"center\">\n  <a name=\"readme-top\"></a>\n  <h1>@eenlars/mcp</h1>\n  <p>MCP Server for Workflow Management & Execution</p>\n</div>\n\n# Workflow MCP Server\n\nA Model Context Protocol (MCP) server for executing workflows programmatically. Invoke workflows with status tracking, async/sync execution modes, and graceful cancellation.\n\n## Features\n\n- **Workflow Management** - List, execute, and manage workflow invocations\n- **Async/Sync Execution** - Choose between immediate results or long-running async jobs\n- **Status Tracking** - Poll execution status and retrieve results\n- **Graceful Cancellation** - Cancel running workflows with proper cleanup\n- **Error Handling** - Comprehensive error codes and detailed error messages\n- **Flexible Transport** - Support for stdio, SSE, and HTTP streaming modes\n- **Configuration** - Environment variables for custom API endpoints\n\n## Installation\n\n### With npx\n\n```bash\nnpx @eenlars/mcp\n```\n\n### Global Installation\n\n```bash\nnpm install -g @eenlars/mcp\nmcp-workflow\n```\n\n### As a Dependency\n\n```bash\nnpm install @eenlars/mcp\n```\n\n## Configuration\n\n### Environment Variables\n\n#### Required\n\n- `LUCKY_API_KEY` - Your Lucky API key for authentication\n\n#### Optional\n\n- `LUCKY_API_URL` - Custom API endpoint (default: `http://localhost:3000`)\n- `PORT` - Server port for HTTP modes (default: `3000`)\n- `HOST` - Server host (default: `localhost`)\n\n### Running Modes\n\n#### Stdio Mode (Default)\n\n```bash\nexport LUCKY_API_KEY=your-api-key\nnpx @eenlars/mcp\n```\n\n#### HTTP Streaming\n\n```bash\nexport LUCKY_API_KEY=your-api-key\nexport HTTP_STREAMABLE_SERVER=true\nnpx @eenlars/mcp\n# Server runs on http://localhost:3000/mcp\n```\n\n#### SSE Local\n\n```bash\nexport LUCKY_API_KEY=your-api-key\nexport SSE_LOCAL=true\nnpx @eenlars/mcp\n```\n\n## Usage\n\n### Available Tools\n\n#### 1. List Workflows\n\n```json\n{\n  \"name\": \"lucky_list_workflows\",\n  \"arguments\": {}\n}\n```\n\nReturns all workflows available to the authenticated user with metadata:\n- `workflow_id` - Unique identifier\n- `name` - Human-readable name\n- `description` - What the workflow does\n- `inputSchema` - JSONSchema7 for expected input\n- `outputSchema` - JSONSchema7 for output structure\n- `created_at` - Creation timestamp\n\n#### 2. Run Workflow\n\n```json\n{\n  \"name\": \"lucky_run_workflow\",\n  \"arguments\": {\n    \"workflow_id\": \"wf_research_paper\",\n    \"input\": { \"topic\": \"AI Safety\" },\n    \"options\": {\n      \"timeoutMs\": 30000,\n      \"trace\": false\n    }\n  }\n}\n```\n\nExecute a workflow with the given input.\n\n**Execution Modes:**\n- **Sync** (timeoutMs ≤ 30s) - Returns output immediately\n- **Async** (timeoutMs > 30s) - Returns `invocation_id` for polling\n\n**Parameters:**\n- `workflow_id` (required) - From `lucky_list_workflows`\n- `input` (required) - Must match workflow's `inputSchema`\n- `options` (optional)\n  - `timeoutMs` - Max execution time in milliseconds (default: 30000, max: 600000)\n  - `trace` - Enable detailed execution tracing (default: false)\n\n**Response (Sync):**\n```json\n{\n  \"output\": {\n    \"paper\": \"Comprehensive analysis of AI Safety...\",\n    \"citations\": [...]\n  }\n}\n```\n\n**Response (Async):**\n```json\n{\n  \"invocation_id\": \"inv_abc123\",\n  \"state\": \"running\"\n}\n```\n\n#### 3. Check Execution Status\n\n```json\n{\n  \"name\": \"lucky_check_status\",\n  \"arguments\": {\n    \"invocation_id\": \"inv_abc123\"\n  }\n}\n```\n\nCheck the status of a running or completed workflow.\n\n**States:**\n- `running` - Execution in progress\n- `completed` - Finished successfully\n- `failed` - Encountered an error\n- `cancelled` - User cancelled the execution\n- `cancelling` - Cancellation in progress\n- `not_found` - Invalid invocation ID\n\n**Response:**\n```json\n{\n  \"state\": \"completed\",\n  \"invocationId\": \"inv_abc123\",\n  \"createdAt\": \"2025-01-15T10:30:00Z\",\n  \"output\": {\n    \"paper\": \"Comprehensive analysis...\",\n    \"citations\": [...]\n  }\n}\n```\n\n#### 4. Cancel Workflow\n\n```json\n{\n  \"name\": \"lucky_cancel_workflow\",\n  \"arguments\": {\n    \"invocation_id\": \"inv_abc123\"\n  }\n}\n```\n\nRequest cancellation of a running workflow. Cancellation is graceful and may take time to complete.\n\n## Error Codes\n\n| Code | Meaning |\n|------|---------|\n| -32001 | Workflow not found or access denied |\n| -32002 | Input validation failed |\n| -32003 | Workflow execution failed |\n| -32004 | Execution timeout |\n| 401 | Invalid or missing API key |\n| 404 | Workflow or invocation not found |\n\n## Integration Examples\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"workflows\": {\n      \"command\": \"npx\",\n      \"args\": [\"@eenlars/mcp\"],\n      \"env\": {\n        \"LUCKY_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\n1. Open Cursor Settings\n2. Go to Features > MCP Servers\n3. Add new MCP server:\n\n```json\n{\n  \"mcpServers\": {\n    \"workflows\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@eenlars/mcp\"],\n      \"env\": {\n        \"LUCKY_API_KEY\": \"YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n### VS Code\n\nAdd to User Settings (JSON):\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"workflows\": {\n        \"command\": \"npx\",\n        \"args\": [\"-y\", \"@eenlars/mcp\"],\n        \"env\": {\n          \"LUCKY_API_KEY\": \"${input:apiKey}\"\n        }\n      }\n    }\n  }\n}\n```\n\n## Workflow Execution Flow\n\n```\n1. Call lucky_list_workflows to discover available workflows\n   ↓\n2. Review the workflow's inputSchema to understand required input\n   ↓\n3. Call lucky_run_workflow with workflow_id and properly formatted input\n   ↓\n4. If async mode (timeoutMs > 30s):\n   - Receive invocation_id\n   - Poll with lucky_check_status to monitor progress\n   - Retrieve results when state = \"completed\"\n   ↓\n5. Optionally call lucky_cancel_workflow to stop execution\n```\n\n## Development\n\n### Build\n\n```bash\nbun run build\n# or\nnpm run build\n```\n\n### Test\n\n```bash\nbun run test\n# or\nnpm test\n```\n\n### Start Server\n\n```bash\nnpm start                              # Stdio mode\nCLOUD_SERVICE=true npm start          # Cloud mode\nHTTP_STREAMABLE_SERVER=true npm start # HTTP mode\n```\n\n## Publishing\n\n```bash\nnpm run publish              # Publish latest version\nnpm run publish-beta         # Publish beta tag\n```\n\n## License\n\nMIT License - see LICENSE file for details\n\n---\n\n**Need help?** Check the error code table above or consult the integration examples for your editor.\n","readmeFilename":"README.md","_rev":"1-c7e932bec51bcf123078243cfe586fb1"}