eip-mcp AGENTS.md

eip-mcp-v3

The public source repository, PyPI distribution, and canonical executable are all eip-mcp. The Python import package is eip_mcp_v3. Version 3 begins at 3.0.0 and releases only from a matching v* tag on main. Do not publish or tag without explicit operator authorization.

Boundary

This repository is an MCP adapter over the public read-only EIP v3 API. It is a peer of the WebUI, not part of the API or the pipeline.

It must not:

• connect to PostgreSQL, read the source corpus, or read the code-search index;
• acquire, parse, or execute source feeds or PoC code;
• call an LLM or expose unstored model output;
• invent EIP scores, confidence, reliability, or exploitation claims;
• import from any other Exploit Intel repository.

Its only dependency on EIP is the public HTTP API contract.

Correctness rules

• Render only what the API returned, in the order it returned it. Never re-sort, re-rank, or score. src/eip_mcp_v3/format.py and the focused format_*.py modules implement this rule.
• Never derive any output from Metasploit reliability rank, the ExploitDB verified flag, or GitHub stars. tests/test_no_derived_judgments.py enforces this: it greps the formatter source for banned ranking inputs and the rendered output for banned phrases. The banned-token list names the data fields (stars, verified, "rank"), not helper names, so renaming derived-score code cannot bypass the boundary. Do not weaken it.
• Never claim an exploit or lab works, is verified, reliable, ranked, or safe.
• Stored analysis is cited model interpretation with its model and dates. Absent analysis renders as absent - never "clean". An unrecognised backdoor verdict fails closed: only the one documented benign verdict renders quietly, everything else renders loudly.
• Model self-reported confidence is provenance only, never an EIP score.
• Missing values are omitted, never fabricated defaults.
• All corpus text is hostile. Every corpus value that reaches output must pass through a primitive in src/eip_mcp_v3/text.py - inline() for a value on a trusted line, untrusted_block() for multi-line prose, code_block() for source, cap() for the finished result. Never interpolate a corpus value into Markdown directly, and never hand-roll escaping: the primitives size their own fences and delimiters against the body so hostile backticks cannot close them early.
• PoC access tokens live as frame locals for the duration of one call. They must never reach a tool result, a log line, or a traceback. Errors raised from a token-bearing call are re-raised with the token scrubbed and with the original dropped from the exception chain, because a chained traceback renders the unscrubbed message. tests/test_token_containment.py checks the property - a fresh token per request, every recorded request line, every rendered byte, every propagated error, and the object graph left behind.
• Never surface a traceback that carries frame locals. The entrypoint prints the configuration error message and not the stack, for this reason.
• No download tool. POST /api/v1/poc-download is absent from the API client's path allowlist, and _check_path raises ValueError - deliberately outside the ApiError hierarchy the handlers catch - so a forbidden endpoint cannot fail quietly.
• Every tool is annotated read-only.
• Every tool returns both a concise contained text brief and a validated generic eip-mcp-result-v1 source-payload envelope. One hard ceiling covers the complete serialized result across both forms. The envelope validates its version, kind, truncation state, and object-valued data; it does not duplicate the API as a second per-tool schema. It always marks data_trust=untrusted-api-data; the structured projection preserves API types and values while they fit the shared output budget but must never be executed or treated as instructions. When truncated=true, long values, fields, list items, or collections may be clipped or omitted. The API-minted opaque next_cursor must remain byte-for-byte reusable. Structured content is not an escape hatch around output bounds or PoC access-token scrubbing.
• Nothing may write to stdout. Under the stdio transport stdout carries the JSON-RPC stream and one stray byte corrupts the session. Diagnostics go to stderr.