Metadata-Version: 2.4
Name: pymcpx
Version: 0.1.0
Summary: MCP-compatible LangChain tools for AI agents — calculator, datetime, converter, and more.
Project-URL: Homepage, https://github.com/pymcpx/pymcpx
Project-URL: Repository, https://github.com/pymcpx/pymcpx
Project-URL: Issues, https://github.com/pymcpx/pymcpx/issues
Author: PyMCPX Contributors
License: MIT
Keywords: agents,ai,calculator,converter,datetime,langchain,mcp,tools
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0
Provides-Extra: all
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: langchain-core>=0.2; extra == 'all'
Provides-Extra: aviationstack
Requires-Dist: httpx>=0.27; extra == 'aviationstack'
Requires-Dist: langchain-core>=0.2; extra == 'aviationstack'
Provides-Extra: calculator
Requires-Dist: langchain-core>=0.2; extra == 'calculator'
Provides-Extra: converter
Requires-Dist: langchain-core>=0.2; extra == 'converter'
Provides-Extra: datetime
Requires-Dist: langchain-core>=0.2; extra == 'datetime'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: langchain-core>=0.2; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: pyupgrade>=3.15; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: exchangeratehost
Requires-Dist: httpx>=0.27; extra == 'exchangeratehost'
Requires-Dist: langchain-core>=0.2; extra == 'exchangeratehost'
Provides-Extra: fixer
Requires-Dist: httpx>=0.27; extra == 'fixer'
Requires-Dist: langchain-core>=0.2; extra == 'fixer'
Provides-Extra: ipstack
Requires-Dist: httpx>=0.27; extra == 'ipstack'
Requires-Dist: langchain-core>=0.2; extra == 'ipstack'
Provides-Extra: marketstack
Requires-Dist: httpx>=0.27; extra == 'marketstack'
Requires-Dist: langchain-core>=0.2; extra == 'marketstack'
Provides-Extra: numverify
Requires-Dist: httpx>=0.27; extra == 'numverify'
Requires-Dist: langchain-core>=0.2; extra == 'numverify'
Provides-Extra: screenshotlayer
Requires-Dist: httpx>=0.27; extra == 'screenshotlayer'
Requires-Dist: langchain-core>=0.2; extra == 'screenshotlayer'
Provides-Extra: weatherstack
Requires-Dist: httpx>=0.27; extra == 'weatherstack'
Requires-Dist: langchain-core>=0.2; extra == 'weatherstack'
Provides-Extra: zenserp
Requires-Dist: httpx>=0.27; extra == 'zenserp'
Requires-Dist: langchain-core>=0.2; extra == 'zenserp'
Description-Content-Type: text/markdown

# PyMCPX

> **MCP-compatible LangChain tools for AI agents — calculator, datetime, converter, and more.**

[![Python](https://img.shields.io/badge/Python-FFD43B?style=for-the-badge&logo=python&logoColor=blue)](https://pypi.org/project/pymcpx/)
[![License: MIT](https://img.shields.io/badge/MIT-red?style=for-the-badge)](LICENSE)
[![Pypi: Pymcpx](https://img.shields.io/badge/pypi-3775A9?style=for-the-badge&logo=pypi&logoColor=white)](PyPi)

---

## Features

- 🔌 **MCP-compatible** — every tool exposes a stable name and JSON schema consumable by any MCP host
- 🦜 **LangChain-native** — each tool extends `BaseTool` with typed `args_schema`
- 🧱 **Pydantic v2** — validated inputs and outputs
- 🧪 **Simulation engine** — run agent workflows offline without any API keys
- 📦 **Service extras** — install only what you need: `pip install pymcpx[calculator]`

---

## Installation

```bash
# Core package (no service dependencies)
pip install pymcpx

# Specific service
pip install pymcpx[calculator]
pip install pymcpx[datetime]
pip install pymcpx[converter]

# All services
pip install pymcpx[all]

# Development
pip install pymcpx[dev]
```

## Services

For full details on the tools, schemas, and offline simulation engines of each service, refer to their respective service-level `README.md` files:

| Service               | Status   | Install Extra              | Documentation                                        |
| --------------------- | -------- | -------------------------- | ---------------------------------------------------- |
| **Calculator**        | ✅ Ready | `pymcpx[calculator]`       | [README](pymcpx/services/calculator/README.md)       |
| **Converter**         | ✅ Ready | `pymcpx[converter]`        | [README](pymcpx/services/converter/README.md)        |
| **Datetime**          | ✅ Ready | `pymcpx[datetime]`         | [README](pymcpx/services/datetime/README.md)         |
| **IPstack**           | ✅ Ready | `pymcpx[ipstack]`          | [README](pymcpx/services/ipstack/README.md)          |
| **Marketstack**       | ✅ Ready | `pymcpx[marketstack]`      | [README](pymcpx/services/marketstack/README.md)      |
| **Weatherstack**      | ✅ Ready | `pymcpx[weatherstack]`     | [README](pymcpx/services/weatherstack/README.md)     |
| **Numverify**         | ✅ Ready | `pymcpx[numverify]`        | [README](pymcpx/services/numverify/README.md)        |
| **Fixer**             | ✅ Ready | `pymcpx[fixer]`            | [README](pymcpx/services/fixer/README.md)            |
| **Aviationstack**     | ✅ Ready | `pymcpx[aviationstack]`    | [README](pymcpx/services/aviationstack/README.md)    |
| **Zenserp**           | ✅ Ready | `pymcpx[zenserp]`          | [README](pymcpx/services/zenserp/README.md)          |
| **Screenshotlayer**   | ✅ Ready | `pymcpx[screenshotlayer]`  | [README](pymcpx/services/screenshotlayer/README.md)  |
| **ExchangeRate.host** | ✅ Ready | `pymcpx[exchangeratehost]` | [README](pymcpx/services/exchangeratehost/README.md) |

## Contributing

### Getting Started

```bash
git clone https://github.com/your-org/pymcpx.git
cd pymcpx
pip install -e ".[dev]"
```

### Workflow

1. Create a branch: `git checkout -b feat/my-feature`
2. Make changes following the coding conventions
3. Add / update tests
4. Run tests: `pytest`
5. Submit a Pull Request

### Adding a New Service

Create a new directory under `pymcpx/services/<name>/` following the layout of `pymcpx/services/ipstack/`:

- `SimulationEngine/models.py` — Pydantic input models
- `SimulationEngine/utils.py` — business logic, API clients
- `tools.py` — `BaseTool` subclasses + `MCP_TOOLS` list
- `SimulationEngine/engine.py` — offline simulation engine
- `tests/test_<name>.py` — unit tests with `respx` mocks
- `README.md` — service documentation including:
  - Prerequisites (API key setup)
  - Installation command
  - Tools table with names, classes, descriptions, and input keys
  - Usage examples (individual tools, toolkit, MCP integration)

Then add a re-export shim at `pymcpx/<name>.py`, register the optional dependency in `pyproject.toml`, and add the service row to the README Services table.

### Pull Request Requirements

- All tests pass
- No new ruff warnings
- New services include all required files (see above)

### Continuous Integration

CI (`.github/workflows/tests.yml`) runs automatically on every push and pull request across Python 3.11 and 3.12 with coverage reporting.

## Special Thanks

Special thanks to the [Public APIs](https://github.com/public-apis/public-apis) repository, a manually curated list of public APIs from many domains, which serves as a treasure trove of APIs and inspired our external service integrations.

## License

MIT © PyMCPX Contributors
