Metadata-Version: 2.4
Name: steampunk-spotter-mcp
Version: 6.7.0a7
Summary: MCP server for Steampunk Spotter: Lets AI agents verify Ansible and Terraform code against your policies.
Author-email: "XLAB d.o.o." <pypi@xlab.si>
Project-URL: Homepage, https://spotter.steampunk.si/
Project-URL: Source Code, https://gitlab.com/xlab-steampunk/steampunk-spotter-client/spotter-cli
Project-URL: Bug Tracker, https://gitlab.com/xlab-steampunk/steampunk-spotter-client/spotter-cli/-/issues
Project-URL: Documentation, https://spotter.steampunk.si/docs/
Project-URL: Changelog, https://gitlab.com/xlab-steampunk/steampunk-spotter-client/spotter-cli/-/blob/main/CHANGELOG.txt
Keywords: ansible,automation,spotter,scanner,quality,playbook,governance,policy,compliance,security,ai,terraform,iac,steampunk,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
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
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Framework :: Ansible
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<3,>=2.2
Requires-Dist: pydantic>=2
Requires-Dist: steampunk-spotter<7,>=6.7.0a7
Dynamic: license-file
Dynamic: requires-dist

# Steampunk Spotter MCP Server

[![PyPI](https://img.shields.io/pypi/v/steampunk-spotter-mcp)](https://pypi.org/project/steampunk-spotter-mcp/)

The Steampunk Spotter MCP server connects [Steampunk Spotter] scanning abilities with AI
agents, so they can check the code as they write.
It uses the [Steampunk Spotter CLI][steampunk-spotter], which is installed
together with it.

## Installation

Requirements:
- [uv] for the recommended install, or
- Python >= 3.10 for other install options (see below).

Add the following entry to your MCP configuration (see [Agent setup](#agent-setup)
for agent-specific instructions):

```json
{
  "mcpServers": {
    "spotter": {
      "command": "uvx",
      "args": ["--python", ">=3.10", "steampunk-spotter-mcp@latest"]
    }
  }
}
```

### Alternative install

To avoid uv dependency, use any python package manager to install the server into your Python environment:

```shell
$ pip install steampunk-spotter-mcp
```

This provides the `spotter-mcp` console script. Use it as the command, with
the absolute path to it:

```json
{
  "mcpServers": {
    "spotter": {
      "command": "/path/to/.venv/bin/spotter-mcp"
    }
  }
}
```

## Authentication

### Recommended: login with Spotter CLI

Log in once and the MCP server uses the stored credentials (see [CLI authentication]
for all login options).

```shell
$ spotter login
```

Without the CLI installed, log in through `uvx`:

```shell
$ uvx --from steampunk-spotter spotter login
```

For on-prem, **first** set the endpoint in `~/.config/steampunk-spotter/spotter.json`
(add the key if the file already exists), then log in:

```json
{"endpoint": "<spotter-api-url>"}
```

For details, see [Setting the API endpoint] in the CLI documentation.

### Alternative: set env variables

The MCP server authenticates with these environment variables, which take
precedence over the stored login:

| Variable                               | Description                                                                        |
|----------------------------------------|------------------------------------------------------------------------------------|
| `SPOTTER_TOKEN`                        | API token ([how to create one](https://spotter.steampunk.si/docs/web/#api-tokens)) |
| `SPOTTER_USERNAME`, `SPOTTER_PASSWORD` | Alternative to the token                                                           |
| `SPOTTER_ENDPOINT`                     | On-prem only: URL of your Spotter API                                              |

**Option 1: set env variables in your MCP config**

Set them in the `env` block of your user-level MCP configuration. Do not put
them in a project-level config that is committed to version control.

```json
"env": {
  "SPOTTER_TOKEN": "<your-token>",
  "SPOTTER_ENDPOINT": "<spotter-api-url>"
}
```

**Option 2: set env variables in your shell**

Most agents pass their own environment to the MCP server, so you can leave
`env` out and instead:

- export the variables in your shell profile (e.g. `~/.profile`), or
- set them per project with [direnv](https://direnv.net/) (`.envrc`).

Start the agent from a shell where the variables are set.

## Agent setup

The examples use the recommended `uvx` install. Add `env` only if you
authenticate with environment variables.

Each agent can register the server in one of two scopes:

- **User:** available in all your projects. Use this scope if you put
  credentials in `env`.
- **Project:** usually a `.mcp.json` file in the repository root, shared with your team
  through version control. Never put credentials here.

### Claude Code

- **User:**
  ```shell
  $ claude mcp add --scope user spotter -- uvx --python ">=3.10" steampunk-spotter-mcp@latest
  ```
- **Project:** add the [JSON entry](#installation) to `.mcp.json`, or run the
  command above with `--scope project`.

### GitHub Copilot (VS Code and Copilot CLI)

- **User:** add the [JSON entry](#installation) to `~/.copilot/mcp-config.json`.
- **Project:** add it to `.mcp.json`.

## Acknowledgment
This tool was created by [XLAB Steampunk], IT automation specialists and
leading experts in building Enterprise Ansible Collections.

[Steampunk Spotter]: https://spotter.steampunk.si/
[steampunk-spotter]: https://pypi.org/project/steampunk-spotter/
[CLI authentication]: https://spotter.steampunk.si/docs/cli/#authentication
[Setting the API endpoint]: https://spotter.steampunk.si/docs/cli/#setting-api-endpoint
[uv]: https://docs.astral.sh/uv/
[XLAB Steampunk]: https://steampunk.si/
