tambora-mcp 0.1.0

MCP server for Tambora test case management

tambora-mcp

MCP server that exposes Tambora 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 installed, you don't need to install anything up front — point your MCP client at uvx tambora-mcp@latest (see MCP Setup 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

pip install tambora-mcp

To install a specific version:

pip install tambora-mcp==0.6.0

Option C — Local development (contributors/maintainers)

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

Verify installation

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:

{
  "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:

{
  "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:

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. 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