superproductivity-mcp 1.2.5__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- superproductivity_mcp-1.2.5/.github/workflows/build.yml +38 -0
- superproductivity_mcp-1.2.5/.github/workflows/publish-dev.yml +53 -0
- superproductivity_mcp-1.2.5/.github/workflows/publish.yml +54 -0
- superproductivity_mcp-1.2.5/.github/workflows/release.yml +49 -0
- superproductivity_mcp-1.2.5/.github/workflows/version-gate.yml +85 -0
- superproductivity_mcp-1.2.5/.gitignore +39 -0
- superproductivity_mcp-1.2.5/.mcp.json.example +14 -0
- superproductivity_mcp-1.2.5/.mise.toml +2 -0
- superproductivity_mcp-1.2.5/LICENSE.txt +21 -0
- superproductivity_mcp-1.2.5/PKG-INFO +164 -0
- superproductivity_mcp-1.2.5/README.md +154 -0
- superproductivity_mcp-1.2.5/build-plugin.sh +23 -0
- superproductivity_mcp-1.2.5/docs/superpowers/plans/2026-04-29-packaging-distribution.md +350 -0
- superproductivity_mcp-1.2.5/docs/superpowers/plans/2026-04-30-gitflow-ci.md +418 -0
- superproductivity_mcp-1.2.5/docs/superpowers/specs/2026-04-29-gitflow-ci-design.md +136 -0
- superproductivity_mcp-1.2.5/docs/superpowers/specs/2026-04-29-packaging-distribution-design.md +106 -0
- superproductivity_mcp-1.2.5/plugin/index.html +487 -0
- superproductivity_mcp-1.2.5/plugin/manifest.json +39 -0
- superproductivity_mcp-1.2.5/plugin/plugin.js +949 -0
- superproductivity_mcp-1.2.5/pyproject.toml +30 -0
- superproductivity_mcp-1.2.5/src/superproductivity_mcp/__init__.py +1 -0
- superproductivity_mcp-1.2.5/src/superproductivity_mcp/__main__.py +3 -0
- superproductivity_mcp-1.2.5/src/superproductivity_mcp/server.py +1042 -0
- superproductivity_mcp-1.2.5/tests/__init__.py +0 -0
- superproductivity_mcp-1.2.5/tests/test_mcp_logic.py +126 -0
- superproductivity_mcp-1.2.5/uv.lock +861 -0
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
name: Build checks
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
pull_request:
|
|
5
|
+
branches: [main]
|
|
6
|
+
|
|
7
|
+
jobs:
|
|
8
|
+
build-plugin:
|
|
9
|
+
runs-on: ubuntu-latest
|
|
10
|
+
steps:
|
|
11
|
+
- uses: actions/checkout@v4
|
|
12
|
+
|
|
13
|
+
- name: Build plugin zip
|
|
14
|
+
run: bash build-plugin.sh
|
|
15
|
+
|
|
16
|
+
- name: Verify zip exists
|
|
17
|
+
run: |
|
|
18
|
+
VERSION=$(python3 -c "import json; print(json.load(open('plugin/manifest.json'))['version'])")
|
|
19
|
+
ZIP="plugin/plugin-v${VERSION}.zip"
|
|
20
|
+
test -f "$ZIP" && echo "OK: $ZIP" || (echo "ERROR: $ZIP not found" && exit 1)
|
|
21
|
+
|
|
22
|
+
build-mcp:
|
|
23
|
+
runs-on: ubuntu-latest
|
|
24
|
+
steps:
|
|
25
|
+
- uses: actions/checkout@v4
|
|
26
|
+
|
|
27
|
+
- uses: astral-sh/setup-uv@v5
|
|
28
|
+
with:
|
|
29
|
+
enable-cache: true
|
|
30
|
+
|
|
31
|
+
- name: Build MCP wheel
|
|
32
|
+
run: uv build
|
|
33
|
+
|
|
34
|
+
- name: Verify artifacts
|
|
35
|
+
run: |
|
|
36
|
+
ls dist/*.whl dist/*.tar.gz \
|
|
37
|
+
&& echo "OK: MCP package built" \
|
|
38
|
+
|| (echo "ERROR: dist artifacts missing" && exit 1)
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
name: Publish dev release
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches:
|
|
6
|
+
- dev
|
|
7
|
+
tags:
|
|
8
|
+
- "v*.dev*"
|
|
9
|
+
- "v*a*"
|
|
10
|
+
- "v*b*"
|
|
11
|
+
- "v*rc*"
|
|
12
|
+
|
|
13
|
+
jobs:
|
|
14
|
+
publish-dev:
|
|
15
|
+
runs-on: ubuntu-latest
|
|
16
|
+
if: startsWith(github.ref, 'refs/tags/') || contains(github.event.head_commit.message, '[publish]')
|
|
17
|
+
steps:
|
|
18
|
+
- uses: actions/checkout@v4
|
|
19
|
+
|
|
20
|
+
- uses: astral-sh/setup-uv@v5
|
|
21
|
+
with:
|
|
22
|
+
enable-cache: true
|
|
23
|
+
|
|
24
|
+
- name: Compute pre-release version
|
|
25
|
+
id: version
|
|
26
|
+
run: |
|
|
27
|
+
if [[ "$GITHUB_REF" == refs/tags/* ]]; then
|
|
28
|
+
VERSION="${GITHUB_REF_NAME#v}"
|
|
29
|
+
echo "source=tag" >> "$GITHUB_OUTPUT"
|
|
30
|
+
else
|
|
31
|
+
CURRENT=$(python3 -c "
|
|
32
|
+
import re
|
|
33
|
+
m = re.search(r'version = \"([^\"]+)\"', open('pyproject.toml').read())
|
|
34
|
+
print(m.group(1))
|
|
35
|
+
")
|
|
36
|
+
VERSION="${CURRENT}.dev${{ github.run_number }}"
|
|
37
|
+
echo "source=keyword" >> "$GITHUB_OUTPUT"
|
|
38
|
+
fi
|
|
39
|
+
echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
|
|
40
|
+
echo "Pre-release version: ${VERSION}"
|
|
41
|
+
|
|
42
|
+
- name: Patch pyproject.toml version
|
|
43
|
+
run: |
|
|
44
|
+
sed -i "s/^version = \".*\"/version = \"${{ steps.version.outputs.version }}\"/" pyproject.toml
|
|
45
|
+
grep "^version" pyproject.toml
|
|
46
|
+
|
|
47
|
+
- name: Build package
|
|
48
|
+
run: uv build
|
|
49
|
+
|
|
50
|
+
- name: Publish to PyPI
|
|
51
|
+
run: uv publish
|
|
52
|
+
env:
|
|
53
|
+
UV_PUBLISH_TOKEN: ${{ secrets.UV_PUBLISH_TOKEN }}
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
name: Publish to PyPI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
workflow_run:
|
|
5
|
+
workflows: ["Build and release plugin"]
|
|
6
|
+
types: [completed]
|
|
7
|
+
branches: [main]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
publish:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
# Only run if the release workflow succeeded
|
|
13
|
+
if: github.event.workflow_run.conclusion == 'success'
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v4
|
|
16
|
+
|
|
17
|
+
- name: Check version is stable release
|
|
18
|
+
id: check
|
|
19
|
+
run: |
|
|
20
|
+
pip install packaging --quiet
|
|
21
|
+
python3 << 'PYEOF'
|
|
22
|
+
import re, sys
|
|
23
|
+
from pathlib import Path
|
|
24
|
+
from packaging.version import Version
|
|
25
|
+
|
|
26
|
+
text = Path("pyproject.toml").read_text()
|
|
27
|
+
m = re.search(r'^version\s*=\s*"([^"]+)"', text, re.MULTILINE)
|
|
28
|
+
if not m:
|
|
29
|
+
print("ERROR: version not found in pyproject.toml")
|
|
30
|
+
sys.exit(1)
|
|
31
|
+
|
|
32
|
+
version = m.group(1)
|
|
33
|
+
v = Version(version)
|
|
34
|
+
is_pre = "true" if v.is_prerelease else "false"
|
|
35
|
+
print(f"Version: {version} pre-release: {is_pre}")
|
|
36
|
+
with open(__import__("os").environ["GITHUB_OUTPUT"], "a") as f:
|
|
37
|
+
f.write(f"skip={is_pre}\n")
|
|
38
|
+
f.write(f"version={version}\n")
|
|
39
|
+
PYEOF
|
|
40
|
+
|
|
41
|
+
- uses: astral-sh/setup-uv@v5
|
|
42
|
+
if: steps.check.outputs.skip == 'false'
|
|
43
|
+
with:
|
|
44
|
+
enable-cache: true
|
|
45
|
+
|
|
46
|
+
- name: Build package
|
|
47
|
+
if: steps.check.outputs.skip == 'false'
|
|
48
|
+
run: uv build
|
|
49
|
+
|
|
50
|
+
- name: Publish to PyPI
|
|
51
|
+
if: steps.check.outputs.skip == 'false'
|
|
52
|
+
run: uv publish
|
|
53
|
+
env:
|
|
54
|
+
UV_PUBLISH_TOKEN: ${{ secrets.UV_PUBLISH_TOKEN }}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
name: Build and release plugin
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
workflow_dispatch:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
release:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
permissions:
|
|
12
|
+
contents: write
|
|
13
|
+
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v4
|
|
16
|
+
|
|
17
|
+
- name: Read version from manifest
|
|
18
|
+
id: version
|
|
19
|
+
run: |
|
|
20
|
+
VERSION=$(python3 -c "import json; print(json.load(open('plugin/manifest.json'))['version'])")
|
|
21
|
+
echo "version=$VERSION" >> "$GITHUB_OUTPUT"
|
|
22
|
+
echo "tag=v$VERSION" >> "$GITHUB_OUTPUT"
|
|
23
|
+
|
|
24
|
+
- name: Build plugin zip
|
|
25
|
+
run: bash build-plugin.sh
|
|
26
|
+
|
|
27
|
+
- name: Upload build artifact
|
|
28
|
+
uses: actions/upload-artifact@v4
|
|
29
|
+
with:
|
|
30
|
+
name: plugin-v${{ steps.version.outputs.version }}
|
|
31
|
+
path: plugin/plugin-v${{ steps.version.outputs.version }}.zip
|
|
32
|
+
retention-days: 90
|
|
33
|
+
|
|
34
|
+
- name: Publish GitHub Release
|
|
35
|
+
env:
|
|
36
|
+
GH_TOKEN: ${{ github.token }}
|
|
37
|
+
run: |
|
|
38
|
+
TAG="${{ steps.version.outputs.tag }}"
|
|
39
|
+
ZIP="plugin/plugin-v${{ steps.version.outputs.version }}.zip"
|
|
40
|
+
|
|
41
|
+
if gh release view "$TAG" &>/dev/null; then
|
|
42
|
+
echo "Release $TAG already exists — updating asset"
|
|
43
|
+
gh release upload "$TAG" "$ZIP" --clobber
|
|
44
|
+
else
|
|
45
|
+
echo "Creating release $TAG"
|
|
46
|
+
gh release create "$TAG" "$ZIP" \
|
|
47
|
+
--title "Plugin v${{ steps.version.outputs.version }}" \
|
|
48
|
+
--notes "See changelog in \`plugin/manifest.json\`."
|
|
49
|
+
fi
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
name: Version gate
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
pull_request:
|
|
5
|
+
branches: [main]
|
|
6
|
+
|
|
7
|
+
jobs:
|
|
8
|
+
version-gate:
|
|
9
|
+
runs-on: ubuntu-latest
|
|
10
|
+
steps:
|
|
11
|
+
- uses: actions/checkout@v4
|
|
12
|
+
with:
|
|
13
|
+
fetch-depth: 0
|
|
14
|
+
|
|
15
|
+
- name: Check version consistency and bump
|
|
16
|
+
run: |
|
|
17
|
+
pip install packaging --quiet
|
|
18
|
+
python3 << 'PYEOF'
|
|
19
|
+
import json, re, sys, subprocess
|
|
20
|
+
from pathlib import Path
|
|
21
|
+
from packaging.version import Version
|
|
22
|
+
|
|
23
|
+
versions = {}
|
|
24
|
+
|
|
25
|
+
# pyproject.toml (required)
|
|
26
|
+
text = Path("pyproject.toml").read_text()
|
|
27
|
+
m = re.search(r'^version\s*=\s*"([^"]+)"', text, re.MULTILINE)
|
|
28
|
+
if not m:
|
|
29
|
+
print("ERROR: version not found in pyproject.toml")
|
|
30
|
+
sys.exit(1)
|
|
31
|
+
versions["pyproject.toml"] = m.group(1)
|
|
32
|
+
|
|
33
|
+
# src/superproductivity_mcp/__init__.py (present after packaging PR merges)
|
|
34
|
+
init_path = Path("src/superproductivity_mcp/__init__.py")
|
|
35
|
+
if init_path.exists():
|
|
36
|
+
m = re.search(r'^__version__\s*=\s*"([^"]+)"', init_path.read_text(), re.MULTILINE)
|
|
37
|
+
if m:
|
|
38
|
+
versions["src/superproductivity_mcp/__init__.py"] = m.group(1)
|
|
39
|
+
|
|
40
|
+
# src/superproductivity_mcp/server.py (present after packaging PR merges)
|
|
41
|
+
server_path = Path("src/superproductivity_mcp/server.py")
|
|
42
|
+
if server_path.exists():
|
|
43
|
+
m = re.search(r'server_version="([^"]+)"', server_path.read_text())
|
|
44
|
+
if m:
|
|
45
|
+
versions["src/superproductivity_mcp/server.py"] = m.group(1)
|
|
46
|
+
|
|
47
|
+
# plugin/manifest.json (required)
|
|
48
|
+
manifest = json.loads(Path("plugin/manifest.json").read_text())
|
|
49
|
+
versions["plugin/manifest.json"] = manifest["version"]
|
|
50
|
+
|
|
51
|
+
print("Versions found:")
|
|
52
|
+
for f, v in sorted(versions.items()):
|
|
53
|
+
print(f" {f}: {v}")
|
|
54
|
+
|
|
55
|
+
# All found versions must match
|
|
56
|
+
unique = set(versions.values())
|
|
57
|
+
if len(unique) > 1:
|
|
58
|
+
print("\nERROR: Version mismatch across files!")
|
|
59
|
+
for f, v in sorted(versions.items()):
|
|
60
|
+
print(f" {f}: {v}")
|
|
61
|
+
sys.exit(1)
|
|
62
|
+
|
|
63
|
+
pr_version = list(unique)[0]
|
|
64
|
+
print(f"\nAll files consistent: v{pr_version}")
|
|
65
|
+
|
|
66
|
+
# Must be strictly greater than current main
|
|
67
|
+
result = subprocess.run(
|
|
68
|
+
["git", "show", "origin/main:pyproject.toml"],
|
|
69
|
+
capture_output=True, text=True
|
|
70
|
+
)
|
|
71
|
+
m = re.search(r'^version\s*=\s*"([^"]+)"', result.stdout, re.MULTILINE)
|
|
72
|
+
if not m:
|
|
73
|
+
print("WARNING: could not read version from main — skipping bump check")
|
|
74
|
+
sys.exit(0)
|
|
75
|
+
|
|
76
|
+
main_version = m.group(1)
|
|
77
|
+
print(f"main: v{main_version}")
|
|
78
|
+
|
|
79
|
+
if Version(pr_version) <= Version(main_version):
|
|
80
|
+
print(f"\nERROR: v{pr_version} must be strictly greater than main (v{main_version}).")
|
|
81
|
+
print("Bump the version in pyproject.toml, __init__.py, server.py, and plugin/manifest.json.")
|
|
82
|
+
sys.exit(1)
|
|
83
|
+
|
|
84
|
+
print(f"\nVersion bump confirmed: {main_version} -> {pr_version}")
|
|
85
|
+
PYEOF
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*.pyo
|
|
5
|
+
.venv/
|
|
6
|
+
*.egg-info/
|
|
7
|
+
dist/
|
|
8
|
+
build/
|
|
9
|
+
|
|
10
|
+
# uv
|
|
11
|
+
.python-version
|
|
12
|
+
|
|
13
|
+
# macOS
|
|
14
|
+
.DS_Store
|
|
15
|
+
.AppleDouble
|
|
16
|
+
.LSOverride
|
|
17
|
+
|
|
18
|
+
# IDE
|
|
19
|
+
.vscode/
|
|
20
|
+
.idea/
|
|
21
|
+
|
|
22
|
+
# Local MCP config (contains machine-specific absolute paths)
|
|
23
|
+
.mcp.json
|
|
24
|
+
|
|
25
|
+
# Claude Code local settings
|
|
26
|
+
.claude/settings.local.json
|
|
27
|
+
|
|
28
|
+
# Runtime directories created by the MCP server
|
|
29
|
+
plugin_commands/
|
|
30
|
+
plugin_responses/
|
|
31
|
+
|
|
32
|
+
# Backups created by setup scripts
|
|
33
|
+
*.backup
|
|
34
|
+
|
|
35
|
+
# Plugin build artefacts
|
|
36
|
+
plugin/*.zip
|
|
37
|
+
|
|
38
|
+
# Git worktrees
|
|
39
|
+
.worktrees/
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 organicmoron
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: superproductivity-mcp
|
|
3
|
+
Version: 1.2.5
|
|
4
|
+
Summary: Super Productivity MCP server for Claude Desktop integration
|
|
5
|
+
Project-URL: Homepage, https://github.com/ben-elliot-nice/superproductivity-mcp
|
|
6
|
+
License-File: LICENSE.txt
|
|
7
|
+
Requires-Python: >=3.10
|
|
8
|
+
Requires-Dist: mcp>=1.0.0
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
|
|
11
|
+
# SP-MCP
|
|
12
|
+
|
|
13
|
+
Bridge between the amazing [Super Productivity](https://github.com/johannesjo/super-productivity/) app and MCP (Model Context Protocol) servers for Claude Desktop integration.
|
|
14
|
+
|
|
15
|
+
This MCP and plugin allows Claude Desktop to directly interact with Super Productivity through the MCP protocol. Create update,tasks, manage projects and tags, and get information from Super Productivity.
|
|
16
|
+
|
|
17
|
+
Make sure to backup your Super Productivity before using in case of data loss. I've provided a plugin.zip for convenience but feel free to make your own from the files.
|
|
18
|
+
|
|
19
|
+
(Can't delete tasks right now (but it can mark them as done))
|
|
20
|
+
|
|
21
|
+
## Demo
|
|
22
|
+
|
|
23
|
+
https://github.com/user-attachments/assets/cc118173-023f-48cb-8213-427027e475af
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
## Requirements
|
|
27
|
+
|
|
28
|
+
- Super Productivity 14.0.0 or higher
|
|
29
|
+
- Claude Desktop
|
|
30
|
+
- Python 3.10 or higher
|
|
31
|
+
|
|
32
|
+
## Installation
|
|
33
|
+
|
|
34
|
+
### 1. Install the MCP server
|
|
35
|
+
|
|
36
|
+
Add to your Claude Desktop config:
|
|
37
|
+
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
38
|
+
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
39
|
+
|
|
40
|
+
```json
|
|
41
|
+
{
|
|
42
|
+
"mcpServers": {
|
|
43
|
+
"super-productivity": {
|
|
44
|
+
"command": "uvx",
|
|
45
|
+
"args": ["superproductivity-mcp"]
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
`uvx` fetches the latest version from PyPI automatically — no Python install or repo clone needed. Requires [uv](https://docs.astral.sh/uv/) to be installed (`brew install uv` on macOS).
|
|
52
|
+
|
|
53
|
+
### 2. Install the plugin
|
|
54
|
+
|
|
55
|
+
- Open Super Productivity → Settings → Plugins
|
|
56
|
+
- Click "Upload Plugin"
|
|
57
|
+
- Select the `plugin.zip` from the [latest GitHub release](https://github.com/Ben-Elliot/superproductivity-mcp/releases)
|
|
58
|
+
|
|
59
|
+
### 3. Restart Claude Desktop
|
|
60
|
+
|
|
61
|
+
## Usage
|
|
62
|
+
|
|
63
|
+
### Creating Tasks
|
|
64
|
+
```
|
|
65
|
+
"Create a task to review the quarterly budget #finance +work"
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### Task Management
|
|
69
|
+
```
|
|
70
|
+
"Show me all my tasks"
|
|
71
|
+
"Mark the budget review task as complete"
|
|
72
|
+
"Update the task 'Meeting prep' with notes about the agenda"
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Project and Tag Management
|
|
76
|
+
```
|
|
77
|
+
"Create a new project called 'Website Redesign'"
|
|
78
|
+
"Show me all projects"
|
|
79
|
+
"Get all tags"
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Dashboard
|
|
83
|
+
|
|
84
|
+
Access the SP-MCP dashboard from the menu. The dashboard shows:
|
|
85
|
+
- Real-time statistics
|
|
86
|
+
- Connection status
|
|
87
|
+
- Activity logs
|
|
88
|
+
- Settings (polling frequency: default 2 seconds)
|
|
89
|
+
|
|
90
|
+
## Communication
|
|
91
|
+
|
|
92
|
+
The plugin uses file-based communication through:
|
|
93
|
+
- Windows: `%APPDATA%\super-productivity-mcp\`
|
|
94
|
+
- Linux: `~/.local/share/super-productivity-mcp/`
|
|
95
|
+
- macOS: `~/Library/Application Support/super-productivity-mcp/`
|
|
96
|
+
|
|
97
|
+
Commands are exchanged through `plugin_commands/` and `plugin_responses/` directories.
|
|
98
|
+
|
|
99
|
+
## Contributing
|
|
100
|
+
|
|
101
|
+
Pull requests are welcome. Please open an issue first if you're planning a significant change.
|
|
102
|
+
|
|
103
|
+
### Local Environment
|
|
104
|
+
|
|
105
|
+
This project uses [mise](https://mise.jdx.dev/) to manage the Python runtime. Install it first:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
brew install mise
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Then from the repo root, let mise install the correct Python version:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
mise install
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Dependencies are managed with [uv](https://docs.astral.sh/uv/). Install it, then sync the project:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
brew install uv
|
|
121
|
+
uv sync
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
This creates a `.venv` and installs all dependencies from `uv.lock`.
|
|
125
|
+
|
|
126
|
+
### MCP Config
|
|
127
|
+
|
|
128
|
+
Copy `.mcp.json.example` to `.mcp.json` and update the paths to point to your local clone:
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
cp .mcp.json.example .mcp.json
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
`.mcp.json` is gitignored — it contains machine-specific absolute paths and should not be committed.
|
|
135
|
+
|
|
136
|
+
### Running the Server
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
uv run superproductivity-mcp
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Or let Claude Code pick it up automatically via `.mcp.json`.
|
|
143
|
+
|
|
144
|
+
### Repo Structure
|
|
145
|
+
|
|
146
|
+
```
|
|
147
|
+
src/superproductivity_mcp/ # MCP server Python package (install via uvx)
|
|
148
|
+
plugin/ # Super Productivity plugin files
|
|
149
|
+
plugin.js # Main plugin JS (install via SP Settings → Plugins)
|
|
150
|
+
plugin.zip # Pre-packaged zip for convenience
|
|
151
|
+
index.html # Plugin UI
|
|
152
|
+
manifest.json # Plugin manifest
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
## Troubleshooting
|
|
156
|
+
|
|
157
|
+
### Plugin Not Loading
|
|
158
|
+
- Check Super Productivity version (14.0.0+ required)
|
|
159
|
+
- Verify plugin permissions include `nodeExecution`
|
|
160
|
+
|
|
161
|
+
### Commands Not Working
|
|
162
|
+
- Verify both plugin and MCP server are running
|
|
163
|
+
- Check file permissions on communication directories
|
|
164
|
+
- Check `mcp_server.log` in the data directory
|
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
# SP-MCP
|
|
2
|
+
|
|
3
|
+
Bridge between the amazing [Super Productivity](https://github.com/johannesjo/super-productivity/) app and MCP (Model Context Protocol) servers for Claude Desktop integration.
|
|
4
|
+
|
|
5
|
+
This MCP and plugin allows Claude Desktop to directly interact with Super Productivity through the MCP protocol. Create update,tasks, manage projects and tags, and get information from Super Productivity.
|
|
6
|
+
|
|
7
|
+
Make sure to backup your Super Productivity before using in case of data loss. I've provided a plugin.zip for convenience but feel free to make your own from the files.
|
|
8
|
+
|
|
9
|
+
(Can't delete tasks right now (but it can mark them as done))
|
|
10
|
+
|
|
11
|
+
## Demo
|
|
12
|
+
|
|
13
|
+
https://github.com/user-attachments/assets/cc118173-023f-48cb-8213-427027e475af
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
## Requirements
|
|
17
|
+
|
|
18
|
+
- Super Productivity 14.0.0 or higher
|
|
19
|
+
- Claude Desktop
|
|
20
|
+
- Python 3.10 or higher
|
|
21
|
+
|
|
22
|
+
## Installation
|
|
23
|
+
|
|
24
|
+
### 1. Install the MCP server
|
|
25
|
+
|
|
26
|
+
Add to your Claude Desktop config:
|
|
27
|
+
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
28
|
+
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
29
|
+
|
|
30
|
+
```json
|
|
31
|
+
{
|
|
32
|
+
"mcpServers": {
|
|
33
|
+
"super-productivity": {
|
|
34
|
+
"command": "uvx",
|
|
35
|
+
"args": ["superproductivity-mcp"]
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`uvx` fetches the latest version from PyPI automatically — no Python install or repo clone needed. Requires [uv](https://docs.astral.sh/uv/) to be installed (`brew install uv` on macOS).
|
|
42
|
+
|
|
43
|
+
### 2. Install the plugin
|
|
44
|
+
|
|
45
|
+
- Open Super Productivity → Settings → Plugins
|
|
46
|
+
- Click "Upload Plugin"
|
|
47
|
+
- Select the `plugin.zip` from the [latest GitHub release](https://github.com/Ben-Elliot/superproductivity-mcp/releases)
|
|
48
|
+
|
|
49
|
+
### 3. Restart Claude Desktop
|
|
50
|
+
|
|
51
|
+
## Usage
|
|
52
|
+
|
|
53
|
+
### Creating Tasks
|
|
54
|
+
```
|
|
55
|
+
"Create a task to review the quarterly budget #finance +work"
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Task Management
|
|
59
|
+
```
|
|
60
|
+
"Show me all my tasks"
|
|
61
|
+
"Mark the budget review task as complete"
|
|
62
|
+
"Update the task 'Meeting prep' with notes about the agenda"
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### Project and Tag Management
|
|
66
|
+
```
|
|
67
|
+
"Create a new project called 'Website Redesign'"
|
|
68
|
+
"Show me all projects"
|
|
69
|
+
"Get all tags"
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Dashboard
|
|
73
|
+
|
|
74
|
+
Access the SP-MCP dashboard from the menu. The dashboard shows:
|
|
75
|
+
- Real-time statistics
|
|
76
|
+
- Connection status
|
|
77
|
+
- Activity logs
|
|
78
|
+
- Settings (polling frequency: default 2 seconds)
|
|
79
|
+
|
|
80
|
+
## Communication
|
|
81
|
+
|
|
82
|
+
The plugin uses file-based communication through:
|
|
83
|
+
- Windows: `%APPDATA%\super-productivity-mcp\`
|
|
84
|
+
- Linux: `~/.local/share/super-productivity-mcp/`
|
|
85
|
+
- macOS: `~/Library/Application Support/super-productivity-mcp/`
|
|
86
|
+
|
|
87
|
+
Commands are exchanged through `plugin_commands/` and `plugin_responses/` directories.
|
|
88
|
+
|
|
89
|
+
## Contributing
|
|
90
|
+
|
|
91
|
+
Pull requests are welcome. Please open an issue first if you're planning a significant change.
|
|
92
|
+
|
|
93
|
+
### Local Environment
|
|
94
|
+
|
|
95
|
+
This project uses [mise](https://mise.jdx.dev/) to manage the Python runtime. Install it first:
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
brew install mise
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Then from the repo root, let mise install the correct Python version:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
mise install
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Dependencies are managed with [uv](https://docs.astral.sh/uv/). Install it, then sync the project:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
brew install uv
|
|
111
|
+
uv sync
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
This creates a `.venv` and installs all dependencies from `uv.lock`.
|
|
115
|
+
|
|
116
|
+
### MCP Config
|
|
117
|
+
|
|
118
|
+
Copy `.mcp.json.example` to `.mcp.json` and update the paths to point to your local clone:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
cp .mcp.json.example .mcp.json
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
`.mcp.json` is gitignored — it contains machine-specific absolute paths and should not be committed.
|
|
125
|
+
|
|
126
|
+
### Running the Server
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
uv run superproductivity-mcp
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Or let Claude Code pick it up automatically via `.mcp.json`.
|
|
133
|
+
|
|
134
|
+
### Repo Structure
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
src/superproductivity_mcp/ # MCP server Python package (install via uvx)
|
|
138
|
+
plugin/ # Super Productivity plugin files
|
|
139
|
+
plugin.js # Main plugin JS (install via SP Settings → Plugins)
|
|
140
|
+
plugin.zip # Pre-packaged zip for convenience
|
|
141
|
+
index.html # Plugin UI
|
|
142
|
+
manifest.json # Plugin manifest
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
## Troubleshooting
|
|
146
|
+
|
|
147
|
+
### Plugin Not Loading
|
|
148
|
+
- Check Super Productivity version (14.0.0+ required)
|
|
149
|
+
- Verify plugin permissions include `nodeExecution`
|
|
150
|
+
|
|
151
|
+
### Commands Not Working
|
|
152
|
+
- Verify both plugin and MCP server are running
|
|
153
|
+
- Check file permissions on communication directories
|
|
154
|
+
- Check `mcp_server.log` in the data directory
|