plugvan-mcp 0.1.1__tar.gz

plugvan_mcp-0.1.1/.gitignore

@@ -0,0 +1,43 @@
+# Çevre değişkenleri ve Gizli Anahtarlar (API Tokens)
+.env
+*.env
+.env.*
+!.env.example
+
+# Google OAuth kimlik, oturum ve token dosyaları
+credentials.json
+credentials*.json
+client_secret*.json
+client_secrets.json
+token.json
+token*.json
+*.token
+*.pickle
+
+# Kişisel / Yerel görev ve veri dosyaları
+tasks.json
+debug_tasks.py
+debug_*.py
+scratch/
+*.log
+
+# Python ortamı, bytecode ve cache
+venv/
+.venv/
+env/
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE, Editör ve İşletim Sistemi dosyaları
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+# Claude Code kişisel ayarları
+.claude/settings.local.json

plugvan_mcp-0.1.1/CHANGELOG.md

@@ -0,0 +1,272 @@
+# Changelog
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Backlog
+- `update_section`: expose `order` and `collapsed` (supported by the SDK).
+- `project_move`: needs the Sync API's separate command.
+
+## [0.1.1] - 2026-10-20
+
+The first release published to PyPI: `plugvan-mcp` 0.1.1 installs from
+PyPI as well as from the GitHub Release assets. It contains the changes
+tested in 0.1.1rc1.
+
+### Added
+- Final releases are published to PyPI with trusted publishing (#78): a
+  `vX.Y.Z` tag uploads the sdist and wheel that CI built and tested, with
+  no API token or secret, after the maintainer approves the `pypi`
+  deployment, then checks that PyPI serves exactly those files, with the
+  same names and sha256 digests.
+- Release candidates are published the same way to TestPyPI only (#77),
+  to rehearse a release before it reaches PyPI.
+- Release checks ahead of publishing (#76): the release checks that both
+  archive file names carry exactly the tag's version, and every PR runs
+  `twine check --strict`, so the README must render as the PyPI project
+  description.
+
+### Changed
+- Release versions must be canonical, `X.Y.Z` or `X.Y.ZrcN` (#76); other
+  spellings, and `a`, `b`, `dev`, `post` and local versions, are
+  rejected before anything is published. Only an `X.Y.ZrcN` version is a
+  prerelease.
+- The README reads the same on GitHub and on PyPI, where it is the
+  project description: the architecture diagram is plain text, warnings
+  are plain quotes, the LICENSE links are absolute, and the navigation
+  links point at headings.
+
+### Fixed
+- README: the install step finds `uvx` with `where.exe uvx`, which also
+  works in PowerShell (there, plain `where` is an alias of `Where-Object`
+  and prints nothing).
+
+## [0.1.1rc1] - 2026-10-20
+
+Release candidate for 0.1.1, published to TestPyPI only to rehearse the
+PyPI release; it is not uploaded to PyPI.
+
+### Added
+- Release candidates are published to TestPyPI with trusted publishing
+  (#77): a `vX.Y.ZrcN` tag uploads the sdist and wheel that CI built and
+  tested, with no API token or secret, then checks that TestPyPI serves
+  exactly those files, with the same names and sha256 digests.
+- Release checks ahead of PyPI publishing (#76): the release checks that
+  both archive file names carry exactly the tag's version, and every PR
+  runs `twine check --strict`, so the README must render as the PyPI
+  project description.
+
+### Changed
+- Release versions must be canonical, `X.Y.Z` or `X.Y.ZrcN` (#76); other
+  spellings, and `a`, `b`, `dev`, `post` and local versions, are
+  rejected before anything is published. Only an `X.Y.ZrcN` version is a
+  prerelease.
+- The README reads the same on GitHub and on PyPI, where it is the
+  project description: the architecture diagram is plain text, warnings
+  are plain quotes, the LICENSE links are absolute, and the navigation
+  links point at headings.
+
+### Fixed
+- README: the install step finds `uvx` with `where.exe uvx`, which also
+  works in PowerShell (there, plain `where` is an alias of `Where-Object`
+  and prints nothing).
+
+## [0.1.0] - 2026-10-19
+
+First public release of Plugvan: Todoist tools for Claude Desktop as an
+MCP server over STDIO. It runs locally; Claude Desktop starts it as a
+subprocess, so no web server or deployment is needed.
+
+### Added
+- Todoist tools for tasks (with subtasks and deadlines), projects (with
+  subprojects), sections, labels and comments.
+- Validated inputs and clear errors. Project, section and label names
+  are matched case-insensitively, with Turkish/Unicode normalization. An
+  unknown name returns an error and nothing is written; when several
+  items match, the tool lists up to 5 candidates as `name (ID)` and asks
+  for the ID. The delete and update tools for projects, sections and
+  labels accept only an ID or an exact name. Names are limited to 120
+  characters for projects and sections and 60 for labels.
+- Tool results in English (default) or Turkish, selected with the
+  `PLUGVAN_LANG` environment variable (`en` or `tr`). Tool descriptions
+  and logs are always English.
+- Install without cloning (#63): the `plugvan-mcp` distribution (Python
+  3.10+) installs from the release wheel with uvx or with pip into a
+  virtual environment, and `plugvan-mcp todoist` starts the server. The
+  README has the Claude Desktop configs. `plugvan-mcp --version` prints
+  the installed version.
+- Configuration in the Claude Desktop config's `env` block:
+  `TODOIST_API_TOKEN` and the optional `PLUGVAN_LANG`. `plugvan-mcp`
+  does not read a `.env` file.
+- Each release ships a wheel and an sdist as assets.
+
+### Security
+- HTTP response bodies of failed Todoist API calls are logged only at
+  DEBUG level (#57); the HTTP status is still logged at ERROR. Response
+  bodies can echo user content and account data, so they stay out of the
+  default (INFO) logs.
+- The token in the `env` block is stored in plain text in
+  `claude_desktop_config.json`; keep that file private and never commit
+  it to a repository.
+
+### Removed
+- The legacy Bridge code (webhook server, Google Tasks sync worker,
+  Gemini tool schema) is removed; it is preserved at the tag
+  `legacy-bridge-final`.
+
+### Upgrading from a checkout
+- If you ran the server from a checkout before, update a Claude Desktop
+  config that runs `todoist_mcp.py` to `"args": ["-m", "plugvan.todoist"]`
+  with `"PYTHONPATH": "<REPO_PATH>"` in `env`, then restart Claude
+  Desktop.
+- Tool results now default to English. To keep Turkish output, set
+  `PLUGVAN_LANG=tr` in `.env` or in the `env` block of the Claude Desktop
+  config, then restart Claude Desktop.
+- `requirements.txt` is replaced by `pip install -e ".[test]"`: in an
+  existing checkout venv, run it instead of
+  `pip install -r requirements.txt`.
+
+## [0.1.0rc1] - 2026-10-19
+
+Release candidate for 0.1.0.
+
+## Development history (before 0.1.0)
+
+Detailed entries from development before the first release, kept for reference.
+
+### Changed
+- README: install Plugvan for Claude Desktop without a clone, with uvx
+  or pip from the release wheel; the token goes in the config's `env`
+  block (#63).
+- HTTP response bodies of failed Todoist API calls are logged only at
+  DEBUG level (#57). The HTTP status is still logged at ERROR. Response
+  bodies can echo user content and account data, so they no longer appear
+  in the default (INFO) logs.
+- The sdist now contains only what is needed to build and describe the
+  package: `plugvan/`, `pyproject.toml`, `PKG-INFO`, `README.md`, `LICENSE`,
+  `CHANGELOG.md` and `.gitignore` (which hatchling always adds). Tests,
+  docs, CI files, `CLAUDE.md` and `.env.example` are no longer included
+  (#61). The wheel is unchanged.
+- **`.env` is read only by `python -m plugvan.todoist` (#59).** The new
+  `plugvan-mcp todoist` console script never reads `.env`; it takes
+  `TODOIST_API_TOKEN` and `PLUGVAN_LANG` from the environment, i.e. the
+  `env` block of the MCP client config, which is the supported way to
+  configure it. `python -m plugvan.todoist` keeps loading `.env` as
+  before, and variables from the client's `env` block still win over it.
+- **Breaking: tool results are now in English by default (#37).**
+  - Every MCP tool result and error message now defaults to English. The
+    new optional `PLUGVAN_LANG` environment variable selects the language:
+    `en` (default) or `tr`. An unsupported value falls back to English and
+    is logged once.
+  - **Migration:** to keep the previous Turkish output, set
+    `PLUGVAN_LANG=tr` in `.env` or in the `env` block of the Claude Desktop
+    config, then restart Claude Desktop. With `PLUGVAN_LANG=tr` the tool
+    results are the same as before.
+  - Tool descriptions and logs are always English, in both languages.
+  - Tool surface: `create_task`'s `project_name` default is now `"Inbox"`
+    (was `"Gelen Kutusu"`); a task without a project still goes to the
+    Inbox. The `parent_id` description is now English, and the
+    `project_name` description and the tool description say `'Inbox'`.
+- **Breaking: safer name resolution in the MCP tools (#9).**
+  - `delete_project`, `update_project`, `delete_section`, `update_section`,
+    `delete_label` and `update_label` no longer use partial matching or the
+    Inbox alias. They accept only an ID or an exact name.
+  - An unknown project, section or label name now returns an error, and
+    nothing is written. Previously `create_task` silently created the task in
+    the Inbox.
+  - Sections are matched only by ID or exact name, and only inside the
+    resolved project. In `update_task` without `project_name`, that is the
+    task's current project.
+  - `update_task` validates the target project and section before writing.
+    The old "Görev güncellendi fakat hedef proje bulunamadı" and "…hedef
+    bölüm bulunamadı" messages are gone, because nothing is updated any more
+    when the target is missing.
+  - When several items match, the tool returns an ambiguity error that lists
+    at most 5 candidates as `name (ID)` and asks for the ID.
+  - Labels: a leading `@` is stripped, and two labels whose names differ only
+    by case are treated as ambiguous.
+  - A project name that partially matches exactly one project is still
+    accepted by `create_task`, `update_task`, `create_project` (parent),
+    `create_section` and `list_sections`. The message shows the project's
+    real name instead of the input.
+  - A failed lookup (Todoist API error while listing) returns the tool's
+    generic error instead of "not found". Only the error type is logged.
+- The Todoist MCP server moved from the single-file `todoist_mcp.py` into
+  the `plugvan.todoist` package (server, client, limits, resolvers, and one
+  tools module per domain). No behavior change: same 22 tools, names,
+  descriptions and schemas.
+- Entry point is now `python -m plugvan.todoist` (the old script is removed,
+  no shim).
+- Tests patch a single target: `plugvan.todoist.client.get_api_client`
+  (renamed from the private helper). MCP tests now live in `tests/todoist/`.
+- **Action required:** Claude Desktop configs that run the old
+  `todoist_mcp.py` path must be updated to `"args": ["-m", "plugvan.todoist"]`
+  with `"PYTHONPATH": "<REPO_PATH>"` in `env`, then restart Claude Desktop.
+
+### Added
+- Tag-triggered GitHub Releases (#62): pushing a `v<version>` tag on a
+  commit on `main` creates a GitHub Release with the sdist and wheel that
+  the `package (ubuntu-24.04, Python 3.10)` job built and tested in the
+  same run, after every test and package job passed. The tag must be
+  exactly `v` + the `pyproject.toml` version, and the release notes are
+  that version's CHANGELOG section. Tags containing `rc` are published
+  as prereleases.
+- CI package jobs (#61): `package (ubuntu-24.04, Python 3.10)` builds the
+  sdist and wheel once, checks their contents against an allowlist and a
+  ban list, installs the wheel into a clean venv and runs the
+  installed-mode tests (the STDIO server check and the `.env` rules)
+  before uploading the files as an artifact.
+  `package (windows-2025, Python 3.14)` installs and tests that same
+  artifact on Windows.
+- `plugvan-mcp` console script (#59): `plugvan-mcp todoist` starts the
+  Todoist MCP server over STDIO, like `python -m plugvan.todoist`.
+  `plugvan-mcp --version` prints the installed version. A missing or
+  unknown integration prints usage on stderr and exits with status 2.
+- `pyproject.toml`: the project is now the Python distribution `plugvan-mcp`
+  (import package `plugvan`, Python 3.10+), and `pyproject.toml` is the
+  single source of its dependencies. Test-only dependencies are in the
+  `test` extra (#58).
+- Name-resolution tests: the four resolver outcomes, ambiguity and the
+  5-candidate cap, no write on any error, and no exception text or HTTP
+  response in tool output or logs.
+- MCP tool surface snapshot test: all 22 tools' name, description,
+  input and output schema are compared against a fixture recorded before
+  the move.
+- `update_section` MCP tool: rename a Todoist section by ID or name.
+  Optional `project_name_or_id` scopes name resolution so same-named
+  sections in different projects can't be confused.
+- Tests for `update_section` (rename by name/ID, project scoping,
+  not-found, empty/too-long input, sanitized error).
+
+### Removed
+- **The legacy Bridge surface.** The repository is now only the
+  `plugvan.todoist` MCP server; MCP tools and behavior are unchanged.
+  Removed: the FastAPI webhook server (`app.py`), the webhook client
+  (`send_to_bridge.py`), the standalone CLI (`main.py`), the Google Tasks
+  sync worker (`sync_worker.py`), the shared legacy core (`parser.py`,
+  `models.py`, `config.py`, `todoist_client.py`), the Gemini tool schema
+  (`gemini_tool_schema.json`), the sample tasks file (`tasks_sample.json`),
+  `Dockerfile` / `.dockerignore`, and their tests.
+- The last commit with this code is tagged `legacy-bridge-final`; recover
+  it with `git checkout legacy-bridge-final`.
+- Dropped dependencies: `requests`, `pydantic-settings`, `colorama`,
+  `fastapi`, `uvicorn`, `google-auth`, `google-auth-oauthlib`,
+  `google-auth-httplib2`, `google-api-python-client`, `pytest-asyncio`.
+- `WEBHOOK_SECRET_TOKEN` and `ALLOWED_ORIGINS` are no longer read; only
+  `TODOIST_API_TOKEN` is needed.
+- `requirements.txt` (#58). **Migration:** in an existing checkout venv,
+  run `pip install -e ".[test]"` instead of `pip install -r requirements.txt`.
+  The `python -m plugvan.todoist` Claude Desktop config keeps working
+  unchanged.
+- The unused standalone `fastmcp` dependency (#58). The server uses the
+  MCP SDK's built-in FastMCP; standalone `fastmcp` will be added back
+  with the tool-name namespacing migration.
+
+### Fixed
+- MCP clients on Python 3.10–3.12 received indented tool descriptions: the
+  3.13+ compiler strips docstring indentation, and older versions did not.
+  Descriptions are now normalized at tool registration with a port of the
+  3.13 compiler's docstring cleaning, so every supported version publishes
+  the same descriptions as 3.13+. Tool docstrings, names and schemas are
+  unchanged.

plugvan_mcp-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nuri Kağan Kurubaş
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.