appknox-mcp 1.0.0__tar.gz

appknox_mcp-1.0.0/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "appknox",
+  "description": "Appknox MCP server and Claude Code plugin (slash commands + fixer agent).",
+  "owner": {
+    "name": "Appknox"
+  },
+  "plugins": [
+    {
+      "name": "appknox",
+      "source": "./",
+      "description": "Appknox KnoxIQ fix-and-verify: fetch the vulnerabilities Appknox found in your app, fix them in your repo, verify with the finding's PoC, and re-scan."
+    }
+  ]
+}

appknox_mcp-1.0.0/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "appknox",
+  "description": "Appknox KnoxIQ fix-and-verify: fetch the vulnerabilities Appknox found in your app, fix them in your repo, verify with the finding's PoC, and re-scan.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Appknox"
+  }
+}

appknox_mcp-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [develop]
+  push:
+    branches: [develop]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Run tests
+        run: uv run pytest -q
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      # Runs the exact hooks in .pre-commit-config.yaml (black, ruff, mypy,
+      # plus the hygiene checks) — a pre-commit hook is opt-in locally and
+      # skippable with --no-verify, so this is what actually enforces it.
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+      - name: Run pre-commit hooks
+        run: uv run --with pre-commit pre-commit run --all-files --show-diff-on-failure
+
+  # Single required status check for branch protection, instead of naming
+  # `test`/`lint` individually there — this succeeds only if every job in the
+  # workflow did, so adding a new job here later doesn't also require a
+  # branch-protection settings change to actually gate merges on it.
+  ci:
+    name: CI
+    runs-on: ubuntu-latest
+    needs: [test, lint]
+    if: always()
+    steps:
+      - name: Check all jobs succeeded
+        run: |
+          if [ "${{ needs.test.result }}" != "success" ] || [ "${{ needs.lint.result }}" != "success" ]; then
+            echo "::error::One or more required CI jobs failed (test=${{ needs.test.result }}, lint=${{ needs.lint.result }})."
+            exit 1
+          fi

appknox_mcp-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,113 @@
+name: Build, Attach & Publish Release
+
+# Fires when a GitHub Release is published — created by YOU (GitHub UI's
+# "Draft a new release", or `gh release create <tag>` from your own login),
+# never by this workflow itself. That distinction matters: GitHub's
+# anti-recursion guard blocks an event created by a workflow's own
+# GITHUB_TOKEN from triggering other workflows, so a release this workflow
+# created would never actually fire `release: published` — which is exactly
+# why release creation now has to be a human action, not automated. In
+# exchange, you get full control: pick any tag (new or existing) and any
+# branch/commit as the release's target, from GitHub's own release UI.
+#
+# Verifies pyproject.toml's version at that exact commit matches the tag you
+# chose (a mismatch almost always means you forgot to bump the version before
+# tagging), then tests, builds the wheel + sdist, smoke-tests the BUILT wheel,
+# attaches both to the release you created, and publishes:
+#   - "Set as a pre-release" checked  -> TestPyPI (safe, repeatable dry run)
+#   - unchecked (a real release)      -> PyPI
+#
+# Requires one-time setup on both index's side before this can succeed —
+# nothing here works until you do this by hand (PyPI Trusted Publishing has no
+# API for it):
+#   1. On test.pypi.org and pypi.org, under your account -> Publishing, add a
+#      "pending" trusted publisher for this project:
+#        - PyPI project name: appknox-mcp
+#        - Owner: appknox   Repository: appknox-mcp
+#        - Workflow filename: publish.yml
+#        - Environment name: testpypi (on test.pypi.org) / pypi (on pypi.org)
+#   2. In this repo's Settings -> Environments, create two environments named
+#      "testpypi" and "pypi" (the names must match what you registered above).
+#      Optionally add required reviewers to the "pypi" environment for a manual
+#      gate on real publishes.
+# No secrets to create or store — Trusted Publishing uses this job's own OIDC
+# token (the `id-token: write` permission below), which is why the workflow
+# filename and environment name both have to match exactly what you registered.
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # Has to be resolved here, not inside a step — environment protection
+    # rules are evaluated before the job's steps run. github.event.release is
+    # available directly since this triggers on the release event itself —
+    # no separate lookup job needed (unlike when we reacted to a workflow_run).
+    environment: ${{ github.event.release.prerelease && 'testpypi' || 'pypi' }}
+    permissions:
+      contents: write # to attach the wheel/sdist to the release you created
+      id-token: write # PyPI/TestPyPI Trusted Publishing (OIDC)
+    env:
+      # Dummy token so importing the server / running tests never blocks on
+      # auth. Not a credential — the server accepts an empty/placeholder
+      # token and only fails on an actual API call, which this never makes.
+      APPKNOX_ACCESS_TOKEN: "PLACEHOLDER:PLACEHOLDER"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Build exactly what you tagged, not whatever the default branch's
+          # HEAD happens to be.
+          ref: ${{ github.event.release.tag_name }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Verify pyproject.toml's version matches the release tag
+        run: |
+          EXPECTED="v$(uv version --short)"
+          TAG="${{ github.event.release.tag_name }}"
+          if [ "$TAG" != "$EXPECTED" ]; then
+            echo "::error::Release tag '$TAG' doesn't match pyproject.toml's version"\
+              "('$EXPECTED' at this commit). Bump the version to match before"\
+              "tagging, or delete this release and re-tag."
+            exit 1
+          fi
+
+      - name: Run tests
+        run: uv run pytest -q
+
+      - name: Build wheel + sdist
+        run: uv build
+
+      - name: Smoke-test the built wheel (import + tool count) in a clean venv
+        run: |
+          uv venv /tmp/verify
+          uv pip install --python /tmp/verify/bin/python dist/*.whl
+          # Run from /tmp so a source-relative file (e.g. the repo's docs/) can't
+          # mask a packaging bug — this is exactly what caught the spec-load crash.
+          cd /tmp
+          /tmp/verify/bin/python -c "import asyncio, appknox_mcp.server as s; n=len(asyncio.run(s.mcp.list_tools())); print(f'built wheel OK — {n} tools'); assert n >= 7, n"
+
+      - name: Attach wheel + sdist to the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "${{ github.event.release.tag_name }}" dist/*.whl dist/*.tar.gz --clobber
+
+      - name: Publish to TestPyPI (prerelease dry run)
+        if: github.event.release.prerelease
+        run: uv publish --index testpypi
+
+      - name: Publish to PyPI
+        if: ${{ !github.event.release.prerelease }}
+        run: uv publish
+
+      - name: Summary
+        run: |
+          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+            echo "### Published to TestPyPI :test_tube:" >> "$GITHUB_STEP_SUMMARY"
+            echo "Verify with: \`uv tool install --reinstall --index https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ --index-strategy unsafe-best-match appknox-mcp\`" >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "### Published to PyPI :rocket:" >> "$GITHUB_STEP_SUMMARY"
+            echo "Verify with: \`uv tool install --reinstall appknox-mcp\`" >> "$GITHUB_STEP_SUMMARY"
+          fi

appknox_mcp-1.0.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.env
+.python-version
+uv.lock
+.zed/
+.DS_Store
+CLAUDE.md
+.claude/

appknox_mcp-1.0.0/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "appknox": {
+      "command": "uv",
+      "args": ["run", "appknox-mcp"],
+      "env": {
+        "APPKNOX_ACCESS_TOKEN": "${APPKNOX_ACCESS_TOKEN}",
+        "APPKNOX_BASE_URL": "${APPKNOX_BASE_URL}"
+      }
+    }
+  }
+}

appknox_mcp-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,34 @@
+# Installed with `uv run pre-commit install` (one-time, per clone) so these
+# run automatically on `git commit`. CI (.github/workflows/ci.yml) runs the
+# same checks via `uv run pre-commit run --all-files` — a pre-commit hook is
+# opt-in locally and skippable with `--no-verify`, so CI is what actually
+# enforces this on every PR, not just a courtesy for whoever remembers to
+# install it.
+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-merge-conflict
+      - id: check-added-large-files
+
+  - repo: https://github.com/psf/black
+    rev: 25.9.0
+    hooks:
+      - id: black
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.7
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.18.2
+    hooks:
+      - id: mypy
+        additional_dependencies: ["fastmcp>=2.0.0,<4.0.0", "httpx>=0.27.0", "pydantic>=2.0.0"]
+        files: ^src/

appknox_mcp-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+## Setup
+
+```bash
+uv sync
+uv run pre-commit install
+```
+
+The second command wires up git's `pre-commit` hook so black, ruff, and mypy
+(plus a few hygiene checks) run automatically on every `git commit` — see
+`.pre-commit-config.yaml`. It only touches files you've staged, so it's fast.
+
+To run everything by hand (e.g. before opening a PR):
+
+```bash
+uv run pre-commit run --all-files
+```
+
+CI runs this same command on every PR — a local git hook is opt-in and
+skippable with `git commit --no-verify`, so CI is what actually enforces it.
+
+## Branch rules
+
+`develop` is the default branch and requires at least one approving review
+plus a green CI run before a PR can merge — direct pushes aren't allowed for
+regular contributors. Target `develop` with your PR unless you're stacking on
+another open PR. (Repo admins can still push directly — see Releasing below,
+which relies on exactly that to bump the version with no PR round-trip.)
+
+## Tests
+
+```bash
+uv run pytest -q
+```
+
+## Releasing
+
+```bash
+./scripts/release.sh patch      # or minor / major
+./scripts/release.sh patch --real   # skip TestPyPI, publish straight to PyPI
+```
+
+Bumps `pyproject.toml`'s version, pushes it straight to `develop`, tags it,
+and creates a GitHub Release using your own `gh` login — which is what
+triggers `.github/workflows/publish.yml` to actually build, test, and publish
+(TestPyPI by default, or real PyPI with `--real`). No PAT or stored secret
+involved: since it's your own account doing the push and creating the
+release, branch protection's admin exemption and GitHub's normal "a human did
+this" behavior both apply, exactly as if you'd done each step by hand.
+
+Must be run from a clean `develop` checkout, by an account with admin access
+to this repo (needed to push directly, bypassing the PR requirement above).

appknox_mcp-1.0.0/INSTALL.md

@@ -0,0 +1,329 @@
+# Installing the Appknox MCP server
+
+This document is written so an **AI coding agent** (Claude Code, Cursor, Codex, …)
+can install and wire up the Appknox MCP server end-to-end. A human can follow it
+too. It needs no clone of this repo — the server installs as a global command,
+and this exact file ships inside the package: once step 1 below is done, run
+`appknox-mcp --install-guide` any time to print it again.
+
+> **Agent:** if a user handed you this repo's URL (or this file) and said "install
+> it," you're in the right place — do the steps below in order. **First identify
+> which client you are actually running as** (Claude Code, Cursor, Codex, GitHub
+> Copilot CLI, VS Code, Windsurf, Claude Desktop, or something else) — you need
+> this for step 3 regardless, and it matters more once you reach the section
+> titled "Claude Code only": if you are not Claude Code, skip that entire
+> section (do not run its commands "just in case" or because it looked like the
+> next step in order) and go straight to the step after it. The only things to
+> ask the user for are their **Access Key ID + Secret Access Key** (step 2) and,
+> if it's unclear, **which client** to configure. Never print the secret back.
+
+## 0. Prerequisite: `uv`
+
+If `uv` is not on PATH, install it:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh      # macOS/Linux
+# Windows PowerShell: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Then ensure `~/.local/bin` is on PATH (the installer usually handles this).
+
+## 1. Install the server as a global tool
+
+**You (the agent) run these commands** — the user doesn't. Try them **in order,
+stopping at the first that works**; all produce a location-independent
+`appknox-mcp` command on PATH (usually `~/.local/bin/appknox-mcp`).
+
+> **Always include `--reinstall`** on every `uv tool install` below, even the
+> very first attempt. Without it, `uv` silently does **nothing** if any
+> version of `appknox-mcp` is already installed — including a stale one that
+> predates a flag like `--install-guide` — so re-running "install" can look
+> like it worked while actually leaving old, broken code in place. This is a
+> real failure mode that has happened, not a hypothetical edge case.
+
+**a) From PyPI (preferred — try this first).**
+```bash
+uv tool install --reinstall appknox-mcp
+```
+Not live yet — while `appknox-mcp` is only on TestPyPI, install from there
+instead (needs `--extra-index-url` since deps like `fastmcp` aren't on
+TestPyPI, and `--index-strategy unsafe-best-match` to let `uv` resolve across
+both indexes):
+```bash
+uv tool install --reinstall --index https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ --index-strategy unsafe-best-match appknox-mcp
+```
+Once it's on real PyPI, switch to the plain command above and skip straight to
+verifying — only fall through to (b) if both of these fail.
+
+**b) From a released wheel.**
+The repo is **private for now**, so download the wheel with the GitHub CLI (it
+uses the user's existing `gh`/GitHub auth), then install the local file:
+
+```bash
+gh release download --repo appknox/appknox-mcp --pattern '*.whl' --dir /tmp/appknox-mcp
+uv tool install --reinstall /tmp/appknox-mcp/*.whl
+```
+Add `<tag>` (e.g. `v0.1.0`) as the first arg to `gh release download` to pin a
+version; omit it for the latest. **When the repo is public**, skip `gh` entirely
+and install straight from the asset URL:
+`uv tool install --reinstall "https://github.com/appknox/appknox-mcp/releases/latest/download/appknox_mcp-<version>-py3-none-any.whl"`.
+
+**c) From git (no release needed).**
+```bash
+uv tool install --reinstall "git+ssh://git@github.com/appknox/appknox-mcp@develop"   # private: uses the user's SSH key
+# public: uv tool install --reinstall "git+https://github.com/appknox/appknox-mcp@develop"
+```
+
+**d) From a local checkout** (if the user already cloned it):
+`uv tool install --reinstall /path/to/appknox-mcp`.
+
+Then verify — `command -v appknox-mcp` only proves *a* binary is on PATH, not
+that it's actually the one you just installed (a stale prior install would
+also pass that check silently, as `--reinstall` above exists specifically to
+prevent). Confirm the real thing instead:
+
+```bash
+appknox-mcp --install-guide | head -1
+```
+
+If that doesn't print `# Installing the Appknox MCP server`, the install
+didn't actually take — re-run step 1's command with `--reinstall` (if you
+skipped it) rather than assuming this step is broken.
+
+To update later: `uv tool upgrade appknox-mcp` (works regardless of which
+source it was originally installed from) or re-run the `gh release download` +
+`uv tool install --reinstall` step for a newer wheel.
+
+## 2. Ask the user for credentials
+
+Prompt the user for three things (from Appknox dashboard → **Service Accounts**):
+
+1. **Access Key ID**
+2. **Secret Access Key**
+3. **Base URL** — the API host for their Appknox instance. Don't assume a
+   default: white-labeled deployments use a different host, so ask rather than
+   guess (their dashboard has it if they're unsure; Appknox's own KnoxIQ beta
+   host is `https://sherlock-mcp.staging.appknox.io`, for reference only).
+
+Combine the first two into the token the server expects:
+`APPKNOX_ACCESS_TOKEN = "<Access Key ID>:<Secret Access Key>"` (a single colon
+between them). Hold these in memory for step 3 — never echo the secret back to
+the user or write it anywhere except the client config's `env`.
+
+## 3. Write the MCP config for the client
+
+Figure out which client you're configuring (if you're an agent, that's usually
+the client you're running in; otherwise ask). **Merge** the `appknox` entry into
+the existing config — never overwrite other servers. Use `command: "appknox-mcp"`
+with **no args** (the tool install put it on PATH).
+
+### JSON clients — Cursor, Claude Desktop, Windsurf, Claude Code
+
+Key is `mcpServers`. Files:
+
+| Client | Config file |
+|---|---|
+| Cursor | `~/.cursor/mcp.json` |
+| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` |
+| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Claude Code (this project) | `.mcp.json` in the repo |
+
+```json
+{
+  "mcpServers": {
+    "appknox": {
+      "command": "appknox-mcp",
+      "env": {
+        "APPKNOX_ACCESS_TOKEN": "<Access Key ID>:<Secret Access Key>",
+        "APPKNOX_BASE_URL": "<your Appknox base URL>"
+      }
+    }
+  }
+}
+```
+
+### GitHub Copilot CLI — `~/.copilot/mcp-config.json`
+
+Key is `mcpServers` too, but each entry additionally needs `"type": "local"`
+(Copilot CLI's name for a stdio server) and a `"tools"` allowlist — omit
+`"tools"` and the server starts but exposes none of its tools:
+
+```json
+{
+  "mcpServers": {
+    "appknox": {
+      "type": "local",
+      "command": "appknox-mcp",
+      "args": [],
+      "env": {
+        "APPKNOX_ACCESS_TOKEN": "<Access Key ID>:<Secret Access Key>",
+        "APPKNOX_BASE_URL": "<your Appknox base URL>"
+      },
+      "tools": ["*"]
+    }
+  }
+}
+```
+
+The path honors `$COPILOT_HOME` if set (defaults to `~/.copilot`). Verify with
+`/mcp` inside a `copilot` session.
+
+> **Note:** this is the standalone **GitHub Copilot CLI**, not Copilot Chat
+> inside VS Code — that one is configured via the **VS Code** section below
+> (VS Code's `.vscode/mcp.json` is shared by both plain VS Code MCP support and
+> Copilot Chat).
+
+> **Important — Copilot CLI ignores this server's workflow guidance by
+> default.** Every MCP server can send high-level instructions alongside its
+> tools (ours describes the resolve → triage → fix → verify flow, how to
+> select findings, etc.) — Copilot CLI deliberately does **not** feed these
+> into the model unless you start it with `copilot --allow-all-mcp-server-instructions`
+> (v1.0.66+). Without that flag, Copilot only sees each tool's own
+> name/parameters/docstring, not the overall workflow — it can still call the
+> tools correctly, but won't follow the intended multi-step flow or
+> presentation guidance (e.g. showing exploitability) unless asked explicitly
+> each time. Recommend this flag to anyone using Copilot CLI who wants the
+> guided experience the other clients get by default.
+
+### VS Code — `.vscode/mcp.json`
+
+Key is `servers` and the entry needs `"type": "stdio"`:
+
+```json
+{
+  "servers": {
+    "appknox": {
+      "type": "stdio",
+      "command": "appknox-mcp",
+      "env": { "APPKNOX_ACCESS_TOKEN": "…", "APPKNOX_BASE_URL": "…" }
+    }
+  }
+}
+```
+
+This is project-scoped (only active in this one repo), unlike every other
+client here — `appknox-mcp --configure vscode` writes the same project-scoped
+file, we don't automate the alternative below. VS Code does have a genuine
+**user-scope** option (works in every workspace): Command Palette → **MCP:
+Open User Configuration**, or `code --add-mcp '{"name":"appknox",...}'` and
+choose **Global** over **Workspace**. VS Code's own docs recommend *against* a
+literal secret even there — use an `${input:...}` variable (`password: true`)
+instead, which prompts once and caches the value in VS Code's own secret
+storage from then on. Set that up by hand if you want VS Code to behave like
+the other clients here; see [VS Code's MCP docs](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
+for the exact `inputs` array syntax.
+
+### Codex — `~/.codex/config.toml`
+
+The env vars **must** go under a nested `[mcp_servers.appknox.env]` table, or
+Codex silently ignores them:
+
+```toml
+[mcp_servers.appknox]
+command = "appknox-mcp"
+args = []
+
+[mcp_servers.appknox.env]
+APPKNOX_ACCESS_TOKEN = "<Access Key ID>:<Secret Access Key>"
+APPKNOX_BASE_URL = "<your Appknox base URL>"
+```
+
+> You can skip writing any of the JSON/TOML above by hand and instead let the
+> already-installed `appknox-mcp` command do the merge for you (handles the
+> Codex nesting, Copilot's `type`/`tools` fields, etc. correctly) — works with
+> **no repo clone needed**, since the writer ships inside the package itself:
+> `APPKNOX_ACCESS_TOKEN=<id>:<secret> appknox-mcp --configure <name> --base-url <url>`.
+> To remove an entry later: `appknox-mcp --remove-client <name>`.
+
+### Keep project-scoped tokens out of git
+
+`vscode` (`.vscode/mcp.json`) lives in the app repo and now contains the
+token — add it to that repo's `.gitignore`. `claude` no longer needs this: it
+registers at user scope (`~/.claude.json`, outside any repo), not a
+project-scoped file.
+
+### Claude Code only: the plugin (slash commands + fixer agent)
+
+> **STOP — agent, check this first:** this section applies ONLY if you are
+> Claude Code. If you are Copilot CLI, Cursor, Codex, VS Code, Windsurf, Claude
+> Desktop, or anything else, **skip this entire section** — do not run
+> `claude plugin ...` commands (the `claude` CLI likely isn't even installed in
+> your environment, and this step is not part of your setup at all) — and
+> continue at "4. Restart and verify" below.
+
+The MCP config above gets Claude Code the **tools**, but not `/appknox:triage`,
+`/appknox:fix`, `/appknox:upload`, `/appknox:verify`, or the `appknox-fixer`
+sub-agent — those only load if this repo is installed as a Claude Code
+**plugin**, which is a separate registration.
+
+**a) No-clone (preferred — works from a bare `uv tool install`, needs no
+GitHub access at all).** The wheel bundles the plugin's files; this extracts
+them to `~/.appknox-mcp/claude-plugin` and registers that local path:
+
+```bash
+appknox-mcp --install-claude-plugin
+```
+
+**b) From a repo you already have cloned locally**, or the GitHub-hosted form
+(needs the repo on its default branch and — until it's public — doesn't
+reliably work; see below):
+
+```bash
+claude plugin marketplace add /path/to/appknox-mcp   # local clone's path
+# or: claude plugin marketplace add appknox/appknox-mcp
+claude plugin install appknox@appknox -y
+```
+
+> **Two separate ways the GitHub-hosted form (b, second line) fails, easy to
+> confuse — (a) and (b)'s local-path form both sidestep both of these:**
+> 1. `.claude-plugin/marketplace.json` must exist **on the repo's default
+>    branch** (`develop`, not `main`) — `claude plugin marketplace add
+>    owner/repo` always clones that branch, never a feature branch.
+> 2. Even on the default branch, `claude plugin marketplace add owner/repo`
+>    does **not** reliably work against a private repo today — it clones via
+>    its own internal git (SSH needs a key already loaded in `ssh-agent`;
+>    HTTPS fails outright, ignoring `gh`/keychain credentials). See
+>    [anthropics/claude-code#17201](https://github.com/anthropics/claude-code/issues/17201).
+
+This installs at **user scope** (the default), so the commands/agent are
+available from any repo afterward, not just the one you ran this in. Commands
+are namespaced `/appknox:<name>` (Claude Code's plugin system always prefixes
+`<plugin>:<command>` — there's no way to opt out of that and still use the
+formal plugin mechanism). Its bundled MCP entry reads `APPKNOX_ACCESS_TOKEN`/
+`APPKNOX_BASE_URL` from the environment at launch — export them in the user's
+shell profile, or rely on the project-scoped `.mcp.json` above (token baked in,
+works without exporting anything, but only in that one repo).
+`scripts/install.sh`/`install.ps1` do this step automatically when Claude Code
+is selected.
+
+## 4. Restart and verify
+
+MCP servers are spawned when the client starts, so **restart the client** (fully
+quit Claude Desktop with Cmd+Q; restart the Codex or Copilot CLI session; reopen
+Cursor). Then:
+
+- Claude Code / Codex / Copilot CLI: run `/mcp` — you should see `appknox` with
+  8 tools.
+- Claude Code only: run `claude plugin list` — you should see `appknox@appknox`
+  enabled; try `/appknox:triage` to confirm the slash commands loaded.
+- Ask: *"list the Appknox tools"* — the agent should see `resolve_latest_file`,
+  `list_analyses`, `knoxiq_get_fix_plan`, `knoxiq_prepare_fix`,
+  `knoxiq_verify_fixes`, etc.
+
+## 5. Update / uninstall
+
+```bash
+uv tool upgrade appknox-mcp          # pull the latest server
+uv tool uninstall appknox-mcp        # remove the server
+```
+
+Before (or instead of) removing the server itself, remove its entry from each
+client's config: `appknox-mcp --remove-client <client>` — this needs no repo
+clone, since it ships inside the package (see the note in step 3). If the repo
+happens to be cloned, `scripts/uninstall.sh <client>`/`scripts/uninstall.ps1
+<client>` do the same thing and additionally remove the Claude Code plugin
+registration for `claude`. To remove just the plugin by hand:
+`claude plugin uninstall appknox@appknox` then
+`claude plugin marketplace remove appknox`.

appknox_mcp-1.0.0/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2026 Appknox. All rights reserved.
+
+This software and its associated documentation (the "Software") are the
+proprietary and confidential property of Appknox. The Software is licensed, not
+sold, and may be used only in accordance with the terms of a separate written
+agreement with Appknox. Unauthorized copying, distribution, modification, public
+display, or use of the Software, in whole or in part, via any medium, is strictly
+prohibited.
+
+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 APPKNOX BE
+LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF, OR IN
+CONNECTION WITH THE SOFTWARE OR ITS USE.