Metadata-Version: 2.4
Name: mcp-anvil
Version: 0.2.0
Summary: Local MCP daemon with a dashboard, REST/WebSocket API, and 64 built-in tools — plus scaffold, audit, and inspect for your own Model Context Protocol servers.
Project-URL: Homepage, https://aiinfradecoded.com/mcp-anvil
Project-URL: Documentation, https://aiinfradecoded.com/mcp-anvil/docs
Project-URL: Repository, https://github.com/aiinfradecoded/mcp-anvil
Project-URL: Issues, https://github.com/aiinfradecoded/mcp-anvil/issues
Author-email: AI Infra Decoded <hello@aiinfradecoded.com>
License: Commercial — see LICENSE.md
Keywords: ai-agents,llm,mcp,model-context-protocol,scaffolding,security-audit
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: anyio>=4.4
Requires-Dist: cryptography>=42.0
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: mcp>=1.0
Requires-Dist: pillow>=10.0
Requires-Dist: pydantic>=2.7
Requires-Dist: pystray>=0.19
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn>=0.30
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# MCP Anvil
<!-- mcp-name: com.aiinfradecoded/mcp-anvil -->
> A local MCP toolbox. One daemon hosts every Model Context Protocol
> server at a single address, a browser dashboard makes them
> point-and-click, 64 tools ship ready to call, and one config entry
> exposes the whole thing to Claude. CLI for scripts, dashboard for
> exploration.

[![PyPI version](https://img.shields.io/pypi/v/mcp-anvil.svg)](https://pypi.org/project/mcp-anvil/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-anvil.svg)](https://pypi.org/project/mcp-anvil/)
[![Site](https://img.shields.io/badge/site-aiinfradecoded.com%2Fmcp--anvil-22d3ee)](https://aiinfradecoded.com/mcp-anvil)

```bash
pipx install mcp-anvil
mcp-anvil license activate "<your-key>"   # the blob from your purchase email
mcp-anvil setup                           # starts the daemon, opens the dashboard
```

That is the whole post-purchase path. The rest of this README explains
what you just installed and how to wire it into your LLM client.

---

## Requirements

- **Python 3.11+.** 3.11 and 3.12 are the most thoroughly tested; if you
  have several Python versions installed, prefer one of those. `pipx`
  picks an interpreter for you and keeps the install isolated.
- **No other system dependencies.** Docker, Node, etc. are requirements
  of the servers you *manage* with Anvil, not of Anvil itself.
- **Works offline.** No telemetry. License verification is local (see
  [Licensing](#licensing)).
- **Cross-platform.** Windows, macOS, and Linux. On Windows the CLI
  forces UTF-8 output so Rich renders correctly on the default console.

---

## What you get — the architecture

Five surfaces, one install. They all share one daemon and one tool
catalog.

```
                       mcp-anvil daemon  (127.0.0.1:7820)
                       ┌───────────────────────────────────┐
                       │  - hosts every MCP server you add   │
   browser  ──────────▶│  - serves the dashboard (8 tabs)    │
   (dashboard)         │  - 64 built-in tools                │
                       │  - REST + WebSocket API             │
   your shell ────────▶│                                     │
   (mcp-anvil CLI)     └───────────────┬─────────────────────┘
                                       │
   Claude Desktop / Code ──────────────┘
   (one config entry  ──▶  mcp-anvil router  ──▶  daemon)
```

| Surface | What it is |
|---|---|
| **Daemon** | A long-lived local process on `127.0.0.1:7820` that hosts every MCP server you register and exposes them over one HTTP/WebSocket API. Start it with `mcp-anvil daemon start`. |
| **Dashboard** | A browser UI served *by* the daemon at `http://127.0.0.1:7820`. Eight tabs: Servers, Tools, Templates, Saved Calls, Prompts, History, Events, Help. |
| **64 built-in tools** | A ready-to-call toolkit (six categories, below) the daemon serves out of the box. |
| **CLI** | The `mcp-anvil` binary. Everything the dashboard does, scriptable from any shell. |
| **Router** | `mcp-anvil router` — an MCP proxy that exposes every daemon-managed tool to Claude Desktop, Claude Code, or any HTTP-MCP client through a single entry. |

---

## After you purchase: up and running in five minutes

### 1. Install

```bash
pipx install mcp-anvil      # recommended — isolated install
# or
pip install mcp-anvil       # works fine inside a venv
```

### 2. Activate your license

After checkout you receive a base32-encoded license blob by email.

```bash
mcp-anvil license activate "AB3CD4EF..."   # paste your key
mcp-anvil license status                    # confirm it took
```

The license is stored at `~/.mcp-anvil/license.json` and verified
locally — no network call.

### 3. Run the setup wizard

```bash
mcp-anvil setup
```

The interactive wizard walks you through the whole first run:

1. Shows your version + daemon/license status.
2. Starts the daemon (default: yes).
3. Activates a license key if you have not already (optional — the trial
   works without one).
4. Opens the dashboard in your browser (default: yes).
5. Prints your next steps.

### 4. Open the dashboard

If you skipped step 4 of the wizard, the daemon serves the dashboard at:

```
http://127.0.0.1:7820
```

Click a tool, fill the auto-generated form, and watch the response stream
back in the History tab.

### 5. Connect Claude (or any MCP client)

See [Connecting to Claude](#connecting-to-claude-and-other-clients) below.
One config entry exposes all 64 tools (plus anything else you have
registered) inside the LLM.

---

## The 64-tool catalog

Every tool is one async function with a JSON schema. Call any of them
from Claude, the dashboard, the CLI (`mcp-anvil tool run <name>`), or
curl against the daemon API.

| Category | Count | What it covers |
|---|---:|---|
| **Read + run, anywhere on disk** | 7 | Read files, glob/grep a tree, run a shell command, hit an HTTP endpoint, check git status, run pytest. |
| **Pull text + data out of any file** | 12 | Extract text from PDFs and Excel; parse CSV / JSON / YAML / TOML / INI / Markdown; sniff a file's real type; read image dimensions. |
| **Answer "is this URL alive?"** | 11 | DNS lookups, TCP port checks, SSL cert inspection, HTTP latency, security-header audits, page scraping. |
| **Inspect the machine the daemon runs on** | 9 | CPU / memory / disk, process list, env-var read with auto-masked secrets, cross-platform shell. |
| **Encode, hash, audit, generate** | 13 | Base64 / URL round-trips, SHA-256 + HMAC, JWT decode, secret scanning, secure UUIDs and random strings. |
| **Survey a codebase fast** | 12 | Detect language, count lines per language, find TODO/FIXME, browse git log/diff/branches, validate JSON Schema, diff files. |

Need something the toolkit does not cover? In the dashboard's **Tools**
tab, **+ New tool** scaffolds a Python function that becomes a live MCP
tool immediately — no build step, no restart. Custom tools live at
`~/.mcp-anvil/tools/custom/`.

---

## Connecting to Claude and other clients

The **router** is a thin proxy in front of the daemon. Register it once;
every tool the daemon manages becomes visible to the client, and new
tools show up without a restart.

### Claude Desktop / Claude Code (stdio)

Add this to your Claude Desktop config
(`~/.config/claude/claude_desktop_config.json` on Linux;
`%APPDATA%\Claude\claude_desktop_config.json` on Windows;
`~/Library/Application Support/Claude/claude_desktop_config.json` on
macOS):

```json
{
  "mcpServers": {
    "anvil": {
      "command": "mcp-anvil",
      "args": ["router"]
    }
  }
}
```

Restart Claude Desktop. It will see every tool the daemon manages.

### HTTP-MCP clients (streamable HTTP)

```bash
mcp-anvil router --transport streamable-http --port 7830
# serves MCP at http://127.0.0.1:7830/mcp
```

Point your HTTP-MCP client at that URL.

### Import the servers you already have

The dashboard's **Servers** tab reads your existing client configs and
lists every MCP server it finds, so you can register them under Anvil
with one click:

```
Claude Desktop  ->  claude_desktop_config.json
Claude Code     ->  ~/.claude.json + ./.claude/mcp.json
Cursor          ->  ~/.cursor/mcp.json
Project-local   ->  ./.mcp.json
```

(stdio servers import end-to-end; HTTP/SSE servers are detected but not
yet hostable.)

---

## Command reference

```bash
mcp-anvil                 # branded banner + daemon/license status
mcp-anvil --help          # full command tree
mcp-anvil --version       # print version and exit
```

| Command | Purpose |
|---|---|
| `setup` | Interactive first-run wizard (start daemon, activate license, open dashboard). |
| `quickstart` | Print the short command tour. |
| `new <name>` | Scaffold a complete, audit-clean MCP server project. **Free.** |
| `audit <path>` | 21-rule security + health audit of an MCP server. |
| `inspect <path>` | Live single-server playground UI at `http://127.0.0.1:7800`. |
| `daemon start\|stop\|status` | Control the local daemon. |
| `server ...` | Add / list / start / stop / call MCP servers under the daemon. |
| `tool list\|show\|run` | Use the built-in tool catalog from the shell. |
| `template ...` | Save and replay tool-call presets. |
| `prompt ...` | Manage saved prompt files. |
| `router` | MCP proxy for Claude Desktop / Code / HTTP clients. |
| `mcp-server` | Serve the built-in catalog over stdio with no daemon (used by Agent Forge's fallback path). |
| `bundle` / `keys` | Sign, verify, and export portable server bundles; manage trusted signing keys. |
| `tray` | System-tray indicator for the daemon. |
| `client` | OAuth client management for third-party apps driving the daemon. |
| `docs export` | Export the daemon's API reference (markdown / OpenAPI / TypeScript). |
| `license activate\|status` | Manage your license. |
| `reset` | Wipe local state and return to factory defaults. |

`daemon status` exits non-zero when the daemon is *not* running — that is
the intended health-check behavior, not an error.

---

## The audit, grounded in research

`mcp-anvil audit` runs 21 rules — 12 static checks + 9 runtime probes —
each mapped to a published finding:

- [arXiv 2506.13538](https://arxiv.org/abs/2506.13538) — empirical study
  of 1,899 MCP servers (auth gaps, session-in-URL leaks).
- [arXiv 2603.05637](https://arxiv.org/abs/2603.05637) — MCP fault
  taxonomy; two-thirds of OS-dependent faults are Windows-specific.
- [AgentDojo](https://arxiv.org/abs/2406.13352) — adversarial injection
  probes, ported into the opt-in fuzz phase (`--enable-fuzz`).

```bash
mcp-anvil audit ./my-server                    # full audit
mcp-anvil audit ./my-server --html report.html # shareable report
mcp-anvil audit ./my-server --strict           # fail CI on any warning
```

---

## Licensing

MCP Anvil is a commercial product.

- **`mcp-anvil new` is free forever** — scaffold as many servers as you
  like without a license.
- A **14-day full-feature trial** starts automatically the first time you
  run a paid command. No signup.
- **Activate your license** (`mcp-anvil license activate "<key>"`) to keep
  the full toolkit, daemon, dashboard, and router after the trial.

The license is an Ed25519-signed JSON blob, verified locally against an
embedded public key — no phoning home on the happy path.

| Tier | Price | What you get |
|---|---|---|
| **Free** | $0 | `new` + the 14-day trial |
| **Personal** | $29 one-time | Everything. 1 developer, 1 year of updates |
| **Team** | $99 one-time | Everything. 5 developer seats, 1 year of updates |

[Buy a license ->](https://aiinfradecoded.com/mcp-anvil)

---

## Where your data lives

Everything Anvil writes is under `~/.mcp-anvil/`:

| Path | Contents |
|---|---|
| `config.json` | Daemon host/port, daemon name, preferences. |
| `license.json` | Your activated license envelope. |
| `state.json` | Trial start timestamp. |
| `credentials.json` | OAuth client id/secret pairs (mode 0600). |
| `servers/` | Registered MCP server configs. |
| `tools/builtin/`, `tools/custom/`, `tools/templates/` | Built-in catalog, your custom tools, template bundles. |
| `prompts/` | Saved prompt files. |
| `logs/daemon.log` | Daemon output. |
| `daemon.pid` | Present while the daemon is running. |
| `trusted_keys/` | Ed25519 public keys for verifying signed bundles. |

`mcp-anvil reset` clears this (with a prompt before touching your
license).

---

## Troubleshooting

- **`tool list` says the daemon is not running.** Start it:
  `mcp-anvil daemon start`. The built-in tools are served by the daemon.
- **Port 7820 already in use.** Set a different port in
  `~/.mcp-anvil/config.json`, then `mcp-anvil daemon stop && mcp-anvil
  daemon start`.
- **`daemon status` returns a non-zero exit code.** Expected when the
  daemon is stopped — it is a health check, not a crash.
- **Multiple Python versions.** If `pip install` resolves a version that
  lacks wheels for a dependency, install under Python 3.11 or 3.12 (the
  tested versions), e.g. `pipx install --python 3.12 mcp-anvil`.
- **Daemon will not start — check the log.** `~/.mcp-anvil/logs/daemon.log`
  has the stack trace.

---

## Support

- Site: <https://aiinfradecoded.com/mcp-anvil>
- Issues: <https://github.com/aiinfradecoded/mcp-anvil/issues>
- Email: <hello@aiinfradecoded.com>

Built by [AI Infra Decoded](https://aiinfradecoded.com). Commercial
license — see [LICENSE.md](./LICENSE.md).
