@taiga-ai/mcp-server 0.25.0-rc.474 → 0.26.0-rc.480

package/README.md

@@ -0,0 +1,111 @@
+# @taiga-ai/mcp-server
+
+The [Taiga](https://tai.ga) MCP server lets an AI assistant work with your Taiga organization from the editor. It can:
+
+- read where a product stands, its policies, initiatives, runs and findings;
+- operate the line: queue initiatives, review plans, follow runs;
+- set up factories and products.
+
+It runs locally over stdio and calls the Taiga API with your API key.
+
+## Before you install
+
+1. Create an API key in Taiga under **Settings > Account > API keys**.
+2. The key acts as you. It can do what your role can do, within the key's scopes.
+
+The examples pin a release (`@taiga-ai/mcp-server@0.26.0`), so an install runs the version you chose rather than whatever `latest` is at the next start. Taiga's settings page shows the snippet for your environment.
+
+## Install
+
+### Claude Code
+
+Paste your key when the command waits for it; it is read without echo and stays out of your shell history:
+
+```sh
+read -rs TAIGA_API_KEY && claude mcp add taiga -e TAIGA_API_KEY="$TAIGA_API_KEY" -- npx -y @taiga-ai/mcp-server@0.26.0
+```
+
+### Claude Desktop
+
+In `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "taiga": {
+      "command": "npx",
+      "args": ["-y", "@taiga-ai/mcp-server@0.26.0"],
+      "env": { "TAIGA_API_KEY": "your-key-here" }
+    }
+  }
+}
+```
+
+### Cursor and Windsurf
+
+The same `mcpServers` block, in `.cursor/mcp.json` or `.windsurf/mcp.json`.
+
+### VS Code
+
+In `.vscode/mcp.json`. VS Code reads `servers`, and can prompt for the key once and keep it out of the file:
+
+```json
+{
+  "inputs": [{ "type": "promptString", "id": "taiga-api-key", "description": "Taiga API key", "password": true }],
+  "servers": {
+    "taiga": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@taiga-ai/mcp-server@0.26.0"],
+      "env": { "TAIGA_API_KEY": "${input:taiga-api-key}" }
+    }
+  }
+}
+```
+
+### Codex
+
+In `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.taiga]
+command = "npx"
+args = ["-y", "@taiga-ai/mcp-server@0.26.0"]
+env = { TAIGA_API_KEY = "your-key-here" }
+```
+
+## Configuration
+
+| Variable        | Required                         | Meaning                                                                                                                                      |
+| --------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TAIGA_API_KEY` | Yes                              | Your API key.                                                                                                                                |
+| `TAIGA_API_URL` | For `@dev` and `@staging` builds | The Taiga API. A release defaults to `https://api.eu.tai.ga`. It must be https (plain http only for `localhost`), with no query or fragment. |
+
+## First steps
+
+- Ask about a product. The assistant starts with `taiga_get_product_context`, which takes the git remote of the checkout you are in, a slug or an ID.
+- `taiga_list_action_required` lists what waits on people.
+- `taiga_whoami` says which tools your key can call.
+
+## How it behaves
+
+This is what a security reviewer should know.
+
+- **Named tools, one risk class each.** Every tool is one of four kinds: a read, a plain write, a write that starts paid agent work, or a write others see. No tool switches between kinds on an argument, so a client can allow the reads and prompt on the rest.
+- **Reads are free, writes are announced.**
+  - A tool that writes opens its description with "Writes.", "Ask first (paid agent work)." or "Ask first (others see it).".
+  - The server tells the assistant to wait for your yes before an ask-first tool.
+  - Your client's own approval prompt is the control that enforces it.
+- **The key is the boundary.** The API enforces what the key may do, product by product. The server only registers the tools your key can use.
+- **Record text is data.** Initiative descriptions, document text, findings and pull request titles were written by people or agents. The server tells the assistant to read them as data, never as instructions.
+- **Version check.** The server checks at start that the Taiga API it reached supports this version, and refuses to start if not, saying why.
+- **Nothing on stdout but the protocol.** The server writes only protocol messages to stdout. Its log goes to stderr and does not include your email.
+
+Organization administration stays in the web. That covers members and roles, SSO, API keys, connecting GitHub, the Discovery conversation, and deleting factories and products.
+
+## Troubleshooting
+
+- **"TAIGA_API_KEY environment variable is required":** the client did not pass the key to the server. Check the `env` block or the `-e` flag.
+- **"Failed to validate API key":** the key is wrong, revoked or expired. Create a new one.
+- **"The Taiga API at ... is older than @taiga-ai/mcp-server ... needs":** run the release your Taiga environment names on its settings page.
+- **"This is a pre-release build":** `@dev` and `@staging` builds are for Taiga's own environments and need `TAIGA_API_URL`.