Skip to content

feat: Connect clients with plug and check connections with doctor - #4

Merged
johnxie merged 6 commits into
mainfrom
feat/connect-doctor
Nov 18, 2026
Merged

johnxie merged 6 commits into
mainfrom
feat/connect-doctor

Conversation

@johnxie

@johnxie johnxie commented Nov 18, 2026

Copy link
Copy Markdown
Member

What changes

  • plug <client> (alias connect) connects Claude Code, Codex, Cursor, VS Code, or Claude Desktop to https://www.taskade.com/mcp. The default is the browser sign-in (OAuth). No token goes anywhere.
  • plug with no client lists the clients on the machine and the command for each. It changes nothing.
  • doctor (alias whoami) checks Node.js, the server and its OAuth metadata, a token with MCP initialize and tools/list, and the client config files. The old whoami called a path that does not exist and always failed with 404.
  • --yes, --print, --project, --token, --json, --verbose, --version. An unknown command exits 1.
  • This makes the line in the Taskade settings page true: npx @taskade/cli plug claude-desktop now gives the steps and copies the URL.
  • Tests with node:test in a temporary HOME, CI on Node 18 to 24, a release workflow with npm trusted publishing, a new README, CHANGELOG.md, and SECURITY.md. Version 0.2.0. No runtime dependency.

Each client config shape comes from the public documentation of the client, cited in src/clients.mjs. Windsurf is left out: its docs now give two different config files for two builds, and a wrong config is worse than a missing client.

What each command does on your machine

Command What changes
plug Nothing. It lists the clients that it finds.
plug claude-code After a "y", it runs claude mcp add --transport http --scope user taskade https://www.taskade.com/mcp. Claude Code writes ~/.claude.json. With --project, Claude Code writes .mcp.json in the current folder.
plug codex After a "y", it runs codex mcp add taskade --url https://www.taskade.com/mcp, then codex mcp login taskade if the add step did not sign in. Codex writes ~/.codex/config.toml.
plug cursor After a "y", it merges one taskade entry into ~/.cursor/mcp.json (or .cursor/mcp.json with --project). It writes <file>.bak-<timestamp> first.
plug vscode After a "y", it runs code --add-mcp (the user profile). With --project, it merges one entry into .vscode/mcp.json.
plug claude-desktop Only the clipboard: it copies the URL. Claude keeps connectors in the Claude account.
plug ... --print Nothing. This is the default on a pipe or in CI.
plug ... --token The config then holds the token from TASKADE_TOKEN (Codex keeps only the variable name).
doctor Nothing. It reads files and sends requests to the server URL.

Before and after

Before (0.1.0)

  npx @taskade/cli plug claude-desktop
        |
        v
  "Paste your Taskade PAT (tskdp_...):"   <- the package is not on npm, and
        |                                    claude-desktop is not a client name
        v
  prints a JSON block with the token, writes nothing

  npx github:taskade/cli whoami  ->  "API returned 404 Not Found"  (always)
After (0.2.0)

  npx github:taskade/cli plug cursor
        |
        v
  Cursor reads ~/.cursor/mcp.json.
  The change:  + "taskade": { "url": "https://www.taskade.com/mcp" }
  Write ~/.cursor/mcp.json? [y/N] y
        |
        v
  backup, temp file, rename, same mode  ->  open Cursor, sign in to Taskade

  npx github:taskade/cli doctor
        |
        v
  ok    The server answers. Without sign-in it returns 401 and names its sign-in metadata.
  ok    Sign-in metadata: https://www.taskade.com/mcp/.well-known/oauth-protected-resource
  fail  The server refused the token (401: Invalid or expired token).
        Next: Create a new token at https://www.taskade.com/settings/api and set TASKADE_TOKEN to it.

How to check

Run each step in a temporary HOME, so that your real configs stay as they are.

Step Command Expected result
1 git clone -b feat/connect-doctor https://github.com/taskade/cli && cd cli && npm test Every test passes.
2 export HOME=$(mktemp -d) && cd "$HOME" A new empty HOME.
3 node <clone>/bin/cli.mjs plug A list of the clients that it finds. Nothing changes.
4 node <clone>/bin/cli.mjs plug claude-code --print The claude mcp add command. Nothing runs.
5 node <clone>/bin/cli.mjs plug cursor in a terminal, answer y ~/.cursor/mcp.json holds the taskade entry.
6 Run step 5 again "Already connected". No new backup.
7 echo '{ bad' > ~/.cursor/mcp.json && node <clone>/bin/cli.mjs plug cursor --yes Exit 1, "not valid JSON", the file is unchanged.
8 node <clone>/bin/cli.mjs plug claude-desktop The 3 steps, and the URL on the clipboard.
9 node <clone>/bin/cli.mjs doctor ok lines for the server, the token check skipped, exit 0 if every client file is valid.
10 TASKADE_TOKEN=tskdp_fake node <clone>/bin/cli.mjs doctor fail The server refused the token (401: Invalid or expired token), exit 1.
11 node <clone>/bin/cli.mjs plug cursor --token=abc Exit 1, "Never pass a token on the command line".

For the owner

  1. First npm publish. The release workflow uses npm trusted publishing, which needs the package to exist first. After this PR merges, publish 0.2.0 once by hand from a clean checkout of main: npm publish --access public.
  2. Trusted publisher. On npmjs.com, open the settings of @taskade/cli and add a trusted publisher: GitHub Actions, organization taskade, repository cli, workflow release.yml. From then on, a published GitHub release with the tag v<version> publishes the package with provenance and no token secret.
  3. The settings line. The Taskade settings page shows npx @taskade/cli plug claude-desktop and says "writes this for you automatically". After step 1 that command runs, and it gives the 3 Connectors steps and copies the URL. Claude Desktop has no supported file entry for a remote server with sign-in, so the CLI cannot write it. The settings text can say "copies the URL and gives the steps" to match.
  4. The examples. With the first npm release, change npx github:taskade/cli to npx @taskade/cli in the README and in the RUN constant in src/clients.mjs.

plug connects Claude Code, Codex, Cursor, VS Code, and Claude Desktop to
https://www.taskade.com/mcp with the browser sign-in. It runs the command
of the client, or it merges one entry into the JSON config file with a
diff, a backup, and an atomic write. --token reads a personal access
token from TASKADE_TOKEN only.

doctor checks Node.js, the server and its sign-in metadata, a token with
MCP initialize and tools/list, and the client config files. whoami is now
an alias of doctor, so the old command works again.

Version 0.2.0. The package now ships src/.
Each test gets its own HOME, USERPROFILE, APPDATA, and PATH. Fake claude,
codex, code, and clipboard commands record their arguments. A fake MCP
server on 127.0.0.1 answers with JSON, with an event stream, with 401,
and with 403.
CI runs npm test on Node 18, 20, 22, and 24 on Linux, and on Node 22 on
macOS and Windows. The release workflow checks that the tag equals the
package version, then publishes through npm trusted publishing.
Lead with the one command, say what each command changes on the machine,
and point to the setup prompt that needs no CLI. Add the changelog and
the security policy. The copyright holder is TASKCADE INC.
Copilot AI lite review requested due to automatic review settings November 18, 2026 23:00
Comment thread test/cli.test.mjs Fixed

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Several unresolved security, cross-platform configuration, error-handling, and rollback issues could expose tokens, prevent existing configs from being updated, or leave integrations disconnected.

5 open issues
What changed in this PR

This pull request replaces the legacy token-printing CLI with OAuth-first MCP client connections and Taskade server diagnostics.

Changes:

  • Adds plug/connect support for Claude Code, Codex, Cursor, VS Code, and Claude Desktop.
  • Adds doctor/whoami checks for Node.js, OAuth metadata, MCP authentication, tools, and client configurations.
  • Adds configuration merging and backups, comprehensive tests, security documentation, CI, and npm release automation.
File Description
test/​system.test.mjs Tests terminal prompts, secret masking, and system helper behavior.
test/​plug.test.mjs Tests client connection flows, configuration updates, token handling, and command execution.
test/​helpers.mjs Provides isolated test environments, subprocess helpers, and fake MCP server utilities.
test/​fixtures/​fake-client.mjs Provides fake client and clipboard commands for integration tests.
test/​doctor.test.mjs Tests server discovery, OAuth metadata, MCP requests, token failures, and client diagnostics.
test/​cli.test.mjs Tests command parsing, aliases, options, help, version output, errors, and URL validation.
src/​system.mjs Provides environment, process, path, terminal, clipboard, and redaction helpers.
src/​plug.mjs Implements client connection flows, prompts, token handling, command execution, and configuration updates.
src/​doctor.mjs Implements server, OAuth, token, MCP, and client configuration diagnostics.
src/​config-file.mjs Implements JSON parsing, merging, backups, formatting preservation, and atomic writes.
src/​clients.mjs Defines supported clients, configuration formats, detection, and server URL handling.
src/​cli.mjs Parses commands, aliases, options, validation, help, and version output.
SECURITY.md Documents vulnerability reporting and token-handling practices.
README.md Documents supported clients, connection commands, diagnostics, token usage, and release procedures.
package.json Updates the package version, metadata, scripts, published files, and publishing configuration.
LICENSE Updates the project copyright information.
CHANGELOG.md Records the 0.2.0 feature set and behavior changes.
bin/​cli.mjs Provides the executable entry point for the modular CLI.
.github/​workflows/​release.yml Adds version-checked npm trusted publishing with provenance.
.github/​workflows/​ci.yml Adds cross-version and cross-platform Node.js test automation.

Review effort: Lite

Comment thread src/config-file.mjs
try {
writeFileSync(temp, text, { mode });
chmodSync(temp, mode);
renameSync(temp, target);
Comment thread src/plug.mjs
Comment on lines +344 to +346
let backup;
try {
backup = writeConfig(file, text, { newMode: token ? 0o600 : 0o644 });
Comment thread src/cli.mjs
}
const maxArgs = name === "plug" ? 1 : 0;
if (rest.length > maxArgs) {
io.stderr.write(`Too many arguments for ${command}: ${rest.slice(maxArgs).join(" ")}\n`);
Comment thread src/doctor.mjs
}
add("server", "ok", `Sign-in metadata: ${match[1]}`);

const issuer = new URL(servers[0]);
Comment thread src/plug.mjs
Comment on lines +183 to +187
if (existing) {
const removed = await runCommand(io, bin, ["mcp", "remove", "--scope", scope, SERVER_NAME]);
if (removed.code !== 0) return fail(`claude mcp remove failed (${removed.error || `exit code ${removed.code}`}).`);
}
const added = await runCommand(io, bin, args);
@johnxie
johnxie merged commit 860e43a into main Nov 18, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants