EvidenceLens MCP

EvidenceLens MCP is a TypeScript Model Context Protocol server for read-only evidence review. The single review_evidence tool accepts four distinct required course roles plus optional evidence, normalizes inline and explicitly configured filesystem sources, and returns schema-validated findings with typed provenance. Deterministic rules remain independently retained alongside an optional DeepSeek second opinion.

Assignment review commands

Use $el-help, $el-prepare, $el-check, $el-final, $el-recheck and $el-prompt through the installation and command guide. Stage commands share the existing assignment-review Skill; help and export do not start a review. Prompt capture/export and independent Codex execution remain later-phase work. Installation tests and real host discovery are reported separately.

Related MCP server: Observability Agent MCP

Local Development

npm install
npm run dev
npm test
npm run test:deepseek-live # opt-in adapter-only Vision structure
npm run docker:review:real # opt-in complete Docker MCP stdio proof
npm run build

npm run dev starts the MCP server over stdio from src/server.ts. npm test runs the full credential-free, no-network contract, normalizer, fixture, safety, and MCP protocol suite; it excludes the live provider test and sets EVIDENCELENS_DISABLE_PROVIDER=1 so ambient DeepSeek credentials cannot enable provider calls. npm run build type-checks and compiles the server.

Docker deployment and offline validation

The canonical fresh-checkout Docker runbook is docs/docker-deployment.md. It covers the hardened direct-stdio image, the whole-project read-only /workspace mount, the exact course=/workspace allowlist, the four fixed evidence fixtures, and the explicit credentialed DeepSeek path.

The routine commands are credential-free and no-network:

docker compose --profile smoke build
npm run docker:smoke
npm run test:e2e

The smoke path validates MCP initialize, tools/list, and tools/call over stdio. The E2E path injects an offline-compatible provider and checks schemas, findings, typed citations, hashes, and logical filesystem://course/... provenance without asserting model prose. It does not call DeepSeek.

Optional DeepSeek provider

Runtime reads the ignored .evidencelens.local.json file (or explicitly supplied DEEPSEEK_* environment values) and registers only the built-in DeepSeek provider. Start from the redacted .evidencelens.local.example.json:

{
  "apiKey": "REPLACE_WITH_DEEPSEEK_API_KEY",
  "baseUrl": "https://api.deepseek.com",
  "model": "deepseek-v4-pro",
  "timeoutMs": 30000,
  "maxRetries": 2,
  "maxTotalWaitMs": 10000,
  "temperature": 0.2
}

The default model is deepseek-v4-pro; the allowlist is deepseek-v4-pro, deepseek-v4-flash, and deepseek-v4-flash-vision-exp. By default EvidenceLens omits max_tokens and uses DeepSeek's documented model/mode default. An explicit maxTokens or DEEPSEEK_MAX_TOKENS value is validated between 1 and 393,216 and then forwarded. Thinking mode is enabled with reasoning_effort: high for the V4 text models; the vision model uses the official base64 image_url Chat Completions format and preserves provider-default thinking behavior. Timeouts are bounded to 1–120 seconds, retries to 0–2, and total retry wait to 1–60 seconds. Configuration is typed and fail-closed; arbitrary provider names or npm modules are never loaded. The certified Compose review/proof path requires DEEPSEEK_MAX_TOKENS to be absent and ignores hostile host overrides; proof retries remain zero and the proof request budget remains one.

Provider-enabled local and Docker startup requires a valid .evidencelens.local.json file or valid DEEPSEEK_* environment configuration. Missing, malformed, conflicting, or unreadable configuration exits with the sanitized PROVIDER_CONFIGURATION classification; it never falls back to deterministic-only output. Set exactly EVIDENCELENS_DISABLE_PROVIDER=1 for intentional offline operation, as used by routine no-network tests and smoke checks. Injected providers and typed providerConfig are embedding/test seams, not end-user configuration options.

Two real-provider commands are deliberately opt-in. npm run test:deepseek-live checks adapter-only Vision structure using either DEEPSEEK_API_KEY from the process environment or the ignored .evidencelens.local.json file; it skips only when neither usable credential source exists. npm run docker:review:real checks the complete credentialed Docker MCP stdio path and requires a process-level DEEPSEEK_API_KEY plus Docker. Both commands require network access and may incur API cost, and both are excluded from npm test. The live screenshot check uses deepseek-v4-flash-vision-exp; V4 text models use thinking mode, while the vision request uses the official base64 image_url format without thinking parameters. A finish_reason of length is accepted only when the returned content independently passes the same bounded single-root extraction, strict schema, and locally bound provenance validation as stop; incomplete or invalid content still fails closed. Byte-for-byte equality remains scoped to deterministic-only offline output; neither live command promises byte-for-byte equality of model prose, and assertions cover structure, safe attribution, provider finding namespacing, and locally validated citation/hash provenance. The model returns compact evidence references; local normalized evidence remains authoritative for citation binding and provenance. Credential-free fixtures remain the required regression gate. Injected-provider E2E remains a credential-free semantic test and is not credentialed proof.

MCP Contract

See docs/mcp-contract.md for the exact four-role request contract, duplicate-ID and stable errors, deterministic finding fields and citation mapping, root configuration grammar, byte limits, filesystem:// provenance, transient analysis boundary, and read-only/no-provider behavior. See docs/docker-deployment.md for container-specific mounts, profiles, and startup preflight behavior.

For identical inputs, deterministic-only offline results are byte-for-byte equal and retain the fixed request/timestamp mapping. Provider-backed finding content may vary between calls. Provider-backed responses guarantee only strict schema validation, safe attribution, provider finding namespacing, and locally validated citation/hash provenance.

Provider-backed responses add an optional metadata.provider child only when provider findings are returned. Only provider name and model are public attribution. Credentials/API keys, endpoint/base URL, prompt text/version, input fingerprint, provider request/result envelope, raw upstream response, and retry/transport internals are never public and never serialized. Existing deterministic analyzer metadata and deterministic-only response bytes remain unchanged.

Platform note: the default filesystem reader uses descriptor-relative component walking on Linux. On macOS, where this project has no supported Node openat/openat2 binding, default anchored filesystem reads fail closed with sanitized ACCESS_DENIED and no bytes; there is no pathname fallback. Phase 2 inline evidence remains supported, and embedding tests may inject a reviewed safe filesystem adapter for portable filesystem-read coverage.

Optional filesystem roots

Filesystem access is disabled when no roots are configured; the server never falls back to the current directory, home directory, repository, or another broad default. Configure explicit roots with repeated id=absolute-path entries separated by commas or semicolons:

EVIDENCELENS_ALLOWED_ROOTS='course=/absolute/path/course;examples=/absolute/path/examples' npm run dev

Root IDs match [A-Za-z][A-Za-z0-9_-]{0,31}. Empty entries, duplicate IDs, canonical path collisions, unreadable roots, non-directories, relative paths, and malformed entries fail with the stable message Invalid filesystem root configuration; paths are never echoed.