Fornece um gate de validação externo para textos gerados por IA, utilizando um modelo separado para verificar a precisão e vazamentos de PII nos outputs.
Também conhecido como mrhpython/lens-mcp, @soulfield/lens-mcp
- Stars
- 0
- Ferramentas
- 10
- Downloads, 30 dias
- —
- Versão mais recente
- 1.1.1
- Último commit
- 3 de nov. de 2026
- Licença
- MIT
O que é o MCP Soulfield Lens?
Fornece um gate de validação externo para textos gerados por IA, utilizando um modelo separado para verificar a precisão e vazamentos de PII nos outputs. Ele expõe 10 ferramentas, como validate_content, scrub_pii, lens_health.
Resumo gerado a partir do README do projeto
Sobre o MCP server de Soulfield Lens
O Soulfield Lens atua como um gate de validação independente para textos gerados por modelos de IA. Ao contrário dos fluxos de trabalho padrão, onde um modelo avalia o próprio trabalho, este MCP server utiliza um modelo separado para verificar a precisão e possíveis vazamentos de PII nos outputs. Ele opera como um limite local via stdio que se comunica com a Lens API hospedada em api.soulfield.one, garantindo que apenas o texto finalizado seja enviado para revisão, mantendo o acesso ao repositório restrito à sua máquina local.
Desenvolvedores podem escolher entre dois níveis de funcionalidade. O nível gate fornece ferramentas como validate_content para verificações gerais e scrub_pii para escanear identificadores estruturados, como SSNs ou chaves de API. O nível validator oferece uma orquestração local mais profunda por meio de ferramentas como validate_artifact, que pode realizar verificações de consistência entre múltiplos arquivos. Este nível requer a biblioteca lens-kit para funcionar. O sistema foi projetado para ser fail-closed, o que significa que qualquer caso limítrofe ou incerto retorna um status UNKNOWN em vez de uma aprovação silenciosa.
O que você pode fazer com ele
- 1Verificar a precisão do output da IAUse o nível gate para executar uma verificação externa no texto gerado para garantir que ele atenda a padrões específicos de um domínio.
- 2Prevenir vazamentos de dados sensíveisEscanear textos em busca de segredos estruturados e identificadores pessoais, como números de cartão de crédito ou strings de conexão de banco de dados.
- 3Garantir consistência entre arquivosVerificar se valores numéricos em um resumo correspondem aos dados encontrados nos arquivos de origem originais.
Escrito a partir do README do projeto. Cada caso de uso é verificado com uma citação dele.
Como instalar o MCP Soulfield Lens
Formatos verificados em 10 nov 2026Adicionar ao CursorAdicionar ao GooseInstalar o MCP Soulfield Lens no Claude Code
$ claude mcp add --env 'SOULFIELD_API_KEY=<YOUR_SOULFIELD_API_KEY>' lens-mcp -- npx -y @soulfield/lens-mcpInstalar o MCP Soulfield Lens no Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"lens-mcp": {
"command": "npx",
"args": [
"-y",
"@soulfield/lens-mcp"
],
"env": {
"SOULFIELD_API_KEY": "<YOUR_SOULFIELD_API_KEY>"
}
}
}
}Instalar o MCP Soulfield Lens no VS Code
.vscode/mcp.json
{
"servers": {
"lens-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@soulfield/lens-mcp"
],
"env": {
"SOULFIELD_API_KEY": "<YOUR_SOULFIELD_API_KEY>"
}
}
}
}Instalar o MCP Soulfield Lens no VS Code CLI
$ code --add-mcp '{"name":"lens-mcp","type":"stdio","command":"npx","args":["-y","@soulfield/lens-mcp"],"env":{"SOULFIELD_API_KEY":"<YOUR_SOULFIELD_API_KEY>"}}'Instalar o MCP Soulfield Lens no Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"lens-mcp": {
"command": "npx",
"args": [
"-y",
"@soulfield/lens-mcp"
],
"env": {
"SOULFIELD_API_KEY": "<YOUR_SOULFIELD_API_KEY>"
}
}
}
}Instalar o MCP Soulfield Lens no Codex
$ codex mcp add lens-mcp --env 'SOULFIELD_API_KEY=<YOUR_SOULFIELD_API_KEY>' -- npx -y @soulfield/lens-mcpInstalar o MCP Soulfield Lens no Codex config.toml
~/.codex/config.toml
[mcp_servers.lens-mcp] command = "npx" args = ["-y", "@soulfield/lens-mcp"] [mcp_servers.lens-mcp.env] SOULFIELD_API_KEY = "<YOUR_SOULFIELD_API_KEY>"
Instalar o MCP Soulfield Lens no Gemini CLI
$ gemini mcp add -s user -e 'SOULFIELD_API_KEY=<YOUR_SOULFIELD_API_KEY>' lens-mcp npx -- -y @soulfield/lens-mcpInstalar o MCP Soulfield Lens no Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"lens-mcp": {
"command": "npx",
"args": [
"-y",
"@soulfield/lens-mcp"
],
"env": {
"SOULFIELD_API_KEY": "<YOUR_SOULFIELD_API_KEY>"
}
}
}
}Ferramentas do MCP Soulfield Lens 10
Detectadas a partir do READMEvalidate_contentscrub_piilens_healthvalidate_artifactlens_consistency_leakslens_consistency_numberslens_consistency_markerslens_catches_relevantlens_catches_addlens_catches_stats
| validate_content | — | |
| scrub_pii | — | |
| lens_health | — | |
| validate_artifact | — | |
| lens_consistency_leaks | — | |
| lens_consistency_numbers | — | |
| lens_consistency_markers | — | |
| lens_catches_relevant | — | |
| lens_catches_add | — | |
| lens_catches_stats | — |
Configuração
SOULFIELD_API_KEYSecretoAPI key for validate_content and scrub_pii. Get one free, self-serve, no card, at https://api.soulfield.one/pricing#signup. lens_health needs no key.
SOULFIELD_API_BASELens API base URL. Use https://api.soulfield.one for the hosted service.
| Nome | Descrição | Tipo |
|---|---|---|
| SOULFIELD_API_KEY | API key for validate_content and scrub_pii. Get one free, self-serve, no card, at https://api.soulfield.one/pricing#signup. lens_health needs no key. | Secreto |
| SOULFIELD_API_BASE | Lens API base URL. Use https://api.soulfield.one for the hosted service. |
Verificações automatizadas
Executado em 13 de nov. de 2026Relatório completo →Passou em nossas verificações automatizadas. Isso não é uma auditoria de segurança: leia o código e dê ao servidor o acesso mais restrito de que ele precisa. Como as verificações funcionam
- Repositório de origem vinculado e acessívelPassou
- Licença de código aberto (OSI)Passou
- Commit ou release no último anoPassou
- Nome do pacote não é próximo a um pacote popularPassou
- O endpoint remoto usa HTTPSNão verificado
- Ferramentas destrutivas estão rotuladasPassou
- Sem instruções ocultas para o modeloPassou
- Nenhum aviso crítico no pacote ou em suas dependênciasPassou
README
Ver no GitHubSoulfield Lens — MCP server
Long jobs can use validation_submit followed by validation_receipt on a
fresh MCP connection. Save the returned job ID with the candidate SHA-256 locally.
Retrieve that ID after a polling timeout; do not submit the content again.
Pending, failed, expired and incomplete jobs confer no clearance. An uncertain
submission without a returned ID must not be automatically retried. The existing
validate_content tool is unchanged. See test/validation-jobs.test.cjs for
offline recovery and Rights-preservation fixtures.
Outside-in validation for AI-generated text, as an MCP tool.
Every AI tool asks the same model that wrote the answer whether it's any good. It says yes. The Soulfield Lens is outside-in: a separate model runs a fixed gate over your output. It checks text — it doesn't write it. This package puts that gate inside Claude Code, Cursor, and any other MCP-compatible agent, so output can be validated on the path where it's generated.
The gate is fail-closed: a borderline case returns UNKNOWN, never a silent pass. There is no generation step, so it can't fabricate claims of its own — only check. It can still be wrong about a judgment; that is exactly why borderline cases return UNKNOWN instead of a confident yes.
This is a local stdio boundary around the hosted Lens API (api.soulfield.one). It keeps repository access on the caller's machine and sends only the finished artifact text to the API gate. A scrub also sends the lines of your own identity file (LENS_PUBLIC_IDENTITY_FILE) that occur in that text, so they are not redacted.
It exposes two tiers. The gate tier (3 tools) needs nothing but an API key. The validator tier (7 tools) adds one local orchestration entry point plus the optional lens-kit cross-file checks and defect memory that the single-document gate cannot see. Skip local evidence inputs and the gate tier works exactly as before.
Try it before you install anything
The keyless demo endpoint runs the same gate — a few runs a day per IP, no signup:
curl -s https://api.soulfield.one/v1/demo \
-H 'content-type: application/json' \
-d '{"text": "<paste the AI output you are about to ship>"}'
Install
npm install -g @soulfield/lens-mcp
Or run without installing: npx @soulfield/lens-mcp.
Claude Code
claude mcp add soulfield-lens \
-e SOULFIELD_API_BASE=https://api.soulfield.one \
-e SOULFIELD_API_KEY=<your-key> \
-- npx @soulfield/lens-mcp
Any MCP client (JSON config)
{
"mcpServers": {
"soulfield-lens": {
"command": "npx",
"args": ["@soulfield/lens-mcp"],
"env": {
"SOULFIELD_API_BASE": "https://api.soulfield.one",
"SOULFIELD_API_KEY": "<your-key>"
}
}
}
}
Production calls need an API key — request one at hello@soulfield.one. lens_health works without one.
Tools
Gate tier — hosted API, works out of the box
| Tool | What it does | Auth |
|---|---|---|
validate_content |
Runs the outside-in gate over text. Returns pass/fail, score, per-dimension results, and violation details with reasoning. Optional domain (general, finance, marketing, legal, seo, agency) and context (audience/purpose). |
key |
scrub_pii |
Server-side scan for structured PII and secrets — emails, UK/US phone numbers, credit-card numbers, US SSNs, UK NI/UTR numbers, database connection strings, and common API-key/credential patterns. Returns scrubbed text (each match replaced by a type marker) plus findings. Pattern-based, no LLM call. Targets structured identifiers — it does not detect personal names or free-form PII, and structured-format coverage is best-effort, not exhaustive. | key |
lens_health |
Checks the Lens API is up. Returns status and version. | none |
Validator tier — local; consistency checks require lens-kit
Version note: the validator tier lands in 1.1.0. If
npm view @soulfield/lens-mcp versionstill reports1.0.0, the registry has not caught up with this repo yet andnpx @soulfield/lens-mcpwill give you the three gate-tier tools only. Install from source in the meantime.
Artifact orchestration:
validate_artifactlands in 1.2.0. Its bounded local evidence search is built into this MCP package. Requested consistency checks still requirelens-kit.
Side effect worth knowing: every validator-tier call appends a row to
RUNS.mdin its working directory — that is the kit's run ledger, by design. The directory is thecwdargument, or the server's own cwd if you omit it, so passcwdexplicitly if you care where the ledger lives. Sensitive flag values are redacted in the row (--deny <redacted>), so deny terms do not land on disk.
Prerequisite: pip install lens_kit (Apache-2.0, github.com/mrhpython/lens-kit), or set LENS_KIT_BIN to its path. Without it these six tools return UNKNOWN with an error — never a silent pass. No API key needed: they run locally and make no LLM call.
Why they run locally and not on the hosted API: they take file paths off your disk. A hosted endpoint that accepted arbitrary local paths would be a file-disclosure vector, not a feature. On stdio the paths are your own machine, so the capability is safe here and only here — and for that reason it will not be added to the hosted API.
| Tool | What it does | Exit semantics |
|---|---|---|
validate_artifact |
Reads one local artifact, searches only explicitly permitted evidence roots, runs requested consistency checks, and sends only the artifact text to the API gate. It labels the result gate-only or evidence-preflight+gate. A literal match is a source location, not proof; a separate validator agent must read and adjudicate it before issuing a full-validator verdict. |
consistency violation → FAIL; incomplete evidence/check error → UNKNOWN; otherwise PENDING_AGENT_REVIEW |
lens_consistency_leaks |
Scans files for deny-list terms (case-insensitive literal). Run on every customer-facing file before an irreversible publish: catches a real client name, an internal codename or a banned absolute surviving into shipped copy. A credential scanner will not find these, because nothing here is a credential. Negation-blind: a banned phrase quoted in order to disclaim it matches identically to the same phrase asserted. | hit proves the string is present — adjudicate the verdict |
lens_consistency_numbers |
Checks every numeric literal in a summary actually appears in the body it summarizes. Catches the invented figure. Tripwire: literal matching only, no derived arithmetic, and a figure cited as superseded ("supersedes the ~471 estimate") flags exactly like a stale one. Review, don't auto-trust. | violation / clean |
lens_consistency_markers |
Checks evidence markers in a source survive into every rendered output — the caveat or citation dropped between formats. Case-SENSITIVE, unlike leaks above: TRIPWIRE will not match Tripwire and reads as dropped when nothing was. Tripwire: a deliberate subset render also under-counts legitimately. |
violation / clean |
Choosing deny terms and markers. These three are tripwires, not oracles — on a live run over this project's own copy they produced six flags and zero true defects, across three distinct false-positive classes (negation, superseded-figure, casing). That is the designed behaviour, and it is why the doctrine is adjudicate, never auto-apply. Deny terms work best as strings that are wrong in every context — a real client name, an internal codename — rather than claims you do not make, which legitimately appear inside disclaimers. Markers work best when their casing is stable across source and render.
| lens_catches_relevant | Reads the defect bank before you validate: prior named defects for an artifact type, most-recurrent first. Patterns at threshold are marked [PROMOTE] — they recur often enough to deserve a fixed check. | — |
| lens_catches_add | Records a named defect so it is caught next time: what was wrong, the general pattern, the forward rule. Routine passes are rejected by design — only real defects. | — |
| lens_catches_stats | Per-pattern recurrence counts with promote suggestions. Tells you what to harden next. | — |
The two tiers are complementary, not alternatives. The gate has no tools and no file access — that is precisely what makes it an independent check, and it is also why it cannot see a contradiction spread across two files. The validator tier sees the disk; the gate owns the score. Pair them: gather substrate evidence with the local tools, hand the text to the gate, and never argue a gate FAIL into a PASS. Full protocol: docs/VALIDATOR-AGENT.md.
One local entry point
validate_artifact makes the boundary explicit in one call:
{
"artifact_path": "output/candidate.md",
"evidence_roots": ["reports", "output/proof"],
"evidence_queries": [
{
"claim": "measured-result",
"query": "113/113 rows scored",
"case_sensitive": true
}
],
"domain": "agency",
"context": "Internal technical handoff"
}
The response includes evidence_scope, files_read, searches_and_commands, claims_verified, and claims_unverified. claims_verified is deliberately empty: grep proves that text exists at a source location, not that the claim is true. The separate validator agent must read the located evidence, reason across the files, and attach the final full-validator receipt.
Evidence file contents and local absolute paths are never added to the API request. Directory searches skip .git, node_modules, symlinks, and binary files and fail closed when configured safety limits are exceeded.
What you get per run: receipts — what was checked, what passed, what was held, and why. Machine-readable, not a badge. We won't hand you a guaranteed accuracy number for your data: scores don't transfer across models, datasets, and runtimes, and a tool that promises a fixed figure on data it has never seen is making the exact claim this gate exists to catch.
Long inputs
Inputs of ~4,000 characters and up are submitted as an async job and polled to completion automatically, so a single long validation never dies on a request timeout. Short inputs use the fast synchronous path. No configuration needed.
Configuration (env vars)
| Variable | Default | Purpose |
|---|---|---|
SOULFIELD_API_BASE |
http://localhost:8002 |
Lens API base URL. Use https://api.soulfield.one for the hosted service, or your own deployment. |
SOULFIELD_API_KEY |
— | Required for validate_content and scrub_pii. |
SOULFIELD_VALIDATE_TIMEOUT_MS |
180000 |
Per-request timeout for the sync path. |
SOULFIELD_VALIDATE_BUDGET_MS |
600000 |
Total wall-clock budget for the async poll loop. |
SOULFIELD_ASYNC_MIN_CHARS |
4000 |
Input length at which the async path kicks in. |
LENS_KIT_BIN |
lens-kit |
Path to the lens-kit CLI for the validator tier. Only needed if it is not on PATH. |
LENS_KIT_TIMEOUT_MS |
120000 |
Timeout for a validator-tier command. On timeout the verdict is UNKNOWN, never a pass. |
LENS_CATCHES_DIR |
~/dev/tools/lens-kit |
Default working directory for the three lens_catches_* tools, so every catch lands in one catches.jsonl. A leading ~ is expanded. Falls back to the server's cwd if the directory does not exist. A cwd argument still wins. Catches can hold verbatim snippets, so catches.jsonl must stay out of git; the lens-kit repo ignores it. |
LENS_PUBLIC_IDENTITY_FILE |
~/.config/soulfield-lens/public-identity.txt |
Your own published details (name, postal address, contact email, phone), one per line. /v1/scrub calls send the lines that occur in the text as keep, so your own details are not redacted from your outgoing work; anyone else's still are. No file: nothing is kept. |
LENS_RECEIPT_DIR |
unset | When set, each gate result from validate_content, validate_artifact and a completed validation_submit job appends one line to <dir>/receipts.jsonl (text hash, domain, context, per-lens verdicts, findings with short quotes; no document text). A leading ~ is expanded. The text, scrubbed by POST /v1/scrub, goes to <dir>/private/docs/<sha256>.txt, and <dir>/private/.gitignore holds *. The line's context, issues and quotes are scrubbed by one more /v1/scrub call; quotes are cut to 300 characters after the scrub. If a scrub fails, that text is not saved (doc_status or findings_status says so). The scrub finds structured identifiers only; names survive it. A write failure never fails the validation. |
The rest of the product
This wrapper is one of several surfaces on the same engine:
- Free one-output audit — api.soulfield.one/audit. The audit is the demo.
- Wire it in (SDK stop-hook and middleware) — api.soulfield.one/developers.
- Own it — the kit: lenses, compiler, self-improve loop, validator agent, Apache-2.0. Train it on your own data. Public repo: github.com/mrhpython/lens-kit — clone it,
pip install -e ".[dev]", and the test suite runs offline with no key. Installing it is also what activates the validator tier above.
We hold our own marketing copy to the same gate this package exposes.
License
MIT — see LICENSE. (The lens-kit product is licensed separately under Apache-2.0.)
Perguntas sobre o MCP Soulfield Lens
Como adiciono o MCP Soulfield Lens ao Claude Code?
Execute claude mcp add --env 'SOULFIELD_API_KEY=<YOUR_SOULFIELD_API_KEY>' lens-mcp -- npx -y @soulfield/lens-mcp no seu terminal. Adicione --scope user para torná-lo disponível em todos os projetos.
Como adiciono o MCP Soulfield Lens ao Cursor?
Abra ~/.cursor/mcp.json e adicione o servidor em mcpServers, usando a configuração do Cursor mostrada na seção de instalação acima.
Quais ferramentas o MCP Soulfield Lens oferece?
Ele expõe 10 ferramentas, incluindo validate_content, scrub_pii, lens_health, validate_artifact, lens_consistency_leaks.
Como o processo de validação difere da autocorreção padrão de um LLM?
Diferente dos métodos padrão onde um modelo verifica o próprio trabalho, o Soulfield Lens utiliza um modelo separado para executar um gate fixo sobre o output.
O servidor envia meus arquivos locais para a API?
Não, a API hospedada recebe apenas o texto do artefato finalizado. Caminhos de arquivos locais e evidências são tratados localmente para evitar vetores de exposição de arquivos.
Posso usar a ferramenta sem uma chave de API?
Sim, a ferramenta lens_health funciona sem chave, e o endpoint de demonstração sem chave permite algumas execuções por dia por IP.