local-evidence-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@local-evidence-mcp search for incident reports about server outage"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Local Evidence MCP
A policy-constrained local evidence boundary for MCP clients.
Generated from the checked-in synthetic policy, server tool definitions, and named test inventory. It shows the intended capability boundary; the 18 tests are executable checks, not a completeness score or an independent security audit.
Local Evidence MCP retrieves a small, policy-gated evidence set and records reviewed conclusions without giving an agent general filesystem access.
This repository demonstrates a practical RAG and agent-harness pattern:
policy-gated reads instead of whole-vault access;
redaction before content reaches the client or search index;
optional local Ollama embeddings with deterministic lexical fallback;
content-digest embedding caches that do not store source text;
create-only notes and an append-only lesson ledger;
newline-delimited JSON-RPC over stdio with no runtime dependencies; and
explicit rejection of likely credentials and raw challenge flags.
The included vault and policy are synthetic examples. No personal vault data, private policy, embedding cache, agent configuration, or credentials are part of this repository.
Architecture
flowchart LR
Client["MCP client"] -->|"JSON-RPC over stdio"| Server["Local Evidence MCP"]
Server --> Policy["Policy validation"]
Policy --> Guard["Path and symlink guard"]
Guard --> Read["Allowlisted UTF-8 notes"]
Read --> Redact["Credential and raw-flag redaction"]
Redact --> Lexical["Lexical ranking"]
Redact --> LocalEmbed["Optional loopback embeddings"]
Lexical --> Results["Source-labelled results"]
LocalEmbed --> Results
Server -->|"O_EXCL"| Create["Create-only drafts"]
Server -->|"O_APPEND"| Append["Append-only lessons"]The server advertises no shell, SSH, browser, messaging, remote retrieval, or arbitrary filesystem capability. The only optional HTTP call is to an unauthenticated loopback embedding endpoint.
Related MCP server: Jusratio Case File
Quick start
Requirements: Python 3.11 or newer. Ollama is optional.
git clone https://github.com/Labeeb2339/local-evidence-mcp.git
cd local-evidence-mcp
./run_server.cmd --checkOn macOS or Linux:
chmod +x run_server.sh
./run_server.sh --checkThe default health check uses examples/vault and
examples/policy.example.json. If Ollama is not available, the check reports
that lexical fallback is active; retrieval still works.
Try a JSON-RPC request directly:
'{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | ./run_server.cmdConfigure your own evidence root
Copy the example policy to a local, ignored file and edit only the relative paths that should be visible:
Copy-Item examples/policy.example.json policy.json
$env:LOCAL_EVIDENCE_ROOT = "D:\path\to\your\notes"
$env:LOCAL_EVIDENCE_POLICY = "$PWD\policy.json"
./run_server.cmd --checkThe policy separates four decisions:
Section | Purpose |
| Exact files the server may read |
| Non-recursive relative globs, such as |
| Paths denied even if another rule matches |
| One create-only directory and one append-only file |
Limits cap file size, result count, write size, index size, and chunk length. Absolute paths, traversal components, NTFS stream syntax, recursive read globs, and linked files are rejected.
To force offline lexical mode, set embeddings.enabled to false. When
embeddings are enabled, the endpoint must use plain HTTP on 127.0.0.1,
localhost, or ::1; remote and credential-bearing URLs are refused.
MCP client configuration
After installing the package with python -m pip install -e ., a client can
launch it with the console script:
{
"mcpServers": {
"local-evidence": {
"command": "local-evidence-mcp",
"args": [
"--root",
"<absolute-path-to-evidence-root>",
"--policy",
"<absolute-path-to-local-policy.json>"
]
}
}
}Keep the real policy and evidence root outside version control. The example policy is safe to publish because it references only the included synthetic fixtures.
Tools
Tool | Boundary |
| Reports configured capabilities and exclusions |
| Searches sanitized allowlisted chunks |
| Reads one sanitized allowlisted file |
| Creates a new draft with exclusive-create semantics |
| Appends one evidence-backed entry to a fixed ledger |
Tool input is checked again at runtime instead of relying only on the JSON schemas presented to the MCP client.
Security properties
Risk | Control |
Broad filesystem exposure | Relative allowlist plus resolved-root containment |
Traversal or linked-file escape | Component validation and symlink rejection |
Secret leakage in reads | Redaction before direct output and chunking |
Sensitive query or durable write | Credential and raw-flag rejection |
Destructive overwrite | `O_CREAT |
Rewrite of the lesson ledger | Fixed destination opened with |
Embedding data leakage | Loopback-only endpoint and vector-only cache |
Prompt injection in notes | Evidence warnings and no execution tools |
Regex redaction is defense in depth, not a substitute for keeping secrets out of the evidence root. Local operating-system permissions still define who can start the process and edit its policy.
Test
The full suite uses only the standard library:
$env:PYTHONPATH = "src"
python -m unittest discover -s tests -v
python scripts/generate_readme_assets.py --checkCI runs the suite on Python 3.11, 3.12, and 3.13 and performs a Gitleaks scan. Tests cover path containment, exclusions, redaction, lexical fallback, semantic ranking, plaintext-free caching, create-only and append-only writes, sensitive input rejection, symlink handling, and MCP protocol responses.
Design scope
This is a compact reference implementation, not a hosted vector database or an enterprise authorization service. It's most useful when an assistant needs a small local knowledge boundary that degrades safely when the embedding service is offline.
License
Available Tools
5 toolsevidence_append_lessonC
Append one evidence-backed lesson to the configured ledger.
Inputs: lesson (required), subject (required), verified_evidence (required), source_refs.
evidence_create_noteB
Create a new evidence note in one configured directory; never overwrite.
Inputs: slug (required), title (required), summary (required), decision (required), +4 more.
evidence_readA
Read one allowlisted UTF-8 note with potential credentials and raw challenge flags redacted.
Inputs: relative_path (required).
evidence_searchB
Search allowlisted local notes with optional local embeddings and deterministic lexical fallback.
Inputs: query (required), max_results.
evidence_statusA
Show the configured evidence boundary, retrieval mode, and write policy.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a distinct, non-overlapping purpose: read a single note, create a note, check status, search notes, and append a lesson. There is no ambiguity about which tool to use for a given operation.
All tools share the 'evidence_' prefix and mostly follow a verb_noun pattern (read, create_note, search, append_lesson). 'evidence_status' is a minor deviation as it uses a noun rather than an explicit verb like 'get_status' or 'show_status', but the overall pattern is consistent and readable.
With 5 tools, the server is well-scoped for its purpose of managing local evidence notes. Each tool covers a core operation without unnecessary bloat, making the set easy to navigate.
The tool set covers the primary lifecycle: create, read, search, and append lessons, plus status. It lacks explicit update/delete operations, but given the 'never overwrite' policy and the append-only nature of lessons, these omissions are likely intentional and not a major gap.
Related MCP Connectors
Guarded MCP server for agent-readable business truth, provenance, readiness, and discovery.
Evidence-readiness MCP server: validate, audit, and score briefs, memos, and evidence packs.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceLocal-first MCP server for safely searching, reading, summarizing, tagging, deduplicating, and organizing local files with scoped access, read-only defaults, and dry-run plans.19MIT
- AlicenseBqualityAmaintenanceLocal-first MCP server that transforms civil case PDFs into queryable cases with structural provenance, evidence IDs, and page-level verification for drafting and factual review.22Apache 2.0
- AlicenseAqualityDmaintenanceA local-first, model-neutral MCP server for collecting and normalizing change-scoped release evidence. It provides deterministic Git change summaries, evidence collection, and review bundles for agent review.74 npmApache 2.0
- FlicenseNot gradedqualityDmaintenanceAn MCP server exposing narrowly scoped storage workflows with Overseer approval integration and redacted execution evidence, currently in fixture-only development for testing via stdio.-