sp-local-bridge 0.2.1__tar.gz

sp_local_bridge-0.2.1/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.{js,json,yaml,yml,toml,md}]
+indent_style = space
+indent_size = 2
+
+[Makefile]
+indent_style = tab

sp_local_bridge-0.2.1/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      dev-deps:
+        patterns:
+          - "ruff"
+          - "pyright"
+          - "pytest*"
+          - "pre-commit"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

sp_local_bridge-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Least privilege by default: these jobs only read the repository.
+# A job needing more declares it itself, so the elevation stays visible
+# at the job that uses it.
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --python ${{ matrix.python-version }}
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Type check
+        run: uv run pyright
+
+      - name: Test
+        run: uv run pytest --cov --cov-report=xml
+
+      - name: Build
+        run: uv build --quiet
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.11'
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-report
+          path: coverage.xml

sp_local_bridge-0.2.1/.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build docs
+        run: npm run docs:build
+
+      - uses: actions/configure-pages@v6
+
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

sp_local_bridge-0.2.1/.github/workflows/release.yml

@@ -0,0 +1,81 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+# Least privilege by default; the publish job adds id-token for PyPI's
+# trusted publishing and nothing else.
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run checks
+        run: |
+          uv run ruff format --check .
+          uv run ruff check .
+          uv run pyright
+          uv run pytest
+
+      - name: Build package
+        run: uv build
+
+      - name: Generate checksums
+        run: |
+          cd dist
+          sha256sum * > SHA256SUMS
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          generate_release_notes: true
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+            dist/SHA256SUMS
+
+      # Only the distributions — pypi-publish rejects a directory containing
+      # anything else, and SHA256SUMS is not a distribution.
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    # Must match the PyPI trusted publisher configuration exactly: this
+    # workflow filename and this environment name are both part of the claim
+    # PyPI verifies.
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

sp_local_bridge-0.2.1/.gitignore

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+MANIFEST
+
+# Node (docs site only)
+node_modules/
+docs/.vitepress/dist/
+docs/.vitepress/cache/
+docs/.vitepress/.temp/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Type checkers
+.mypy_cache/
+.pytype/
+.pyre/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environments / secrets
+.env
+.envrc
+
+# Build artifacts
+*.whl
+
+# Personal working files (planning, research, notes)
+working/
+
+# Reference repos (cloned for development reference)
+refs/
+
+# Plugin (not shipped until fallback implementation exists)
+plugin/
+
+# VitePress (docs site)
+.vitepress
+.temp

sp_local_bridge-0.2.1/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-added-large-files
+        args: [--maxkb=500]
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.12
+    hooks:
+      - id: ruff-format
+      - id: ruff
+        args: [--fix]

sp_local_bridge-0.2.1/.python-version

@@ -0,0 +1 @@
+3.11

sp_local_bridge-0.2.1/AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS.md
+
+Instructions for AI coding agents working in this repository.
+
+## Project
+
+Super Productivity Local Bridge — a local automation bridge for the Super Productivity desktop app. Uses the SP Local REST API (`http://127.0.0.1:3876`) as the primary app-control path, with MCP as one thin host adapter.
+
+## Stack
+
+- **Python 3.11+** with `uv` for environment/dependency management
+- **Pydantic** for models and validation
+- **httpx** for the SP Local REST client
+- **MCP Python SDK** for the MCP adapter (stdio transport)
+- **Ruff** for formatting and linting
+- **Pyright** for type checking
+- **Pytest** for testing
+
+## Layout
+
+```
+src/sp_local_bridge/       Python package (src layout)
+  core/                    Core operation models, errors, service
+  sp_rest/                 SP Local REST API client
+  adapters/                Host adapters (MCP server)
+  diagnostics/             Doctor, health checks
+  cli.py                   CLI entry point
+tests/                     Pytest tests
+scripts/                   Install/uninstall shell scripts
+docs/                      Documentation + host guides
+```
+
+## Commands
+
+```sh
+uv sync                    # Install deps (creates .venv)
+uv run ruff format .       # Format
+uv run ruff check .        # Lint
+uv run pyright             # Type check
+uv run pytest              # Test
+uv run pytest --cov        # Test with coverage
+make check                 # Run all checks (format, lint, types, tests)
+```
+
+## Conventions
+
+- All Python code lives under `src/sp_local_bridge/` (src layout).
+- Use pydantic BaseModel for data structures crossing boundaries.
+- Use `httpx.AsyncClient` for HTTP calls to SP.
+- MCP adapter is thin — all logic lives in `core/`.
+- No Claude/agent-specific language in tool descriptions or core code.
+- Use SP-native camelCase field names at REST boundaries (`projectId`, `tagIds`).
+- Type annotations on all public functions.
+- Tests in `tests/` mirror `src/` structure.
+
+## Do NOT
+
+- Add runtime deps without discussing (the dep tree is intentionally small).
+- Put business logic in the MCP adapter.
+- Reference specific AI hosts (Claude, Cursor, etc.) outside `docs/hosts/`.
+- Create files named after phases or milestones.
+- Commit `.venv/`, `working/`, `refs/`, or build artifacts.

sp_local_bridge-0.2.1/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.1] — 2026-09-05
+
+Final release. The project is archived; this version exists so the package name
+is registered on PyPI and cannot be claimed by anyone else.
+
+### Changed
+
+- Publish to PyPI from CI using trusted publishing (OIDC), so the distribution
+  that carries this name has verifiable provenance. Earlier releases were
+  GitHub Release artifacts only — the name was never registered on PyPI, which
+  left it available for anyone to take.
+- The release is **yanked** on PyPI: the name stays reserved, but resolvers skip
+  it, so it will not be installed by accident. An exact pin
+  (`sp-local-bridge==0.2.1`) still resolves for anyone who genuinely needs it.
+
+### Note
+
+No functional changes. Use
+[super-productivity-local-gobridge](https://github.com/CameronBrooks11/super-productivity-local-gobridge)
+instead.
+
+## [0.2.0] — 2026-05-31
+
+### Added
+
+- **Task list filters**: `query`, `projectId`, `tagId`, `includeDone`, `source` parameters on `task.list`
+- **Time fields**: `timeEstimate` and `timeSpent` (milliseconds, non-negative) on `task.create` and `task.update`
+- **Current task**: `task.get_current` to read the active task, `task.set_current` to set or clear it
+- **Status read**: `status.get` operation for SP application status summary
+- **Project/tag search**: `query` parameter on `project.list` and `tag.list`
+- MCP tools: `get_status`, `get_current_task`, `set_current_task`
+- CLI commands: `status`, `tasks current`, `tasks set-current <id>`, `tasks clear-current`, filter flags on `tasks list`, `--query` on `projects list` / `tags list`
+- 46 new tests (212 total)
+
+### Changed
+
+- Operation count: 13 → 16
+- `task.list` now accepts optional filter payload (previously rejected any payload)
+- `project.list` and `tag.list` now accept optional `query` payload
+
+## [0.1.1] — 2026-05-31
+
+### Added
+
+- `sp-local-bridge-configure` command for auto-writing MCP config to host files
+- Agent setup skill (`skills/sp-local-bridge-setup/`) for guided installation
+- Regression tests for TOML preservation, doctor parse-error handling, uninstall ordering
+
+### Fixed
+
+- TOML auto-config: surgical write now only touches `[mcp_servers.superProductivity]`, preserving all other file content including inline tables, env maps, and numbers
+- TOML auto-config: malformed existing TOML fails closed (error code 1) instead of silently appending
+- TOML auto-config: removal now deletes descendant tables (e.g. `[mcp_servers.superProductivity.env]`)
+- Doctor: malformed host config produces a failed diagnostic check instead of crashing or false-passing
+- Uninstall: host config cleanup runs before package removal; failures are surfaced clearly
+
+## [0.1.0] — 2026-05-30
+
+### Added
+
+- Core operation layer with 13 operations: `task.list`, `task.get`, `task.create`, `task.update`, `task.complete`, `task.uncomplete`, `task.start`, `task.stop_current`, `task.archive`, `task.restore`, `project.list`, `tag.list`, `bridge.health`
+- SP Local REST API client with full envelope parsing, timeout handling, and error translation
+- MCP adapter with tool annotations, structured content, and complete input schemas
+- CLI with `health`, `tasks`, `projects`, `tags` subcommands
+- Doctor command (`sp-local-bridge-doctor`) for bridge health diagnostics
+- Host config generator (`sp-local-bridge-print-config`) for MCP host setup
+- Install/uninstall scripts with `--dry-run` support
+- CI pipeline (GitHub Actions) with Python 3.11/3.12/3.13 matrix
+- 135+ tests covering core validation, REST translation, MCP protocol, and diagnostics
+- Documentation: operations reference, host setup guides
+
+### Notes
+
+- Plugin fallback (file-spool bridge) is deferred — all operations use the Local REST API
+- Requires Super Productivity desktop app with Local REST API enabled (Settings → Misc)

sp_local_bridge-0.2.1/CLAUDE.md

@@ -0,0 +1,3 @@
+# CLAUDE.md
+
+See [AGENTS.md](AGENTS.md) for all agent instructions.

sp_local_bridge-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cameron Brooks
+
+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.

sp_local_bridge-0.2.1/Makefile

@@ -0,0 +1,53 @@
+.PHONY: install format lint typecheck test cov check clean build doctor print-config checksums
+
+## Install dependencies
+install:
+	uv sync
+
+## Format code
+format:
+	uv run ruff format .
+
+## Lint code (with auto-fix)
+lint:
+	uv run ruff check --fix .
+
+## Type check
+typecheck:
+	uv run pyright
+
+## Run tests
+test:
+	uv run pytest
+
+## Run tests with coverage
+cov:
+	uv run pytest --cov --cov-report=term-missing
+
+## Run all checks (CI-equivalent)
+check: install
+	uv run ruff format --check .
+	uv run ruff check .
+	uv run pyright
+	uv run pytest
+	uv build --quiet
+
+## Build release artifacts
+build:
+	uv build
+
+## Generate checksums for release artifacts
+checksums:
+	cd dist && sha256sum * > checksums.txt
+
+## Run bridge doctor
+doctor:
+	uv run sp-local-bridge-doctor
+
+## Print host config
+print-config:
+	uv run sp-local-bridge-print-config claude-desktop
+
+## Remove build artifacts
+clean:
+	rm -rf dist/ build/ *.egg-info .pytest_cache .ruff_cache .mypy_cache htmlcov .coverage

sp_local_bridge-0.2.1/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.5
+Name: sp-local-bridge
+Version: 0.2.1
+Summary: Local automation bridge for Super Productivity — REST-first with MCP adapter
+Project-URL: Repository, https://github.com/CameronBrooks11/super-productivity-local-bridge
+Author: Cameron Brooks
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automation,local-bridge,mcp,super-productivity
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: mcp<3,>=1.9
+Requires-Dist: pydantic<3,>=2.12
+Description-Content-Type: text/markdown
+
+# Super Productivity Local Bridge
+
+> [!IMPORTANT]
+> **This repository is archived. It has been superseded by the [Go bridge](https://github.com/CameronBrooks11/super-productivity-local-gobridge).**
+>
+> The Go rewrite provides the same 16 operations, installs as a single binary
+> with no Python or `uv` runtime to manage, and is where all further development
+> happens. This repository is read-only: no further fixes, releases, or
+> dependency updates.
+>
+> **New and existing installations should move to
+> [super-productivity-local-gobridge](https://github.com/CameronBrooks11/super-productivity-local-gobridge)**
+> ([docs](https://cameronbrooks11.github.io/super-productivity-local-gobridge/),
+> [migration guide](https://cameronbrooks11.github.io/super-productivity-local-gobridge/migration)).
+>
+> The content below describes the final Python release (v0.2.0) and is kept for
+> reference.
+
+[![CI](https://github.com/CameronBrooks11/super-productivity-local-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/CameronBrooks11/super-productivity-local-bridge/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Control [Super Productivity](https://super-productivity.com/) tasks, projects, and tags from MCP hosts, CLI, and local automation tools — all through the desktop app's Local REST API.
+
+## Why
+
+Super Productivity is a great task manager. This bridge lets AI coding agents and automation scripts interact with it programmatically — creating tasks, tracking work, and managing projects without leaving your workflow.
+
+The bridge talks only to your local Super Productivity API on `127.0.0.1:3876`. Your MCP host may have its own data handling, so review the host's privacy model before granting task access.
+
+## Features
+
+- **16 operations** — list/get/create/update/complete/uncomplete/start/stop/archive/restore tasks, current task get/set, list projects, list tags, status, health check, plus filters and time fields
+- **MCP adapter** — live-validated with VS Code Copilot; includes setup guides and config generation for Claude Desktop and Codex CLI
+- **CLI** — command-line access to common operations (health, status, list/get/create tasks, current task, projects, tags)
+- **Host config generator** — prints ready-to-paste config with absolute paths for each supported host
+- **Doctor command** — diagnoses connectivity and configuration issues
+
+## Install
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```sh
+git clone https://github.com/CameronBrooks11/super-productivity-local-bridge.git
+cd super-productivity-local-bridge
+scripts/install.sh
+```
+
+Use `--dry-run` to preview.
+
+Alternatively, install from a [GitHub Release](https://github.com/CameronBrooks11/super-productivity-local-bridge/releases) wheel:
+
+```sh
+uv tool install https://github.com/CameronBrooks11/super-productivity-local-bridge/releases/download/v0.2.0/sp_local_bridge-0.2.0-py3-none-any.whl
+```
+
+## Configure an MCP Host
+
+```sh
+sp-local-bridge-print-config vscode-copilot   # VS Code Copilot
+sp-local-bridge-print-config claude-desktop    # Claude Desktop
+sp-local-bridge-print-config codex             # Codex CLI
+```
+
+Add the printed snippet to the config file shown in the output, then restart the host.
+
+See the [host setup guides](https://cameronbrooks11.github.io/super-productivity-local-bridge/hosts/) for detailed instructions.
+
+## Verify
+
+```sh
+sp-local-bridge-doctor
+```
+
+## Safety
+
+This bridge has **write access** to your Super Productivity data (create, update, complete, archive tasks). It talks only to localhost. `task.delete` is intentionally excluded. Back up your SP data before heavy automation use.
+
+See [Security](https://cameronbrooks11.github.io/super-productivity-local-bridge/security) for the full risk profile.
+
+## Documentation
+
+Full docs: [cameronbrooks11.github.io/super-productivity-local-bridge](https://cameronbrooks11.github.io/super-productivity-local-bridge/)
+
+- [Getting Started](https://cameronbrooks11.github.io/super-productivity-local-bridge/getting-started)
+- [Operations Reference](https://cameronbrooks11.github.io/super-productivity-local-bridge/operations)
+- [Architecture](https://cameronbrooks11.github.io/super-productivity-local-bridge/architecture)
+- [Troubleshooting](https://cameronbrooks11.github.io/super-productivity-local-bridge/troubleshooting)
+
+## Development
+
+```sh
+uv sync                     # Install deps
+make check                  # Format, lint, typecheck, test, build
+uv run pytest --cov         # Tests with coverage
+uv run pre-commit install   # Git hooks
+```
+
+## License
+
+[MIT](LICENSE)