ark-self-recon

ark-self-recon — runtime self-diagnostic for MCP servers

Self-recon: a health-check function that tells you whether your MCP server's state is healthy, degraded, or critical — cacache or JSONL, single call.

Why

The problem. MCP servers store state in cacache caches, JSONL files, and WAL journals. Over hours or days, caches go stale, WAL files accumulate uncheckpointed writes, and orphan files drift in without being flagged. There is no built-in health check for any of it — operators discover degraded state only when something breaks.

Why now. As the ark-* MCP fleet grows and state stores multiply, manual inspection doesn't scale. A single selfRecon() call replaces ad-hoc checks with a scored, actionable report — making per-server health as routine as a heartbeat.

What it does. Zero-config scan that detects state type (cacache vs JSONL), measures freshness against configurable TTL, and returns a scored report with warnings. Drop it into any MCP server for an instant diagnostic endpoint.

Who it's for

• MCP server maintainers — add a self-recon tool to any server with one import
• Platform operators — fleet health checks across multiple MCP servers
• AI agent evaluators — verify tool state health before or after invocation

Standalone use case: point it at any cacache directory or JSONL state folder — no ark-* server required.

Quick Start

npm install ark-self-recon

import { selfRecon } from "ark-self-recon";

const report = await selfRecon("/path/to/state");
console.log(report.health.score);     // 0-100
console.log(report.health.status);    // "good" | "degraded" | "critical"
console.log(report.health.warnings);  // string[]

Use case — JSONL state-store with WAL detection (operator role):

const report = await selfRecon("/path/to/jsonl-dir", { kind: "state-store" });
console.log(report.snapshot.walPending);  // uncheckpointed journal count

Developer persona — raw scan (no scoring) for custom health logic, easy adoption into existing tooling:

import { scan, scanCache, scanStateDir } from "ark-self-recon/core";
const snapshot = await scanCache("/path/to/cacache");
console.log(snapshot.staleRatio, snapshot.avgFreshnessS);

Architecture

Two-phase pipeline — call selfRecon(dir) or compose the stages yourself:

  selfRecon(dir)
    ├── detectTarget(dir) → { type, path }
    ├── scan[Cache|StateDir](path) → snapshot
    └── score[Health|StateDir](snapshot) → health

• scan: reads cacache entries via stream (no full load into memory), or walks JSON/JSONL files detecting .journal WAL signals
• score: weighs entries against staleness TTL (default 7d), flags orphan files, returns 0-100 score with typed warnings

Configuration

Param	Type	Default	Description
kind	"cache" | "state-store"	"cache"	Forces state-store mode for JSONL/WAL directories
stalenessMs	number	604800000 (7d)	TTL for cacache staleness detection
walThreshold	number	5	Pending WAL files before warning
expected	string[]	[]	Expected state files (orphan detection)

Export surface

Import path	Contents
ark-self-recon	Curated top-level: selfRecon, scanCache, scoreHealth
ark-self-recon/core	Full API: scan, scanCache, scanStateDir, detectTarget, scoreHealth, scoreStateDir, selfRecon
ark-self-recon/scanner	Internal: scanCache, scanStateDir, detectTarget
ark-self-recon/scorer	Internal: scoreHealth, scoreStateDir
ark-self-recon/benchmark	Benchmark: runBenchmark, runChainBench, selfReconBench, predictFailures

Benchmark integration

Consumer projects use the benchmark module for predictions and performance measurement.

Prediction engine — ark-delegator wraps predict with server-specific rules:

import { predict, storePredictions } from "ark-self-recon/benchmark";
import type { PredictionRule, FailurePrediction } from "ark-self-recon/benchmark";

Standalone benchmark — ark-gist runs a self-recon benchmark direct from the package:

import { selfReconBench } from "ark-self-recon/benchmark";

const report = await selfReconBench();
console.log(report.perSize.map(p => `${p.entryCount} entries: scan ${p.scan.avg}ms`).join("\n"));

Explicitly Not

• A monitoring agent or cron daemon — single-shot scan, no watch mode
• A metrics dashboard — returns a report object, no visualization or charting
• A runtime supervisor — no restart, recovery, or alerting logic
• A replacement for fs.stat — health scoring uses data semantics, not filesystem timestamps alone

Documentation

Doc	What it covers
docs/API.md	Full API reference with type signatures
docs/ARCHITECTURE.md	System design, components, data flow
docs/DESIGN.md	Design decisions, constraints, tradeoffs
CE.md	AI entry point with config, pipeline overview

License

Apache-2.0