# MCP Drift State Tracker

MCP server that enforces code completeness, intercepts context erosion, and
neutralizes LLM output degradation across multi-language repository workspaces.

Pure TypeScript. JSON-driven language profiles. Zero Python. Zero runtime bloat.

---

## Author

**Jeremy Anderson** — [dcos.net](https://dcos.net)

## What It Does

LLMs degrade output quality as context windows fill: they drop imports, leave
stub bodies, omit function implementations, and produce structurally incomplete
code. This server provides a real-time audit layer over any MCP-compatible coding
client, flagging those patterns before they persist in the codebase.

### Core Capabilities

- **Multi-language parsing** — 20+ languages supported via data-driven JSON
  profiles. No per-language parser classes.
- **Stub and placeholder detection** — flags `pass`, `TODO`, `FIXME`,
  `raise NotImplementedError`, `undefined`, `return null`, and language-specific
  stub patterns.
- **Import and dependency tracking** — verifies that declared imports
  correspond to symbols used in the file.
- **Structural completeness verification** — confirms that declared classes,
  functions, and interfaces have non-empty bodies.
- **Drift scoring** — assigns a numeric drift score to files and sessions to
  quantify context erosion.
- **State persistence** — writes audit state to `.mcp_drift_state.json` at the
  repository root for cross-session continuity.

## Architecture

The parsing engine is entirely data-driven. A single `index.ts` runtime loads
`language_profiles.json` at startup, compiles all regex patterns once, and
dispatches files to the correct parsing strategy via a flat extension-to-profile
dispatch table. No cascading conditionals. No nested control flow.

```
index.ts                          MCP server runtime
├── language_profiles.json        language definitions, dispatch table, aliases
├── controller_config.json        downstream AI service endpoints
├── mcp_config.json               client integration reference config
└── Makefile                      standardized build and deploy targets
```

### Language Support

| Category | Extensions | Strategy |
|---|---|---|
| C-style / Brace | `.js` `.jsx` `.ts` `.tsx` `.c` `.cpp` `.h` `.hpp` `.java` `.cs` `.kt` `.kts` `.swift` `.dart` `.pike` `.pmod` `.r` | Brace-depth counting via `cStyleDefault` |
| Brace (custom) | `.rs` `.go` `.php` `.hack` `.sh` `.zsh` `.ps1` | Per-language regex overrides in `braceProfiles` |
| Block-end keywords | `.jl` `.lua` `.ex` `.exs` `.adb` `.ads` `.au3` `.vbs` | Start/end keyword pairing with nest-depth increment rules |
| Sequential labels | `.bat` `.cmd` `.sql` | Label-based or statement-delimited flow |
| Indentation-sensitive | `.mojo` `.hs` `.elm` | Signature detection with indent-level body verification |

Duplicate profiles (`.sh`/`.zsh`/`.ps1`, `.ex`/`.exs`, `.adb`/`.ads`,
`.bat`/`.cmd`, `.php`/`.hack`) resolve through the `_aliases` map in
`language_profiles.json`. Adding a new language requires appending one entry
to the dispatch table and restarting the server.

## MCP Tools

| Tool | Purpose |
|---|---|
| `scan_file` | Scan a single source file for drift indicators |
| `scan_workspace` | Recursively scan a workspace directory, respecting `globalIgnoreDirs` |
| `get_drift_report` | Retrieve accumulated drift state and scores |
| `reset_drift_state` | Clear drift state to begin a fresh audit session |

## Requirements

- **Node.js** >= 20.0.0
- **npm** (bundled with Node.js)

## Installation

```bash
git clone https://git.dcos.net/dcosnet/mcp-drift-state-tracker.git
cd mcp-drift-state-tracker
make
```

## Running

```bash
make dev       # development, no compile step
make prod      # compile and run
make inspect   # interactive MCP tool testing via Inspector
```

## Configuration

### `language_profiles.json`

All language-specific regex patterns, stub detectors, file extension routing,
and ignore rules. Validated against the inline `$schema`. Key structure:

- `_dispatch` — flat lookup table mapping every supported extension to its
  profile category and profile key. The runtime resolves extensions in O(1)
  without cascading conditionals.
- `_aliases` — maps duplicate extensions to their canonical profile key.
- `_stubDefaults` — common stub patterns applied to profiles that omit an
  explicit `stubs` array.
- `globalIgnoreDirs` — directories skipped during workspace scans.
- `stateFileName` — per-repo state file name.
- `cStyleDefault` — fallback regex set for brace-matching languages.
- `braceProfiles` / `braceExtensions` — custom overrides and extension lists.
- `blockEndProfiles` — start/end keyword patterns.
- `sequentialProfiles` — label-based flow definitions.
- `indentationProfiles` — indent-sensitive language definitions.

### `controller_config.json`

Downstream AI service endpoints. All ports are integers. All service keys are
lowercase slugs. The `base_dir` follows FHS conventions.

| Service | Port | Purpose |
|---|---|---|
| ollama | 11434 | Local inference engine |
| open-webui | 8080 | Browser-based LLM chat interface |
| aider-web | 8501 | Web frontend for Aider |
| hermes | 8000 | Orchestration proxy |
| odysseus | 7000 | Orchestration proxy |
| dify-engine | 5001 | Workflow automation platform |

### `mcp_config.json`

Client integration reference. Uses `${MCP_TRACKER_PATH}` environment variable
for path resolution — set once, referenced everywhere.

## License

AGPL-3.0 — Copyright (c) 2026 Jeremy Anderson. [dcos.net](https://dcos.net)

## Repository

[https://git.dcos.net/dcosnet/mcp-drift-state-tracker/](https://git.dcos.net/dcosnet/mcp-drift-state-tracker/)