Repository navigation
1.1.0: MCP server and Claude Code hook
ai-surface now runs inside the AI coding tools that write the code: as an MCP server, and as an automatic post-edit hook for Claude Code. The finding arrives at the moment the surface is created, not at PR time.
Added
- MCP server:
ai-surface mcp. A stdio Model Context Protocol server any MCP client can launch (Claude Code, Cursor, Windsurf, Cline). Two tools:scan_ai_surface(path, max_surfaces)inventories a path with counts, top risks, governance frameworks, and the highest-severity surfaces;check_new_ai_surface(path, baseline_file)reports only what is NEW, MODIFIED, or REMOVED since the previous call, or since a given committed baseline. Every entry carries the compliance block (OWASP LLM Top 10 ids, EU AI Act / NIST AI RMF / ISO 42001 clauses, remediation). Read-only, offline, no network listener. Installed with the optional extrapip install "apisec-ai-surface[mcp]"(Python 3.10+; works with mcp 1.x and 2.x). - Claude Code hook:
ai-surface hook claude-code. APostToolUsehook that diffs the AI surface after everyEdit/Write/MultiEdit/NotebookEdit/Bashcall and injects the finding into the session when a change introduces or expands AI surface, plus aSessionStartmode that seeds the baseline so the very first surface-adding edit is caught. Silent on ordinary edits, exits 0 on every internal error so it never breaks the editor, refuses to scan a home directory or filesystem root, and scans once per edit (in-process).--resetforgets the rolling baseline. ai-surface init --claude-code. Writes the hook into.claude/settings.jsonand the MCP server into.mcp.jsonfor the current repo, merging with existing entries and idempotent on re-run.docs/INTEGRATIONS.mdcovering both integrations, the hook contract, state location, and troubleshooting.
Changed
- Integration state lives outside the repository. The rolling baselines used by the MCP tool and the hook are stored under a per-user state directory (
$XDG_CACHE_HOME/ai-surface,~/.cache/ai-surface, or%LOCALAPPDATA%\ai-surface; override withAI_SURFACE_STATE_DIR), keyed by repo path. They never touch a committed.ai-surface-baseline.json, which stays a reviewable CI control, and never appear as untracked files. - Diff JSON carries governance standards.
scan --baseline -o json(and the Action's diff) now serializes added and removed findings through the JSON reporter, so their risk flags include thestandardsjoin exactly as in a full report. Additive; schema version unchanged. - The self-test matrix and the security scan install the
[mcp]extra so the MCP protocol round-trip runs in CI on Python 3.10+.
Install: pip install "apisec-ai-surface[mcp]" then ai-surface init --claude-code. Full guide: docs/INTEGRATIONS.md.