MCP-Drift-State-Tracker/BLOG.md

# Integrating MCP Drift State Tracker with Your AI Coding Stack

Integration guides for wiring the tracker into production tooling. All configs
derive from `controller_config.json` and `mcp_config.json` — these reflect the
actual service topology the tracker targets.

---

## 1. Odysseus

Local AI coding orchestration proxy on port 7000 (`controller_config.json`).
Odysseus sits between the LLM backend (Ollama) and the coding frontend,
managing tool calls, context windows, and session state.

Drift tracking is critical here. Odysseus manages long coding sessions where
the LLM iterates on files across dozens of turns. By turn 30, the model drops
imports, leaves `TODO` stubs, and produces structurally incomplete code. The
tracker operates as a post-edit audit gate.

### Config

```json
{
  "mcpServers": {
    "mcp-drift-state-tracker": {
      "command": "node",
      "args": ["${MCP_TRACKER_PATH}/dist/index.js"],
      "env": {
        "MCP_CONTROLLER_PORT": "7000",
        "MCP_CONTROLLER_MODEL": "ollama/llama3"
      }
    }
  }
}
```

### Workflow

Invoke `scan_workspace` on the target directory after each significant edit
cycle. When the drift score exceeds the configured threshold, Odysseus
re-prompts the LLM to correct the flagged files. This creates a closed-loop
quality gate: the model writes code, the tracker audits it, Odysseus feeds the
audit results back into the next generation pass.

### Recommended System Prompt Addition

> After editing more than 5 files in a session, run `get_drift_report` and fix
> every file with a drift score above 0.3 before concluding.

---

## 2. Hermes

Orchestration proxy on port 8000. Hermes handles focused, single-task coding
with strict tool governance.

### Config

```json
{
  "mcpServers": {
    "mcp-drift-state-tracker": {
      "command": "node",
      "args": ["${MCP_TRACKER_PATH}/dist/index.js"],
      "env": {
        "MCP_CONTROLLER_PORT": "8000",
        "MCP_CONTROLLER_MODEL": "ollama/llama3"
      }
    }
  }
}
```

### Workflow

Register `scan_file` as a post-write hook in Hermes's tool registry. Every time
Hermes instructs the LLM to write or modify a file, it immediately follows with
`scan_file` on that path. When stubs or missing imports are detected, Hermes
re-issues the write instruction with the audit feedback appended to the context.

This is lighter-weight than `scan_workspace` and aligns with Hermes's
task-oriented design. Reserve `scan_workspace` for session-end review.

---

## 3. Open WebUI

Browser-based LLM interface on port 8080. Provides Ollama with workspace
management, model selection, and MCP server support via its Functions/Tools
system.

### Config

Navigate to **Admin Settings > Tools > MCP Servers** and add:

| Field | Value |
|---|---|
| Name | `mcp-drift-state-tracker` |
| Command | `node` |
| Args | `${MCP_TRACKER_PATH}/dist/index.js` |

Or add to Open WebUI's `functions.yaml`:

```yaml
mcp_servers:
  mcp-drift-state-tracker:
    command: node
    args:
      - "${MCP_TRACKER_PATH}/dist/index.js"
```

### Workflow

Open WebUI exposes the tracker directly in the chat interface. After the LLM
completes a multi-file change, the user types "check my code for drift" — this
triggers `scan_workspace` via the MCP tool and returns a structured report in
the chat.

### Recommended System Prompt Addition

> After completing any multi-file code change, automatically run
> `scan_workspace` on the project directory and present the drift report.

---

## 4. Claude Desktop / Claude Code

Anthropic's desktop and CLI clients. MCP servers are first-class citizens.

### Config

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mcp-drift-state-tracker": {
      "command": "node",
      "args": ["${MCP_TRACKER_PATH}/dist/index.js"]
    }
  }
}
```

### Workflow

Claude maintains strong context in single-session coding. Drift appears in
long refactoring sessions regardless. Run `scan_file` after each file write and
`scan_workspace` at session end. Claude interprets drift reports and
corrects flagged stubs on the first retry pass.

---

## 5. Cursor / Windsurf / VS Code (Continue.dev)

IDE-native AI coding assistants. Cursor and Windsurf provide built-in MCP
support. Continue.dev adds MCP integration to vanilla VS Code.

### Config (Cursor / Windsurf)

Add to the IDE's MCP settings (`.cursor/mcp.json` or the MCP settings panel):

```json
{
  "mcpServers": {
    "mcp-drift-state-tracker": {
      "command": "node",
      "args": ["${MCP_TRACKER_PATH}/dist/index.js"]
    }
  }
}
```

### Config (Continue.dev)

```json
{
  "mcp": {
    "servers": {
      "mcp-drift-state-tracker": {
        "command": "node",
        "args": ["${MCP_TRACKER_PATH}/dist/index.js"]
      }
    }
  }
}
```

### Workflow

IDE integrations provide the tightest feedback loop. When the AI assistant
writes a file, configure a post-save hook to run `scan_file` on the current
buffer. Drift results appear inline or in a side panel. Incomplete code is
catched before it enters version control.

---

## 6. Dify Engine

Workflow automation platform for LLM applications on port 5001. Dify builds
multi-step AI pipelines with conditional branching, tool calls, and
human-in-the-loop stages.

### Integration Method

Dify does not consume MCP servers natively. Wrap the tracker as an external
tool via Dify's **API Tool** node.

1. Host the tracker as a persistent process:
   ```bash
   node ${MCP_TRACKER_PATH}/dist/index.js
   ```
2. In Dify, create an **HTTP Request** tool node targeting the tracker's MCP
   transport endpoint. Stdio-based servers require an adapter such as
   `mcp-proxy` to expose them over HTTP.
3. Alternatively, define a Dify **Function Tool** that shells out to the tracker:
   ```python
   import subprocess
   import json

   def scan_workspace(path: str) -> dict:
       result = subprocess.run(
           ["node", "${MCP_TRACKER_PATH}/dist/index.js"],
           input=json.dumps({"tool": "scan_workspace", "arguments": {"path": path}}),
           capture_output=True,
           text=True
       )
       return json.loads(result.stdout)
   ```

### Workflow

Place the drift check as a conditional gate between the **Code Generation** step
and the **Output / Commit** step. When `scan_workspace` returns a drift score
above the configured threshold, route back to the generation step with the
audit feedback injected into the prompt. This creates an automated quality loop
without human intervention.

---

## 7. Aider

Terminal-based AI pair programmer with MCP support.

### Config

CLI flag:

```bash
aider --mcp-server "mcp-drift-state-tracker:node:${MCP_TRACKER_PATH}/dist/index.js"
```

Or in `.aider.conf.yml`:

```yaml
mcp-servers:
  mcp-drift-state-tracker:
    command: node
    args: ["${MCP_TRACKER_PATH}/dist/index.js"]
```

### Workflow

Aider operates in long terminal sessions with large repos and is prone to
context erosion. The tracker catches semantic incompleteness that static
linters miss — a function that compiles but contains a `pass` body, for
example. Run `scan_file` on every file Aider touches. Run `scan_workspace`
every 10 commits to catch drift in files the model edited earlier in the
session.

---

## 8. Cline (VS Code Extension)

Autonomous AI coding agent for VS Code. Creates files, runs commands, and
manages entire development tasks.

### Config

```json
{
  "mcpServers": {
    "mcp-drift-state-tracker": {
      "command": "node",
      "args": ["${MCP_TRACKER_PATH}/dist/index.js"]
    }
  }
}
```

### Workflow

Cline's autonomy makes drift tracking essential. A single task like "implement
user authentication across the backend" creates 8-10 files in one run.
Configure Cline to run `scan_workspace` as its final step before marking a task
complete. Files with high drift scores are flagged for a correction pass.

---

## Scan Strategy

| Trigger | Tool | Rationale |
|---|---|---|
| After every file edit | `scan_file` | Immediate feedback, lowest latency |
| After multi-file refactor | `scan_workspace` | Catches cross-file drift |
| Session end | `get_drift_report` | Summary for human review |
| New session start | `get_drift_report` | Establishes baseline from prior state |
| Pre-commit | `scan_workspace` | Quality gate on every commit |

## Extending Language Profiles

Add project-specific stub patterns to the relevant language profile's `stubs`
array in `language_profiles.json`:

```json
".ts": {
  "stubs": ["pass", "TODO", "FIXME", "throw new Error(\"not implemented\")", "// @ts-ignore"]
}
```

## Relationship to Static Analysis

The tracker does not replace ESLint, Ruff, Clippy, or any static analysis tool.
It targets a distinct failure class: semantic incompleteness that compiles but
represents degraded LLM output. Run static analysis for correctness. Run drift
tracking for completeness. Both are necessary.

---

All integration configs reference the service ports and model names from
`controller_config.json`. Set `MCP_TRACKER_PATH` to the absolute path of this
repository and all configs resolve correctly.