basecamp-cli-mcp 0.6.0__tar.gz

basecamp_cli_mcp-0.6.0/.gitignore

@@ -0,0 +1,7 @@
+/.venv/
+/dist/
+/build/
+__pycache__/
+*.egg-info/
+*.pyc
+.pytest_cache/

basecamp_cli_mcp-0.6.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: basecamp-cli-mcp
+Version: 0.6.0
+Summary: MCP server that wraps the basecamp CLI.
+Project-URL: Homepage, https://github.com/FutureWorkshops/basecamp-cli-mcp
+Project-URL: Source, https://github.com/FutureWorkshops/basecamp-cli-mcp
+Author-email: Matt Brooke-Smith <matt@futureworkshops.com>
+License: MIT
+Keywords: basecamp,mcp,model-context-protocol
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.2
+Description-Content-Type: text/markdown
+
+# basecamp-cli-mcp
+
+A Model Context Protocol (MCP) server that wraps the [`basecamp`](https://github.com/basecamp/cli)
+CLI. Every non-shortcut CLI action (`projects list`, `todos create`, `cards update`, etc.) is
+exposed as an MCP tool, so MCP-compatible clients (Claude Code, Claude Desktop, etc.) can
+drive Basecamp directly.
+
+## Requirements
+
+- Python ≥ 3.11
+- The `basecamp` CLI on `PATH`, already authenticated (`basecamp setup`) — see [First-time setup](#first-time-setup) below to do both in one command
+- [`uv`](https://docs.astral.sh/uv/) for the recommended install
+
+## First-time setup
+
+If you don't have the `basecamp` CLI installed yet:
+
+```sh
+uvx basecamp-cli-mcp setup
+```
+
+This checks for the `basecamp` binary, runs the official installer (`curl -fsSL https://basecamp.com/install-cli | bash`) after a y/N prompt if it's missing, then runs `basecamp setup` to walk you through OAuth.
+
+On macOS, after auth completes it offers to:
+
+1. Add `basecamp` to your `claude_desktop_config.json` (with a timestamped backup of any existing file).
+2. Restart Claude Desktop.
+
+Both steps prompt y/N. macOS and Linux only for the install/auth — on Windows the command prints the PowerShell installer and exits. The Claude Desktop step is macOS-only.
+
+## Run
+
+The fastest way — no install step at all:
+
+```sh
+uvx basecamp-cli-mcp
+```
+
+`uvx` resolves the package, runs it in an ephemeral isolated env, and exec's it on stdin/stdout.
+
+To install permanently:
+
+```sh
+uv tool install basecamp-cli-mcp
+basecamp-cli-mcp
+```
+
+### Add to Claude Code
+
+```sh
+claude mcp add basecamp -- uvx basecamp-cli-mcp
+```
+
+### Add to Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "basecamp": {
+      "command": "uvx",
+      "args": ["basecamp-cli-mcp"]
+    }
+  }
+}
+```
+
+If `uvx` isn't on Desktop's `PATH` (it strips most of your shell `PATH`), use the absolute path — `which uvx` from your shell.
+
+### Filtering tools
+
+By default the server exposes all 250+ tools. Most agents only need a handful, and a smaller
+catalog speeds up tool selection. Filter with `--include` / `--exclude` (fnmatch globs against
+tool names; both flags repeatable):
+
+```sh
+basecamp-cli-mcp --include 'cards_*' --include 'todos_*'
+basecamp-cli-mcp --include '*' --exclude 'webhooks_*' --exclude 'templates_*'
+```
+
+Register multiple profiles in `claude_desktop_config.json` and turn them on per task:
+
+```json
+{
+  "mcpServers": {
+    "basecamp-cards": {
+      "command": "uvx",
+      "args": ["basecamp-cli-mcp", "--include", "cards_*", "--include", "projects_list"]
+    },
+    "basecamp-todos": {
+      "command": "uvx",
+      "args": ["basecamp-cli-mcp", "--include", "todos_*", "--include", "projects_list"]
+    },
+    "basecamp-full": {
+      "command": "uvx",
+      "args": ["basecamp-cli-mcp"]
+    }
+  }
+}
+```
+
+### `BASECAMP_BIN`
+
+If the `basecamp` CLI isn't on the spawned process's `PATH` (a real risk under Claude Desktop), set:
+
+```json
+"env": { "BASECAMP_BIN": "/absolute/path/to/basecamp" }
+```
+
+## How it works
+
+Tool schemas are pre-generated and committed to `src/basecamp_cli_mcp/data/tools.json` (shipped
+inside the wheel as package data). At runtime the server loads that file and registers one MCP
+tool per entry. Each tool:
+
+1. Builds `argv` from positional arguments and flags defined in the schema.
+2. Shells out: `basecamp <group> <action> <args...> --json`.
+3. Returns the parsed `data` field from the CLI's `{ok, data}` envelope to the MCP client.
+
+Shortcut commands (`todo`, `done`, `card`, `comment`, etc.) are intentionally excluded — their
+underlying actions (`todos_create`, `cards_create`, …) are already exposed.
+
+## Regenerating tool schemas
+
+After upgrading the `basecamp` CLI:
+
+```sh
+uv run basecamp-cli-mcp generate
+```
+
+Review the diff in `src/basecamp_cli_mcp/data/tools.json` and commit. The generator reads
+`basecamp commands --json` and parses `basecamp <group> <action> --help` for each action.
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+uv build                       # wheel + sdist into dist/
+```
+
+Layout:
+
+- `src/basecamp_cli_mcp/server.py` — wires up the MCP server from `data/tools.json`
+- `src/basecamp_cli_mcp/runner.py` — builds argv and shells out
+- `src/basecamp_cli_mcp/generator.py` — regenerates `data/tools.json`
+- `src/basecamp_cli_mcp/help_parser.py` — parses `--help` text into a schema
+- `src/basecamp_cli_mcp/cli.py` — entrypoint (`basecamp-cli-mcp`)
+- `src/basecamp_cli_mcp/data/tools.json` — generated tool schemas (committed)

basecamp_cli_mcp-0.6.0/README.md

@@ -0,0 +1,148 @@
+# basecamp-cli-mcp
+
+A Model Context Protocol (MCP) server that wraps the [`basecamp`](https://github.com/basecamp/cli)
+CLI. Every non-shortcut CLI action (`projects list`, `todos create`, `cards update`, etc.) is
+exposed as an MCP tool, so MCP-compatible clients (Claude Code, Claude Desktop, etc.) can
+drive Basecamp directly.
+
+## Requirements
+
+- Python ≥ 3.11
+- The `basecamp` CLI on `PATH`, already authenticated (`basecamp setup`) — see [First-time setup](#first-time-setup) below to do both in one command
+- [`uv`](https://docs.astral.sh/uv/) for the recommended install
+
+## First-time setup
+
+If you don't have the `basecamp` CLI installed yet:
+
+```sh
+uvx basecamp-cli-mcp setup
+```
+
+This checks for the `basecamp` binary, runs the official installer (`curl -fsSL https://basecamp.com/install-cli | bash`) after a y/N prompt if it's missing, then runs `basecamp setup` to walk you through OAuth.
+
+On macOS, after auth completes it offers to:
+
+1. Add `basecamp` to your `claude_desktop_config.json` (with a timestamped backup of any existing file).
+2. Restart Claude Desktop.
+
+Both steps prompt y/N. macOS and Linux only for the install/auth — on Windows the command prints the PowerShell installer and exits. The Claude Desktop step is macOS-only.
+
+## Run
+
+The fastest way — no install step at all:
+
+```sh
+uvx basecamp-cli-mcp
+```
+
+`uvx` resolves the package, runs it in an ephemeral isolated env, and exec's it on stdin/stdout.
+
+To install permanently:
+
+```sh
+uv tool install basecamp-cli-mcp
+basecamp-cli-mcp
+```
+
+### Add to Claude Code
+
+```sh
+claude mcp add basecamp -- uvx basecamp-cli-mcp
+```
+
+### Add to Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "basecamp": {
+      "command": "uvx",
+      "args": ["basecamp-cli-mcp"]
+    }
+  }
+}
+```
+
+If `uvx` isn't on Desktop's `PATH` (it strips most of your shell `PATH`), use the absolute path — `which uvx` from your shell.
+
+### Filtering tools
+
+By default the server exposes all 250+ tools. Most agents only need a handful, and a smaller
+catalog speeds up tool selection. Filter with `--include` / `--exclude` (fnmatch globs against
+tool names; both flags repeatable):
+
+```sh
+basecamp-cli-mcp --include 'cards_*' --include 'todos_*'
+basecamp-cli-mcp --include '*' --exclude 'webhooks_*' --exclude 'templates_*'
+```
+
+Register multiple profiles in `claude_desktop_config.json` and turn them on per task:
+
+```json
+{
+  "mcpServers": {
+    "basecamp-cards": {
+      "command": "uvx",
+      "args": ["basecamp-cli-mcp", "--include", "cards_*", "--include", "projects_list"]
+    },
+    "basecamp-todos": {
+      "command": "uvx",
+      "args": ["basecamp-cli-mcp", "--include", "todos_*", "--include", "projects_list"]
+    },
+    "basecamp-full": {
+      "command": "uvx",
+      "args": ["basecamp-cli-mcp"]
+    }
+  }
+}
+```
+
+### `BASECAMP_BIN`
+
+If the `basecamp` CLI isn't on the spawned process's `PATH` (a real risk under Claude Desktop), set:
+
+```json
+"env": { "BASECAMP_BIN": "/absolute/path/to/basecamp" }
+```
+
+## How it works
+
+Tool schemas are pre-generated and committed to `src/basecamp_cli_mcp/data/tools.json` (shipped
+inside the wheel as package data). At runtime the server loads that file and registers one MCP
+tool per entry. Each tool:
+
+1. Builds `argv` from positional arguments and flags defined in the schema.
+2. Shells out: `basecamp <group> <action> <args...> --json`.
+3. Returns the parsed `data` field from the CLI's `{ok, data}` envelope to the MCP client.
+
+Shortcut commands (`todo`, `done`, `card`, `comment`, etc.) are intentionally excluded — their
+underlying actions (`todos_create`, `cards_create`, …) are already exposed.
+
+## Regenerating tool schemas
+
+After upgrading the `basecamp` CLI:
+
+```sh
+uv run basecamp-cli-mcp generate
+```
+
+Review the diff in `src/basecamp_cli_mcp/data/tools.json` and commit. The generator reads
+`basecamp commands --json` and parses `basecamp <group> <action> --help` for each action.
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+uv build                       # wheel + sdist into dist/
+```
+
+Layout:
+
+- `src/basecamp_cli_mcp/server.py` — wires up the MCP server from `data/tools.json`
+- `src/basecamp_cli_mcp/runner.py` — builds argv and shells out
+- `src/basecamp_cli_mcp/generator.py` — regenerates `data/tools.json`
+- `src/basecamp_cli_mcp/help_parser.py` — parses `--help` text into a schema
+- `src/basecamp_cli_mcp/cli.py` — entrypoint (`basecamp-cli-mcp`)
+- `src/basecamp_cli_mcp/data/tools.json` — generated tool schemas (committed)

basecamp_cli_mcp-0.6.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "basecamp-cli-mcp"
+version = "0.6.0"
+description = "MCP server that wraps the basecamp CLI."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Matt Brooke-Smith", email = "matt@futureworkshops.com" }]
+keywords = ["mcp", "basecamp", "model-context-protocol"]
+
+dependencies = [
+    "mcp>=1.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/FutureWorkshops/basecamp-cli-mcp"
+Source = "https://github.com/FutureWorkshops/basecamp-cli-mcp"
+
+[project.scripts]
+basecamp-cli-mcp = "basecamp_cli_mcp.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/basecamp_cli_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/basecamp_cli_mcp", "tests", "README.md", "LICENSE"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

basecamp_cli_mcp-0.6.0/src/basecamp_cli_mcp/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("basecamp-cli-mcp")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

basecamp_cli_mcp-0.6.0/src/basecamp_cli_mcp/cli.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from importlib.resources import files
+from pathlib import Path
+
+from . import __version__
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="basecamp-cli-mcp",
+        description="MCP server that wraps the basecamp CLI.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "--include",
+        action="append",
+        default=None,
+        metavar="PATTERN",
+        help=(
+            "Only expose tools whose name matches PATTERN (fnmatch glob). "
+            "Repeatable. Example: --include 'cards_*' --include 'todos_*'."
+        ),
+    )
+    parser.add_argument(
+        "--exclude",
+        action="append",
+        default=None,
+        metavar="PATTERN",
+        help="Hide tools whose name matches PATTERN. Repeatable. Applied after --include.",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    gen = sub.add_parser("generate", help="Regenerate data/tools.json from the basecamp CLI.")
+    gen.add_argument(
+        "--output",
+        type=Path,
+        default=None,
+        help="Path to write tools.json (default: in-tree data/tools.json next to this package).",
+    )
+
+    sub.add_parser(
+        "setup",
+        help="Install the basecamp CLI (if missing) and run `basecamp setup` to authenticate.",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command == "generate":
+        return _generate(args.output)
+
+    if args.command == "setup":
+        from .setup_cmd import run as run_setup
+
+        return run_setup()
+
+    from . import server
+
+    asyncio.run(server.run(include=args.include, exclude=args.exclude))
+    return 0
+
+
+def _generate(output: Path | None) -> int:
+    from .generator import Generator
+
+    tools = Generator().generate()
+    if output is None:
+        output = Path(str(files("basecamp_cli_mcp") / "data" / "tools.json"))
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(tools, indent=2) + "\n", encoding="utf-8")
+    print(f"Wrote {len(tools)} tools to {output}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())