Metadata-Version: 2.4
Name: tambora-mcp
Version: 0.1.0
Summary: MCP server for Tambora test case management
Project-URL: Homepage, https://github.com/koombea/tambora-mcp
Project-URL: Repository, https://github.com/koombea/tambora-mcp
Author-email: Koombea <jesus.palomino@koombea.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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 :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: fastmcp
Requires-Dist: requests>=2.28.0
Description-Content-Type: text/markdown

# tambora-mcp

MCP server that exposes [Tambora](https://tambora.io) test case management operations as native tools for Claude. Allows Claude to create test cases, manage test runs, and list existing tests without generating and executing scripts manually.

## Requirements

- Python 3.10+
- A running Tambora instance with API access
- Claude Code (claude.ai/code) or any MCP-compatible client

---

## Installation

### Option A — No install, via `uvx` (recommended)

If you have [uv](https://docs.astral.sh/uv/) installed, you don't need to install anything up front — point your MCP client at `uvx tambora-mcp@latest` (see [MCP Setup](#mcp-setup-in-claude-code) below). The `@latest` suffix matters: without it, `uvx` resolves the version once and reuses that cached environment on later runs instead of re-checking PyPI.

### Option B — Persistent install from PyPI

```bash
pip install tambora-mcp
```

To install a specific version:

```bash
pip install tambora-mcp==0.6.0
```

### Option C — Local development (contributors/maintainers)

```bash
git clone https://github.com/koombea/tambora-mcp.git
cd tambora-mcp
pip install -e .
```

### Verify installation

```bash
tambora-mcp --help
```

---

## MCP Setup in Claude Code

### 1. Locate or create your `.mcp.json`

The `.mcp.json` file lives at the root of your project (project-level) or at `~/.claude/mcp.json` (global).

### 2. Add the tambora server

Recommended — no install step, via `uvx`:

```json
{
  "mcpServers": {
    "tambora": {
      "command": "uvx",
      "args": ["tambora-mcp@latest"],
      "env": {
        "TAMBORA_BASE_URL": "https://your-instance.tambora.com",
        "TAMBORA_API_KEY": "your-api-key"
      }
    }
  }
}
```

Alternative — if you already did a persistent `pip install tambora-mcp`:

```json
{
  "mcpServers": {
    "tambora": {
      "command": "tambora-mcp",
      "env": {
        "TAMBORA_BASE_URL": "https://your-instance.tambora.com",
        "TAMBORA_API_KEY": "your-api-key"
      }
    }
  }
}
```

| Variable | Description |
|---|---|
| `TAMBORA_BASE_URL` | Base URL of your Tambora instance |
| `TAMBORA_API_KEY` | API key for authentication (project is derived from the token) |

### 3. Restart Claude Code

After saving `.mcp.json`, restart Claude Code so it picks up the new MCP server. You can verify it loaded correctly by asking Claude:

> "Check connectivity to Tambora"

---

## Available MCP Tools

### Test Cases

| Tool | Description |
|---|---|
| `check_connectivity` | Verify the Tambora API is reachable |
| `create_test_case` | Create a single BDD test case |
| `create_test_cases` | Bulk-create test cases from a list |
| `edit_test_case` | Edit an existing test case (title, gherkin, severity, module, suite, labels) |
| `list_test_cases` | List test cases filtered by module, suite, or labels |

### Suites

| Tool | Description |
|---|---|
| `list_suites` | List all suites (modules and their children) in the project |
| `add_test_cases_to_suite` | Add test cases to an existing suite by name or UUID |

### Test Runs

| Tool | Description |
|---|---|
| `create_test_run` | Create a new test run |
| `edit_test_run` | Edit an existing test run (name, description, or status) |
| `complete_test_run` | Mark a test run as completed |
| `list_test_run_cases` | List all test cases assigned to a specific test run (by code or name) |

> **Note:** `assign_test_cases`, `add_test_run_results`, and `create_test_run_from_suite` require a backend endpoint not yet available. They will be enabled in a future release.

---

## Usage Examples

Once the MCP server is registered, Claude can interact with Tambora conversationally:

> "Check connectivity to Tambora"

> "Create a test case for the login flow with Given/When/Then steps under the Authentication module"

> "Bulk-create 3 test cases for the Sign Up suite"

> "List all test cases in the Authentication module, Login suite"

> "Edit TC-MPP-42 and mark it as manual"

> "List all suites in the project"

> "Add TC-MPP-42 and TC-MPP-43 to the Login suite"

> "Create a test run called 'Regression v1.2.0' and mark it as In Progress"

> "Complete test run TR-MPP-14"

### End-to-end workflow example

```
1. Read requirements from a Jira ticket or spec
2. Bulk-create BDD test cases in the appropriate module and suite
3. Add the test cases to the relevant suite with add_test_cases_to_suite
4. Create a Test Run with a descriptive name
5. Complete the Test Run once execution is done
```

---

## Releasing a New Version (for maintainers)

Versioning is automatic — the package version is derived from the git tag at build time, so there's nothing to bump in source. To cut a release:

```bash
git tag v0.6.0
git push origin v0.6.0
```

Pushing the tag triggers `.github/workflows/publish.yml`, which builds the package and publishes it to PyPI. Watch the run under the repo's **Actions** tab, then confirm the new version is live at [pypi.org/project/tambora-mcp](https://pypi.org/project/tambora-mcp/). Users on `uvx tambora-mcp@latest` pick up the new version automatically; persistent installs upgrade with `pip install --upgrade tambora-mcp`.

---

## Architecture

```
tambora_mcp/
├── server.py     # FastMCP server, tool definitions, env config
├── client.py     # Low-level HTTP client for the Tambora REST API
├── creator.py    # High-level adapter used at test-generation time
└── __main__.py   # Entry point for python -m tambora_mcp
```

- **`TamboraClient`** — handles HTTP, retries, and error handling. POST timeouts abort immediately and do not retry to prevent duplicate creation.
- **`TamboraCreator`** — normalizes MCP input fields (`gherkin`, `severity`, `is_automated`) into the API schema (`description`, `priority`, `automation_status`).
- **`server.py`** — wires everything together via FastMCP and reads configuration from environment variables at startup.

---

## Changelog

### v0.5.0

- **New tool**: `list_test_run_cases` — list all test cases assigned to a test run, filterable by code or name. Each result includes code, summary, description, suite, severity, automation status, and tags.
- **New filters for `list_test_cases`**: `code` (look up a specific test case), `created_after`, and `created_before` (ISO 8601 date range filtering).
- **Tags on creation**: `create_test_case` now accepts a `tags` parameter that is sent to the API on creation. No extra edit call required.
- **Rename**: `labels` parameter renamed to `tags` across `create_test_case`, `list_test_cases`, `creator.py`, and `client.py` for consistency with Tambora's terminology.
- **Fix**: `create_test_case` now defaults `is_automated` to `false` instead of `true`.

### v0.4.0

- **Breaking change**: `feature`/`story` parameters renamed to `module`/`suite` across all tools to match Tambora's hierarchy model (Module → Suite).
- **New tools**: `edit_test_case`, `list_suites`, `add_test_cases_to_suite`.
- **Fix**: corrected suite API endpoint paths (`/suites/` → `/suite/`).
- **Fix**: `edit_test_case` response now correctly reads the nested `data.data` envelope from the API.
- **Fix**: `assign_test_cases` and `add_test_cases_to_suite` now accept `test_case_codes` as a JSON string for reliable MCP client compatibility.

### v0.3.1

- **Fix**: `create_test_case` and `bulk_create_test_cases` no longer receive `project_key` from `TamboraCreator`.

### v0.3.0

- **New tool**: `edit_test_run`.
- **Fix**: corrected test run API endpoint paths (`test-runs` → `testrun`).
- **Fix**: `create_test_run` now sends `status` with a default of `"Pending"`.
- **Fix**: `create_test_cases` and `add_test_run_results` now accept list parameters as JSON strings.
- **Fix**: `complete_test_run` response now correctly reads the `status` field.

### v0.2.0

- Added `list_test_cases`, `create_test_run`, `create_test_run_from_suite`, `assign_test_cases`, `add_test_run_results`, `complete_test_run` tools.

### v0.1.0

- Initial release with `check_connectivity`, `create_test_case`, `create_test_cases`.

---

## License

MIT
