Metadata-Version: 2.4
Name: sulu-mcp
Version: 1.0.0
Summary: MCP server exposing Sulu TMS to LLM agents (read + triage)
Project-URL: Homepage, https://aisulu.dev
Project-URL: Documentation, https://docs.aisulu.dev/integrations/mcp
Author: Sulu
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: mcp,sulu,test-management,testing,tms
Classifier: Intended Audience :: Developers
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 :: Testing
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.27.2
Description-Content-Type: text/markdown

# Sulu MCP server

An [MCP](https://modelcontextprotocol.io) server that lets an LLM agent observe and
triage a [Sulu](https://aisulu.dev) TMS instance. It is a thin client over Sulu's
existing REST API — **no backend changes required**. It runs locally over stdio.

## What it exposes

37 tools (read + triage + authoring + ingest), all acting as the user who owns the API token:

- **Observe:** `check_connection`, `list_projects`, `get_project`, `project_glance`,
  `top_failing_tests`, `list_test_cases`, `get_test_case`, `get_test_case_markdown`
  (agent-facing Markdown scenario for executing the case), `search_test_cases`,
  `list_launches`, `get_launch`, `list_launch_results`, `get_test_result`,
  `list_launch_defects`, `list_tags`, `list_defects`, `get_defect`,
  `get_folder_tree`, `list_test_plans`, `get_test_plan`.
- **Author / organize (write):** `create_test_case`, `update_test_case` (steps,
  precondition, expected result, parameters, tag ids, folder), `create_tag`,
  `create_folder`, `move_test_case_to_folder`, `create_test_plan`, `set_test_plan_cases`.
- **Triage (write):** `set_test_result_status`, `assign_results`, `create_defect`,
  `close_defect`, `reopen_defect`, `link_defect_results`, `link_defect_cases`.
- **Execute (write):** `create_launch` (seeds selected cases), `finish_launch`.
- **Ingest (write):** `upload_test_report` — upload an allure-results dir / JUnit XML / ZIP as a new launch.

## Install

The package is published on PyPI as [`sulu-mcp`](https://pypi.org/project/sulu-mcp/).
With [uv](https://docs.astral.sh/uv/) installed, no explicit install step is needed —
`uvx sulu-mcp` fetches and runs it.

Mint a token in Sulu: **Profile → API tokens** (it is shown in plaintext once).

## Configuration

| Env var | Required | Default | Meaning |
|---|---|---|---|
| `SULU_API_TOKEN` | yes | — | Personal API token (Bearer). The agent acts as this user. |
| `SULU_BASE_URL` | no | `http://localhost:8080` | Sulu base URL (no trailing `/api`) — `https://app.aisulu.dev` for SaaS, or your on-premise instance URL. |
| `SULU_PROJECT_ID` | no | — | Default project for `upload_test_report` when the call omits `project_id`. |

## Register in Claude Code

The server name comes **first**, then the `-e` env flags, then `--` and the launch
command. `-e/--env` is variadic — placed before the name it swallows `sulu` as a value
(`Invalid environment variable format: sulu`):

```bash
claude mcp add sulu \
  -e SULU_API_TOKEN=<token> -e SULU_BASE_URL=https://app.aisulu.dev \
  -- uvx sulu-mcp
```

## Register in Claude Desktop

Add to its `mcpServers` config:

```json
{
  "mcpServers": {
    "sulu": {
      "command": "uvx",
      "args": ["sulu-mcp"],
      "env": { "SULU_API_TOKEN": "<token>", "SULU_BASE_URL": "https://app.aisulu.dev" }
    }
  }
}
```

## From source (this repo)

```bash
cd mcp
uv sync
cp .env.example .env   # then set SULU_API_TOKEN
SULU_API_TOKEN=<token> uv run sulu-mcp
```

To register a from-source checkout instead of the PyPI package, replace `uvx sulu-mcp`
with `uv --directory /absolute/path/to/sulu/mcp run sulu-mcp` in the commands above.

## Test

```bash
cd mcp && uv run pytest
```

## Scope

stdio only; single user (env token); read + triage + authoring + ingest. Authoring of
test-case scenarios is done via `update_test_case` (the create endpoint takes metadata
only). **Out of scope:** running automated tests on CI (no thin REST path — use a CI Job
in the web UI), custom-field *values*, folder rename/move/delete, tag update/delete,
defect↔Jira, deletes/bulk-destructive ops, schema mutation, remote/HTTP transport,
multi-user auth.

## License

Apache-2.0 — the full text ships in the package's `LICENSE` file. The Sulu product
itself is licensed separately.
