taskadence-mcp 0.1.0__py3-none-any.whl

taskadence_mcp/__init__.py

@@ -0,0 +1,14 @@
+"""taskadence-mcp — TasKadence's MCP server for clients that start a local process.
+
+A PROXY, not a second server: it speaks MCP over stdio to the client and forwards every JSON-RPC message to the
+remote TasKadence MCP server (`<TASKADENCE_API_URL>/mcp`, Streamable HTTP) with
+`Authorization: Bearer $TASKADENCE_TOKEN`.
+The tools, the read-only / tool-group enforcement and the audit trail are the remote server's; this package has no
+tool of its own (a test fails if it grows one).
+"""
+
+from ._version import __version__
+from .config import Config, ConfigError, load_config
+from .proxy import run_proxy
+
+__all__ = ["Config", "ConfigError", "__version__", "load_config", "run_proxy"]

taskadence_mcp/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

taskadence_mcp/_version.py

@@ -0,0 +1,3 @@
+"""The version. `release.yml` stamps it from the tag (`v0.1.0` → `0.1.0`) with `taskadence`'s; `0.x` is pre-release."""
+
+__version__ = "0.1.0"

taskadence_mcp/cli.py

@@ -0,0 +1,57 @@
+"""`taskadence-mcp` — the console script (`uvx taskadence-mcp`). Diagnostics go to stderr; stdout is JSON-RPC only."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import warnings
+
+import anyio
+
+from ._version import __version__
+from .config import BRAND_NAME, GROUPS_ENV, READONLY_ENV, SLUG, TOKEN_ENV, URL_ENV, ConfigError, load_config, redact
+from .proxy import run_proxy, stderr_log
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog=f"{SLUG}-mcp",
+        description=f"{BRAND_NAME}'s MCP server over stdio: a proxy to the remote server (<api>/mcp). "
+        f"The token is read from {TOKEN_ENV}, never from a flag.",
+        epilog=f"Environment: {TOKEN_ENV} (required), {URL_ENV}, {READONLY_ENV}, {GROUPS_ENV}. Flags win.",
+    )
+    p.add_argument("--api-url", help=f"the API's origin (else {URL_ENV}, else production)")
+    p.add_argument(
+        "--readonly",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help=f"only read tools, enforced by the server (else {READONLY_ENV})",
+    )
+    p.add_argument(
+        "--groups", help=f"comma-separated tool groups, e.g. tasks,projects (else {GROUPS_ENV}; default: all but admin)"
+    )
+    p.add_argument("--version", action="version", version=f"{BRAND_NAME} MCP ({SLUG}-mcp) {__version__}")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    ns = parser().parse_args(argv)
+    try:
+        with warnings.catch_warnings(record=True) as caught:  # a pre-rename variable: one stderr line
+            warnings.simplefilter("always", DeprecationWarning)
+            config = load_config(api_url=ns.api_url, readonly=ns.readonly, groups=ns.groups)
+    except ConfigError as exc:
+        stderr_log(str(exc))
+        return 2
+    for warning in caught:
+        stderr_log(f"warning: {warning.message}")
+    stderr_log(f"proxying stdio to {redact(config.mcp_url)}")
+    try:
+        anyio.run(run_proxy, config)
+    except KeyboardInterrupt:
+        return 130
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

taskadence_mcp/config.py

@@ -0,0 +1,131 @@
+"""Where the proxy connects, as whom, and with which options — flags first, then the environment.
+
+The names are `TASKADENCE_*` on purpose — the environment of the *packages* (and of the `tm` CLI, which reads
+the same `TASKADENCE_TOKEN` / `TASKADENCE_API_URL`). The pre-rename `TASKSMATE_*` names are still read when the new one
+is unset, with a `DeprecationWarning` (printed on stderr by the console script). `…_TM` suffixes are the API's own
+server-side convention; do not "fix" these to match it.
+
+    TASKADENCE_TOKEN         required — a `tkd_live_…` / `tkd_test_…` access token (Developers → Tokens; a pre-rename
+                             `tm_live_…` / `tm_test_…` token works too)
+    TASKADENCE_API_URL       the API's origin (default: production); `/mcp` is added here
+    TASKADENCE_MCP_READONLY  `1` / `true` → `?readonly=1`: the SERVER lists and allows only read tools
+    TASKADENCE_MCP_GROUPS    `tasks,projects` → `?groups=…`: the SERVER enables only those groups (`me` is always on)
+
+Flags `--api-url`, `--readonly` / `--no-readonly`, `--groups` win over the environment. There is no `--token` flag:
+a command line is visible to every process on the machine.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import warnings
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from urllib.parse import quote
+
+BRAND_NAME = "TasKadence"  # the wordmark (5.8c), prose only; `_brand.py` in the SDK is the source
+SLUG = "taskadence"
+ENV_PREFIX = "TASKADENCE_"
+LEGACY_ENV_PREFIX = "TASKSMATE_"  # pre-rename; read with a DeprecationWarning when the new name is unset
+
+TOKEN_ENV = ENV_PREFIX + "TOKEN"  # the variable NAME
+URL_ENV = ENV_PREFIX + "API_URL"
+READONLY_ENV = ENV_PREFIX + "MCP_READONLY"
+GROUPS_ENV = ENV_PREFIX + "MCP_GROUPS"
+
+# The production API — the Python SDK's DEFAULT_BASE_URL (the backend's clients table names the same one).
+DEFAULT_API_URL = "https://api.taskadence.com"
+MCP_PATH = "/mcp"
+
+_TRUE, _FALSE = frozenset({"1", "true", "yes", "on"}), frozenset({"0", "false", "no", "off", ""})
+# `tkd_live_` / `tkd_test_`, and the pre-rename `tm_live_` / `tm_test_` (those tokens keep working).
+_TOKEN_SHAPED = re.compile(r"(?:tkd|tm)_(?:live|test)_[A-Za-z0-9_-]*")
+
+
+class ConfigError(ValueError):
+    """A configuration the proxy cannot start with. The message never contains the token."""
+
+
+@dataclass(frozen=True)
+class Config:
+    token: str = field(repr=False)
+    api_url: str
+    readonly: bool = False
+    groups: tuple[str, ...] | None = None
+
+    @property
+    def mcp_url(self) -> str:
+        """`<api>/mcp[?readonly=1][&groups=a,b]` — the remote server's own URL contract (5.1)."""
+        query = []
+        if self.readonly:
+            query.append("readonly=1")
+        if self.groups is not None:
+            query.append("groups=" + quote(",".join(self.groups), safe=","))
+        return f"{self.api_url}{MCP_PATH}" + ("?" + "&".join(query) if query else "")
+
+
+def redact(text: str) -> str:
+    """Anything token-shaped becomes `tkd_…` — a belt for every line this package writes."""
+    return _TOKEN_SHAPED.sub("tkd_…", text)
+
+
+def _env(env: Mapping[str, str], name: str) -> str | None:
+    """`name` (a `TASKADENCE_*` variable), else its deprecated `TASKSMATE_*` twin with a `DeprecationWarning`."""
+    if name in env:
+        return env[name]
+    legacy = LEGACY_ENV_PREFIX + name.removeprefix(ENV_PREFIX)
+    if legacy in env:
+        warnings.warn(
+            f"{legacy} is deprecated: {SLUG}-mcp reads {name}. Rename it in the client's MCP config.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        return env[legacy]
+    return None
+
+
+def _bool(name: str, value: str) -> bool:
+    v = value.strip().lower()
+    if v in _TRUE:
+        return True
+    if v in _FALSE:
+        return False
+    raise ConfigError(f"{name} must be 1 or 0 (got {value!r})")
+
+
+def _groups(value: str) -> tuple[str, ...]:
+    groups = tuple(dict.fromkeys(g.strip().lower() for g in value.split(",") if g.strip()))
+    if not groups:
+        raise ConfigError(
+            "groups is empty: name at least one group (e.g. tasks,projects), or leave it unset for the default"
+        )
+    return groups
+
+
+def _api_url(value: str) -> str:
+    url = value.strip().rstrip("/").removesuffix(MCP_PATH).removesuffix("/v1").rstrip("/")
+    if not url.startswith(("http://", "https://")):
+        raise ConfigError(f"{URL_ENV} / --api-url must start with http:// or https:// (got {redact(value)!r})")
+    return url
+
+
+def load_config(
+    *,
+    api_url: str | None = None,
+    readonly: bool | None = None,
+    groups: str | None = None,
+    environ: Mapping[str, str] | None = None,
+) -> Config:
+    """The flags (None = not given) over the environment."""
+    env = os.environ if environ is None else environ
+    token = (_env(env, TOKEN_ENV) or "").strip()
+    if not token:
+        raise ConfigError(
+            f"{TOKEN_ENV} is not set: create an access token in {BRAND_NAME} (Developers → Tokens) and put it in the "
+            f"client's MCP config as {TOKEN_ENV}"
+        )
+    url = _api_url(api_url if api_url is not None else (_env(env, URL_ENV) or DEFAULT_API_URL))
+    ro = readonly if readonly is not None else _bool(READONLY_ENV, _env(env, READONLY_ENV) or "")
+    raw_groups = groups if groups is not None else (_env(env, GROUPS_ENV) or None)  # an empty variable = unset
+    return Config(token=token, api_url=url, readonly=ro, groups=_groups(raw_groups) if raw_groups is not None else None)

taskadence_mcp/proxy.py

@@ -0,0 +1,182 @@
+"""The bridge: MCP over stdio on one side, the remote server over Streamable HTTP on the other.
+
+Every JSON-RPC message the client writes goes to the server unchanged (`initialize` included — the server is
+stateless), and every message the server answers goes back unchanged; `tools/list` is the server's list. The SDK's
+own transports do the protocol work (`mcp.server.stdio.stdio_server`, `mcp.client.streamable_http`).
+
+One thing is added: an HTTP refusal becomes a JSON-RPC error. The SDK's HTTP client turns a non-2xx answer into an
+exception that no request is waiting for — the client would hang. `ProblemTransport` (an httpx transport wrapper)
+answers such a POST itself with a JSON-RPC error for THAT request id: a 401 names `TASKADENCE_TOKEN` (never its value),
+a 400 carries the server's problem detail (an unknown group), anything else the status and detail; an unreachable
+server says so. Each also writes one line to stderr. stdout carries JSON-RPC only.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Callable
+from typing import Any, TextIO
+
+import anyio
+import httpx
+from anyio.abc import ObjectReceiveStream, ObjectSendStream
+from mcp.client.streamable_http import streamable_http_client
+from mcp.shared.message import SessionMessage
+from mcp.types import JSONRPCError, JSONRPCRequest, JSONRPCResponse
+
+from ._version import __version__
+from .config import BRAND_NAME, SLUG, TOKEN_ENV, Config, redact
+
+UNAUTHORIZED = -32001  # JSON-RPC implementation-defined server errors: -32000 … -32099
+HTTP_ERROR = -32002
+UNREACHABLE = -32003
+DRAIN_SECONDS = 30.0  # after stdin closes: how long answers still in flight are waited for
+
+Log = Callable[[str], None]
+
+
+def stderr_log(line: str) -> None:
+    print(f"{SLUG}-mcp: {redact(line)}", file=sys.stderr, flush=True)
+
+
+def _problem(response_body: bytes) -> dict[str, Any]:
+    try:
+        body = json.loads(response_body or b"{}")
+    except ValueError:
+        return {}
+    return body if isinstance(body, dict) else {}
+
+
+def _jsonrpc_error(request_id: Any, code: int, message: str, data: dict[str, Any]) -> httpx.Response:
+    payload = {"jsonrpc": "2.0", "id": request_id, "error": {"code": code, "message": redact(message), "data": data}}
+    return httpx.Response(200, headers={"content-type": "application/json"}, content=json.dumps(payload).encode())
+
+
+class ProblemTransport(httpx.AsyncBaseTransport):
+    """Wraps the real transport: a refused or failed POST of a request is answered with a JSON-RPC error."""
+
+    def __init__(self, inner: httpx.AsyncBaseTransport, log: Log = stderr_log) -> None:
+        self._inner = inner
+        self._log = log
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        rpc = self._rpc(request)
+        try:
+            response = await self._inner.handle_async_request(request)
+        except httpx.TransportError as exc:
+            if rpc is None:
+                raise
+            where = f"{request.url.scheme}://{request.url.host}" + (f":{request.url.port}" if request.url.port else "")
+            self._log(f"cannot reach {where} ({type(exc).__name__}) — check TASKADENCE_API_URL and the network")
+            return self._answer(rpc, UNREACHABLE, f"{BRAND_NAME} MCP server unreachable at {where}", {"url": where})
+        if rpc is None or response.status_code < 400:
+            return response
+        body = await response.aread()
+        await response.aclose()
+        problem = _problem(body)
+        detail = str(problem.get("detail") or problem.get("title") or response.reason_phrase)
+        data: dict[str, Any] = {
+            "status": response.status_code,
+            **{k: problem[k] for k in ("type", "title", "detail", "errors", "request_id") if k in problem},
+        }
+        if response.status_code == 401:
+            self._log(f"the server refused {TOKEN_ENV} (401): {detail}")
+            message = (
+                f"{BRAND_NAME} refused the access token in {TOKEN_ENV} (401): {detail}. "
+                "Create one in Developers → Tokens."
+            )
+            return self._answer(rpc, UNAUTHORIZED, message, data)
+        self._log(f"the server answered {response.status_code}: {detail}")
+        return self._answer(rpc, HTTP_ERROR, f"{BRAND_NAME} MCP server: {response.status_code} {detail}", data)
+
+    @staticmethod
+    def _rpc(request: httpx.Request) -> dict[str, Any] | None:
+        """The JSON-RPC message a POST carries, or None (a GET / DELETE, or a body that is not JSON)."""
+        if request.method != "POST":
+            return None
+        try:
+            body = json.loads(request.content or b"null")
+        except ValueError:
+            return None
+        return body if isinstance(body, dict) else None
+
+    @staticmethod
+    def _answer(rpc: dict[str, Any], code: int, message: str, data: dict[str, Any]) -> httpx.Response:
+        if "id" not in rpc or "method" not in rpc:  # a notification (or a response): nothing waits for an answer
+            return httpx.Response(202)
+        return _jsonrpc_error(rpc["id"], code, message, data)
+
+    async def aclose(self) -> None:
+        await self._inner.aclose()
+
+
+def http_client(
+    config: Config, *, transport: httpx.AsyncBaseTransport | None = None, log: Log = stderr_log
+) -> httpx.AsyncClient:
+    """The client the SDK's Streamable HTTP transport uses: the bearer, our User-Agent, MCP's timeouts."""
+    inner = transport or httpx.AsyncHTTPTransport()
+    return httpx.AsyncClient(
+        transport=ProblemTransport(inner, log),
+        headers={"Authorization": f"Bearer {config.token}", "User-Agent": f"{SLUG}-mcp/{__version__} (python)"},
+        timeout=httpx.Timeout(30.0, read=300.0),
+        follow_redirects=False,
+    )
+
+
+async def bridge(
+    client_read: ObjectReceiveStream[SessionMessage | Exception],
+    client_write: ObjectSendStream[SessionMessage],
+    config: Config,
+    *,
+    transport: httpx.AsyncBaseTransport | None = None,
+    log: Log = stderr_log,
+) -> None:
+    """Forward messages both ways until the client closes its side (stdin EOF); then answer what is still in flight
+    (at most `DRAIN_SECONDS`) and close the client's side, so the process ends."""
+    pending: set[Any] = set()  # ids of requests sent upstream and not answered yet
+    async with (
+        client_write,
+        http_client(config, transport=transport, log=log) as http,
+        streamable_http_client(config.mcp_url, http_client=http, terminate_on_close=False) as (
+            server_read,
+            server_write,
+            _,
+        ),
+        anyio.create_task_group() as tg,
+    ):
+
+        async def upstream() -> None:
+            async for message in client_read:
+                if isinstance(message, Exception):
+                    log(f"ignored a message that is not JSON-RPC: {type(message).__name__}")
+                    continue
+                if isinstance(message.message.root, JSONRPCRequest):
+                    pending.add(message.message.root.id)
+                await server_write.send(message)
+            with anyio.move_on_after(DRAIN_SECONDS):
+                while pending:
+                    await anyio.sleep(0.02)
+            tg.cancel_scope.cancel()
+
+        async def downstream() -> None:
+            async for message in server_read:
+                if isinstance(message, Exception):
+                    log(f"transport error: {type(message).__name__}: {message}")
+                    continue
+                if isinstance(message.message.root, JSONRPCResponse | JSONRPCError):
+                    pending.discard(message.message.root.id)
+                await client_write.send(message)
+
+        tg.start_soon(upstream)
+        tg.start_soon(downstream)
+
+
+async def run_proxy(config: Config, *, stdin: TextIO | None = None, stdout: TextIO | None = None) -> None:
+    """stdio ↔ the remote server, for the life of the process."""
+    from mcp.server.stdio import stdio_server
+
+    stdin_stream = anyio.wrap_file(stdin) if stdin is not None else None
+    stdout_stream = anyio.wrap_file(stdout) if stdout is not None else None
+    async with stdio_server(stdin_stream, stdout_stream) as (read, write):
+        await bridge(read, write, config)

taskadence_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,222 @@
+Metadata-Version: 2.5
+Name: taskadence-mcp
+Version: 0.1.0
+Summary: The TasKadence MCP server for clients that start a local process: a stdio proxy to the remote server (uvx taskadence-mcp).
+Project-URL: Homepage, https://taskadence.com
+Project-URL: Documentation, https://docs.taskadence.com/mcp/connect/
+Project-URL: Source, https://github.com/indrasol/taskadence-python/tree/main/packages/taskadence-mcp
+Project-URL: Issues, https://github.com/indrasol/taskadence-python/issues
+Project-URL: Changelog, https://github.com/indrasol/taskadence-python/blob/main/CHANGELOG.md
+Author: Indrasol
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: agents,ai,claude,mcp,model context protocol,stdio,taskadence
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Scheduling
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: mcp<2,>=1.30
+Provides-Extra: dev
+Requires-Dist: anyio>=4; extra == 'dev'
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy<2.4,>=1.11; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff==0.16.9; extra == 'dev'
+Requires-Dist: starlette>=0.40; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# taskadence-mcp: TasKadence for AI assistants that start a local program
+
+[![PyPI version](https://img.shields.io/pypi/v/taskadence-mcp)](https://pypi.org/project/taskadence-mcp/)
+[![Python versions](https://img.shields.io/pypi/pyversions/taskadence-mcp)](https://pypi.org/project/taskadence-mcp/)
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue)](https://github.com/indrasol/taskadence-python/blob/main/LICENSE)
+
+[TasKadence](https://taskadence.com) is task and project management for teams. `taskadence-mcp` lets an AI assistant
+(Claude Desktop, Claude Code, Cursor, VS Code and others) read and update your TasKadence tasks, projects and teams,
+through the Model Context Protocol (MCP).
+
+**Do I need this, or the URL?** If your assistant can add an MCP server by URL (often called a remote server or a
+custom connector), use the URL `https://api.taskadence.com/mcp` instead: you sign in with OAuth and there is no token
+to manage. See [Connect](https://docs.taskadence.com/mcp/connect/). Use this package when your assistant can only start
+a local program (a "stdio" server), or when you want it to use a token you created yourself.
+
+Its twin on npm, `npx -y @taskadence/mcp`, does exactly the same with Node.js; pick whichever runtime you have.
+
+> **`0.x` is a pre-release.** Any `0.x` release may change anything; pin a version in configs you depend on.
+
+**Documentation:** [docs.taskadence.com](https://docs.taskadence.com/mcp/) ·
+**Source:** [GitHub](https://github.com/indrasol/taskadence-python) · **Issues:** [GitHub issues](https://github.com/indrasol/taskadence-python/issues)
+
+## Set up in 3 steps
+
+You need a TasKadence account and about five minutes.
+
+### 1. Get a token
+
+A token is a password for programs: the assistant uses it to act for you in one organization.
+
+1. In TasKadence, open **Developers** in the sidebar, stay on the **Tokens** tab and click **Create token**.
+2. Give it a name you will recognise later (for example "Claude Desktop").
+3. Under **Scopes**, tick what the assistant may do. For an assistant that only looks: **Read** on the **Tasks**,
+   **Projects** and **Teams** rows. To let it create and change things too: **Write** on those rows (Write includes
+   Read). The scopes decide which tools the assistant sees.
+4. Click **Create token** and copy it (it starts with `tkd_live_`). **It is shown once.**
+
+Shortcut: **Developers > MCP** in TasKadence writes the configuration for your client, with a new token already in it.
+
+### 2. Install uv
+
+`uvx` comes with [uv](https://docs.astral.sh/uv/getting-started/installation/), a Python tool runner. It downloads and
+runs `taskadence-mcp` (and a suitable Python, if you have none) the first time your client starts it. Skip this step
+if `uvx --version` already prints a version.
+
+macOS or Linux:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Windows PowerShell:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Prefer pip? `pip install taskadence-mcp` installs a `taskadence-mcp` command; then use `"command": "taskadence-mcp"`
+and `"args": []` below. `taskadence-mcp --help` lists the options.
+
+### 3. Add it to your client
+
+Paste your token where the examples say `tkd_live_your_token_here`, then restart the client.
+
+**Claude Desktop.** Open **Settings > Developer > Edit Config**. That opens `claude_desktop_config.json`, which lives
+at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and
+`%APPDATA%\Claude\claude_desktop_config.json` on Windows. Add the `taskadence` entry (keep any other servers already
+under `mcpServers`), save, then quit Claude Desktop completely and open it again.
+
+```json
+{
+  "mcpServers": {
+    "taskadence": {
+      "command": "uvx",
+      "args": ["taskadence-mcp"],
+      "env": { "TASKADENCE_TOKEN": "tkd_live_your_token_here" }
+    }
+  }
+}
+```
+
+**Claude Code.** One command (add `--scope user` to use it in every project):
+
+```bash
+claude mcp add --env TASKADENCE_TOKEN=tkd_live_your_token_here --transport stdio taskadence -- uvx taskadence-mcp
+```
+
+**Cursor.** Put the same JSON as Claude Desktop in `~/.cursor/mcp.json` for every project
+(`%USERPROFILE%\.cursor\mcp.json` on Windows), or in `.cursor/mcp.json` inside one project.
+
+**VS Code.** Put this in `.vscode/mcp.json` in your workspace, or, for every workspace, run **MCP: Open User
+Configuration** from the Command Palette. VS Code uses `servers` and `"type": "stdio"`:
+
+```json
+{
+  "servers": {
+    "taskadence": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["taskadence-mcp"],
+      "env": { "TASKADENCE_TOKEN": "tkd_live_your_token_here" }
+    }
+  }
+}
+```
+
+Keep tokens out of git: a project file (`.cursor/mcp.json`, `.vscode/mcp.json`) is easy to commit by mistake, so
+prefer the user-level file for a config that holds a token.
+
+## Check it works
+
+Ask your assistant: *"Which TasKadence account and organization are you connected to?"* It should call the `whoami`
+tool (your client may ask you to allow it first) and answer with your name and your organization. Then try *"List my
+tasks that are in progress."*
+
+Your client also lists its MCP servers: `taskadence` should be there, connected, with its tools (in Claude Code, type
+`/mcp`). An error or an empty tool list means one of the problems below.
+
+## Troubleshooting
+
+- **"TASKADENCE_TOKEN is not set":** the `env` block is missing or the name is misspelled. Fix the config and restart
+  the client.
+- **Token refused (401):** the error says "TasKadence refused the access token in TASKADENCE_TOKEN (401)". The token
+  was copied wrong, has expired or was revoked. Create a new one in **Developers > Tokens**, replace it in the config,
+  and restart the client.
+- **A tool is missing, or "insufficient scope":** the token's scopes decide which tools appear. Create a token with
+  **Write** ticked to let the assistant change things (scopes cannot be added to an existing token).
+  `TASKADENCE_MCP_READONLY=1` hides every tool that writes, and `TASKADENCE_MCP_GROUPS` limits the tool groups (see
+  Configure below).
+- **`uvx` not found (`spawn uvx ENOENT`):** install it (step 2), then restart the client. On macOS an app
+  opened from the Dock may not see your terminal's `PATH`: put the full path in `"command"` (find it with
+  `which uvx`; on Windows, `where uvx`).
+- **Wrong Python 3.10 version:** `taskadence-mcp` needs Python 3.10 or later. Check with `python --version`.
+- **"MCP server unreachable":** the computer cannot reach the TasKadence API. Check the network, and
+  `TASKADENCE_API_URL` if you set it.
+
+Still stuck? Open a [GitHub issue](https://github.com/indrasol/taskadence-python/issues) with the error message and your client's name; never paste a live
+token.
+
+## Configure
+
+Everything is optional except the token. Set these in the `env` block of your client's config, or pass the flags in
+`args`.
+
+| Variable | Flag | |
+|---|---|---|
+| `TASKADENCE_TOKEN` | none | **Required.** A personal access token (`tkd_live_…`). |
+| `TASKADENCE_API_URL` | `--api-url` | The API's origin. Default: `https://api.taskadence.com`. `/mcp` is added. |
+| `TASKADENCE_MCP_READONLY` | `--readonly` / `--no-readonly` | `1`: only tools that read, enforced by the server. |
+| `TASKADENCE_MCP_GROUPS` | `--groups` | For example `tasks,projects`: only those tool groups. Default: every group except `admin`; `me` is always on. |
+
+Flags win over the environment. There is no token flag: a command line is visible to every process on the machine.
+The tools and groups are listed in [Tools](https://docs.taskadence.com/mcp/tools/).
+
+## What it does, exactly
+
+`taskadence-mcp` is a proxy, not a second server: it speaks MCP over stdio to your client and forwards every message to the
+TasKadence remote MCP server (`<api>/mcp`, Streamable HTTP) with your token. The tools, the read-only and tool-group
+enforcement, and the audit trail are the remote server's.
+
+- stdin goes to the remote server unchanged (`initialize` included; the server is stateless), and the server's answers
+  go to stdout unchanged. stdout carries JSON-RPC and nothing else; diagnostics go to stderr, never the token.
+- A refused token (401) is answered with a JSON-RPC error naming `TASKADENCE_TOKEN` (code `-32001`), any other HTTP
+  refusal with its status and the server's detail (`-32002`; an unknown group is a 400), an unreachable server with
+  `-32003`. Each also writes one line to stderr.
+- It holds no tool of its own and reaches nothing but `<api>/mcp`.
+
+## Requirements
+
+Python 3.10 or later. Depends on `mcp` (the official MCP SDK, `<2`) and `httpx`.
+
+## Support and security
+
+Bugs and questions: [GitHub issues](https://github.com/indrasol/taskadence-python/issues); never paste a live token. Vulnerabilities: report them privately as
+described in [SECURITY.md](https://github.com/indrasol/taskadence-python/blob/main/SECURITY.md) (GitHub private vulnerability reporting, or
+srvcs.infra@indrasol.com).
+
+## License
+
+Apache License 2.0. See [LICENSE](https://github.com/indrasol/taskadence-python/blob/main/LICENSE). The license grants no right to use the TasKadence or
+Indrasol names or marks.

taskadence_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+taskadence_mcp/__init__.py,sha256=JocCBWNDIt0cKCqa6aouDd0F0pDui-DQrTBlg5Ue4no,686
+taskadence_mcp/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+taskadence_mcp/_version.py,sha256=xYfYu8kWH6qTlsHY3EWOGGXeanO_73F-Q1cHode1BRs,145
+taskadence_mcp/cli.py,sha256=bkOhHgg-yGaSu0qGl4spb-GLsBVAN6HQkVzzPSGvowE,2079
+taskadence_mcp/config.py,sha256=eRQjBv860u0SIHbGPDNt-bCmeX3-MG_KQRGNEz2Z1FE,5533
+taskadence_mcp/proxy.py,sha256=h4GkzurkW3HuZLuJbH5LHcUJL9mzcTPkLnI9qDn6H3Q,8220
+taskadence_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+taskadence_mcp-0.1.0.dist-info/METADATA,sha256=RJBdrSANLxM9xxDfywhUFs4Y4yB1yNv9yXzYHBii4jA,11021
+taskadence_mcp-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+taskadence_mcp-0.1.0.dist-info/entry_points.txt,sha256=B0pWOELRgerE4nqlm9dXAmfJmcgX6sanC7mfY0rKEtI,59
+taskadence_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+taskadence_mcp-0.1.0.dist-info/licenses/NOTICE,sha256=XqW5JQItL0shyyA_LLMkQGrcfEHL_RartDaS-0EFR_A,46
+taskadence_mcp-0.1.0.dist-info/RECORD,,

taskadence_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

taskadence_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+taskadence-mcp = taskadence_mcp.cli:main

taskadence_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

taskadence_mcp-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,2 @@
+Taskadence Python SDK
+Copyright 2026 Indrasol