perplexity-agent-mcp CLAUDE.md

Working on perplexity-agent-mcp

This file is guardrails for an agent contributing to this repository, not a summary of what it does — read README.md for that. It exists because this project has a specific, easy-to-trip failure mode: a well-intentioned change that looks like an obvious improvement and quietly breaks the one property the whole repo exists to have. Two concrete examples that would each pass a casual glance:

• Adding requests (or any other third-party package) because it's more ergonomic than urllib.request. This project's entire pitch is zero runtime dependencies — see SECURITY.md for why that's a security property, not a style preference.
• Adding a print() for debugging and forgetting to remove it, or having any code path write to the real stdout. stdout is the JSON-RPC protocol stream; one stray line corrupts it, and the client-side symptom is a baffling parse error, not an obvious crash.

Both are mechanically caught before merge (tests/test_no_dependencies.py; the stdout-rebind + tests/test_no_secrets.py), but catching a mistake in CI is worse than not making it. This file exists so you don't make it.

Also read: CONTRIBUTING.md for the contributor workflow, SECURITY.md for the full threat model, and docs/specs/2026-07-22-perplexity-agent-mcp-design.md for the original design rationale. If any of those, or this file, disagree with perplexity_agent_mcp.py itself, the code is correct and the doc is stale — fix the doc, don't trust it over the source.

1. Hard invariants

Every one of these applies to every change, no exceptions without discussing it with the maintainer first. Quoted from the implementation plan's Global Constraints:

• Zero third-party runtime dependencies in the server, and no extras either. stdlib only. No requirements.txt, no MCP SDK, no pip install for users. The llm adapter has dependencies, but it is a separate distribution built from llm-plugin/ — installing the server never pulls it in. Enforced by tests/test_no_dependencies.py, which allows the adapter exactly two dependencies and the server none.
• Python floor >=3.10. No match statements requiring 3.11+, no tomllib in the server itself (3.11+), no PEP 695 generics. Develop on 3.14.6; CI matrix covers 3.10–3.14.
• Single outbound host: https://api.perplexity.ai only. Hardcoded constant. No environment-variable base-URL override — it is an API-key exfiltration vector (SECURITY.md §Network).
• The API key is never printed, logged, echoed, or attached to an exception. Read from PERPLEXITY_API_KEY at call time, not import time.
• stdout is exclusively JSON-RPC. All logging goes to stderr. main() calls _claim_stdout(), which grabs the real stdout and points sys.stdout at stderr. It is deliberately NOT an import-time side effect: the llm adapter imports this module, and hijacking stdout on import would redirect that whole program's output. Don't move it back.
• Two MCP protocol revisions, one process. Modern 2026-07-28 (stateless, no handshake) and legacy 2025-11-25 / 2025-06-18 / 2025-03-26. Era is decided per request, structurally — never by a flag, a setting, or state carried from an earlier request. The three precedence rules live above HANDLERS in the source; that comment is the authority, not this line.
• Never error on version negotiation — in initialize only. Echo the requested legacy version on a match, else return 2025-11-25. The modern path has the opposite rule and MUST return -32022 for a revision it does not speak. Do not unify these two. They are pinned by tests from opposite sides precisely because unifying them looks like a tidy-up.
• 2026-07-28 must never enter SUPPORTED_PROTOCOL_VERSIONS, which is the legacy-negotiable set. It is derived from the tail of ADVERTISED_PROTOCOL_VERSIONS so this is impossible rather than merely forbidden; keep the derivation.
• Validation errors are isError: true, never JSON-RPC -32602 (SEP-1303 — see §3 below).
• Line length 100. Ruff-formatted. mypy --strict clean. Every public function annotated.
• Comment density is high by design. This file's product is auditability; a reader must follow it top to bottom without cross-referencing.
• Copyright: Copyright (c) 2026, Constantin Gonzalez. License: BSD-3-Clause.
• Never claim cancellation reduces the bill — in code comments, tool descriptions, or docs.