Metadata-Version: 2.4
Name: osidb-mcp
Version: 0.1.0
Summary: Model Context Protocol (MCP) server for OSIDB using osidb-bindings
Project-URL: Homepage, https://github.com/RedHatProductSecurity/osidb
Project-URL: Repository, https://github.com/RedHatProductSecurity/osidb-bindings
Author: osidb-mcp contributors
License-Expression: MIT
License-File: LICENSE
Keywords: cve,kerberos,mcp,osidb,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT 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 :: Security
Requires-Python: >=3.10
Requires-Dist: mcp<2,>=1.0
Requires-Dist: osidb-bindings<6,>=5.10.0
Provides-Extra: dev
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# osidb-mcp

Python [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for [OSIDB](https://github.com/RedHatProductSecurity/osidb), built on [`osidb-bindings`](https://github.com/RedHatProductSecurity/osidb-bindings) from PyPI. Use it from Cursor, Claude Desktop, or any MCP client over **stdio**.

## Install

```bash
pipx install osidb-mcp
# or
pip install osidb-mcp
```

## Configuration (environment)

| Variable | Required | Description |
|----------|----------|-------------|
| `OSIDB_BASE_URL` | yes | OSIDB root URL, e.g. `https://osidb.example.com` |
| `OSIDB_AUTH` | no | `kerberos` (default) or `basic` |
| `OSIDB_USERNAME` / `OSIDB_PASSWORD` | for `basic` | Basic auth for token obtain |
| `OSIDB_VERIFY_SSL` | no | `true` (default) or `false` (prefer `REQUESTS_CA_BUNDLE` for custom CAs) |
| `OSIDB_USER_AGENT` | no | Optional extra User-Agent suffix |
| `OSIDB_MCP_ACCESS_MODE` | no | `readonly` (default) or `readwrite` (mutations reserved for a future release) |

Kerberos: the process must have a valid ticket (`kinit`) for the OSIDB HTTP service.

Optional keys forwarded by bindings: `BUGZILLA_API_KEY`, `JIRA_ACCESS_TOKEN`, `JIRA_API_EMAIL`.

## Cursor / Claude MCP snippet

```json
{
  "mcpServers": {
    "osidb": {
      "command": "osidb-mcp",
      "env": {
        "OSIDB_BASE_URL": "https://your-internal-osidb",
        "OSIDB_AUTH": "kerberos",
        "OSIDB_VERIFY_SSL": "true",
        "OSIDB_MCP_ACCESS_MODE": "readonly"
      }
    }
  }
}
```

## Tools (read-only)

- `osidb_status` — health / version style status
- `osidb_whoami` — `/osidb/whoami`
- `flaw_get` — single flaw with optional `include_fields` / `exclude_fields`
- `flaws_list` / `flaws_count` — filter by `components_in`, `affects_ps_module_in`, `workflow_state_in`, `impact` / `impact_in`, `owner_isempty`, embargo flags, ISO8601 `changed_after` / `changed_before`, plus allowlisted `extra_query` keys from the OSIDB OpenAPI
- `flaws_search` — full-text `search`
- `affects_list` — affect-centric rows with `ps_module` / `ps_component` / `ps_update_stream` and `flaw__*` filters
- `trackers_list` — tracker filings with CVE / module / component filters
- `flaw_comments_list`, `flaw_references_list`, `flaw_cvss_scores_list`

`limit` is capped at **100** per request.

## Analyst examples

- **Critical open flaws touching `httpd`:** `flaws_list` with `impact="CRITICAL"`, `workflow_state_in` set to the non-terminal states your instance uses, and `components_in=["httpd"]` or `affects_ps_component="httpd"` depending on how data is modeled.
- **Unowned important CVEs for a RHEL major:** `flaws_list` with `owner_isempty=true`, `impact_in=["IMPORTANT"]`, and `affects_ps_module_in` / `affects_ps_update_stream_in` set to the **exact** PS strings your OSIDB uses for that major (confirm in your internal docs).

## Security

- Outputs may include **embargoed** content; treat transcripts and logs according to your data classification policy.
- Prefer `readonly` (default). `readwrite` does not enable mutations yet but is reserved for explicit future write tools.
- Never commit `OSIDB_PASSWORD`; use IDE env or secret stores.

## Development

```bash
uv venv .venv && source .venv/bin/activate
uv pip install -e ".[dev]"
python -m osidb_mcp
pytest
pip-audit
```

## License

MIT — see [LICENSE](LICENSE).
