No description
  • JavaScript 100%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
dsh 630cb2980f
All checks were successful
CI / check (push) Successful in 22s
docs: 0.1.1 live verification and publication state
20/20 live tool checks passed against Kaggle CLI 2.2.5 with OAuth. v0.1.1
is on the Forgejo registry and its npmjs stage awaits 2FA approval (#5);
the running web profile still needs a restart to load 0.1.1.
2026-11-14 23:40:46 +00:00
.forgejo/workflows feat: initial dsh-kaggle plugin (CLI tools + optional MCP adapter) 2026-11-11 22:11:48 +00:00
devops feat: initial dsh-kaggle plugin (CLI tools + optional MCP adapter) 2026-11-11 22:11:48 +00:00
docs fix: align parsers with live Kaggle CLI 2.2.5 (0.1.1) 2026-11-14 23:38:40 +00:00
lib fix: align parsers with live Kaggle CLI 2.2.5 (0.1.1) 2026-11-14 23:38:40 +00:00
locale feat: initial dsh-kaggle plugin (CLI tools + optional MCP adapter) 2026-11-11 22:11:48 +00:00
scripts fix: align parsers with live Kaggle CLI 2.2.5 (0.1.1) 2026-11-14 23:38:40 +00:00
test fix: align parsers with live Kaggle CLI 2.2.5 (0.1.1) 2026-11-14 23:38:40 +00:00
.gitignore feat: initial dsh-kaggle plugin (CLI tools + optional MCP adapter) 2026-11-11 22:11:48 +00:00
AGENTS.md docs: 0.1.1 live verification and publication state 2026-11-14 23:40:46 +00:00
CHANGELOG.md fix: align parsers with live Kaggle CLI 2.2.5 (0.1.1) 2026-11-14 23:38:40 +00:00
cordis.patch.yml feat: initial dsh-kaggle plugin (CLI tools + optional MCP adapter) 2026-11-11 22:11:48 +00:00
icon.svg feat: initial dsh-kaggle plugin (CLI tools + optional MCP adapter) 2026-11-11 22:11:48 +00:00
input feat: initial dsh-kaggle plugin (CLI tools + optional MCP adapter) 2026-11-11 22:11:48 +00:00
LICENSE Initial commit 2026-11-11 21:45:07 +00:00
LOG.md docs: 0.1.1 live verification and publication state 2026-11-14 23:40:46 +00:00
package.json fix: align parsers with live Kaggle CLI 2.2.5 (0.1.1) 2026-11-14 23:38:40 +00:00
README.md fix: align parsers with live Kaggle CLI 2.2.5 (0.1.1) 2026-11-14 23:38:40 +00:00
TASKS.md docs: 0.1.1 live verification and publication state 2026-11-14 23:40:46 +00:00

dsh-kaggle

Agent-native Kaggle tools for DeepSeek Harness: search and download datasets, read competitions and leaderboards, pull/push notebooks, inspect models, browse forums — plus an optional adapter for Kaggle's official MCP server.

Status: 0.1.1. 31 native kaggle_* tools over the Kaggle CLI (2.2.x) and two MCP diagnostics; the optional Kaggle MCP adapter is off by default because the server is beta. Live-verified against Kaggle CLI 2.2.5 with OAuth (20/20 read-only checks); CI tests stay offline.

Why

Kaggle's CLI is the workhorse behind projects like ml-lab/LinA, ml-lab/tardits and ml-lab/hijack, but an agent driving it spends context on shell syntax, progress bars, pagination, Next Page Token preambles, CSV/JSON label quirks, and publishes that exit 0 after failing. Kaggle also ships a remote MCP server (https://www.kaggle.com/mcp) that covers interactive notebook sessions, benchmarks and write-ups — but with nested protobuf-style requests and per-endpoint auth.

dsh-kaggle turns both into typed tools:

  • CLI-first, no Python import in the Host: the plugin spawns kaggle, injects the token through the environment, parses JSON defensively, confines every download to the session workspace, and returns {ok, data | error}.
  • Optional MCP adapter: opt in to register the server's tools as mcp__kaggle__* for the surfaces the CLI does not cover.

Tool surface

Area Tools
Diagnostics kaggle_plugin_info, kaggle_mcp_status, kaggle_mcp_refresh
Search kaggle_search (competitions, datasets, notebooks, models, users, discussions, benchmarks)
Datasets kaggle_datasets_list, kaggle_dataset_files, kaggle_dataset_status, kaggle_dataset_download, kaggle_dataset_create, kaggle_dataset_version, kaggle_dataset_init
Competitions kaggle_competitions_list, kaggle_competition_files, kaggle_competition_download, kaggle_competition_leaderboard, kaggle_competition_submissions, kaggle_competition_submit, kaggle_competition_pages
Notebooks kaggle_kernels_list, kaggle_kernel_pull, kaggle_kernel_push, kaggle_kernel_status, kaggle_kernel_logs, kaggle_kernel_output, kaggle_kernel_files
Models kaggle_models_list, kaggle_models_files, kaggle_model_download, kaggle_models_get
Forums kaggle_forums_list, kaggle_forum_topics, kaggle_forum_topic
Quota kaggle_quota

List tools return a page of rows plus next_page_token; downloads stream to disk and return a manifest (path, files, bytes, total_files, up_to_date).

Install

Prerequisites:

  • the Kaggle CLI (pipx install kaggle or uv tool install kaggle, Python ≥ 3.11; on Python 3.14 the PyPI metadata omits six, so use uv tool install kaggle --with six). A bare cliBin: kaggle is also looked up in ~/.local/bin and the uv/pipx tool directories, because the Host's systemd PATH may not include them;
  • Kaggle credentials: kaggle auth login (OAuth), or a token (KGAT…) in ~/.kaggle/access_token / KAGGLE_API_TOKEN, or a legacy ~/.kaggle/kaggle.json.

Install the plugin from the Forgejo registry:

# Forgejo registry
dsh plugin --profile web add \
  --registry https://git.pvlb.dev/api/packages/dsh-plugins/npm/ \
  dsh-kaggle@0.1.1

# or from npmjs
dsh plugin --profile web add dsh-kaggle@0.1.1

Restart the profile if the Plugin Manager reports restart-required, then call kaggle_plugin_info.

Auth

The plugin adds one credential source in front of the CLI's own login: the DSH credential ref KAGGLE_API_TOKEN (authMode: auto by default). When it resolves, the token is injected as the child's KAGGLE_API_TOKEN environment variable — never as an argument and never into a tool result. When it does not, the CLI's OAuth login or token file is used unchanged.

kaggle_plugin_info reports which sources exist (booleans only) and never a token value. Store a token in DSH Settings → Credentials if you prefer the credential store over ~/.kaggle; do not paste it into chat.

MCP (beta)

Off by default. Enable it in the dsh-kaggle row config:

mcpEnabled: true
mcpAuthMode: auto        # auto | bearer | none
mcpTokenEnv: KAGGLE_API_TOKEN
mcpTools: []             # optional allowlist globs, e.g. ["search_*", "get_*"]
mcpExcludeTools: []

kaggle_mcp_status shows the connection, registered tools and last error; kaggle_mcp_refresh re-lists the server's tools and swaps the registered set without a plugin release. auto connects anonymously when no token is stored — public search/topic tools work that way; notebook sessions, benchmarks and quota need a KGAT token. Upstream tools keep their { request: {…} } schemas, so prefer the native kaggle_* tools for everyday work.

Safety

  • Writes (dataset/notebook/model publish, competition submissions) name an exact target; the tool descriptions tell the agent to confirm with the operator first. There is no delete tool and no auto-submit in 0.1.0.
  • Tokens are redacted from every captured stream and never logged.
  • Downloads and uploads must stay inside the session workspace; .., absolute escapes and missing files are rejected before the CLI runs.
  • The CLI's exit code is not trusted for writes: Dataset creation error: …, Kernel push error: … and Submission failed with exit 0 become upload_failed with the redacted tail.
  • Tests are offline against a fake CLI. No test touches Kaggle or the network.

Errors

Code Meaning
invalid_input bad ref/flag/page size, missing metadata file, missing path
path_refused a path escaped the session workspace
cli_missing kaggle not found (install the CLI or set cliBin)
cli_auth Kaggle auth required or rejected
cli_config the CLI could not create its config directory
cli_timeout the command exceeded its wall clock
cli_parse output was not the expected JSON (reported, never guessed)
forbidden / not_found / rate_limited mapped HTTP failures, with hints
download_failed / upload_failed write/transfer failure (including exit-0 traps)
mcp_disabled / mcp_auth / mcp_unavailable optional MCP adapter states

Configuration

cliBin, authMode, credentialRef, configDir, downloadRoot, pageSize, commandTimeoutMs, downloadTimeoutMs, maxOutputBytes, noWarn and the mcp* fields. Defaults are safe for config: {}; see kaggle_plugin_info for the effective values.

Development

git clone git@git.pvlb.dev:dsh-plugins/dsh-kaggle.git
cd dsh-kaggle
node scripts/dev-link-dsh.mjs
npm test                  # offline unit/integration tests
npm run check             # syntax + tests
npm pack --dry-run        # published file list

# opt-in live checks (never in CI)
KAGGLE_LIVE_SMOKE=1 node scripts/smoke-live.mjs        # CLI runner probes
KAGGLE_LIVE_SMOKE=1 node scripts/smoke-tools-live.mjs  # all read-only tools

Research and design: docs/kaggle-cli.md, docs/kaggle-mcp.md, docs/design.md, docs/roadmap.md, docs/releasing.md. House rules: AGENTS.md.

License

Apache-2.0 — see LICENSE. The Kaggle CLI is Apache-2.0; Kaggle's service is governed by its own terms.