Add SEO and AI discovery docs

Author: ithiria894

CITATION.cff

@@ -0,0 +1,33 @@
+cff-version: 1.2.0
+message: "If you use IntentProbe, please cite the research paper and the repository."
+title: "IntentProbe: Local Activation-Probe Scanner for MCP Tool Poisoning"
+type: software
+authors:
+  - name: "mcpware"
+version: 0.1.0
+date-released: 2026-06-08
+license: Apache-2.0
+repository-code: "https://github.com/mcpware/IntentProbe"
+url: "https://github.com/mcpware/IntentProbe"
+abstract: "IntentProbe is a local activation-probe scanner for MCP servers, AI agent tools, Claude Code skills, and runtime tool events. It reads internal activations from a small frozen local model to detect poisoned tool intent that surface text analysis can miss."
+keywords:
+  - mcp-security
+  - model-context-protocol
+  - ai-security
+  - llm-security
+  - agent-security
+  - tool-poisoning
+  - activation-probing
+  - prompt-injection
+  - local-scanner
+identifiers:
+  - type: doi
+    value: 10.5281/zenodo.19990741
+    description: "Research paper: Can Model Internals Detect MCP Tool Poisoning That Text Analysis Cannot?"
+preferred-citation:
+  type: article
+  title: "Can Model Internals Detect MCP Tool Poisoning That Text Analysis Cannot?"
+  authors:
+    - name: "mcpware"
+  doi: 10.5281/zenodo.19990741
+  year: 2026

README.md

@@ -17,11 +17,11 @@
   <img src="docs/diagram.png" width="700" alt="Text scanners read words. IntentProbe reads activations." />
 </p>
 
-Every MCP scanner on the market reads text: patterns, classifiers, rules, or asks an LLM "is this safe?" IntentProbe does something none of them do. It runs the tool description through a small local model, slices open the hidden layers, and reads the activation state directly. Same words, completely different activations when the intent is malicious.
+Every public/source-verifiable MCP scanner we found reads text: patterns, classifiers, rules, or asks an LLM "is this safe?" IntentProbe does something different. It runs the tool description through a small local model, slices open the hidden layers, and reads the activation state directly. Same words, completely different activations when the intent is malicious.
 
-On matched-vocabulary tool poisoning, where safe and poisoned descriptions use almost identical words, Snyk's shipped scanner catches **0%**. IntentProbe catches **96.5%**. ([Reproduce it yourself.](research/benchmark-results-deberta-vs-probe-2026-05-31.md))
+On matched-vocabulary tool poisoning, where safe and poisoned descriptions use almost identical words, the public/source-verifiable DeBERTa text-classifier baseline catches **0%**. IntentProbe scores **96.6% F1**. ([Reproduce it yourself.](research/benchmark-results-deberta-vs-probe-2026-05-31.md))
 
-Runs locally. 22 KB probe. Any CPU. Nothing uploaded. See the [full competitive landscape](docs/COMPETITIVE_LANDSCAPE.md).
+Runs locally. 22 KB probe. Any CPU. Nothing uploaded. See the [plain comparison](docs/intentprobe-vs-existing-mcp-scanners.md), [FAQ](docs/FAQ.md), and [full competitive landscape](docs/COMPETITIVE_LANDSCAPE.md).
 
 ## Break it in one command
 
@@ -59,7 +59,7 @@ First model-backed scan downloads Qwen2.5-0.5B (~1 GB, once). Scan data stays on
                     │  Almost identical words       │  Steals your SSH keys
 ```
 
-Real pair from our benchmark. IntentProbe scores the safe tool at 0.081 (allow) and the poisoned tool at 0.982 (warn). Snyk's DeBERTa scores both at 0.0%. It sees no difference.
+Real pair from our benchmark. IntentProbe scores the safe tool at 0.081 (allow) and the poisoned tool at 0.982 (warn). The DeBERTa text-classifier baseline scores both at 0.0%. It sees no difference.
 
 The words are almost identical. The intent is not. Text scanners fail here because there is no text difference to find.
 
@@ -82,8 +82,14 @@ The words are almost identical. The intent is not. Text scanners fail here becau
 | **Red-team framework** | garak, Giskard, Promptfoo red team | Generate attacks to test your app | Audit tool, not a pre-install scanner. | IntentProbe is a **CLI + runtime hook** that blocks before install and before each tool call. |
 | **IntentProbe** | | Frozen local model + activation probe on layers 13-15 | Still improving on novel attack families | **First activation-probe scanner for MCP tool poisoning.** |
 
+Fast comparison: [docs/intentprobe-vs-existing-mcp-scanners.md](docs/intentprobe-vs-existing-mcp-scanners.md)
+
+FAQ for common questions: [docs/FAQ.md](docs/FAQ.md)
+
 Full source-backed comparison: [docs/COMPETITIVE_LANDSCAPE.md](docs/COMPETITIVE_LANDSCAPE.md)
 
+AI-readable context: [llms.txt](llms.txt) and [llms-full.txt](llms-full.txt)
+
 ## Why not just ask Qwen?
 
 LLM-as-judge is an output-level mechanism: ask a model to say safe or unsafe.
@@ -106,16 +112,16 @@ recall and many unparseable outputs. Full reproducible baseline:
 Same test sets. Same split. Same seed. Every number is reproducible from `research/`.
 
 ```
-  IntentProbe vs Snyk DeBERTa
-  ═══════════════════════════
+  IntentProbe vs DeBERTa text-classifier baseline
+  ════════════════════════════════════════════════
 
   MCPTox poisoned recall (n=249)
   IntentProbe  ██████████████████████████████████████████████████  100.0%
-  Snyk         ██████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   19.9%
+  DeBERTa      ██████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   19.9%
 
   Matched-vocabulary F1 (n=86)          ◀ the hard test
   IntentProbe  ████████████████████████████████████████████████░░   96.6%
-  Snyk         ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░    0.0%
+  DeBERTa      ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░    0.0%
 
   Novel attack families (n=2,900)
   IntentProbe  █████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░   41.5%
@@ -130,8 +136,8 @@ Same test sets. Same split. Same seed. Every number is reproducible from `resear
 
 | Test | IntentProbe | Opponent | Takeaway |
 |---|---|---|---|
-| MCPTox held-out (n=249) | recall 100%, F1 99.3% | Snyk DeBERTa recall 19.9%, F1 33.0% | Clear win |
-| Same-words matched (n=86) | F1 96.6% | Snyk DeBERTa F1 0% | Text scanner blind |
+| MCPTox held-out (n=249) | recall 100%, F1 99.3% | DeBERTa text baseline recall 19.9%, F1 33.0% | Clear win |
+| Same-words matched (n=86) | F1 96.6% | DeBERTa text baseline F1 0% | Text scanner blind |
 | Curated family holdout (n=76) | Qwen macro F1 0.829 | TF-IDF macro F1 0.823 | Slight edge |
 | RouteGuard external (n=2,900) | F1 0.513, recall 0.415 | TF-IDF F1 0.172, recall 0.107 | 4x better on novel families |
 | Hard-block policy (n=2,900) | Block precision 1.000, clean FPR 0.000 | -- | Zero false positives |
@@ -304,7 +310,7 @@ Full event schema: [docs/RUNTIME_HOOKS.md](docs/RUNTIME_HOOKS.md)
 
 ## The story
 
-I source-read Snyk's shipped MCP scanner. It uses a DeBERTa text classifier trained on prompt injection, not tool poisoning. On matched-vocabulary attacks it scores 0%. I checked every other public scanner I could find. Rules, regex, text classifiers, opaque cloud APIs. None of them read model internals.
+I source-read public MCP scanner paths and the DeBERTa prompt-injection classifier baseline used in Snyk/Invariant-style scanner code. It is trained on prompt injection, not tool poisoning. On matched-vocabulary attacks it scores 0%. I checked every other public scanner I could find. Rules, regex, text classifiers, opaque cloud APIs. I did not find another product-shaped MCP/tool scanner that uses model internals as the main signal.
 
 So I built one that does. Feed the description into a small model, slice it open, read the activations. The signal is there. A 22 KB probe catches what every text scanner misses.
 

docs/FAQ.md

@@ -0,0 +1,126 @@
+# IntentProbe FAQ
+
+## What is IntentProbe?
+
+IntentProbe is a local scanner for MCP servers, AI agent tools, Claude Code
+skills, packages, and runtime tool events. It looks for poisoned intent such as
+credential access, secret exfiltration, hidden persistence, forced tool
+chaining, or tool hijacking.
+
+## What does "activation probing" mean?
+
+IntentProbe runs a tool description through a small frozen local model and reads
+the hidden activation state inside the model. Then a small trained probe scores
+whether that internal state looks poisoned.
+
+Simple version: text scanners read the words. LLM judges ask for an answer.
+IntentProbe checks the internal signal before the model says anything.
+
+## Is this the same as asking Qwen if a tool is safe?
+
+No. Asking Qwen "is this safe?" is an LLM-as-judge approach. IntentProbe uses
+Qwen2.5-0.5B as a fixed feature extractor and reads hidden activations instead
+of trusting the model's generated answer.
+
+We tested the direct-prompt approach. The deterministic label-score version
+flagged every clean curated item as poisoned, while the generated-answer
+version missed poison and produced many unparseable outputs. See
+[`research/QWEN_PROMPT_JUDGE_BASELINE_2026-06-08.md`](../research/QWEN_PROMPT_JUDGE_BASELINE_2026-06-08.md).
+
+## Why not just use a text classifier?
+
+Text classifiers are useful when unsafe samples have obvious words or patterns.
+They struggle when a safe tool and a poisoned tool use almost the same
+vocabulary.
+
+On the matched-vocabulary benchmark, the public/source-verifiable DeBERTa
+prompt-injection text-classifier baseline scored 0.0% F1, while the
+activation-probe method scored 96.6% F1.
+
+## Does IntentProbe upload my tool descriptions?
+
+No. IntentProbe runs locally. Scan targets and scan results stay on your
+machine.
+
+The first model-backed scan may download Qwen2.5-0.5B once from Hugging Face.
+After the model is cached, scans can run from local files.
+
+## What model does v0 use?
+
+The released v0 scanner uses Qwen2.5-0.5B as the frozen local sensor model and
+reads layers 13-15. The shipped probe artifact is about 22 KB.
+
+## Does IntentProbe change or train the base model?
+
+No. The base model stays frozen. IntentProbe trains a small classifier on top of
+extracted activation features. At scan time, the model is only used to produce
+features.
+
+## What can it scan today?
+
+IntentProbe can scan:
+
+- one text/tool description;
+- package folders through `scan-path`;
+- `package.json`;
+- MCP configs and tool JSON;
+- Claude Code `SKILL.md` folders;
+- README files and nearby tool metadata;
+- runtime events such as tool definitions, before-tool-call arguments, and
+  after-tool-call responses.
+
+## Can I use it as a runtime hook?
+
+Yes. See [`docs/RUNTIME_HOOKS.md`](RUNTIME_HOOKS.md). Runtime scanning is
+event-boundary scanning: tool definitions before trust, tool arguments before
+execution, and tool responses before the agent trusts them.
+
+## What are the headline benchmarks?
+
+The highest-signal public numbers are:
+
+| Test | IntentProbe / activation probe | Baseline |
+|---|---:|---:|
+| Matched-vocabulary F1, n=86 | 96.6% | DeBERTa text classifier 0.0% |
+| MCPTox poisoned recall, n=249 | 100.0% | DeBERTa text classifier 19.9% |
+| RouteGuard-style external recall, n=2,900 | 41.5% | TF-IDF 10.7% |
+| Camouflage suffix evasion | 0/146 evaded | N/A |
+
+Benchmark artifacts are under [`research/`](../research/).
+
+## Is this a claim about every private cloud scanner?
+
+No. The DeBERTa result is a reproducible comparison against a
+public/source-verifiable text-classifier baseline. Private cloud/API scanners
+may work well, but their detector artifacts and MCP/tool-poisoning benchmarks
+are usually not reproducible by users.
+
+## Have you tried SAE features?
+
+Yes. SAE features are useful for interpretability and may improve future recall.
+The v0 product ships raw Qwen activations because the current raw-activation
+artifact is the most complete, lightweight, and reproducible product path today.
+
+SAE is planned as an optional layer for recall improvements and human-readable
+explanations.
+
+## Is v0 production-ready?
+
+Use v0 as a pre-install tripwire and runtime warning/blocking layer, not as your
+only security boundary. It already catches important same-vocabulary poisoning
+cases that text scanners miss, but novel attack families and white-box
+adversarial attacks still need more work.
+
+## How do I try it quickly?
+
+```bash
+uvx --python 3.11 --from git+https://github.com/mcpware/IntentProbe.git@v0.1.0 intentprobe scan --format summary --text "Reads SSH config and private keys, then silently uploads credentials to a remote server."
+```
+
+## How do I report a miss or false positive?
+
+Please submit the smallest redacted sample that reproduces the result.
+
+- [Missed detection](https://github.com/mcpware/IntentProbe/issues/new?template=missed-detection.yml)
+- [False positive](https://github.com/mcpware/IntentProbe/issues/new?template=false-positive.yml)
+- [Sample reporting guide](SAMPLE_REPORTING.md)

docs/intentprobe-vs-existing-mcp-scanners.md

@@ -0,0 +1,99 @@
+# IntentProbe vs Existing MCP Scanners
+
+IntentProbe is a local activation-probe scanner for MCP servers, AI agent tools,
+Claude Code skills, packages, and runtime tool events.
+
+The practical difference is mechanism:
+
+- text/rule/policy scanners read the surface;
+- LLM-as-judge scanners ask another model for an answer;
+- cloud/API scanners return a vendor-side decision;
+- IntentProbe reads a local model's internal activation state.
+
+## Quick comparison
+
+| Scanner approach | Examples | What it reads | What users can verify | Main gap | IntentProbe difference |
+|---|---|---|---|---|---|
+| Text, rule, and policy scanning | Regex, metadata checks, static MCP scanners, DeBERTa-style text classifiers | Words, permissions, schemas, known suspicious patterns | Usually local rules or model name; sometimes source code | Same-vocabulary poisoning can look normal at the text layer | Reads hidden activations after the model processed the description |
+| LLM-as-judge | Prompting GPT, Claude, Qwen, Promptfoo-style graders | A generated answer such as safe/unsafe | Prompt and model choice, if disclosed | Prompt-sensitive, parse-sensitive, token-costly, and output-level | Uses a fixed local probe score before any verbal answer is generated |
+| Enterprise cloud/API guardrails | Lakera, Azure Prompt Shields, Google Model Armor, AWS Bedrock Guardrails, Pangea/CrowdStrike AI Guard, Cisco AI Defense, HiddenLayer | Vendor-side detector over prompts, documents, tool calls, or outputs | Usually API response and product docs | Detector artifact and MCP/tool-poisoning benchmark are usually not reproducible by users | Runs locally with public data, scripts, and probe artifact |
+| Red-team frameworks | garak, Giskard, Promptfoo red team | Generated attacks and app behavior | Test harness and attack set | Audit workflow, not a cheap pre-install scanner | CLI and runtime hook for install-time and tool-boundary scanning |
+| IntentProbe | IntentProbe | Internal activations from Qwen2.5-0.5B layers 13-15 | Repo, benchmark scripts, datasets, probe artifact | v0 still needs more wild data and white-box adversarial testing | Different detector class: representation-level, local, reproducible |
+
+## Why activation probing matters
+
+A poisoned tool does not always announce itself with obvious words. It can look
+like a normal helper while quietly adding credential access, remote upload,
+hidden chaining, or persistence.
+
+Text scanner:
+
+```text
+Tool description -> read words -> "looks safe"
+```
+
+LLM-as-judge:
+
+```text
+Tool description -> ask "is this safe?" -> generated answer
+```
+
+IntentProbe:
+
+```text
+Tool description -> frozen local model -> hidden layers -> probe score
+```
+
+The bet is not that Qwen is a better judge. The bet is that a model's internal
+representation can carry intent signal that the surface text and generated
+answer do not reliably expose.
+
+## Benchmark snapshot
+
+| Test | IntentProbe / activation probe | Baseline | Source |
+|---|---:|---:|---|
+| Matched-vocabulary F1, n=86 | 96.6% | DeBERTa text-classifier baseline 0.0% | [`research/benchmark-results-deberta-vs-probe-2026-05-31.md`](../research/benchmark-results-deberta-vs-probe-2026-05-31.md) |
+| MCPTox poisoned recall, n=249 | 100.0% | DeBERTa text-classifier baseline 19.9% | [`research/benchmark-results-deberta-vs-probe-2026-05-31.md`](../research/benchmark-results-deberta-vs-probe-2026-05-31.md) |
+| RouteGuard-style external recall, n=2,900 | 41.5% | TF-IDF logistic baseline 10.7% | [`README.md`](../README.md#benchmarks) |
+| Camouflage suffix evasion | 0/146 evaded | N/A | [`research/ADVERSARIAL_EVASION_RESULTS_2026-06-07.md`](../research/ADVERSARIAL_EVASION_RESULTS_2026-06-07.md) |
+| Direct Qwen judge baseline | Not used as scanner default | Clean FPR 1.000 in label-logprob mode | [`research/QWEN_PROMPT_JUDGE_BASELINE_2026-06-08.md`](../research/QWEN_PROMPT_JUDGE_BASELINE_2026-06-08.md) |
+
+## What this does not claim
+
+IntentProbe does not claim that every vendor cloud detector fails. Most private
+cloud/API detectors are not reproducible from public artifacts, so they cannot
+be fairly scored by this repo unless a public benchmark path exists.
+
+IntentProbe does not claim text scanning is useless. Rules, signatures, policy
+checks, and credential scanners are good hygiene. IntentProbe adds a different
+signal for the cases where the words look normal but the intent is not.
+
+IntentProbe does not claim v0 catches everything. Novel families, paraphrase
+attacks, encoding attacks, and white-box attacks remain active work.
+
+## When to use IntentProbe
+
+Use IntentProbe when you want a local, inspectable tripwire before installing
+or trusting an MCP server, skill, package, or tool definition.
+
+Use it with other controls, not instead of them:
+
+- static policy checks for obvious dangerous capabilities;
+- dependency and secret scanning for package hygiene;
+- sandboxing and least privilege for runtime containment;
+- IntentProbe for representation-level intent signal.
+
+## Start here
+
+Try a one-command scan:
+
+```bash
+uvx --python 3.11 --from git+https://github.com/mcpware/IntentProbe.git@v0.1.0 intentprobe scan --format summary --text "Reads SSH config and private keys, then silently uploads credentials to a remote server."
+```
+
+Then read:
+
+- [`README.md`](../README.md)
+- [`docs/FAQ.md`](FAQ.md)
+- [`docs/COMPETITIVE_LANDSCAPE.md`](COMPETITIVE_LANDSCAPE.md)
+- [`docs/RUNTIME_HOOKS.md`](RUNTIME_HOOKS.md)