Add CLI MCP server

.github/workflows/lint.yml

@@ -30,9 +30,9 @@ jobs:
       uses: actions/cache@v6
       with:
         path: .tox
-        key: ${{ runner.os }}-lint-${{ matrix.toxenv }}-${{ hashFiles('setup.cfg') }}
-        restore-keys: |
-          ${{ runner.os }}-lint-${{ matrix.toxenv }}-
+        # Include every dependency declaration in the exact cache key so dependency
+        # changes produce a clean tox environment without relying on partial restores.
+        key: ${{ runner.os }}-lint-${{ matrix.toxenv }}-${{ hashFiles('setup.cfg', 'tox.ini', 'requirements*.txt') }}
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip setuptools tox>4

.github/workflows/test.yml

@@ -26,9 +26,9 @@ jobs:
       uses: actions/cache@v6
       with:
         path: .tox
-        key: ${{ runner.os }}-tox-${{ format('{{py{0}}}', matrix.python-version) }}-${{ hashFiles('setup.cfg') }}
-        restore-keys: |
-          ${{ runner.os }}-tox-${{ format('{{py{0}}}', matrix.python-version) }}-
+        # Include every dependency declaration in the exact cache key so dependency
+        # changes produce a clean tox environment without relying on partial restores.
+        key: ${{ runner.os }}-tox-${{ format('{{py{0}}}', matrix.python-version) }}-${{ hashFiles('setup.cfg', 'tox.ini', 'requirements*.txt') }}
     - name: Install dependencies
       run: |
         sudo apt-get install gettext

.gitignore

@@ -44,3 +44,7 @@ debian/files
 debian/python-taiga*
 debian/python3-taiga*
 .ruff_cache
+.venv
+*.egg-link
+.superpowers
+artifacts

AGENTS.md

@@ -0,0 +1,112 @@
+# Agent instructions
+
+This file gives coding agents (Claude Code and similar) step-by-step
+instructions for tasks specific to this repository. Human-facing docs live in
+``README.rst`` and ``docs/``.
+
+## Registering the Taiga MCP server in the user's global Claude config
+
+This repo ships an MCP server (`taiga/mcp_server/`) that exposes the Taiga
+REST API as tools over stdio, via the `taiga-mcp-server` console script
+(installed by the `mcp` extra: `pip install -e .[mcp]` from this repo, or
+`pip install python-taiga[mcp]` from PyPI).
+
+When asked to "add the Taiga MCP server to Claude" / "register taiga-mcp
+globally" / "add it to my user-wide config", follow this procedure:
+
+1. **Confirm before acting.** Registering at user scope changes the user's
+   global Claude Code config (`~/.claude.json`), applying to every project,
+   not just this repo. Confirm the target Taiga instance and scope with the
+   user before running the command, unless they've already given explicit
+   go-ahead in this conversation.
+
+2. **Get a stable `taiga-mcp-server` binary.** Don't point the MCP config at
+   a project-local `.venv` — Claude Code launches MCP server commands without
+   inheriting an activated venv, and the binary disappears if that venv is
+   ever recreated. Install it somewhere durable instead. There are several
+   equally valid ways to do this; pick whichever fits the user's toolchain,
+   asking if it's unclear, and default to `pip install --user` since it needs
+   nothing beyond a reasonably modern Python:
+   ```bash
+   # default: pip install --user (works with any modern Python/pip)
+   pip install --user "python-taiga[mcp]"          # from PyPI
+   pip install --user -e ".[mcp]"                  # from this checkout
+
+   # pipx (isolated venv per tool, one binary on PATH)
+   pipx install "python-taiga[mcp]"                # from PyPI
+   pipx install --editable ".[mcp]"                # from this checkout
+
+   # uvx (no persistent install; uv manages an ephemeral/cached env)
+   # here the *registered command* becomes `uvx --from "python-taiga[mcp]" taiga-mcp-server`
+   # instead of a resolved path — see the uvx example in step 4.
+   ```
+   After a `pip --user`/`pipx` install, resolve the resulting path and use it
+   verbatim in step 4:
+   ```bash
+   command -v taiga-mcp-server
+   ```
+
+3. **Collect credentials.** Ask the user for:
+   - `TAIGA_HOST` — the Taiga site root, e.g. `https://my.taiga.com`.
+     For self-hosted instances this is *not* an `api.` subdomain and has no
+     `/api` suffix — the client appends `/api/v1` itself.
+   - Either `TAIGA_TOKEN` (pre-issued API token), or both
+     `TAIGA_USERNAME` and `TAIGA_PASSWORD`. A token takes precedence if both
+     are configured.
+   - Optional: `TAIGA_TOKEN_TYPE` (default `Bearer`), `TAIGA_TLS_VERIFY`
+     (default `true`).
+
+   Never pass `--token`/`--password` as CLI arguments — they'd be visible in
+   the process list. Always pass credentials as environment variables.
+
+   **Default to username/password over a token, unless the instance has a
+   real personal-access-token feature.** Stock Taiga (checked against
+   `https://my.taiga.com`) has no self-service PAT: the only tokens it
+   issues are (a) short-lived JWTs from `POST /api/v1/auth` — on that
+   instance, a 24h access token / 8-day refresh token — and (b) OAuth-style
+   "Application" tokens, which require an admin-registered app and a
+   consent/`auth_code` flow (`client.auth_app()`), not something a regular
+   user can self-serve. This server's `auth.py`/CLI has no refresh-token
+   support, so a manually-generated `TAIGA_TOKEN` will just silently stop
+   working after ~24h with no renewal — worse than username/password, which
+   re-authenticates fresh on every server start. Only reach for `TAIGA_TOKEN`
+   when the target instance genuinely offers a durable personal token (e.g.
+   a Taiga Enterprise/hosted deployment with PAT support) — verify that
+   before recommending it, don't assume it exists.
+
+4. **Register at user scope** with `claude mcp add`, using `-e` for every
+   credential env var and the resolved binary (or `uvx` invocation) from
+   step 2:
+   ```bash
+   claude mcp add --scope user taiga \
+     -e TAIGA_HOST=https://my.taiga.com \
+     -e TAIGA_USERNAME=<username> \
+     -e TAIGA_PASSWORD=<password> \
+     -- /absolute/path/to/taiga-mcp-server serve
+   ```
+   or, with a token instead of username/password:
+   ```bash
+   claude mcp add --scope user taiga \
+     -e TAIGA_HOST=https://my.taiga.com \
+     -e TAIGA_TOKEN=<token> \
+     -- /absolute/path/to/taiga-mcp-server serve
+   ```
+   With `uvx` there's no path to resolve — pass the `uvx` invocation itself
+   as the command:
+   ```bash
+   claude mcp add --scope user taiga \
+     -e TAIGA_HOST=https://my.taiga.com \
+     -e TAIGA_TOKEN=<token> \
+     -- uvx --from "python-taiga[mcp]" taiga-mcp-server serve
+   ```
+   `--scope user` (not `local`/`project`) is what makes it "user-wide" —
+   available in every project for that user, stored outside this repo.
+
+5. **Verify** with `claude mcp list` (look for `taiga` ... `✔ Connected`) and
+   `claude mcp get taiga`. If it fails to connect, re-check the resolved
+   binary/command from step 2 and that `TAIGA_HOST` is the site root, not an
+   API subdomain.
+
+6. **Don't persist secrets in the repo.** Credentials belong only in the
+   `claude mcp add -e ...` invocation (stored in the user's own
+   `~/.claude.json`) — never write them into files inside this repository.

MANIFEST.in

@@ -1,8 +1,9 @@
+include AGENTS.md
 include AUTHORS
 include LICENSE
 include README.rst
 include CONTRIBUTING.rst
 include HISTORY.rst
 include requirements.txt
-include requirements-tests.txt
+include requirements-test.txt
 recursive-include taiga *.html *.png *.gif *js *jpg *jpeg *svg *py *mo *po

changes/267.feature

@@ -0,0 +1 @@
+Add MCP server exposing Taiga projects, user stories, tasks, issues, epics, milestones and wiki pages as tools for AI agents. `taiga-mcp-server` also gains `list-tools` and `call` subcommands, letting tools be listed and invoked directly from a shell without an MCP client. The server also exposes custom-attribute value read/write, project membership listing, and epic-user-story linking.

docs/index.rst

@@ -10,6 +10,7 @@ Welcome to python-taiga's documentation!
    :maxdepth: 3
 
    usage
+   mcp
    api
    models
    development