pulse-workflow-mcp CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an MCP (Model Context Protocol) server that enables Claude Code to interact with Pulse workflows. It exposes Pulse workflow operations as MCP tools, allowing workflow creation, node management, edge connections, and publishing.

Development Commands

# Install dependencies (editable mode)
pip install -e ".[dev]"
# or with uv
uv pip install -e ".[dev]"

# Run the server locally
python -m pulse_workflow_mcp

# Run tests
pytest tests/

# Run a single test
pytest tests/test_server.py::TestConfig::test_config_defaults

Environment Variables

export PULSE_API_URL="http://localhost:5001"  # Pulse instance URL
export PULSE_API_KEY="your-api-key"           # Console API key (required)
export PULSE_APP_ID="your-app-id"             # Optional: default app ID

Architecture

src/pulse_workflow_mcp/
├── server.py           # Main MCP server, tool definitions, and call_tool handler
├── dify_client.py      # PulseClient - HTTP client for Pulse API operations
├── config.py           # Configuration via pydantic-settings
├── prompts/            # MCP prompt templates (workflow_context, discovery, etc.)
└── resources/          # MCP resources (workflow state, node type schemas)

Key Components

server.py: Defines all MCP tools (40+ tools) in _get_all_tools() and routes tool calls in call_tool(). Tools are organized into categories:

• App management: list_apps, select_app, create_app
• Node operations: add_node, edit_node, delete_node, batch_add_nodes
• Edge operations: connect_nodes, disconnect_nodes
• Discovery: list_node_types, get_node_schema, list_models, list_datasets
• Workflow: view_workflow, validate_workflow, publish_workflow

dify_client.py: PulseClient class handles all Pulse API communication. Key methods:

• Workflow CRUD via get_workflow(), sync_workflow(), publish_workflow()
• Node/edge manipulation through graph operations
• Auto-initializes workflows for new apps with start node (and LLM+answer for advanced-chat mode)