tappy-mcp 0.1.0__tar.gz

tappy_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest -q

tappy_mcp-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Local agent config
+.claude/

tappy_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- Inspector primitives `tappy read <server> <uri>` (resource contents) and
+  `tappy prompt <server> <name>` (render a prompt) — all three MCP primitives are now
+  exercisable from the CLI.
+- `tappy restore <client>` rolls a client config back to its latest backup (itself backed
+  up first); `tappy restore --list` shows available backups.
+- `tappy add --dry-run` previews the change as a unified diff without writing.
+- `--version` / `-V`.
+- `--path` selector to disambiguate servers that exist in several configs of the same
+  client (e.g. Claude Code's project `./.mcp.json` vs. user `~/.claude.json`).
+- `TAPPY_CONFIG` environment variable: point Tappy at extra config files (standard
+  `mcpServers` shape) it doesn't know natively.
+
+### Changed
+- Renamed the monitoring commands: `ps` → `status`, `stats` → `watch`. Output and framing
+  no longer lean on Docker.
+- `registry --init --from-client` now templates secret `env`/`header` values as `${KEY}`
+  placeholders instead of writing real secrets into the (git-committed) registry file.
+
+### Fixed
+- A config file that fails to parse is now flagged (`parse error`) and writes to it are
+  refused, instead of silently appearing empty and having a sentinel written back into it.
+- `add` no longer mangles arguments that contain spaces (args are kept as a list).
+- `disable` warns when the target client may not honor a `disabled` flag.
+- Inspector/tool errors surface the real MCP cause instead of a TaskGroup wrapper message.
+- Fingerprint store writes are now atomic.
+
+## [0.1.0]
+- Initial release: discovery, safe edits, MCP inspection, monitoring, tool-definition
+  pinning, and the team registry.

tappy_mcp-0.1.0/GUIDE.md

@@ -0,0 +1,380 @@
+# Tappy — User Guide
+
+A practical, task-oriented guide to using Tappy: the CLI that discovers, configures,
+inspects, monitors, and standardizes **MCP (Model Context Protocol)** servers across your
+AI clients (Claude Desktop, Claude Code, Cursor, and more).
+
+If you just want the elevator pitch and install steps, see the [README](README.md). This
+document is the hands-on manual.
+
+---
+
+## Contents
+
+1. [Install](#install)
+2. [Core concepts](#core-concepts)
+3. [Quick start](#quick-start)
+4. [How you name a server (targeting)](#how-you-name-a-server-targeting)
+5. [Command reference](#command-reference)
+   - [Manage](#manage)
+   - [Monitor](#monitor)
+   - [Inspect](#inspect)
+   - [Secure](#secure)
+   - [Team](#team)
+6. [Common workflows](#common-workflows)
+7. [Scripting & CI (JSON + exit codes)](#scripting--ci-json--exit-codes)
+8. [Files, environment & configuration](#files-environment--configuration)
+9. [Safety guarantees](#safety-guarantees)
+10. [Troubleshooting](#troubleshooting)
+11. [Security notes](#security-notes)
+
+---
+
+## Install
+
+Requires Python 3.11+. The PyPI package is **`tappy-mcp`**; it installs the **`tappy`**
+command.
+
+```bash
+pip install tappy-mcp
+# or, isolated (recommended for CLI tools):
+pipx install tappy-mcp
+# or run without installing (the npx equivalent):
+uvx tappy-mcp status
+```
+
+Verify:
+
+```bash
+tappy --version
+tappy help          # grouped overview of every command
+```
+
+---
+
+## Core concepts
+
+| Term | What it means in Tappy |
+|------|------------------------|
+| **Client** | An AI app that runs MCP servers (Claude Desktop, Claude Code, Cursor). Each stores servers in its own JSON config file. |
+| **Server** | A single MCP server entry — either a local **stdio** process (`command` + `args`) or a remote **HTTP/SSE** endpoint (`url`). |
+| **Transport** | How Tappy talks to a server: `stdio`, `http` (streamable), or `sse`. |
+| **Health** | A server's *live* status, obtained by actually connecting and running the MCP handshake — never guessed from config. `running` / `error` / `disabled`. |
+| **Pin / fingerprint** | A recorded hash of a server's tool definitions. Lets Tappy detect when a server changes its tools *after* you trusted it (a "rug-pull"). |
+| **Registry** | A shared `tappy.team.json` listing the servers a team has approved, so everyone can converge on the same set. |
+
+Tappy reads every client's config into **one normalized view**, so the same commands work
+no matter which client a server lives in.
+
+---
+
+## Quick start
+
+```bash
+tappy list              # every server across every client
+tappy status            # ...with live health, latency, and tool counts
+tappy inspect <name>    # full report for one server: status + tools + resources + prompts
+```
+
+Every data command supports `--json` and returns exit code **0** on success / **1** on
+error, so it drops straight into scripts and CI.
+
+---
+
+## How you name a server (targeting)
+
+Most commands take a **target**. There are two ways to specify one:
+
+**1. By name** — a server already in some client's config:
+```bash
+tappy inspect github
+```
+
+**2. Ad-hoc** — a server that isn't installed anywhere yet, described inline:
+```bash
+tappy inspect --command npx --args "-y @modelcontextprotocol/server-everything"
+tappy inspect --url https://example.com/mcp
+```
+
+Narrowing helpers (for named targets):
+
+- `--client <id>` — restrict to one client (`claude_desktop`, `claude_code`, `cursor`, …).
+- `--path <substring>` — restrict to configs whose file path contains a string. Use this
+  when the **same** client has the server in two places (e.g. Claude Code's project
+  `./.mcp.json` vs. user `~/.claude.json`):
+  ```bash
+  tappy disable github --path .mcp.json      # the project one, not the user one
+  ```
+
+**Auto-pick:** the read-only inspector commands (`inspect`, `tools`, `resources`,
+`prompts`, `read`, `prompt`, `probe`, `pin`, `verify`, `call`) will use the sole configured
+server automatically if you don't name one. Destructive commands (`remove`, `disable`,
+`sync`) never auto-pick.
+
+---
+
+## Command reference
+
+Run `tappy <command> -h` for the exact flags of any command.
+
+### Manage
+
+```bash
+tappy list                       # all servers across every client  (alias: ls)
+tappy list --client cursor       # only one client
+tappy clients                    # the discovered config files themselves
+
+# add a stdio server (put the command after `--` so args like -y aren't seen as flags)
+tappy add fs -- npx -y @modelcontextprotocol/server-filesystem .
+
+# add a remote server
+tappy add api --url https://example.com/mcp
+tappy add api --url https://example.com/sse --transport sse --header "Authorization=Bearer XYZ"
+
+# preview a change as a diff without writing anything
+tappy add fs --dry-run -- npx -y @scope/server .
+
+tappy enable fs                  # / tappy disable fs
+tappy remove fs                  # (alias: rm)
+
+# roll a client's config back to its most recent backup
+tappy restore --list             # show available backups
+tappy restore claude_desktop     # restore the latest backup for that client
+```
+
+Notes:
+- `add` writes to the **first discovered client** if you don't pass `--client`; it prints
+  which one it chose.
+- Secret `env`/`header` values are **masked** in all output.
+- A config file that fails to parse is flagged as `parse error`, and Tappy **refuses to
+  write to it** until you fix the JSON by hand.
+
+### Monitor
+
+```bash
+tappy status                     # health snapshot of every server
+tappy status -a                  # include disabled servers
+tappy status --client cursor     # restrict to one client
+tappy status --fail-on-down      # exit non-zero if any enabled server is unreachable (CI)
+tappy status --json              # machine-readable
+
+tappy watch                      # live, auto-refreshing monitor (Ctrl-C to quit)
+tappy watch --interval 2         # refresh faster
+tappy watch --no-stream          # print one snapshot and exit
+
+tappy probe github               # one-line health + latency for a single server
+```
+
+`status`/`watch`/`probe` connect over the **real MCP protocol** — `STATUS` reflects an
+actual handshake, not just whether the config exists. `status` also prints a footer
+warning if any pinned server's tools have drifted.
+
+### Inspect
+
+```bash
+tappy inspect github             # status + tools + resources + prompts + pin status
+tappy tools github               # just the tools, with input schemas
+tappy tools github --json
+tappy resources github           # list resource URIs
+tappy prompts github             # list prompt names
+
+# exercise each of the three MCP primitives:
+tappy call github create_issue -a title="Bug" -a body="..."     # invoke a tool (key=value args)
+tappy call github create_issue --input '{"title":"Bug"}'        # ...or JSON args
+tappy read github "file:///etc/hosts"                            # read a resource's contents
+tappy prompt github review -a lang=python                       # render a prompt's messages
+```
+
+All of these work against installed servers **and** ad-hoc `--command`/`--url` targets.
+
+### Secure
+
+```bash
+tappy pin github                 # trust the current tools (record a fingerprint)
+tappy verify github              # re-check; exit 1 if the tools changed (CI gate)
+```
+
+The first time you `pin`, Tappy stores a hash of the server's tool definitions. `verify`
+compares against it later. A change means the server altered the tools it advertises after
+you trusted it — a potential rug-pull. `inspect` shows pin status inline; `status` warns
+about drift automatically.
+
+### Team
+
+```bash
+# create a shared registry, optionally seeded from a client you already have set up
+tappy registry --init --from-client claude_desktop
+tappy registry                                   # show the approved server set  (alias: team)
+
+tappy apply --dry-run                            # preview provisioning into local clients
+tappy apply                                      # write them (each change backed up)
+tappy apply --client cursor                      # only one client
+
+tappy lint                                       # report drift; exit 1 on unapproved servers (CI gate)
+
+tappy sync github --from claude_desktop --to cursor    # copy a server between clients
+```
+
+Seeding from a client **never writes real secrets** into the registry: `env`/`header`
+values are templated as `${KEY}` placeholders that each developer fills in locally after
+`apply`. Commit `tappy.team.json`; teammates run `tappy apply`.
+
+---
+
+## Common workflows
+
+**"Is everything I rely on actually working right now?"**
+```bash
+tappy status
+```
+
+**"A server is failing — what's wrong?"**
+```bash
+tappy probe <name>               # confirm it's down and see the error
+tappy inspect <name>             # more detail if it connects at all
+```
+
+**"I want to try a server before installing it anywhere."**
+```bash
+tappy inspect --command npx --args "-y @some/mcp-server"
+```
+
+**"Copy a working server from one client to another."**
+```bash
+tappy sync <name> --from claude_desktop --to cursor
+```
+
+**"Lock down a server so I get warned if it changes its tools."**
+```bash
+tappy pin <name>
+# later, or in CI:
+tappy verify <name>              # exits 1 if the tools changed
+```
+
+**"Undo a change I just made."**
+```bash
+tappy restore <client>           # rolls back to the latest backup
+```
+
+**"Standardize a team on the same servers."**
+```bash
+tappy registry --init --from-client claude_desktop   # once, by a maintainer
+git add tappy.team.json && git commit -m "Approved MCP servers"
+# each teammate:
+tappy apply
+```
+
+---
+
+## Scripting & CI (JSON + exit codes)
+
+Every data command accepts `--json` and emits pretty JSON to stdout. Secret values are
+always masked.
+
+**Exit codes:**
+
+| Code | Meaning |
+|------|---------|
+| `0` | success |
+| `1` | error — not found, unreachable, drift detected, or invalid input |
+| `2` | bad command-line usage (argparse) |
+| `130` | interrupted with Ctrl-C |
+
+**CI gate examples:**
+```bash
+tappy status --fail-on-down      # fail the build if any server is down
+tappy verify weather             # fail if a pinned server's tools changed
+tappy lint                       # fail if any client has an unapproved server
+```
+
+**Parse output with `jq`:**
+```bash
+tappy status --json | jq '.[] | select(.health != "running") | .name'
+```
+
+---
+
+## Files, environment & configuration
+
+**Files Tappy owns** (all under `~/.tappy/`):
+
+| Path | Purpose |
+|------|---------|
+| `~/.tappy/backups/` | Timestamped backups written before every config change. |
+| `~/.tappy/fingerprints.json` | Pinned tool fingerprints for rug-pull detection. |
+| `~/.tappy/tappy.team.json` | Default location for the team registry (user scope). |
+
+**Client config files Tappy reads/writes** (discovered automatically):
+
+- Claude Desktop — `~/Library/Application Support/Claude/claude_desktop_config.json`
+  (macOS), `%APPDATA%\Claude\…` (Windows), `~/.config/Claude/…` (Linux)
+- Claude Code — `./.mcp.json` (project) and `~/.claude.json` (user)
+- Cursor — `./.cursor/mcp.json` (project) and `~/.cursor/mcp.json` (user)
+
+**Environment variables:**
+
+| Variable | Effect |
+|----------|--------|
+| `TAPPY_CONFIG` | OS-path-separated list of extra config files (standard `mcpServers` shape) to manage — point Tappy at a client it doesn't know natively. |
+| `TAPPY_REGISTRY` | Path to the team registry, overriding the default lookup. |
+
+Registry path resolves from `--registry` → `$TAPPY_REGISTRY` → `./tappy.team.json` →
+`~/.tappy/tappy.team.json`.
+
+---
+
+## Safety guarantees
+
+When Tappy edits a config file, it guarantees:
+
+- **Non-destructive** — only the `mcpServers` section is touched; every other key in the
+  file is preserved exactly.
+- **Backup-first** — a timestamped copy is written to `~/.tappy/backups/` before any
+  change, so every edit is reversible with `tappy restore`.
+- **Atomic** — writes go to a temp file and are then atomically renamed into place, so a
+  crash can never leave a half-written config.
+- **Refuses broken files** — if a config can't be parsed, Tappy won't write to it (it would
+  otherwise clobber content it couldn't read).
+
+---
+
+## Troubleshooting
+
+**`error: unknown command: X`** — run `tappy help` for the command list. Note the
+monitoring commands are `status` and `watch` (not `ps`/`stats`).
+
+**A server shows `error` in `status`/`probe`.** Tappy actually tried to connect. Common
+causes: the `command` isn't on your `PATH`, a required runtime (`node`/`npx`/`uvx`) is
+missing, a file path in `args` is wrong, or a remote `url` is unreachable. Run
+`tappy probe <name>` to see the underlying error message.
+
+**`... could not be parsed (…); fix its JSON by hand first`.** The client's config file has
+invalid JSON. Fix the JSON, then retry. Tappy deliberately refuses to overwrite a file it
+couldn't read.
+
+**`server '<name>' exists in multiple configs`.** The name is defined in more than one
+config. Disambiguate with `--client` and/or `--path` (the error lists each location).
+
+**`no team registry found`.** Create one with `tappy registry --init`, or point at an
+existing one with `--registry` / `$TAPPY_REGISTRY`.
+
+**A remote server needs auth.** Pass headers when adding it:
+`tappy add api --url … --header "Authorization=Bearer <token>"`. Header values are masked
+in output.
+
+---
+
+## Security notes
+
+- **Secrets in output are masked.** `env` and `header` values show as `***` in tables and
+  `--json`. The real values remain only in the client config files themselves.
+- **The registry never carries real secrets.** Seeding writes `${KEY}` placeholders, not
+  your actual tokens — safe to commit to git.
+- **Rug-pull detection.** Pin the servers you trust (`tappy pin`), then `tappy verify` (or
+  watch the `status` drift footer) to catch a server that changes its advertised tools
+  after approval. Re-pin intentionally when a change is expected.
+
+---
+
+*For the project overview, architecture, and contribution notes, see the
+[README](README.md) and [CHANGELOG](CHANGELOG.md).*

tappy_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aadhil96
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.