tambora-mcp 0.1.0__tar.gz

tambora_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # No test step yet: this repo has no tests/ suite. Add a `pytest`
+      # step here before build once one exists.
+
+      - name: Build
+        run: |
+          pip install hatch
+          hatch build
+
+      - name: Check package metadata
+        run: |
+          pip install twine
+          twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1

tambora_mcp-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+tambora_mcp/_version.py
+
+# Virtual environments
+venv/
+.venv/
+env/
+
+# Environment / secrets
+.env
+*.env
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store

tambora_mcp-0.1.0/.mcp.json

@@ -0,0 +1,17 @@
+{
+  "mcpServers": {
+    "tambora": {
+      "command": "python3",
+      "args": [
+        "-m",
+        "tambora_mcp"
+      ],
+      "cwd": "/Users/jesus.palomino/Documents/GitHub/tambora-mcp",
+      "env": {
+        "TAMBORA_BASE_URL": "http://localhost:8000",
+        "TAMBORA_API_KEY": "vnsGEJS6v0DWaOHFtK3-qJtEimLFJej5M16y2seLrpc",
+        "TAMBORA_PROJECT_KEY": "MPP"
+      }
+    }
+  }
+}

tambora_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,116 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`tambora-mcp` is a [FastMCP](https://github.com/jlowin/fastmcp) server that exposes Tambora test-case management operations as native MCP tools, allowing Claude to create test cases and manage test runs without generating and executing scripts manually.
+
+## Commands
+
+**Install for development:**
+```bash
+pip install -e .
+```
+
+**Run the server:**
+```bash
+tambora-mcp
+# or
+python -m tambora_mcp
+```
+
+**Build the package:**
+```bash
+pip install hatch
+hatch build
+```
+
+**Release a new version:**
+```bash
+git tag v0.6.0
+git push origin v0.6.0
+```
+Pushing a `v*` tag triggers `.github/workflows/publish.yml`, which builds and publishes to PyPI via Trusted Publishing (OIDC — no stored tokens). The version is resolved automatically from the git tag via `hatch-vcs`; never bump a version string in `pyproject.toml`/`__init__.py` by hand, and never run `twine upload` manually.
+
+## Architecture
+
+The package has two distinct layers:
+
+### `TamboraClient` (`client.py`)
+Low-level HTTP client for the Tambora REST API. Key behaviors:
+- All public methods are safe — they catch all network/HTTP errors and return `None`/`False` instead of raising.
+- Retries: `MAX_RETRIES=2` with `RETRY_BACKOFF=1s` exponential backoff.
+- **Critical**: POST requests that time out abort immediately and do NOT retry (`_last_post_timeout` flag), to prevent duplicate creation in Tambora.
+- Bulk create falls back to individual creates on failure, but **not** on timeout.
+- `gherkin_to_prosemirror()` converts Gherkin text into the ProseMirror document schema expected by the Tambora API.
+- Auth uses the `http-api-token` header.
+
+**Field mappings:**
+- Severity → Priority: `critical→Critical`, `normal→Low`, `minor→Trivial`
+- Status: `passed→Passed`, `failed→Failed`, `skipped→Skipped`, `error→Blocked`
+
+### `TamboraCreator` (`creator.py`)
+High-level adapter used at test-generation time (not during test execution). Bridges the MCP tool interface to `TamboraClient`. Normalizes the `gherkin`/`severity`/`is_automated` fields from MCP inputs into the `description`/`priority`/`automation_status` fields expected by the client.
+
+### `server.py`
+FastMCP server wiring. Reads configuration from environment variables at startup and instantiates a module-level `_creator` (TamboraCreator) and `_client` (TamboraClient). Exposes MCP tools: `check_connectivity`, `create_test_case`, `create_test_cases`, `edit_test_case`, `list_test_cases`, `create_test_run`, `edit_test_run`, `assign_test_cases`, `add_test_run_results`, `complete_test_run`, `create_test_run_from_suite`, `list_suites`, `add_test_cases_to_suite`.
+
+**Hierarchy model:** `module` (top-level, `is_module: true`) → `suite` (child, has `parent_id`). Use `module`/`suite` params, not `feature`/`story`.
+
+## Configuration
+
+All configuration is via environment variables:
+
+| Variable | Description |
+|---|---|
+| `TAMBORA_BASE_URL` | Tambora instance URL (e.g. `https://your-instance.tambora.com`) |
+| `TAMBORA_API_KEY` | API key for authentication (project is derived from the token on the backend) |
+
+## MCP Registration
+
+Register in `.mcp.json`. Recommended — no install step, via `uvx` (package is published on PyPI as `tambora-mcp`):
+```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 `tambora-mcp` was installed persistently via `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"
+      }
+    }
+  }
+}
+```
+
+## API Endpoints Used
+
+- `GET /api/v1/health` — connectivity check
+- `POST /api/v1/testcase/external-create` — single test case
+- `POST /api/v1/testcase/external-bulk-create` — bulk test cases
+- `PATCH /api/v1/testcase/{code}/external-edit` — edit existing test case *(backend needed)*
+- `GET /api/v1/testcase/external-list` — list test cases by project/feature/story/labels
+- `GET /api/v1/suite/external-list` — list suites for the project
+- `POST /api/v1/suite/external-add-test-cases` — add test cases to a suite
+- `POST /api/v1/test-runs/external-create` — create test run
+- `PATCH /api/v1/testrun/{code}/external-edit` — edit test run
+- `POST /api/v1/testrun/{code}/external-assign` — assign test case codes to a run
+- `POST /api/v1/testrun/{code}/external-results` — add results
+- `PUT /api/v1/testrun/{code}/external-complete` — complete test run

tambora_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Koombea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tambora_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,261 @@
+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