Zephyr Squad MCP Server
README.md
# Zephyr-Jira MCP + AI Agent Layer
A standalone, self-hosted [Model Context Protocol (MCP)](https://modelcontextprotocol.io) project with two layers:
1. **Atomic tool server** (`zephyr_mcp_server.py`) — exposes Jira and Zephyr Scale test-management operations as MCP tools an AI assistant (Claude, Cursor, Windsurf, Devin, or any MCP-compatible client) can call directly: create test cases, link them to stories, audit test cycles, generate coverage reports.
2. **AI agent layer** (`zephyr_agent_server.py` + `zephyr_agent.py`) — an independent MCP server and CLI that hand whole *multi-step workflows* to an LLM-driven agent ("generate test cases for this story, add steps, link them, and report") using your own provider — Anthropic, OpenAI, Azure OpenAI, or any OpenAI-compatible internal gateway.
---
## Background
Organizations spend significant time creating and managing test assets across the software development lifecycle. Developers, QA engineers, and product teams routinely need to create test cases, document test steps, link tests to Jira stories, and organize them into test cycles. These activities are typically performed manually through the Jira and Zephyr UIs, which makes the process repetitive, time-consuming, and prone to inconsistency — especially during sprint planning, feature delivery, and release testing.
To address this, this project lets an AI assistant interact directly with Jira and Zephyr through natural language. Instead of navigating multiple screens and manually entering data, you describe what you want in plain English and the assistant performs the required actions. The atomic tool server covers single operations; the agent layer goes further and orchestrates entire workflows — plan → create → link → audit → report — in one instruction.
## Problem Statement
There are now hundreds of community and vendor MCP servers available for Jira, Zephyr, and other QA/test-management tools. In practice, almost none of them are usable inside a bank, insurer, or other regulated enterprise environment, because they typically:
- **Route data through a third-party proxy or SaaS backend** that the security team has no visibility into or control over.
- **Risk data leakage** — test data, defect descriptions, and Jira issue content routinely contain confidential project, customer, or infrastructure details that cannot leave the corporate network.
- **Require broad, unscoped credentials** (personal API tokens pasted into config files, no secret rotation, no audit trail).
- **Fail enterprise security review** outright, because the vendor cannot show where the server runs, where the token is stored, or what egress the tool makes.
## Why Not the Official Atlassian MCP Server?
| Reason | Detail |
|---|---|
| **Cloud-only** | `mcp.atlassian.com` only connects to Atlassian Cloud instances (e.g. `yourcompany.atlassian.net`). |
| **Private/on-premise blocked** | Our Jira instance, `https://jira.yourcompany.net`, is a self-hosted, on-premise, corporate deployment. The cloud MCP endpoint cannot reach it. |
| **No Zephyr support** | Even on Cloud, the Atlassian MCP covers only native Jira/Confluence APIs. Zephyr is a third-party plugin with its own separate REST API that isn't exposed by the Atlassian MCP. |
| **No Zephyr API access** | The Atlassian MCP has no knowledge of Zephyr's test case, test step, test cycle, or execution endpoints. |
**Conclusion:** the official Atlassian MCP server is structurally incompatible with this setup — both because of on-premise hosting and because Zephyr is outside its scope. Hence, this custom MCP project.
## Design Principles
- **Standalone, self-hosted.** Both servers run entirely inside your own network (or your own machine) as local processes. There is no external SaaS component, no vendor cloud, and no data ever leaves your environment unless your own Jira instance — or your own chosen LLM endpoint — is reached.
- **Your Jira, your rules.** The Jira base URL is a configuration value you set yourself, e.g. `https://jira.yourcompany.net` — the server talks directly to your Jira/Zephyr instance over your existing network path (VPN, internal DNS, corporate proxy — whatever your organization already enforces). No requests go anywhere else.
- **Your LLM, your rules.** The agent layer is provider-agnostic: one `[llm]` block in `config.toml` points it at Anthropic, OpenAI, Azure OpenAI, or an internal OpenAI-compatible gateway (LiteLLM, vLLM, Ollama). Choose an internal endpoint and LLM traffic stays inside the same boundary as Jira traffic.
- **No secrets in code or config files.** API tokens are never hardcoded and never committed. They resolve at runtime from **Azure Key Vault**, or from environment variables / a gitignored `.env` file (see `.env.example`), so credential storage and rotation stay owned by your existing secrets-management infrastructure.
- **Least-surface footprint.** The servers only implement the operations they explicitly expose as tools — there is no generic proxy, no arbitrary API pass-through, and no catch-all "run any REST call" tool. Mutating agent actions are approval-gated, and `delete_test_case` is hidden unless explicitly enabled.
- **Transparent and auditable.** Every tool call is logged locally (`zephyr_mcp.log`, `zephyr_agent.log`) with the acting user, action, and target issue/project — giving you a local audit trail independent of Jira's own logs.
- **Fail loud at startup.** `validate_config()` runs when either server or the CLI boots — a missing base URL, non-HTTPS Jira, or missing/placeholder token exits immediately instead of failing mid-task.
## What It Does
The tool server wraps `zephyr_client.py` (a thin client over the Jira and Zephyr Scale REST APIs) and exposes each operation as an MCP tool. The agent server then orchestrates those tools with an LLM for multi-step work. Once connected to an MCP client, an assistant can:
| Category | Tools |
|---|---|
| **Resolution** | Resolve project keys, issue keys, and issue types to their underlying Jira IDs |
| **Test case management** | Create, bulk-create, list, and delete Zephyr test cases; discover custom field IDs per project |
| **Test design** | Read and write test steps in Step-by-Step, BDD/Gherkin, or plain-text format |
| **Linking & collaboration** | Link tests to stories/bugs/epics; add comments to any Jira issue |
| **Test cycles & execution** | Fetch test cycles, execution results, and per-cycle pass/fail summaries; audit a cycle for missing attachments or unresolved statuses |
| **Coverage & reporting** | Report test coverage against stories/bugs in a project or sprint; generate aggregate pass/fail summaries |
| **Jira queries** | Fetch any issue by key; run arbitrary JQL searches |
The agent layer adds workflow-level operations on top: `run_workflow`, `cover_story`, `audit_sprint`, `release_report`, `list_workflows` — plus the `run_agent()` function and `zephyr_agent.py` CLI for free-form instructions.
## Architecture
```mermaid
flowchart TD
A["MCP Client<br/>Claude Desktop, coding agents, etc."]
F["CLI / run_agent()<br/>zephyr_agent.py"]
G["zephyr_agent_server.py<br/>FastMCP — workflow-level tools"]
B["zephyr_mcp_server.py<br/>FastMCP — atomic tool definitions, logging"]
C["zephyr_client.py<br/>Jira + Zephyr Scale REST client"]
D["Your Jira Instance<br/>jira.yourcompany.net"]
E["Azure Key Vault / .env<br/>secrets resolved at runtime"]
L["Your LLM Endpoint<br/>Anthropic / OpenAI / Azure / gateway"]
A -->|stdio / streamable-http| B
A -->|stdio / streamable-http| G
G -->|run_agent| F
F -->|in-process tool calls| B
F <-->|tool-call loop| L
B --> C
C -->|REST API + JIRA_TOKEN| D
E -->|Runtime secrets| C
E -->|Runtime secrets| L
style A fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px
style F fill:#fdf3e3,stroke:#e8710a,stroke-width:2px
style G fill:#fdf3e3,stroke:#e8710a,stroke-width:2px
style B fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px
style C fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px
style D fill:#e6f4ea,stroke:#188038,stroke-width:2px
style E fill:#fff4e5,stroke:#f29900,stroke-width:2px
style L fill:#f3e8fd,stroke:#9334e6,stroke-width:2px
```
## Prerequisites
- Python 3.10+
- Access to a Jira instance with Zephyr Scale (ATM) enabled
- An Azure Key Vault instance holding your Jira API token as a secret named `JIRA-TOKEN`, with the identity running this server granted `get`/`list` access to that secret
- An MCP-compatible client (e.g. Claude Desktop)
- *(Agent layer only)* an LLM endpoint — Anthropic/OpenAI/Azure OpenAI or an internal gateway — with its API key in Key Vault (e.g. `ANTHROPIC-API-KEY`); see [AGENT_LAYER.md](docs/AGENT_LAYER.md)
## Setup
1. **Clone and install dependencies**
```bash
git clone https://github.com/VenkateshDoijode/custom-mcp.git
cd custom-mcp
pip install -r requirements.txt
```
2. **Configure `config.toml`** with your Jira details (and LLM settings if you want the agent layer)
```toml
[jira]
base_url = "https://jira.yourcompany.net"
username = "your-jira-username"
[azure]
key_vault_url = "https://your-keyvault-name.vault.azure.net/"
[llm] # agent layer only — see AGENT_LAYER.md §3–4
provider = "anthropic" # or openai | azure_openai | openai_compatible
model = "claude-sonnet-4-5"
```
3. **Provide secrets** — either grant **Key Vault access** to the identity running the server (managed identity, service principal, or `az login`), scoped to read `JIRA-TOKEN` only; **or** copy `.env.example` to `.env` and fill in values (never commit `.env`). Environment variables always take precedence.
4. **Register the server(s) with your MCP client** — see `claude_desktop_config.json` for a working example, and point it at the absolute path of `zephyr_mcp_server.py` (atomic tools) and/or `zephyr_agent_server.py` (workflow agent).
5. **Run it**
```bash
python zephyr_mcp_server.py # atomic tools — stdio for MCP clients
python zephyr_mcp_server.py --http # streamable-http on port 8000
python zephyr_agent_server.py # agent layer — stdio for MCP clients
python zephyr_agent.py "instruction" # agent CLI — no MCP client needed
```
## Use with Any Coding Agent
**Each server works completely independently.** Register one, the other, or both — they are separate FastMCP servers with no shared runtime state:
| Server | Exposes | Use it for |
|---|---|---|
| `zephyr_mcp_server.py` | ~20 atomic Jira/Zephyr tools | Fine-grained control — "create one test case", "comment on PG1-123" |
| `zephyr_agent_server.py` | 5 workflow-level tools (`run_workflow`, `cover_story`, `audit_sprint`, `release_report`, `list_workflows`) | Multi-step jobs — "cover this story end-to-end", "audit the sprint" |
Any MCP-compatible client — Claude Desktop, Cursor, Windsurf, Devin, VS Code MCP, or a custom agent — registers them the same way, as stdio processes:
```json
{
"mcpServers": {
"zephyr-tools": {
"command": "python",
"args": ["/absolute/path/to/custom-mcp/zephyr_mcp_server.py"]
},
"zephyr-agent": {
"command": "python",
"args": ["/absolute/path/to/custom-mcp/zephyr_agent_server.py"]
}
}
}
```
- **Claude Desktop** → `claude_desktop_config.json` (working example in this repo)
- **Cursor / Windsurf** → `~/.cursor/mcp.json` / `~/.codeium/windsurf/mcp_config.json` — same `mcpServers` shape
- **HTTP clients** → start either server with `--http` and point the client at `http://localhost:8000/mcp`
- **No MCP client at all** → `python zephyr_agent.py "instruction"` runs the agent layer directly from the shell
Each server validates config and credentials at startup — a bad setup exits with a clear error in the client's log instead of failing mid-conversation.
## Security Posture
| Concern | How it's handled here |
|---|---|
| Credential storage | Jira token pulled from Azure Key Vault at runtime, or from env vars / a gitignored `.env` file; never stored in code, config, or logs |
| Startup validation | `validate_config()` runs at server/CLI boot — missing URL, non-HTTPS Jira, or missing/placeholder token fails immediately |
| Network exposure | Server runs locally/on-prem; only outbound calls are to your own Jira base URL |
| Data residency | No third-party proxy or SaaS relay — test and issue data never leaves your network boundary |
| Least privilege | Tools are scoped to specific Jira/Zephyr operations, not a general-purpose API proxy |
| Auditability | All tool invocations are logged with the acting user, action, and target key |
| Destructive actions | Operations like `delete_test_case` are explicit, named tools — never a hidden side effect of another call |
> This is a personal/team project, not an officially reviewed enterprise product. Before deploying it in a regulated environment, run it through your organization's standard security and architecture review — the design choices above are meant to make that review straightforward, not to replace it.
## AI Agent Layer
The atomic tools above are now wrapped by an **agent layer**: hand over a whole workflow in one instruction — *"Generate test cases for this new story, link them, and audit last sprint's execution cycle for gaps."* — and the agent chains resolution → creation → linking → reporting itself.
- **Independent second MCP server** (`zephyr_agent_server.py`) — register it in any MCP-compatible coding agent alongside or instead of the atomic server.
- **Provider-agnostic** — Anthropic, OpenAI, Azure OpenAI, or any OpenAI-compatible gateway (LiteLLM, vLLM, Ollama, internal). One `[llm]` block in `config.toml` selects provider/model/endpoint/auth; keys resolve from Azure Key Vault like the Jira token.
- **CLI** (`zephyr_agent.py`) — free-form instructions plus predefined workflows (`cover_story`, `audit_sprint`, `release_report`), with `--dry-run`, approval prompts, and a destructive-tool gate.
- **Same audit trail** — the agent orchestrates the atomic tools in-process, so every action is still logged in `zephyr_mcp.log`.
```bash
python zephyr_agent.py --workflow cover_story --arg issue_key=PG1-123
python zephyr_agent_server.py # stdio — register in your MCP client
```
Full setup, provider configs, and guardrails: **[AGENT_LAYER.md](docs/AGENT_LAYER.md)** — complete run/start runbook: **[RUN_AGENT.md](docs/RUN_AGENT.md)**.
> Agent mode sends Jira issue/story content to the configured LLM endpoint — choose `azure_openai` or an internal `openai_compatible` gateway to keep that traffic inside your network boundary, and review it under the same security process as the rest of this project.
## Repository Contents
| File | Purpose |
|---|---|
| `zephyr_mcp_server.py` | FastMCP server — registers all atomic tools, handles logging and transport |
| `zephyr_client.py` | Jira + Zephyr Scale REST client — the only module that makes Jira HTTP calls |
| `zephyr_agent_server.py` | Independent MCP server exposing the AI agent layer (workflow-level tools) |
| `zephyr_agent.py` | Agent engine (`run_agent`), predefined workflows, CLI (`--chat` for multi-turn) |
| `zephyr_agent_ui.py` | OPTIONAL FastAPI browser chat UI over the same engine (`pip install fastapi uvicorn`) |
| `llm_providers.py` | Provider-agnostic LLM adapters (Anthropic / OpenAI / Azure OpenAI / gateways) |
| `docs/AGENT_LAYER.md` | End-to-end agent layer documentation |
| `docs/RUN_AGENT.md` | Detailed runbook — how to run/start the agent (CLI, MCP, API, cron) |
| `docs/MCP_EXPLAINED.md` | What MCP and FastMCP are, and how this project layers them |
| `docs/DRY_RUN_EXAMPLE.md` | Captured real dry-run — guardrails and tabular output in action |
| `.env.example` | Documented env-var / `.env` template for secrets and LLM config |
| `claude_desktop_config.json` | Example MCP client configuration |
| `requirements.txt` | Python dependencies (tail has optional UI deps, safe to skip) |
## Author
Venkateshwara Doijode — Test Automation Lead
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues