MCP Workflow Engine

MCP server that provides AI coding agents with dependency analysis, impact detection, and build verification tools.

Tools Provided

| Tool | Description | |------|-------------| | get_impact | Find all files affected by changes to a file | | get_impact_from_diff | Aggregate impact across a diff or git changeset | | get_dependencies | List what a file imports | | get_graph_stats | Get dependency graph statistics and circular deps | | verify_build | Run build and return pass/fail with errors | | run_typecheck | Run TypeScript type checking | | run_lint | Run linter | | get_relevant_tests | Suggest test files impacted by a change | | run_tests | Run tests (auto-detected if not provided) | | run_relevant_tests | Run only a provided list of tests (uses {tests} placeholder) | | get_contract_impact | Highlight potential API/contract impacts | | chain_effect_checklist | Generate verification checklist for a file type | | multi_file_checklist | Generate checklists for multiple files | | invalidate_graph_cache | Clear cached dependency graph |

Auto-Detection Behavior

Dependency scanning defaults to src, but if it doesn't exist the server auto-detects common source roots (e.g. lib, app, apps, packages, services) and includes common test dirs (test, tests, __tests__, spec, specs) when present.
You can override scanning with scan_dirs, project_root, and ignore_patterns.
Build and test commands auto-detect common ecosystems (Node, Gradle, Maven, .NET, Go, Rust, Python, Make). You can always pass an explicit command.

Installation

cd mcp-workflow
npm install
npm run build

Configuration

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "workflow-engine": {
      "command": "node",
      "args": ["C:/path/to/mcp-workflow/dist/server.js"]
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.workflow-engine]
command = "node"
args = ["C:/path/to/mcp-workflow/dist/server.js"]

Repo Config (`.workflow-engine.json`)

Place this in the repo being analyzed (the project_root). It overrides auto-detection.

Notes:

ignorePatterns are regular expressions matched against normalized paths (e.g. src/foo/bar.ts).
testCommand supports {tests} placeholder for targeted runs.
dependencyCruiserOptions is passed through to dependency-cruiser (advanced use).
contractDirs scopes where contract files are discovered (defaults to common docs/spec folders).

{
  "scanDirs": ["src", "packages"],
  "testDirs": ["tests", "__tests__"],
  "ignorePatterns": ["\\.generated\\.", "^dist/"],
  "contractDirs": ["docs", "spec", "openapi"],
  "buildCommand": "pnpm build",
  "testCommand": "pnpm test -- {tests}",
  "dependencyCruiserOptions": {
    "tsConfig": "tsconfig.json"
  }
}

Usage Examples

Once configured, the agent can call these tools:

Before implementing a change

Agent: I need to modify src/services/user.ts. Let me check the impact.

[Calls get_impact(file="src/services/user.ts", project_root="C:/path/to/project")]

Result:
{
  "file": "src/services/user.ts",
  "directDependents": ["src/controllers/auth.ts", "src/controllers/admin.ts"],
  "transitiveDependents": ["src/routes/api.ts"],
  "associatedTests": ["src/services/__tests__/user.test.ts"],
  "totalImpacted": 3
}

Get verification checklist

Agent: What should I verify for this change?

[Calls chain_effect_checklist(file="src/services/user.ts")]

Result:
{
  "file": "src/services/user.ts",
  "fileType": "Service/Domain",
  "checklist": [
    {"category": "Controllers", "check": "Verify all calling controllers handle new behavior"},
    {"category": "Return Types", "check": "Check if return type changes affect callers"},
    ...
  ]
}

After implementing

Agent: Let me verify the build passes.

[Calls verify_build()]

Result:
{
  "success": true,
  "output": "Build completed successfully",
  "errors": [],
  "duration": 3420
}

Diff-aware impact

Agent: What will this diff impact?

[Calls get_impact_from_diff(cwd="C:/path/to/project")]

Relevant tests + execution

Agent: Which tests should I run?

[Calls get_relevant_tests(files=["src/services/user.ts"], project_root="C:/path/to/project")]

Agent: Run those tests.

[Calls run_relevant_tests(tests=["src/services/__tests__/user.test.ts"], command="pnpm test -- {tests}")]

Contract impact

Agent: Any contract updates needed?

[Calls get_contract_impact(files=["src/controllers/user.ts"], project_root="C:/path/to/project")]

Workflow Integration

Pair with an AGENTS.md file in your repo:

## Required Workflow

### Step 1: Impact Analysis
Before implementing, use `get_impact` to identify all affected files.

### Step 2: Chain-Effect Checklist
Use `chain_effect_checklist` to get verification items for the file type.

### Step 3: Implementation
Make changes across all affected layers.

### Step 4: Build Verification
Use `verify_build` - task is NOT complete unless this returns success.

Development

npm run dev    # Watch mode
npm run build  # Build once
npm start      # Run server

License

MIT

MCP Workflow Engine