# 🛠️ QuantaLogic MCP Toolbox
> A generic adapter for interacting with one or more MCP servers via JSON-based configuration, with automatic tool discovery, caching, and session management.
---
[](https://pypi.org/project/quantalogic-toolbox-mcp)
[](LICENSE)
---
## 📋 Table of Contents
1. [Installation](#installation)
2. [Configuration](#configuration)
3. [Quickstart Example](#quickstart-example)
4. [Architecture](#architecture)
5. [API Reference](#api-reference)
6. [Contributing](#contributing)
7. [License](#license)
---
## 🚀 Installation
Install from PyPI:
```bash
pip install quantalogic-toolbox-mcp
```
Or with Poetry:
```bash
poetry add quantalogic-toolbox-mcp
```
---
## ⚙️ Configuration
By default, the toolbox reads JSON files from `./mcp_config/` or the directory set by `MCP_CONFIG_DIR`. You can also specify a single file via the `MCP_CONFIG_FILE` environment variable.
Create a config file (`mcp.json`) in `mcp_config/` with the following structure:
```json
{
"mcpServers": {
"sqlite": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v",
"mcp-test:/mcp",
"mcp/sqlite",
"--db-path",
"/mcp/test.db"
]
},
"mcp_hn": {
"command": "uvx",
"args": ["mcp-hn"]
},
"fetcher": {
"command": "npx",
"args": ["-y", "fetcher-mcp"]
},
"job_search": {
"command": "npx",
"args": ["-y", "job-searchoor"]
},
"edgeone": {
"command": "npx",
"args": ["edgeone-pages-mcp"]
}
}
}
```
- **command**: Executable or Docker alias
- **args**: Argument list to launch the server
Environment variables in `env` entries can use `{{ env.VAR_NAME }}` and will be resolved at runtime.
---
## 🏃 Quickstart Example
```python
from quantalogic_toolbox_mcp.tools import get_tools
import asyncio
async def main():
# Discover core and dynamic tools
tools = get_tools()
# List configured servers
from quantalogic_toolbox_mcp.tools import list_servers
servers = await list_servers()
print("Servers:", servers)
# List tools on a server
resources = await tools[0]('sqlite') # mcp_list_tools
print("Tools on sqlite:", resources)
# Call a specific tool dynamically
dynamic = [t for t in tools if hasattr(t, 'server_name') and t.server_name == 'sqlite'][0]
result = await dynamic(input_file="/mcp/test.db")
print("Result:", result)
asyncio.run(main())
```
---
## 🏛️ Architecture
```mermaid
%%{init: { 'theme': 'base', 'themeVariables': {
'primaryColor': '#A3C9E2',
'secondaryColor': '#B7E3CC',
'tertiaryColor': '#F9E0BB',
'lineColor': '#B5B5B5',
'fontFamily': 'Inter, Arial, sans-serif'
} }}%%
flowchart TD
A[Load JSON configs] --> B{Cache valid?}
B -- Yes --> C[Load servers & tools from cache]
B -- No --> D[Read & resolve configs]
D --> E[Fetch tool lists & details]
C & E --> F[Populate `tools_cache`]
F --> G["get_tools()"]
G --> H[Execute core or dynamic tools]
H --> I[Parse & return results]
```
---
## 📖 API Reference
- **get_tools()** → `List[Callable]`
- Returns core functions and dynamic tool wrappers.
- **mcp_list_resources(server_name: str)** → `List[str]`
- **mcp_list_tools(server_name: str)** → `List[str]`
- **mcp_call_tool(server_name: str, tool_name: str, arguments: dict)** → `Any`
- **list_servers()** → `List[str]`
For full signatures and details, refer to `toolboxes/quantalogic-toolbox-mcp/quantalogic_toolbox_mcp/tools.py`.
---
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests in `tests/`
4. Run `pytest` and `ruff .`
5. Submit a pull request against `main`
Please see `CONTRIBUTING.md` for more details.
---
## 📜 License
This project is licensed under the MIT License – see the [LICENSE](../../LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/quantalogic/toolboxes/tree/main/quantalogic-toolbox-mcp",
"name": "quantalogic_toolbox_mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "MCP, Quantalogic, toolbox, client",
"author": "Raphael Mansuy",
"author_email": "raphael.mansuy@quantalogic.com",
"download_url": "https://files.pythonhosted.org/packages/85/ca/b840e86b2d9f9e218a4722d5dc112fa8a3e0ba2baa6cb1e75331a291dfb3/quantalogic_toolbox_mcp-0.13.0.tar.gz",
"platform": null,
"description": "# \ud83d\udee0\ufe0f QuantaLogic MCP Toolbox\n\n> A generic adapter for interacting with one or more MCP servers via JSON-based configuration, with automatic tool discovery, caching, and session management.\n\n---\n\n[](https://pypi.org/project/quantalogic-toolbox-mcp)\n[](LICENSE)\n\n---\n\n## \ud83d\udccb Table of Contents\n\n1. [Installation](#installation)\n2. [Configuration](#configuration)\n3. [Quickstart Example](#quickstart-example)\n4. [Architecture](#architecture)\n5. [API Reference](#api-reference)\n6. [Contributing](#contributing)\n7. [License](#license)\n\n---\n\n## \ud83d\ude80 Installation\n\nInstall from PyPI:\n\n```bash\npip install quantalogic-toolbox-mcp\n```\n\nOr with Poetry:\n\n```bash\npoetry add quantalogic-toolbox-mcp\n```\n\n---\n\n## \u2699\ufe0f Configuration\n\nBy default, the toolbox reads JSON files from `./mcp_config/` or the directory set by `MCP_CONFIG_DIR`. You can also specify a single file via the `MCP_CONFIG_FILE` environment variable.\n\nCreate a config file (`mcp.json`) in `mcp_config/` with the following structure:\n\n```json\n{\n \"mcpServers\": {\n \"sqlite\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-v\",\n \"mcp-test:/mcp\",\n \"mcp/sqlite\",\n \"--db-path\",\n \"/mcp/test.db\"\n ]\n },\n \"mcp_hn\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-hn\"]\n },\n \"fetcher\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"fetcher-mcp\"]\n },\n \"job_search\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"job-searchoor\"]\n },\n \"edgeone\": {\n \"command\": \"npx\",\n \"args\": [\"edgeone-pages-mcp\"]\n }\n }\n}\n```\n\n- **command**: Executable or Docker alias\n- **args**: Argument list to launch the server\n\nEnvironment variables in `env` entries can use `{{ env.VAR_NAME }}` and will be resolved at runtime.\n\n---\n\n## \ud83c\udfc3 Quickstart Example\n\n```python\nfrom quantalogic_toolbox_mcp.tools import get_tools\nimport asyncio\n\nasync def main():\n # Discover core and dynamic tools\n tools = get_tools()\n\n # List configured servers\n from quantalogic_toolbox_mcp.tools import list_servers\n servers = await list_servers()\n print(\"Servers:\", servers)\n\n # List tools on a server\n resources = await tools[0]('sqlite') # mcp_list_tools\n print(\"Tools on sqlite:\", resources)\n\n # Call a specific tool dynamically\n dynamic = [t for t in tools if hasattr(t, 'server_name') and t.server_name == 'sqlite'][0]\n result = await dynamic(input_file=\"/mcp/test.db\")\n print(\"Result:\", result)\n\nasyncio.run(main())\n```\n\n---\n\n## \ud83c\udfdb\ufe0f Architecture\n```mermaid\n%%{init: { 'theme': 'base', 'themeVariables': { \n 'primaryColor': '#A3C9E2', \n 'secondaryColor': '#B7E3CC', \n 'tertiaryColor': '#F9E0BB', \n 'lineColor': '#B5B5B5', \n 'fontFamily': 'Inter, Arial, sans-serif'\n} }}%%\nflowchart TD\n A[Load JSON configs] --> B{Cache valid?}\n B -- Yes --> C[Load servers & tools from cache]\n B -- No --> D[Read & resolve configs]\n D --> E[Fetch tool lists & details]\n C & E --> F[Populate `tools_cache`]\n F --> G[\"get_tools()\"]\n G --> H[Execute core or dynamic tools]\n H --> I[Parse & return results]\n```\n\n---\n\n## \ud83d\udcd6 API Reference\n\n- **get_tools()** \u2192 `List[Callable]`\n - Returns core functions and dynamic tool wrappers.\n\n- **mcp_list_resources(server_name: str)** \u2192 `List[str]`\n- **mcp_list_tools(server_name: str)** \u2192 `List[str]`\n- **mcp_call_tool(server_name: str, tool_name: str, arguments: dict)** \u2192 `Any`\n- **list_servers()** \u2192 `List[str]`\n\nFor full signatures and details, refer to `toolboxes/quantalogic-toolbox-mcp/quantalogic_toolbox_mcp/tools.py`.\n\n---\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests in `tests/`\n4. Run `pytest` and `ruff .`\n5. Submit a pull request against `main`\n\nPlease see `CONTRIBUTING.md` for more details.\n\n---\n\n## \ud83d\udcdc License\n\nThis project is licensed under the MIT License \u2013 see the [LICENSE](../../LICENSE) file for details.",
"bugtrack_url": null,
"license": "MIT",
"summary": "A custom MCP Client for Quantalogic",
"version": "0.13.0",
"project_urls": {
"Documentation": "https://github.com/quantalogic/toolboxes/tree/main/quantalogic-toolbox-mcp#readme",
"Homepage": "https://github.com/quantalogic/toolboxes/tree/main/quantalogic-toolbox-mcp",
"Repository": "https://github.com/quantalogic/toolboxes/tree/main/quantalogic-toolbox-mcp"
},
"split_keywords": [
"mcp",
" quantalogic",
" toolbox",
" client"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8a800fa61a5b5c195671e7a865708d49b6699803da27e08fbc20a34550a05730",
"md5": "ddcaa37a6a9766a39db89818305e5cad",
"sha256": "b7a7634c8164b5d080ee6ec7930afa986ae73d0ace1dc16caffa87b178296eea"
},
"downloads": -1,
"filename": "quantalogic_toolbox_mcp-0.13.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ddcaa37a6a9766a39db89818305e5cad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 14705,
"upload_time": "2025-04-19T07:30:16",
"upload_time_iso_8601": "2025-04-19T07:30:16.814117Z",
"url": "https://files.pythonhosted.org/packages/8a/80/0fa61a5b5c195671e7a865708d49b6699803da27e08fbc20a34550a05730/quantalogic_toolbox_mcp-0.13.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "85cab840e86b2d9f9e218a4722d5dc112fa8a3e0ba2baa6cb1e75331a291dfb3",
"md5": "5fb1af849a70c30139ecf8170bd69c0a",
"sha256": "568a142b3039c999ff5bb70780a6a26050b5a31647d1aee7696b7d5f7db37a4e"
},
"downloads": -1,
"filename": "quantalogic_toolbox_mcp-0.13.0.tar.gz",
"has_sig": false,
"md5_digest": "5fb1af849a70c30139ecf8170bd69c0a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 14703,
"upload_time": "2025-04-19T07:30:18",
"upload_time_iso_8601": "2025-04-19T07:30:18.283448Z",
"url": "https://files.pythonhosted.org/packages/85/ca/b840e86b2d9f9e218a4722d5dc112fa8a3e0ba2baa6cb1e75331a291dfb3/quantalogic_toolbox_mcp-0.13.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-04-19 07:30:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "quantalogic",
"github_project": "toolboxes",
"github_not_found": true,
"lcname": "quantalogic_toolbox_mcp"
}
JSON
