Metadata-Version: 2.1
Name: qcoda-mcp
Version: 0.1.0
Summary: QCoda MCP server + CLI — manage QCoda work items, pipelines, concerns, and PM config from AI coding tools (Claude Code, Cursor, JetBrains, aider) over stdio.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp <2,>=1.10
Requires-Dist: httpx >=0.27

# QCoda MCP — Developer Setup Guide

Connect your AI coding tool (Claude Code, Cursor, JetBrains, aider) to QCoda so you
can manage work items, run analysis pipelines, review concerns, approve builds, and
read PM config — without leaving your editor. No QCoda source checkout required.

---

## 1. Install

Requires **Python 3.11+**.

```bash
pipx install qcoda-mcp        # recommended — isolated, puts `qcoda-mcp` on PATH
# or
pip install qcoda-mcp
# or run without installing:
uvx qcoda-mcp
```

Upgrade later: `pipx upgrade qcoda-mcp` (or `pip install -U qcoda-mcp`).

## 2. Get an API key

QCoda dashboard → **Profile** → copy your `qk_…` API key.

> The key **is your QCoda identity** and carries your write permissions. Treat it like
> a password: keep it in an env var / secrets manager, never commit it.

## 3. Configure your AI tool

All tools use the same two env vars: `QCODA_URL` and `QCODA_API_KEY`.

### Claude Code
Project-level `.mcp.json` (this repo only) or user-level `~/.claude/mcp.json` (all
projects):

```json
{
  "mcpServers": {
    "qcoda": {
      "command": "qcoda-mcp",
      "env": {
        "QCODA_URL": "https://app.qcoda.com",
        "QCODA_API_KEY": "qk_your_key_here"
      }
    }
  }
}
```

If `qcoda-mcp` isn't on PATH (e.g. you used plain `pip` in a venv), use:
`"command": "python", "args": ["-m", "qcoda_mcp"]`.

### Cursor
`~/.cursor/mcp.json` (or project `.cursor/mcp.json`) — same `mcpServers` block shape.

### JetBrains (AI Assistant / MCP) & aider
Point the tool's MCP config at command `qcoda-mcp` with the same two env vars. For
aider, the bundled CLI wrapper also works: `qcoda-mcp` exposes the tools over stdio.

Restart the tool after editing config. You should see the QCoda tools appear.

## 4. Project & context scoping

Most tools auto-detect which QCoda **project + context** you mean from your git repo:
matching your **current branch** against a context's base branch.

- On a branch that matches a QCoda context's base branch → auto-selected.
- No match → pass `project="<id>"` (and `context="<id>"`) explicitly to the tool.

Find ids with `list_scopes` (lists your org's projects + contexts).

## 5. Verify

In your AI tool, ask it to run **`list_work_items`**. If you get items back (or "No
work items found" for an empty project), you're wired. `get_pm_config` shows a
project's PM integration settings (secrets redacted).

## 6. What you can do (tool groups)

- **Work items**: `list_work_items`, `create_work_item`, `clarify_work_item`, `get_spec`, `link_work_items`, `list_work_item_relations`
- **Pipeline**: `get_pipeline_status`, `get_run_history`, `get_agent_report`, `restart_analysis`, `resume_from_agent`, `retry_intake`, `clear_error`
- **Quality**: `get_concerns`, `resolve_concern`, `approve_for_build`, `trigger_qc`
- **PM config**: `get_pm_config`, `set_pm_config` (non-secret keys only)
- **Ledger Q&A**: `ask_qcoda`, `ledger_status`, `list_scopes`

Write actions require your account to have write permission (PRODUCT/TECHNICAL role).
OBSERVER accounts get read-only and a clear refusal on writes.

## 7. Troubleshooting

| Symptom | Fix |
|---|---|
| `QCODA_URL and QCODA_API_KEY … required` | env vars missing from the MCP config block |
| No QCoda tools appear | tool didn't restart, or `command` not found — try `python -m qcoda_mcp` |
| Tools hit the wrong project | branch doesn't match a context; pass `project=`/`context=` |
| `OBSERVER role cannot …` | your account is read-only; ask for PRODUCT/TECHNICAL |
| `ModuleNotFoundError: mcp.server.fastmcp` | wrong `mcp` version — `pipx upgrade qcoda-mcp` (needs mcp 1.x) |

---

Maintainers: publishing + versioning lives in `docs/qcoda_mcp_publishing.md`.
