Metadata-Version: 2.4
Name: flintai-mcp
Version: 0.1.0rc2
Summary: Flint AI platform MCP server: read-only AI-SPM issues, inventory, and remediation guidance for coding agents
Author: SandboxAQ
License: Apache-2.0
Project-URL: Repository, https://github.com/sandbox-quantum/flintai-mcp
Keywords: ai,mcp,security,ai-spm,flintai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.28
Requires-Dist: mcp<2,>=1.27
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == "dev"
Provides-Extra: audit
Requires-Dist: pip-licenses>=5.0; extra == "audit"
Requires-Dist: cyclonedx-bom>=6.0; extra == "audit"
Requires-Dist: pip-audit>=2.7; extra == "audit"
Requires-Dist: pip-tools>=7.4; extra == "audit"
Dynamic: license-file

# flintai-mcp

A local [MCP](https://modelcontextprotocol.io) server (stdio) that gives a coding
agent read-only access to a Flint AI backend's **AI-SPM issues, inventory, and
remediation guidance** so it can fix the flagged code.

It is a thin, authenticated REST client over the Flint AI API — no scanner runs
locally and no backend changes are required. Everything valuable (AI-reasoned
findings, rule-based issues, public-asset vuln enrichment, remediation guidance)
is already computed server-side and served over the existing API / static assets.

The package is named for the platform (`flintai-mcp`) rather than AI-SPM
specifically: v1 ships the AI-SPM tools, but it is intended to grow to cover other
Flint AI product domains (guardrails, ROI, …) over time.

> **This repository is generated.** `flintai-mcp` is developed in SandboxAQ's
> internal monorepo and mirrored here (which also builds and publishes the wheel
> to PyPI). Please file issues here; see [`CONTRIBUTING.md`](CONTRIBUTING.md) to
> propose changes.

> **Phase 1: read-only, remote-backed.** Fast verification of uncommitted fixes (a
> local scan + a synchronous backend "dry-run" endpoint) is a planned Phase 2 and
> is intentionally out of scope here.

## Install & run

The idiomatic way is via the published wheel with `uvx` (no clone, no build step):

```bash
uvx flintai-mcp
```

## Configuration

Set two environment variables:

| Variable           | Meaning                                                  |
| ------------------ | -------------------------------------------------------- |
| `FLINTAI_API_KEY`  | Flint AI API key (`sk_...`).                             |
| `FLINTAI_INSTANCE` | Flint instance base URL, e.g. `https://app.flintai.dev`. |

The instance URL is validated against a fail-closed host allowlist before any
credential is attached.

The **tenant and workspace are auto-discovered** from the API key at startup —
you do not configure any IDs. A key is pinned to exactly one tenant + active
workspace by the backend.

The API key is only ever sent in the `Authorization: ApiKey ...` header and is
never logged.

## Wiring into a coding agent

Add to your MCP client config (Claude Code `.mcp.json`, Cursor, etc.):

```jsonc
{
  "mcpServers": {
    "flintai-mcp": {
      "command": "uvx",
      "args": ["flintai-mcp"],
      "env": {
        "FLINTAI_API_KEY": "sk_...",
        "FLINTAI_INSTANCE": "https://app.flintai.dev"
      }
    }
  }
}
```

## Tools

**Fix-focused**

- `get_context` — show the resolved instance / tenant / workspace.
- `list_issues(severity?, rule_id?, category?, search?, page_size?, cursor?)` —
  list issues; paginated, `page_size` capped at 100.
- `get_issue(issue_id)` — issue detail + assembled rule-level remediation guidance
  + affected objects.
- `get_finding_detail(issue_id, object_id, detail_id?)` — per-finding file path,
  code snippet, evidence, and inline remediation.
- `find_issues_for_file(path, max_issues?)` — issues whose findings reference a
  given working-tree file (client-side scan; matches by shared path suffix).
  The scan follows pagination but is bounded — `max_issues` is capped at 500 and
  the call at 300 backend requests — and returns a `scan` block reporting
  `complete`, `issues_scanned`, `requests` and `errors`. **`complete: false`
  means the caps were hit and the file may have findings this result omits**;
  treat it as "unknown", not as "clean", and narrow the search with
  `list_issues` filters instead.
- `get_remediation_guidance(rule_name)` — rule-level remediation markdown.

**Inventory browse**

- `list_models | list_agents | list_tools | list_mcp_servers(name?, severity?, supplier?, library?, page_size?, cursor?)`
- `get_model | get_agent | get_tool | get_mcp_server(asset_id)` — detail plus
  attached issues, related assets, and code locations.

## Remediation guidance

Rule-level remediation markdown has **no dedicated API** — it is served by the
instance's web server as static assets at `{instance}/assets/docs-remediations/…`
(the same origin and files the web UI reads). This server fetches them at runtime
over HTTP through the shared client and caches them per session; nothing is
bundled into the package. When a rule has no docs (or the assets origin is
unreachable), fall back to the per-finding `remediation` text from
`get_finding_detail`.

For offline development or tests, set `FLINTAI_REMEDIATION_DIR` to a local directory
laid out like the assets (`rule-name-to-remediation-folder-map.json` + per-rule
folders); the loader then reads from disk and never touches the network.

## Development

- Layout: `src/flintai_mcp/` (`src/` layout), tests under `test/`.
- Editable install: `pip install -e '.[dev]'`, then run `flintai-mcp`.
- Docs are fetched from your instance at runtime; for offline work point
  `FLINTAI_REMEDIATION_DIR` at a local copy of the docs directory.

## Tests

```bash
pytest
```

Tests are hermetic (httpx `MockTransport` for the client and the remediation-docs
fetch, a fake client + `FLINTAI_REMEDIATION_DIR` for the tools), so they need no
network or live backend.
