Python MCP Server, Agent driven workflow tracking

[deangoodmanson]

Summary

This PR delivers several major features and improvements to Kruxia Flow:

🤖 MCP Server for AI Agent Integration (NEW)

Complete standalone Python MCP server enabling AI agents (Claude Code, Claude Desktop, custom agents) to orchestrate workflows through the Model Context Protocol.

14 MCP Tools Across 5 Categories:

• Discovery (4 tools): Workflow authoring guide, list definitions, get definition details, list activity types
• Execution (3 tools): Validate workflows, submit workflows, cancel workflows
• Observability (5 tools): Get status, list workflows, get activity output, get costs, estimate costs
• Visualization (2 tools): Render workflow diagrams, render cost breakdowns
• Control (2 tools): Send signals to workflows, list waiting workflows

Key Features:

• Complete workflow authoring guide for agents (YAML structure, template expressions, dependency patterns)
• Client-side workflow validation (syntax, circular dependencies)
• Real-time Mermaid diagram generation with status colors
• Cost estimation and tracking
• Human-in-the-loop support via signals

Documentation:

• MCP Server PRD with full requirements
• Development plan with 13 user stories
• Comprehensive test plan
• User guide with scenarios and decision tree
• 14 individual user story files (US-MCP-1 through US-MCP-14)

Implementation:

• FastMCP-based server with 14 tools
• Pydantic schemas (100% test coverage)
• 29 passing tests (51% overall coverage)
• Uses astral tools (uv, ruff, ty)

---

🐍 Python SDK and Standard Workers

Complete Python SDK for workflow creation and custom worker development, plus pre-built standard workers.

Python SDK Features:

• Pythonic workflow definition API with type safety
• Template expression support ({{INPUT}}, {{activity.output}}, {{SECRET}}, {{WORKFLOW}})
• YAML workflow loading and validation
• Worker SDK for custom activity types
• File-based workflow execution
• Comprehensive error handling

Standard Workers:

• py-std: Universal utilities (httpx, orjson, pydantic, dateutil)
• py-data: ETL/transformation (pandas, polars, duckdb, sqlalchemy)
• py-ml: Training/inference (sklearn, torch, numpy, scipy)
• py-nlp: Text processing (transformers, spacy, tiktoken)

Testing:

• 142 tests covering client, expressions, models, workers
• 96% test coverage
• Integration tests with real API

---

Documentation

New Documentation:

• docs/implementation/mcp-server-prd.md - MCP Server requirements
• docs/implementation/mcp-server-development-plan.md - Implementation plan with user stories
• docs/implementation/mcp-server-test-plan.md - Comprehensive test plan
• docs/implementation/US-MCP-1.md through US-MCP-14.md - Individual user stories
• kruxiaflow-mcp/README.md - MCP server setup and usage

---

---

🤖 Generated with Claude Code

[deangoodmanson]

Let's close this PR, and eventually branch, to re-work the Python MCP server in a different repo, potentially the Python SDK or other Kruxia Flow Utilities repo.