mcp-toolkit-suite

An extensive development kit designed to augment the capabilities of Large Language Models via the Model Context Protocol (MCP). This package furnishes developers with specialized instruments allowing LLMs to interface with external platforms and services, thereby transcending inherent text-generation limitations.

• Source Repository: https://github.com/ai-zerolab/mcp-toolbox/
• (In Progress) Documentation: https://ai-zerolab.github.io/mcp-toolbox/

Core Capabilities

Primary operational target is *nix systems, though compatibility with Windows is expected.

• Shell Instruction Invocation: Facilitates the execution of arbitrary shell commands directed by the LLM.
• Figma Interoperability: Provides mechanisms to query and interact with Figma files, their constituent components, styling rules, and other metadata.
• Modular Design: Features an easily expandable structure for integrating novel API endpoints.
• MCP Adherence: Fully compliant with the Model Context Protocol standard, supporting interaction with agents like Claude Desktop and other MCP-aware LLMs.
• Rigorous Validation: Codebase features comprehensive testing ensuring high reliability and coverage.

Installation Procedures

Using uv (Recommended Installer)

We advocate for leveraging uv for environment management.

bash

Installation of uv utility

curl -LsSf https://astral.sh/uv/install.sh | sh # For Unix-like OSes

or

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # For Windows

Subsequently, utilize uvx "mcp-toolbox@latest" stdio to launch the MCP server instance at the newest stable version. Note that default installations exclude audio and memory utilities; these can be incorporated by specifying the all extra dependency:

Include dependencies: [audio] for sound processing, [memory] for persistence layers, [all] for the complete utility set.

bash uvx "mcp-toolbox[all]@latest" stdio

Deployment via Smithery

To automate the installation of the Toolbox for LLM Augmentation into Claude Desktop using Smithery:

bash npx -y @smithery/cli install @ai-zerolab/mcp-toolbox --client claude

Standard pip Installation

bash pip install "mcp-toolbox[all]"

This permits invocation using the command sequence mcp-toolbox stdio for server initialization.

Configuration Directives

Environmental Variables

Configuration can be customized via the following environment settings:

• FIGMA_API_KEY: Credential for accessing the Figma API service.
• TAVILY_API_KEY: Key required for the Tavily search integration.
• DUCKDUCKGO_API_KEY: Key necessary for DuckDuckGo search functionality.
• BFL_API_KEY: Authentication token for the Flux image creation API.

Persistent Storage Locations (Memory)

Memory tools retain data in these paths:

• macOS: ~/Documents/zerolab/mcp-toolbox/memory (Benefits from iCloud synchronization)
• Other Platforms: ~/.zerolab/mcp-toolbox/memory

Complete Configuration Snippet

To integrate mcp-toolkit-suite with applications such as Claude Desktop, Cline, or Cursor, augment your configuration file as detailed below:

{ "mcpServers": { "zerolab-toolbox": { "command": "uvx", "args": ["--prerelease=allow", "mcp-toolbox@latest", "stdio"], "env": { "FIGMA_API_KEY": "your-figma-api-key", "TAVILY_API_KEY": "your-tavily-api-key", "DUCKDUCKGO_API_KEY": "your-duckduckgo-api-key", "BFL_API_KEY": "your-bfl-api-key" } } } }

For activation of all functionalities:

{ "mcpServers": { "zerolab-toolbox": { "command": "uvx", "args": [ "--prerelease=allow", "--python=3.12", "mcp-toolbox[all]@latest", "stdio" ], "env": { "FIGMA_API_KEY": "your-figma-api-key", "TAVILY_API_KEY": "your-tavily-api-key", "DUCKDUCKGO_API_KEY": "your-duckduckgo-api-key", "BFL_API_KEY": "your-bfl-api-key" } } } }

You can generate a baseline configuration template using:

bash uv run generate_config_template.py

Enumeration of Accessible Instruments

Command Line Interface Utilities

Instrument	Functionality Description
execute_command	Executes a specified instruction on the shell

File System Operations

Instrument	Operational Description
read_file_content	Retrieves textual data contained within a specified file
write_file_content	Persists supplied data into a designated file location
replace_in_file	Modifies file contents by substituting patterns identified via regex
list_directory	Presents contents of a directory, including metadata details

Figma Manipulation Instruments

Instrument	Service Provided
figma_get_file	Fetches a Figma document given its unique identifier
figma_get_file_nodes	Retrieves particular structural elements (nodes) from a file
figma_get_image	Obtains rendered image representations for specified nodes
figma_get_image_fills	Resolves URLs for image assets utilized within a file
figma_get_comments	Accesses associated commentary threads on a file
figma_post_comment	Submits new commentary to a specified Figma document
figma_delete_comment	Erases a previously posted comment
figma_get_team_projects	Lists projects associated with a team workspace
figma_get_project_files	Retrieves all files belonging to a specific project
figma_get_team_components	Queries components defined at the team level
figma_get_file_components	Extracts components defined within a particular file
figma_get_component	Fetches details of a component using its key
figma_get_team_component_sets	Retrieves organized component sets at the team level
figma_get_team_styles	Queries shared style definitions across a team
figma_get_file_styles	Extracts styling rules defined within a document
figma_get_style	Retrieves a specific style object via its key

XiaoyuZhouFM Utilities

Instrument	Capability
xiaoyuzhoufm_download	Facilitates downloading of podcast episodes from XiaoyuZhouFM, with an option for automated m4a to mp3 conversion

Audio Processing Instruments

Instrument	Functionality Description
get_audio_length	Calculates the total duration of an audio asset in seconds
get_audio_text	Extracts transcribed speech from a specified temporal segment of an audio file

Memory Management Instruments

Instrument	Role in Persistence and Recall
think	Directs the tool to process a concept and appends the resultant insight to the operational log
get_session_id	Retrieves the unique identifier for the current interaction session
remember	Persists an abstract concept (summary and full context) into the archival store
recall	Executes a semantic search against stored recollections for relevant data
forget	Purges all entries from the memory persistence database

Document Transformation Instruments (Markitdown)

Instrument	Transformation Function
convert_file_to_markdown	Renders the content of any file format into Markdown via MarkItDown
convert_url_to_markdown	Renders the live content of a specified web URL into Markdown

Internet Interaction Tools

Instrument	Interaction Type
get_html	Retrieves the raw HyperText Markup Language structure from a URI
save_html	Persists the retrieved HTML source from a URI to a local file
search_with_tavily	Executes a web search query utilizing the Tavily engine (API key mandatory)
search_with_duckduckgo	Executes a web search query utilizing the DuckDuckGo engine (API key mandatory)

Flux Image Synthesis Tools

Instrument	Output Creation Function
flux_generate_image	Creates an image based on a textual prompt using the Flux API and saves the output to disk

Operational Walkthroughs

Initializing the MCP Server

bash

Standard invocation using STDIN/STDOUT transport (default)

mcp-toolkit-suite stdio

Alternative invocation using Server-Sent Events (SSE) transport

mcp-toolkit-suite sse --host localhost --port 9871

Interacting via Claude Desktop

1. Configure the necessary server connection settings within Claude Desktop (refer to the Configuration section).
2. Launch the Claude Desktop application.
3. Request Figma file interactions:
4. "Could you retrieve metadata for Figma resource ID: 12345abcde?"
5. "Display the elemental structure within Figma file: 12345abcde"
6. "Fetch all annotations associated with Figma document: 12345abcde"
7. Request execution of system commands:
8. "List the directory contents of the present working location."
9. "Report the current system time."
10. "Display the contents of a designated configuration file."
11. Request podcast episode acquisition from XiaoyuZhouFM:
12. "Acquire this podcast segment: https://www.xiaoyuzhoufm.com/episode/67c3d80fb0167b8db9e3ec0f"
13. "Download and convert to MP3 format the following audio stream: https://www.xiaoyuzhoufm.com/episode/67c3d80fb0167b8db9e3ec0f"
14. Request audio file analysis:
15. "Determine the duration of the file named audio.m4a in seconds."
16. "Transcribe speech data between the 60th and 90th second markers in audio.m4a"
17. "Extract textual content spanning 2 minutes 30 seconds to 3 minutes 0 seconds from the audio asset."
18. Request document format conversion:
19. "Transform the contents of the file document.docx into Markdown syntax."
20. "Convert the information presented at https://example.com into a Markdown document."
21. Request web content retrieval:
22. "Fetch the raw HTML source from https://example.com"
23. "Persist the retrieved HTML structure from https://example.com into a local file"
24. "Perform an internet search for 'advancements in generative artificial intelligence'"
25. Request image generation via Flux:
26. "Synthesize a visual representation of a tranquil mountain vista at sunset."
27. "Create a visual asset depicting a feline in astronaut attire and store it on my primary drive."
28. "Generate a portrait image featuring a feline wearing space exploration gear."
29. Request utilization of persistence features:
    • "Encode this critical piece of information: The capital of the French Republic is Paris."
    • "What is the identifier for my current interaction session?"
    • "Retrieve any stored knowledge pertaining to France."
    • "Reflect upon the potential consequences of global climate change."
    • "Initiate a complete erasure of all recorded knowledge."

Development Workflow

Local Environment Setup

Fork the repository source and clone the contents locally.

bash

Install dependencies in editable mode

make install

Activate the isolated Python environment

source .venv/bin/activate # For macOS/Linux

or

.venv\Scripts\activate # For Windows

Executing Unit Tests

bash make test

Running Linting and Static Checks

bash make check

Compiling Documentation Assets

bash make docs

Integrating Novel Functionality

To incorporate support for a new external service:

1. Modify config.py to include any requisite authentication credentials.
2. Establish a new subdirectory or file within mcp_toolbox/ to house the implementation.
3. Develop the necessary API client abstraction and associated tooling functions.
4. Write and execute tests covering the new logic.
5. Update this README.md to document new environmental parameters and functional instruments.

Consult the development guidelines document for more granular implementation guidance.

Contribution Guidelines

We warmly welcome external contributions! Please feel free to propose enhancements via a Pull Request.

1. Create a personal fork of the repository.
2. Establish a dedicated feature branch (git checkout -b feature/novel-enhancement).
3. Commit your modifications (git commit -m 'Implement novel enhancement feature').
4. Push the new branch to the remote (git push origin feature/novel-enhancement).
5. Submit a formal Pull Request.

Licensing

This software distribution is governed by the terms stipulated in the included licensing file within the repository structure.

WIKIPEDIA: Cloud computing is defined by ISO as "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand." It is commonly abbreviated as "the cloud".

== Defining Attributes == In the year 2011, the U.S. National Institute of Standards and Technology (NIST) established five 'essential characteristics' defining cloud infrastructures. The precise NIST definitions are enumerated below:

On-demand self-service: "A consumer can unilaterally provision computing capabilities, such as server time and network storage, as needed automatically without requiring human interaction with each service provider." Broad network access: "Capabilities are available over the network and accessed through standard mechanisms that promote use by heterogeneous thin or thick client platforms (e.g., mobile phones, tablets, laptops, and workstations)." Resource pooling: " The provider's computing resources are pooled to serve multiple consumers using a multi-tenant model, with different physical and virtual resources dynamically assigned and reassigned according to consumer demand." Rapid elasticity: "Capabilities can be elastically provisioned and released, in some cases automatically, to scale rapidly outward and inward commensurate with demand. To the consumer, the capabilities available for provisioning often appear unlimited and can be appropriated in any quantity at any time." Measured service: "Cloud systems automatically control and optimize resource use by leveraging a metering capability at some level of abstraction appropriate to the type of service (e.g., storage, processing, bandwidth, and active user accounts). Resource usage can be monitored, controlled, and reported, providing transparency for both the provider and consumer of the utilized service. By the year 2023, the International Organization for Standardization (ISO) had subsequently refined and expanded this foundational list.

== Historical Precursors ==

The lineage of cloud computing traces back to the 1960s, with the pioneering concepts of time-sharing gaining traction through Remote Job Entry (RJE) systems. The dominant operational model throughout this decade involved the 'data center' paradigm, where users submitted computational tasks to dedicated operators for execution on mainframe hardware. This era was characterized by intense investigation into methods for democratizing access to large-scale computational resources via time-sharing mechanisms, focusing on optimizing infrastructure, platform layers, applications, and elevating end-user efficiency. The symbolic representation of virtualization as a 'cloud' originated around 1994, utilized by General Magic to denote the conceptual universe of 'locations' reachable by mobile software agents within their Telescript environment. Attribution for this metaphorical usage is generally given to David Hoffman, a communications specialist at General Magic, who adopted it based on its established history in telecommunications networking. The term 'cloud computing' achieved broader recognition in 1996 when Compaq Computer Corporation drafted a strategic business blueprint for forthcoming internet and computing paradigms. The organization's principal goal was to facilitate superch