Metadata-Version: 2.4
Name: mcp-tools-bundle
Version: 1.3.0
Summary: 3 zero-dependency MCP servers in pure Python — CDP scraper, crypto monitor, email sender
Author: AMEOBIUS-team
License: MIT
Project-URL: Homepage, https://github.com/AMEOBIUS-team/mcp-tools-bundle
Project-URL: Repository, https://github.com/AMEOBIUS-team/mcp-tools-bundle
Project-URL: Issues, https://github.com/AMEOBIUS-team/mcp-tools-bundle/issues
Keywords: mcp,ai,agent,tools,cdp,crypto,email,zero-dependency
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# MCP Tools Bundle — 3 Zero-Dependency MCP Servers in Pure Python

[![Tests](https://img.shields.io/badge/tests-105%20passing-brightgreen)](https://github.com/AMEOBIUS-team/mcp-tools-bundle)
[![PyPI](https://img.shields.io/pypi/v/mcp-tools-bundle)](https://pypi.org/project/mcp-tools-bundle/)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue)](https://python.org)
[![Dependencies](https://img.shields.io/badge/dependencies-zero-success)](https://github.com/AMEOBIUS-team/mcp-tools-bundle)
[![MCP](https://img.shields.io/badge/MCP-compatible-orange)](https://modelcontextprotocol.io)

> Three production-ready MCP (Model Context Protocol) servers for AI agents. Zero pip dependencies. Pure Python standard library. 105 tests passing.

## Contents

- [Servers](#servers)
- [Requirements](#requirements)
- [Why Zero Dependencies?](#why-zero-dependencies)
- [Installation](#installation)
- [Running a Server](#running-a-server)
- [Client Integration](#client-integration)
  - [Claude Desktop](#claude-desktop-all-3-servers)
  - [Hermes Agent](#hermes-agent)
- [Server Reference](#server-reference)
  - [mcp-cdp-scraper](#mcp-cdp-scraper--web-scraping-via-chrome-devtools-protocol)
  - [mcp-crypto-monitor](#mcp-crypto-monitor--crypto-wallet--price-monitoring)
  - [mcp-email-sender](#mcp-email-sender--email-validation--smtp)
- [Architecture](#architecture)
- [Testing](#testing)
- [License](#license)

## Servers

| Server | Tools | Tests | Repo |
|--------|-------|-------|------|
| **mcp-cdp-scraper** | 12 | 38 | [AMEOBIUS-team/mcp-cdp-scraper](https://github.com/AMEOBIUS-team/mcp-tools-bundle/tree/main/mcp_tools_bundle) |
| **mcp-crypto-monitor** | 10 | 30 | [AMEOBIUS-team/mcp-crypto-monitor](https://github.com/AMEOBIUS-team/mcp-tools-bundle/tree/main/mcp_tools_bundle) |
| **mcp-email-sender** | 8 | 37 | [AMEOBIUS-team/mcp-email-sender](https://github.com/AMEOBIUS-team/mcp-tools-bundle/tree/main/mcp_tools_bundle) |
| **Total** | **30** | **105** | |

## Requirements

- **Python 3.8+** (3.10+ recommended; the servers are tested against 3.12).
- **An internet connection** for the crypto and scraper servers (they call public APIs / a Chrome instance).
- **No pip packages.** Every server runs on the standard library alone. `pytest` is only needed if you want to run the test suites.

## Why Zero Dependencies?

Every MCP server here uses **only Python's standard library** — no pip installs, no npm, no Playwright, no Selenium, no `requests`. Just Python and an internet connection.

This means:
- **Docker images stay tiny** (~50MB vs 250MB+ with Playwright)
- **No supply chain risk** — no third-party packages to audit
- **Fast CI** — no dependency resolution, no cache invalidation
- **Portable** — works in any Python environment without venv setup

## Installation

Because there are no dependencies, "installing" is just cloning the source and running it.

### Option A — Install script (all 3 servers)

```bash
# Clones all three servers into ~/mcp-servers (override with a path argument)
pip install mcp-tools-bundle

# ...or clone this repo first and run it locally:
git clone https://github.com/AMEOBIUS-team/mcp-tools-bundle.git
cd mcp-tools-bundle
./install.sh                 # installs to ~/mcp-servers
./install.sh /opt/mcp        # or a directory of your choice
```

### Option B — Clone individually

```bash
git clone https://github.com/AMEOBIUS-team/mcp-tools-bundle/tree/main/mcp_tools_bundle.git
git clone https://github.com/AMEOBIUS-team/mcp-tools-bundle/tree/main/mcp_tools_bundle.git
git clone https://github.com/AMEOBIUS-team/mcp-tools-bundle/tree/main/mcp_tools_bundle.git
```

### Verify the install

```bash
cd mcp-cdp-scraper
python -m src.server --manifest    # prints the JSON tool manifest
```

If you see a JSON manifest listing the server's tools, you're ready to go.

## Running a Server

Each server is launched the same way from its own directory:

```bash
cd <server-dir>

# Print the tool manifest (name, description, JSON schema for each tool) and exit
python -m src.server --manifest

# Run as a long-lived MCP server over STDIO (JSON-RPC on stdin/stdout).
# This is the mode MCP clients such as Claude Desktop and Hermes use.
python -m src.server --stdio
```

> **Note:** run the command from the server's root directory so that `python -m src.server` resolves the `src` package. In client configs this is handled by setting `cwd`.

## Client Integration

### Claude Desktop (all 3 servers)

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cdp-scraper": {
      "command": "python",
      "args": ["-m", "src.server", "--stdio"],
      "cwd": "."
    },
    "crypto-monitor": {
      "command": "python",
      "args": ["-m", "src.server", "--stdio"],
      "cwd": "."
    },
    "email-sender": {
      "command": "python",
      "args": ["-m", "src.server", "--stdio"],
      "cwd": ".",
      "env": {
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "587",
        "SMTP_USERNAME": "your@gmail.com",
        "SMTP_PASSWORD": "your-app-password",
        "SMTP_TLS": "true"
      }
    }
  }
}
```

### Hermes Agent

```yaml
mcp:
  servers:
    cdp-scraper:
      command: python
      args: ["-m", "src.server", "--stdio"]
      cwd: .

    crypto-monitor:
      command: python
      args: ["-m", "src.server", "--stdio"]
      cwd: .

    email-sender:
      command: python
      args: ["-m", "src.server", "--stdio"]
      cwd: .
```

## Server Reference

### mcp-cdp-scraper — Web Scraping via Chrome DevTools Protocol

**12 tools:** `scrape_page`, `extract_text`, `extract_links`, `extract_images`, `extract_table`, `fill_form`, `click_element`, `screenshot`, `get_html`, `wait_for`, `scroll_to`, `list_tabs`

Connects to any Chrome/Chromium instance via raw WebSocket CDP. React/Vue compatible form filling using native setters + synthetic events. No Playwright, no Selenium.

```python
from src.server import MCPCDPScraperServer

server = MCPCDPScraperServer()
result = server.handle_tool_call("scrape_page", {"url": "https://news.ycombinator.com"})
print(result)
```

### mcp-crypto-monitor — Crypto Wallet & Price Monitoring

**10 tools:** `get_btc_balance`, `get_eth_balance`, `get_erc20_balance`, `get_btc_transactions`, `get_price`, `get_price_binance`, `get_portfolio_value`, `get_gas_price`, `get_fear_greed`, `monitor_address`

Uses free public APIs only — Blockchain.info, Etherscan, CoinGecko, Binance, alternative.me. No API keys required.

```python
from src.server import MCPCryptoMonitorServer

server = MCPCryptoMonitorServer()

# Current price of a single asset
price = server.handle_tool_call("get_price", {"symbol": "BTC"})

# Total value of a portfolio
value = server.handle_tool_call("get_portfolio_value", {"holdings": {"BTC": 0.5, "ETH": 10.0}})
print(price, value)
```

### mcp-email-sender — Email Validation & SMTP

**8 tools:** `validate_email`, `validate_email_batch`, `check_mx_records`, `is_disposable`, `is_role_based`, `send_email`, `send_email_batch`, `test_smtp_connection`

Email validation (format, disposable, role-based, MX records) + SMTP sending (TLS/SSL, CC/BCC, batch). Pure stdlib (`smtplib`, `email`, `re`, `socket`).

```python
from src.server import MCPEmailServer

server = MCPEmailServer()

# Validate an address (format + MX + disposable/role checks)
result = server.handle_tool_call("validate_email", {"email": "user@gmail.com"})
print(result)
```

SMTP sending is configured via environment variables (`SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD`, `SMTP_TLS`) — see the [Claude Desktop config](#claude-desktop-all-3-servers) above.

## Architecture

Each server follows the same pattern:

```
MCP Client (Claude / Hermes / any)
    │  JSON-RPC over STDIO
    ▼
MCPServer (src/server.py)
    │  Tool dispatch + schema
    ▼
Engine (src/<engine>.py)
    │  Zero-dep business logic
    ▼
External API / Chrome / SMTP
```

## Testing

Each server ships with its own test suite (`pytest` is the only extra you need):

```bash
pip install pytest

cd mcp-cdp-scraper    && python -m pytest tests/ -q   # 38 passed
cd mcp-crypto-monitor && python -m pytest tests/ -q   # 30 passed
cd mcp-email-sender   && python -m pytest tests/ -q   # 37 passed
# Total: 105 tests, all passing
```

### Verify the whole bundle at once

`scripts/verify_bundle.sh` clones all three server repos, confirms each MCP
manifest loads, and runs every test suite — the same integration check that
runs in CI ([`.github/workflows/integration.yml`](.github/workflows/integration.yml)):

```bash
pip install pytest
./scripts/verify_bundle.sh            # uses a temp dir, cleaned up afterwards
./scripts/verify_bundle.sh ./servers  # or keep the clones in ./servers
```

If the server repos are private, set `GIT_TOKEN` to a token with read access
(`GIT_TOKEN=ghp_... ./scripts/verify_bundle.sh`). In CI this comes from an
optional `BUNDLE_TOKEN` secret, falling back to the Actions token.

## License

MIT — all three servers. See [LICENSE](LICENSE).

## Author

AMEOBIUS-team — [github.com/AMEOBIUS-team](https://github.com/AMEOBIUS-team)

BTC/USDT/ETH/XMR accepted via [@darkbot_ai_bot](https://t.me/darkbot_ai_bot)
