quantalogic_toolbox_mcp


Namequantalogic_toolbox_mcp JSON
Version 0.13.0 PyPI version JSON
download
home_pagehttps://github.com/quantalogic/toolboxes/tree/main/quantalogic-toolbox-mcp
SummaryA custom MCP Client for Quantalogic
upload_time2025-04-19 07:30:18
maintainerNone
docs_urlNone
authorRaphael Mansuy
requires_python>=3.10
licenseMIT
keywords mcp quantalogic toolbox client
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 🛠️ 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.

---

[![PyPI Version](https://img.shields.io/pypi/v/quantalogic-toolbox-mcp.svg)](https://pypi.org/project/quantalogic-toolbox-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](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[![PyPI Version](https://img.shields.io/pypi/v/quantalogic-toolbox-mcp.svg)](https://pypi.org/project/quantalogic-toolbox-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](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"
}
        
Elapsed time: 0.39282s