frame-mcp 0.1.0__tar.gz

frame_mcp-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

frame_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.5
+Name: frame-mcp
+Version: 0.1.0
+Summary: Model Context Protocol server for the Frame security scanner.
+Project-URL: Homepage, https://github.com/lambdasec/frame
+Project-URL: Repository, https://github.com/lambdasec/frame-mcp
+Author: lambdasec
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: frame,mcp,sast,security,taint-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: frame-security[scan]>=1.0.0
+Requires-Dist: mcp>=1.2.0
+Description-Content-Type: text/markdown
+
+# frame-mcp
+
+mcp-name: io.github.lambdasec/frame-mcp
+
+An MCP server that exposes the [Frame](https://github.com/lambdasec/frame) security scanner to any MCP client, so a coding agent can scan code, verify fixes, and reason about vulnerabilities over stdio.
+
+Frame combines taint analysis with separation logic verification to find data-flow vulnerabilities (SQL injection, command injection, path traversal, and more), and checks each reported path with a solver. This package wraps the `frame` command line program as MCP tools. It launches `frame` as a subprocess with an explicit argument list, never a shell, and prefers the `frame` executable installed next to the running Python interpreter.
+
+## Install
+
+Run directly with uvx (no separate install step):
+
+```bash
+uvx frame-mcp
+```
+
+### Claude Code
+
+```bash
+claude mcp add frame -- uvx frame-mcp
+```
+
+### Codex
+
+Add this stanza to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.frame]
+command = "uvx"
+args = ["frame-mcp"]
+```
+
+### Cursor
+
+Create `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "frame": {
+      "command": "uvx",
+      "args": ["frame-mcp"]
+    }
+  }
+}
+```
+
+### VS Code
+
+Create `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "frame": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["frame-mcp"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json` under the `mcpServers` key:
+
+```json
+{
+  "mcpServers": {
+    "frame": {
+      "command": "uvx",
+      "args": ["frame-mcp"]
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Add to `~/.gemini/settings.json` under the `mcpServers` key:
+
+```json
+{
+  "mcpServers": {
+    "frame": {
+      "command": "uvx",
+      "args": ["frame-mcp"]
+    }
+  }
+}
+```
+
+### Zed
+
+Add to Zed `settings.json` under `context_servers`:
+
+```json
+{
+  "context_servers": {
+    "frame": {
+      "command": {
+        "path": "uvx",
+        "args": ["frame-mcp"]
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Purpose | Read only |
+| --- | --- | --- |
+| `scan` | Scan a file or directory for vulnerabilities and return findings as JSON. | yes |
+| `write_baseline` | Scan a path and record the findings as a baseline file. | no |
+| `verify` | Re-scan the files behind earlier findings and report whether each is fixed. | yes |
+| `fix` | Generate and verify fixes for findings. Returns a diff by default. | no |
+| `exploit` | Drive an agent to exploit a live, authorized target. | no |
+| `packs_list` | List the framework packs a scan would load. | yes |
+| `packs_check` | Validate framework pack files. | yes |
+| `solve` | Check a separation logic entailment `P \|- Q`. | yes |
+
+A `security-review` prompt chains `scan` (with the AI layer), `verify`, and an offer to `fix`.
+
+## AI features and environment variables
+
+The `scan` tool with `ai=true`, along with `fix` and `exploit`, call an LLM through an OpenAI-compatible endpoint. Configure it with these environment variables in the MCP client that launches the server:
+
+| Variable | Purpose |
+| --- | --- |
+| `FRAME_LLM_BASE_URL` | Base URL of the LLM endpoint, for example a local server or a hosted API. |
+| `FRAME_LLM_API_KEY` | API key for the endpoint, when it requires one. |
+| `FRAME_LLM_MODEL` | Model name to request. |
+| `FRAME_LLM_REPO_ROOT` | Repository root for relative path resolution. |
+
+These are inherited from the server process environment and forwarded to each `frame` subprocess. The plain `scan` (taint analysis plus verification) needs none of them.
+
+## Exploit authorization
+
+The `exploit` tool drives an autonomous agent that sends live traffic to a target. Run it only against systems you own or are explicitly authorized to test. Unauthorized testing of systems you do not control may be illegal.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

frame_mcp-0.1.0/README.md

@@ -0,0 +1,145 @@
+# frame-mcp
+
+mcp-name: io.github.lambdasec/frame-mcp
+
+An MCP server that exposes the [Frame](https://github.com/lambdasec/frame) security scanner to any MCP client, so a coding agent can scan code, verify fixes, and reason about vulnerabilities over stdio.
+
+Frame combines taint analysis with separation logic verification to find data-flow vulnerabilities (SQL injection, command injection, path traversal, and more), and checks each reported path with a solver. This package wraps the `frame` command line program as MCP tools. It launches `frame` as a subprocess with an explicit argument list, never a shell, and prefers the `frame` executable installed next to the running Python interpreter.
+
+## Install
+
+Run directly with uvx (no separate install step):
+
+```bash
+uvx frame-mcp
+```
+
+### Claude Code
+
+```bash
+claude mcp add frame -- uvx frame-mcp
+```
+
+### Codex
+
+Add this stanza to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.frame]
+command = "uvx"
+args = ["frame-mcp"]
+```
+
+### Cursor
+
+Create `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "frame": {
+      "command": "uvx",
+      "args": ["frame-mcp"]
+    }
+  }
+}
+```
+
+### VS Code
+
+Create `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "frame": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["frame-mcp"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json` under the `mcpServers` key:
+
+```json
+{
+  "mcpServers": {
+    "frame": {
+      "command": "uvx",
+      "args": ["frame-mcp"]
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Add to `~/.gemini/settings.json` under the `mcpServers` key:
+
+```json
+{
+  "mcpServers": {
+    "frame": {
+      "command": "uvx",
+      "args": ["frame-mcp"]
+    }
+  }
+}
+```
+
+### Zed
+
+Add to Zed `settings.json` under `context_servers`:
+
+```json
+{
+  "context_servers": {
+    "frame": {
+      "command": {
+        "path": "uvx",
+        "args": ["frame-mcp"]
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Purpose | Read only |
+| --- | --- | --- |
+| `scan` | Scan a file or directory for vulnerabilities and return findings as JSON. | yes |
+| `write_baseline` | Scan a path and record the findings as a baseline file. | no |
+| `verify` | Re-scan the files behind earlier findings and report whether each is fixed. | yes |
+| `fix` | Generate and verify fixes for findings. Returns a diff by default. | no |
+| `exploit` | Drive an agent to exploit a live, authorized target. | no |
+| `packs_list` | List the framework packs a scan would load. | yes |
+| `packs_check` | Validate framework pack files. | yes |
+| `solve` | Check a separation logic entailment `P \|- Q`. | yes |
+
+A `security-review` prompt chains `scan` (with the AI layer), `verify`, and an offer to `fix`.
+
+## AI features and environment variables
+
+The `scan` tool with `ai=true`, along with `fix` and `exploit`, call an LLM through an OpenAI-compatible endpoint. Configure it with these environment variables in the MCP client that launches the server:
+
+| Variable | Purpose |
+| --- | --- |
+| `FRAME_LLM_BASE_URL` | Base URL of the LLM endpoint, for example a local server or a hosted API. |
+| `FRAME_LLM_API_KEY` | API key for the endpoint, when it requires one. |
+| `FRAME_LLM_MODEL` | Model name to request. |
+| `FRAME_LLM_REPO_ROOT` | Repository root for relative path resolution. |
+
+These are inherited from the server process environment and forwarded to each `frame` subprocess. The plain `scan` (taint analysis plus verification) needs none of them.
+
+## Exploit authorization
+
+The `exploit` tool drives an autonomous agent that sends live traffic to a target. Run it only against systems you own or are explicitly authorized to test. Unauthorized testing of systems you do not control may be illegal.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

frame_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "frame-mcp"
+version = "0.1.0"
+description = "Model Context Protocol server for the Frame security scanner."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "lambdasec" }]
+keywords = ["mcp", "security", "sast", "frame", "taint-analysis"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+]
+dependencies = [
+    "frame-security[scan]>=1.0.0",
+    "mcp>=1.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/lambdasec/frame"
+Repository = "https://github.com/lambdasec/frame-mcp"
+
+[project.scripts]
+frame-mcp = "frame_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/frame_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/frame_mcp",
+    "README.md",
+    "LICENSE",
+    "server.json",
+    "tests",
+]

frame_mcp-0.1.0/server.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.lambdasec/frame-mcp",
+  "description": "MCP server for the Frame security scanner: scan, verify, fix, exploit, packs and separation logic.",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/lambdasec/frame-mcp",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "frame-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "FRAME_LLM_BASE_URL",
+          "description": "Base URL of an OpenAI-compatible LLM endpoint for the AI detection, triage, fix and exploit features.",
+          "isRequired": false
+        },
+        {
+          "name": "FRAME_LLM_API_KEY",
+          "description": "API key for the LLM endpoint, when the endpoint requires one.",
+          "isRequired": false,
+          "isSecret": true
+        },
+        {
+          "name": "FRAME_LLM_MODEL",
+          "description": "Model name to request from the LLM endpoint.",
+          "isRequired": false
+        },
+        {
+          "name": "FRAME_LLM_REPO_ROOT",
+          "description": "Repository root the LLM layer resolves relative paths against.",
+          "isRequired": false
+        }
+      ]
+    }
+  ]
+}

frame_mcp-0.1.0/src/frame_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""frame-mcp: a Model Context Protocol server for the Frame security scanner."""
+
+__version__ = "0.1.0"

frame_mcp-0.1.0/src/frame_mcp/server.py

@@ -0,0 +1,455 @@
+"""MCP stdio server that exposes the Frame security scanner CLI as tools.
+
+The server shells out to the ``frame`` command line program using an explicit
+argument list (never ``shell=True``). It prefers the ``frame`` executable that
+sits next to the running Python interpreter, falling back to ``PATH``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any, Optional, Union
+
+try:
+    # mcp 1.x
+    from mcp.server.fastmcp import FastMCP as _Server
+except ModuleNotFoundError:
+    # mcp 2.x renamed FastMCP to MCPServer
+    from mcp.server.mcpserver import MCPServer as _Server
+
+from mcp.types import ToolAnnotations
+
+FindingsInput = Union[str, dict, list]
+
+# Environment variables the Frame LLM layer reads. They are inherited from the
+# server process environment and forwarded to every subprocess.
+_FRAME_LLM_ENV = (
+    "FRAME_LLM_BASE_URL",
+    "FRAME_LLM_API_KEY",
+    "FRAME_LLM_MODEL",
+    "FRAME_LLM_REPO_ROOT",
+)
+
+mcp = _Server("frame")
+
+
+# --------------------------------------------------------------------------
+# process helpers
+# --------------------------------------------------------------------------
+def _frame_executable() -> str:
+    """Resolve the frame binary: next to sys.executable first, then PATH."""
+    candidate = Path(sys.executable).resolve().parent / "frame"
+    if candidate.is_file():
+        return str(candidate)
+    found = shutil.which("frame")
+    if found:
+        return found
+    # Let subprocess raise a clear FileNotFoundError if it is genuinely absent.
+    return "frame"
+
+
+def _subprocess_env() -> dict:
+    """Copy the current environment (carries the FRAME_LLM_* passthrough)."""
+    env = os.environ.copy()
+    # Explicit: ensure the documented variables survive even if a caller
+    # restricted the inherited environment. Absent ones are simply skipped.
+    for name in _FRAME_LLM_ENV:
+        value = os.environ.get(name)
+        if value is not None:
+            env[name] = value
+    return env
+
+
+def _parse_output(proc: subprocess.CompletedProcess) -> Any:
+    """Return parsed JSON stdout, else a raw stdout/stderr/exit_code fallback."""
+    text = proc.stdout or ""
+    try:
+        return json.loads(text)
+    except (ValueError, TypeError):
+        return {
+            "stdout": text,
+            "stderr": proc.stderr or "",
+            "exit_code": proc.returncode,
+        }
+
+
+def _run_frame(
+    args: list[str],
+    *,
+    timeout: float,
+    ok_codes: tuple[int, ...] = (0, 1),
+) -> Any:
+    """Run ``frame <args>`` and return parsed JSON, raising on an error exit.
+
+    Exit codes in ``ok_codes`` (default 0 and 1) are treated as success. Any
+    other code (for example 2, the "cannot verify" status) is surfaced as an
+    error that carries the captured stderr.
+    """
+    cmd = [_frame_executable(), *args]
+    try:
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            env=_subprocess_env(),
+            timeout=timeout,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        raise RuntimeError(
+            "The 'frame' executable was not found. Install frame-security "
+            "with: pip install 'frame-security[scan]'."
+        ) from exc
+    except subprocess.TimeoutExpired as exc:
+        raise RuntimeError(
+            f"frame timed out after {timeout:g}s: {' '.join(args)}"
+        ) from exc
+
+    if proc.returncode not in ok_codes:
+        stderr = (proc.stderr or "").strip()
+        stdout = (proc.stdout or "").strip()
+        detail = stderr or stdout or "no output"
+        raise RuntimeError(
+            f"frame exited with status {proc.returncode}: {detail}"
+        )
+    return _parse_output(proc)
+
+
+def _write_findings_tempfile(findings_json: FindingsInput) -> str:
+    """Accept a JSON string or an object and write it to a temp file.
+
+    Returns the path to a temporary file the caller is responsible for
+    deleting.
+    """
+    if isinstance(findings_json, (dict, list)):
+        payload = json.dumps(findings_json)
+    else:
+        payload = str(findings_json)
+    handle = tempfile.NamedTemporaryFile(
+        mode="w", suffix=".json", delete=False, encoding="utf-8"
+    )
+    try:
+        handle.write(payload)
+    finally:
+        handle.close()
+    return handle.name
+
+
+# --------------------------------------------------------------------------
+# argument builders (pure functions, unit tested without any process launch)
+# --------------------------------------------------------------------------
+def _build_scan_args(
+    path: str,
+    language: Optional[str] = None,
+    ai: bool = False,
+    changed_ref: Optional[str] = None,
+    files: Optional[list[str]] = None,
+    baseline: Optional[str] = None,
+    min_severity: Optional[str] = None,
+    fail_on: str = "none",
+    root: Optional[str] = None,
+    no_cross_file: bool = False,
+    packs: Optional[list[str]] = None,
+) -> list[str]:
+    args = ["scan", path, "-f", "json", "--fail-on", fail_on]
+    if language:
+        args += ["-l", language]
+    if ai:
+        args += ["--ai"]
+    if changed_ref is not None:
+        args += ["--changed", changed_ref]
+    if files:
+        args += ["--files", *files]
+    if baseline:
+        args += ["--baseline", baseline]
+    if min_severity:
+        args += ["--min-severity", min_severity]
+    if root:
+        args += ["--root", root]
+    if no_cross_file:
+        args += ["--no-cross-file"]
+    for pack in packs or []:
+        args += ["--pack", pack]
+    return args
+
+
+def _build_write_baseline_args(path: str, baseline_file: str) -> list[str]:
+    return ["scan", path, "--write-baseline", baseline_file, "--fail-on", "none"]
+
+
+def _build_verify_args(
+    findings_source: str, ids: Optional[list[str]] = None
+) -> list[str]:
+    args = ["verify", findings_source, "-f", "json"]
+    for fp in ids or []:
+        args += ["--id", fp]
+    return args
+
+
+def _build_fix_args(
+    path: str, guidance_file: str, in_place: bool = False
+) -> list[str]:
+    args = ["fix", path, "--guidance", guidance_file, "--format", "json"]
+    if in_place:
+        args += ["--in-place"]
+    return args
+
+
+def _build_exploit_args(
+    target: str,
+    guidance_file: Optional[str] = None,
+    goal: Optional[str] = None,
+    success_check: Optional[str] = None,
+    max_steps: Optional[int] = None,
+) -> list[str]:
+    args = ["exploit", "--target", target, "--format", "json"]
+    if guidance_file:
+        args += ["--guidance", guidance_file]
+    if goal:
+        args += ["--goal", goal]
+    if success_check:
+        args += ["--success-check", success_check]
+    if max_steps is not None:
+        args += ["--max-steps", str(max_steps)]
+    return args
+
+
+def _build_solve_args(entailment: str, model: bool = False) -> list[str]:
+    args = ["solve", entailment, "--format", "json"]
+    if model:
+        args += ["--model"]
+    return args
+
+
+def _build_packs_list_args(path: Optional[str] = None) -> list[str]:
+    args = ["packs", "list"]
+    if path:
+        args += ["--project", path]
+    return args
+
+
+def _build_packs_check_args(files: list[str]) -> list[str]:
+    return ["packs", "check", *files]
+
+
+# --------------------------------------------------------------------------
+# tools
+# --------------------------------------------------------------------------
+@mcp.tool(
+    annotations=ToolAnnotations(title="Scan source for vulnerabilities", readOnlyHint=True),
+)
+def scan(
+    path: str,
+    language: Optional[str] = None,
+    ai: bool = False,
+    changed_ref: Optional[str] = None,
+    files: Optional[list[str]] = None,
+    baseline: Optional[str] = None,
+    min_severity: Optional[str] = None,
+    fail_on: str = "none",
+    root: Optional[str] = None,
+    no_cross_file: bool = False,
+    packs: Optional[list[str]] = None,
+) -> Any:
+    """Scan a file or directory for security vulnerabilities with Frame.
+
+    Runs taint analysis plus separation logic verification and returns the
+    findings as JSON. Set ``ai=True`` to add the LLM detection and triage
+    layer (needs the FRAME_LLM_* environment variables). ``changed_ref`` scans
+    only files that differ from a git ref; ``files`` restricts the scan to a
+    list of files; ``baseline`` reports only findings absent from a baseline
+    file; ``packs`` loads extra framework packs. This tool does not modify any
+    files.
+    """
+    args = _build_scan_args(
+        path,
+        language=language,
+        ai=ai,
+        changed_ref=changed_ref,
+        files=files,
+        baseline=baseline,
+        min_severity=min_severity,
+        fail_on=fail_on,
+        root=root,
+        no_cross_file=no_cross_file,
+        packs=packs,
+    )
+    timeout = 1800.0 if ai else 300.0
+    return _run_frame(args, timeout=timeout, ok_codes=(0, 1))
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        title="Write a scan baseline file",
+        readOnlyHint=False,
+        destructiveHint=False,
+    ),
+)
+def write_baseline(path: str, baseline_file: str) -> Any:
+    """Scan ``path`` and record the findings as a baseline file.
+
+    Writes ``baseline_file`` to disk (creating or overwriting it) and uses
+    ``--fail-on none`` so the current state is accepted. Later scans can pass
+    this file as ``baseline`` to report only new findings.
+    """
+    args = _build_write_baseline_args(path, baseline_file)
+    return _run_frame(args, timeout=300.0, ok_codes=(0, 1))
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(title="Verify earlier findings are fixed", readOnlyHint=True),
+)
+def verify(findings_json: FindingsInput, ids: Optional[list[str]] = None) -> Any:
+    """Re-scan the files behind earlier findings and report their status.
+
+    ``findings_json`` is the JSON produced by ``scan`` (a JSON string or the
+    parsed object). Each finding comes back as fixed, file_removed, present,
+    suppressed, uncertain or unverifiable. Pass ``ids`` (finding fingerprints)
+    to check only specific findings. This tool does not modify any files.
+    """
+    findings_file = _write_findings_tempfile(findings_json)
+    try:
+        args = _build_verify_args(findings_file, ids=ids)
+        return _run_frame(args, timeout=300.0, ok_codes=(0, 1))
+    finally:
+        _safe_unlink(findings_file)
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        title="Generate verified security fixes",
+        readOnlyHint=False,
+        destructiveHint=True,
+    ),
+)
+def fix(path: str, findings_json: FindingsInput, in_place: bool = False) -> Any:
+    """Generate and verify fixes for scan findings.
+
+    By default this returns a unified diff and does not touch any files. Set
+    ``in_place=True`` to write the patches to the source files. Each patch is
+    verified by re-scanning the patched code. This tool needs the FRAME_LLM_*
+    environment variables (FRAME_LLM_BASE_URL, FRAME_LLM_MODEL, and an API key
+    when the endpoint requires one).
+    """
+    findings_file = _write_findings_tempfile(findings_json)
+    try:
+        args = _build_fix_args(path, findings_file, in_place=in_place)
+        return _run_frame(args, timeout=1800.0, ok_codes=(0, 1))
+    finally:
+        _safe_unlink(findings_file)
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        title="Drive an exploitation agent against a target",
+        readOnlyHint=False,
+        destructiveHint=True,
+        openWorldHint=True,
+    ),
+)
+def exploit(
+    target: str,
+    findings_json: Optional[FindingsInput] = None,
+    goal: Optional[str] = None,
+    success_check: Optional[str] = None,
+    max_steps: Optional[int] = None,
+) -> Any:
+    """Drive an LLM agent to exploit a live target. Authorized use only.
+
+    Run this only against systems you own or are explicitly authorized to
+    test. ``target`` is a URL such as http://app:8080. Optionally prime the
+    agent with ``findings_json`` from ``scan``, a plain-language ``goal``, a
+    ``success_check`` shell command (exit 0 means solved), and ``max_steps``.
+    Needs the FRAME_LLM_* environment variables.
+    """
+    findings_file = (
+        _write_findings_tempfile(findings_json) if findings_json is not None else None
+    )
+    try:
+        args = _build_exploit_args(
+            target,
+            guidance_file=findings_file,
+            goal=goal,
+            success_check=success_check,
+            max_steps=max_steps,
+        )
+        return _run_frame(args, timeout=1800.0, ok_codes=(0, 1))
+    finally:
+        if findings_file is not None:
+            _safe_unlink(findings_file)
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(title="List loadable framework packs", readOnlyHint=True),
+)
+def packs_list(path: Optional[str] = None) -> Any:
+    """List the framework packs a scan would load.
+
+    Packs teach Frame a framework's sources, sinks, sanitizers and entry
+    points. Pass ``path`` to include a project directory's .frame/packs.
+    """
+    args = _build_packs_list_args(path)
+    return _run_frame(args, timeout=60.0, ok_codes=(0, 1))
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(title="Validate framework pack files", readOnlyHint=True),
+)
+def packs_check(files: list[str]) -> Any:
+    """Validate one or more framework pack .toml files or directories."""
+    args = _build_packs_check_args(files)
+    return _run_frame(args, timeout=60.0, ok_codes=(0, 1))
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(title="Check a separation logic entailment", readOnlyHint=True),
+)
+def solve(entailment: str, model: bool = False) -> Any:
+    """Check whether a separation logic entailment ``P |- Q`` is valid.
+
+    Example entailment: ``x |-> 5 |- x |-> 5``. Set ``model=True`` to return a
+    countermodel when the entailment is invalid.
+    """
+    args = _build_solve_args(entailment, model=model)
+    return _run_frame(args, timeout=60.0, ok_codes=(0, 1))
+
+
+def _safe_unlink(path: str) -> None:
+    try:
+        os.unlink(path)
+    except OSError:
+        pass
+
+
+# --------------------------------------------------------------------------
+# prompt
+# --------------------------------------------------------------------------
+@mcp.prompt(name="security-review")
+def security_review(path: str) -> str:
+    """Scan a project with the AI layer, verify, then offer to fix."""
+    return (
+        f"Review the code at '{path}' for security vulnerabilities.\n\n"
+        "1. Call the 'scan' tool with path set to this location and ai=true to "
+        "run taint analysis plus the LLM detection and triage layer.\n"
+        "2. Pass the scan result to the 'verify' tool to confirm which findings "
+        "are still present.\n"
+        "3. Summarize each confirmed finding (CWE, file, line, data flow). For "
+        "findings that remain present, offer to call the 'fix' tool, which "
+        "returns a verified diff by default (or writes changes with "
+        "in_place=true). Do not fix anything without the user's go-ahead."
+    )
+
+
+def main() -> None:
+    """Console-script entry point: run the stdio MCP server."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

frame_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,192 @@
+"""Unit tests for frame-mcp argument building. No network, no subprocess."""
+
+import json
+import os
+import unittest
+
+from frame_mcp import server
+
+
+class ScanArgsTest(unittest.TestCase):
+    def test_minimal_defaults(self):
+        args = server._build_scan_args("/code")
+        self.assertEqual(
+            args, ["scan", "/code", "-f", "json", "--fail-on", "none"]
+        )
+
+    def test_all_options(self):
+        args = server._build_scan_args(
+            "/code",
+            language="python",
+            ai=True,
+            changed_ref="HEAD~1",
+            files=["a.py", "b.py"],
+            baseline="base.json",
+            min_severity="high",
+            fail_on="critical",
+            root="/root",
+            no_cross_file=True,
+            packs=["p1.toml", "p2.toml"],
+        )
+        self.assertEqual(
+            args,
+            [
+                "scan", "/code", "-f", "json", "--fail-on", "critical",
+                "-l", "python",
+                "--ai",
+                "--changed", "HEAD~1",
+                "--files", "a.py", "b.py",
+                "--baseline", "base.json",
+                "--min-severity", "high",
+                "--root", "/root",
+                "--no-cross-file",
+                "--pack", "p1.toml",
+                "--pack", "p2.toml",
+            ],
+        )
+
+    def test_changed_ref_empty_string_included(self):
+        # An empty ref is meaningful (frame treats --changed with no value as HEAD).
+        args = server._build_scan_args("/code", changed_ref="")
+        self.assertIn("--changed", args)
+        self.assertEqual(args[args.index("--changed") + 1], "")
+
+
+class WriteBaselineArgsTest(unittest.TestCase):
+    def test_args(self):
+        self.assertEqual(
+            server._build_write_baseline_args("/code", "b.json"),
+            ["scan", "/code", "--write-baseline", "b.json", "--fail-on", "none"],
+        )
+
+
+class VerifyArgsTest(unittest.TestCase):
+    def test_no_ids(self):
+        self.assertEqual(
+            server._build_verify_args("f.json"),
+            ["verify", "f.json", "-f", "json"],
+        )
+
+    def test_with_ids(self):
+        self.assertEqual(
+            server._build_verify_args("-", ids=["aa", "bb"]),
+            ["verify", "-", "-f", "json", "--id", "aa", "--id", "bb"],
+        )
+
+
+class FixArgsTest(unittest.TestCase):
+    def test_default_diff(self):
+        args = server._build_fix_args("/code", "g.json")
+        self.assertEqual(
+            args, ["fix", "/code", "--guidance", "g.json", "--format", "json"]
+        )
+        self.assertNotIn("--in-place", args)
+
+    def test_in_place(self):
+        args = server._build_fix_args("/code", "g.json", in_place=True)
+        self.assertIn("--in-place", args)
+
+
+class ExploitArgsTest(unittest.TestCase):
+    def test_minimal(self):
+        self.assertEqual(
+            server._build_exploit_args("http://app:8080"),
+            ["exploit", "--target", "http://app:8080", "--format", "json"],
+        )
+
+    def test_full(self):
+        args = server._build_exploit_args(
+            "http://app:8080",
+            guidance_file="g.json",
+            goal="read a secret",
+            success_check="test -f /tmp/pwned",
+            max_steps=10,
+        )
+        self.assertEqual(
+            args,
+            [
+                "exploit", "--target", "http://app:8080", "--format", "json",
+                "--guidance", "g.json",
+                "--goal", "read a secret",
+                "--success-check", "test -f /tmp/pwned",
+                "--max-steps", "10",
+            ],
+        )
+
+
+class SolveArgsTest(unittest.TestCase):
+    def test_no_model(self):
+        self.assertEqual(
+            server._build_solve_args("x |-> 5 |- x |-> 5"),
+            ["solve", "x |-> 5 |- x |-> 5", "--format", "json"],
+        )
+
+    def test_with_model(self):
+        self.assertEqual(
+            server._build_solve_args("emp |- x |-> 5", model=True),
+            ["solve", "emp |- x |-> 5", "--format", "json", "--model"],
+        )
+
+
+class PacksArgsTest(unittest.TestCase):
+    def test_list_no_path(self):
+        self.assertEqual(server._build_packs_list_args(), ["packs", "list"])
+
+    def test_list_with_path(self):
+        self.assertEqual(
+            server._build_packs_list_args("/proj"),
+            ["packs", "list", "--project", "/proj"],
+        )
+
+    def test_check(self):
+        self.assertEqual(
+            server._build_packs_check_args(["a.toml", "b.toml"]),
+            ["packs", "check", "a.toml", "b.toml"],
+        )
+
+
+class FindingsTempfileTest(unittest.TestCase):
+    def test_dict_written_as_json(self):
+        path = server._write_findings_tempfile({"schema_version": 1, "files": []})
+        try:
+            with open(path, encoding="utf-8") as fh:
+                data = json.load(fh)
+            self.assertEqual(data["schema_version"], 1)
+        finally:
+            os.unlink(path)
+
+    def test_string_passthrough(self):
+        raw = '{"a": 1}'
+        path = server._write_findings_tempfile(raw)
+        try:
+            with open(path, encoding="utf-8") as fh:
+                self.assertEqual(fh.read(), raw)
+        finally:
+            os.unlink(path)
+
+
+class ParseOutputTest(unittest.TestCase):
+    class _Proc:
+        def __init__(self, stdout, stderr="", returncode=0):
+            self.stdout = stdout
+            self.stderr = stderr
+            self.returncode = returncode
+
+    def test_json_parsed(self):
+        out = server._parse_output(self._Proc('{"ok": true}'))
+        self.assertEqual(out, {"ok": True})
+
+    def test_non_json_fallback(self):
+        out = server._parse_output(self._Proc("not json", stderr="boom", returncode=1))
+        self.assertEqual(out["stdout"], "not json")
+        self.assertEqual(out["stderr"], "boom")
+        self.assertEqual(out["exit_code"], 1)
+
+
+class FrameExecutableTest(unittest.TestCase):
+    def test_returns_string(self):
+        self.assertIsInstance(server._frame_executable(), str)
+
+
+if __name__ == "__main__":
+    unittest.main()