# 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

```bash
cd mcp-workflow
npm install
npm run build
```

## Configuration

### Claude Code

Add to `~/.claude/settings.json`:

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

### Codex CLI

Add to `~/.codex/config.toml`:

```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).

```json
{
  "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:

```markdown
## 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

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

## License

MIT