144 lines
5.6 KiB
Markdown
Executable File
144 lines
5.6 KiB
Markdown
Executable File
# 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/)
|