# Sonatype Nexus MCP Server

[![CI](https://github.com/oomchiller/nexus-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/oomchiller/nexus-mcp-server/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/oomchiller/nexus-mcp-server)](https://github.com/oomchiller/nexus-mcp-server/releases)
[![License](https://img.shields.io/github/license/oomchiller/nexus-mcp-server)](LICENSE)

A [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI
assistants inspect, audit and document a Sonatype Nexus Repository Manager 3.x
instance. It is read-only by default; administrative tools are not even listed
unless you enable them.

```mermaid
flowchart LR
    AI[MCP client] <-->|stdio / Streamable HTTP| Server[nexus-mcp-server]
    Server <-->|REST API| Nexus[Nexus Repository 3.x]
```

## Features

- Inventory of repositories, blob stores, tasks, cleanup policies, routing
  rules, content selectors, users, roles and privileges, as far as the
  configured account can see them.
- A relationship graph (repository → blob store, group → members, repository →
  cleanup policy, role → privilege) behind architecture explanations, risk
  checks and generated Markdown documentation.
- Bounded full-content audit of one repository, with completion evidence.
- Drift check of repositories against a declared state.
- OpenAPI discovery of the instance's REST operations.
- Every tool declares `readOnlyHint`, `destructiveHint`, `idempotentHint` and
  `openWorldHint`; outputs and logs redact the configured password and
  secret-looking keys.
- Starts without configuration, so clients and registries can list its tools;
  calls then report what is missing.

Used in production in read-only mode on Nexus Pro 3.96.1-01; partially
verified on OSS 3.70. See [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md).

## Quick start

The server is listed in the [MCP Registry](https://registry.modelcontextprotocol.io)
as `io.github.oomchiller/nexus-mcp-server`; registry-aware clients can install
it from there. Manual setup:

### Container

```bash
docker run --rm -i \
  -e NEXUS_URL=https://nexus.example.com \
  -e NEXUS_USERNAME=readonly-user \
  -e NEXUS_PASSWORD \
  ghcr.io/oomchiller/nexus-mcp-server:0.2.0
```

Images are published for `linux/amd64` and `linux/arm64`, run as an
unprivileged user over stdio, and are configured through the environment
only. Release digests are listed on the
[releases page](https://github.com/oomchiller/nexus-mcp-server/releases).

### Local process

```json
{
  "mcpServers": {
    "nexus": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oomchiller/nexus-mcp-server@v0.2.0", "nexus-mcp-server"],
      "env": {
        "NEXUS_URL": "https://nexus.example.com",
        "NEXUS_USERNAME": "readonly-user",
        "NEXUS_PASSWORD": "change-me"
      }
    }
  }
}
```

More client examples (Claude Desktop, Codex CLI, Gemini CLI) are in
[examples/](examples/).

## Configuration

Settings come from the environment or a `.env` file in the working directory.

| Variable | Default | Meaning |
| --- | --- | --- |
| `NEXUS_URL` | unset | Nexus base URL. Without it the server starts, and calls report that Nexus is not configured. |
| `NEXUS_USERNAME` / `NEXUS_PASSWORD` | unset | Basic authentication. Use a read-only Nexus account. |
| `NEXUS_VERIFY_TLS` | `true` | Verify the Nexus TLS certificate. |
| `NEXUS_CA_BUNDLE` | unset | PEM file of CA certificates to trust instead of the public roots; needs `NEXUS_VERIFY_TLS=true`. |
| `NEXUS_TIMEOUT_SECONDS` | `30` | HTTP timeout. |
| `NEXUS_ALLOWED_HOSTS` | host of `NEXUS_URL` | Comma-separated hosts the client may contact. |
| `NEXUS_LOG_LEVEL` | `INFO` | Log level (stderr). |
| `NEXUS_MCP_MODE` | `readonly` | `readonly`, `audit` (same gates as `readonly`) or `admin`. |
| `NEXUS_MCP_ENABLE_WRITE_TOOLS` | `false` | With `admin`, lists and allows the write tools. |
| `NEXUS_MCP_ENABLE_RAW_API` | `false` | Lists `nexus_api_call`. |
| `NEXUS_MCP_RAW_API_GET_ONLY` | `false` | Restrict `nexus_api_call` to `GET`. |
| `NEXUS_MCP_MAX_RAW_RESPONSE_BYTES` | `1048576` | Largest Nexus response accepted. |
| `NEXUS_MCP_GRAPH_TTL_SECONDS` | `60` | How long graph tools reuse one Knowledge Graph build; `0` rebuilds on every call. |
| `NEXUS_MCP_ENABLE_PROMPTS` | `true` | Register prompts. |
| `NEXUS_MCP_ENABLE_RESOURCES` | `true` | Register resources. |

Token authentication is not implemented.

The server does not read `SSL_CERT_FILE` or the system trust store. For a
Nexus behind a private CA, set `NEXUS_CA_BUNDLE` rather than disabling
verification. An unreadable bundle, or a bundle with verification disabled,
stops the server at startup.

Gateways that run several instances side by side and prefix only tool names
(Docker MCP Gateway) should set `NEXUS_MCP_ENABLE_PROMPTS=false` and
`NEXUS_MCP_ENABLE_RESOURCES=false`.

### Command line

```text
--transport {stdio,sse,streamable-http}   default stdio
--host HOST / --port PORT                 HTTP bind, default 127.0.0.1:8000, no authentication
--nexus-url URL                           overrides NEXUS_URL
--nexus-username USERNAME                 overrides NEXUS_USERNAME
--verify-ssl / --no-verify-ssl            overrides NEXUS_VERIFY_TLS
--ca-bundle PATH                          overrides NEXUS_CA_BUNDLE
```

Keep `NEXUS_PASSWORD` in the environment, not on the command line.

## Tools

| Group | Tools |
| --- | --- |
| Explanation | `nexus_understand_architecture`, `nexus_explain_repository`, `nexus_explain_storage_strategy` |
| Inventory and documentation | `nexus_generate_inventory_json`, `nexus_generate_architecture_md`, `nexus_generate_repository_catalog_md`, `nexus_audit_repository_content` |
| Audit | `nexus_detect_architecture_smells`, `nexus_generate_audit_report` |
| Drift | `nexus_compare_live_state_with_declared_state` |
| OpenAPI | `nexus_openapi_list_operations`, `nexus_generate_capability_map` |

Listed only when enabled:

| Tool | Requires |
| --- | --- |
| `nexus_api_call` | `NEXUS_MCP_ENABLE_RAW_API=true`; paths are canonicalized and restricted to `/service/rest/`. |
| `nexus_delete_repository`, `nexus_run_task` | `NEXUS_MCP_MODE=admin` and `NEXUS_MCP_ENABLE_WRITE_TOOLS=true`. |

Resources: `nexus://instance/summary`, `nexus://repositories`,
`nexus://blobstores`, `nexus://tasks`, `nexus://cleanup-policies`,
`nexus://security/summary`, `nexus://architecture`, `nexus://knowledge_graph`.
Prompts: `nexus_audit_prompt`, `nexus_iac_drift_prompt`.

Limits worth knowing: drift compares repository name, format and type only;
risk checks cover a small set of graph rules; findings are only as complete as
the REST APIs visible to the account. Optional endpoints that are missing for
version, edition or permission reasons appear as limitations, not failures.

## Safety

- Read-only by default. Write tools and the raw API are not listed unless
  enabled, and every write is still checked against the mode at call time.
- The client contacts only `NEXUS_ALLOWED_HOSTS` and only paths relative to
  `NEXUS_URL`.
- Redaction is defence in depth, not a substitute for a least-privilege Nexus
  account. See [SECURITY.md](SECURITY.md).

## Development

```bash
uv sync --locked
uv run pytest
uv run ruff check . && uv run ruff format --check .
uv run mypy src tests
```

See [CONTRIBUTING.md](CONTRIBUTING.md), [ARCHITECTURE.md](ARCHITECTURE.md),
[DECISIONS.md](DECISIONS.md) and [ROADMAP.md](ROADMAP.md).

## License

MIT; see [LICENSE](LICENSE).