Model Context Protocol Toolkit (mcp-toolkit)

This robust framework elevates the functional scope of LLMs adhering to the Model Context Protocol (MCP). It furnishes a curated assembly of utilities enabling language models to interface directly with external web services and operating system functions, transcending inherent text generation limitations.

• Source Code Repository: https://github.com/ai-zerolab/mcp-toolbox/
• (Under Construction) Detailed Documentation: https://ai-zerolab.github.io/mcp-toolbox/

Core Capabilities

Primarily engineered for Unix-like systems, though compatibility with Windows environments is maintained.

• Shell Instruction Invocation: Permits LLMs to initiate and manage arbitrary command-line operations.
• Design Asset Interfacing: Provides read/write access to Figma canvases, component libraries, and style definitions.
• Modular Extension: Features an easily adaptable structure for integrating novel external API connectors.
• MCP Compliance: Fully interoperable with environments running Claude Desktop and other systems supporting the MCP specification.
• Rigorous Validation: Codebase maintained with comprehensive unit and integration testing.

Deployment Instructions

Recommended Method: Utilizing uv

We strongly advocate for utilizing the uv package installer for dependency management.

bash

Installation sequence for uv

curl -LsSf https://astral.sh/uv/install.sh | sh # For Linux/macOS

Alternatively, for Windows users:

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

Subsequently, execute the MCP server instance via uvx "mcp-toolbox@latest" stdio for the most current stable release. Note that specialized components like audio processing and long-term memory modules are excluded by default. To activate these, install with the all optional dependency set:

Specify [audio], [memory], or [all] for feature inclusion.

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

Installation via Smithery

For automated setup tailored for Claude Desktop using Smithery:

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

Standard Python Installation (pip)

bash pip install "mcp-toolbox[all]"

Use mcp-toolbox stdio to launch the server interface.

System Configuration Prerequisites

Environment Variables for Credentials

Required external access keys must be set in the environment:

• FIGMA_API_KEY: Authentication token for Figma services
• TAVILY_API_KEY: Key for Tavily web search integration
• DUCKDUCKGO_API_KEY: Key for DuckDuckGo search provider
• BFL_API_KEY: Credential for Flux image synthesis API

Volatile Memory Storage Locations

Data persistence for memory tools is mapped as follows:

• macOS: ~/Documents/zerolab/mcp-toolbox/memory (Leverages iCloud synchronization)
• Other Operating Systems: ~/.zerolab/mcp-toolbox/memory

Full Server Definition in Client Configuration

To fully integrate mcp-toolkit with advanced LLM clients (e.g., Claude Desktop, Cline, Cursor), place the following structure into the respective configuration file:

{ "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 access to all optional features:

{ "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" } } } }

A debug configuration scaffold can be generated via:

bash uv run generate_config_template.py

Tool Catalog

System Command Executors

Utility Name	Functionality Description
execute_command	Executes an arbitrary instruction in the shell

File System Manipulation

Utility Name	Functionality Description
read_file_content	Retrieves the textual content stored within a specified file
write_file_content	Persists new textual data into a designated file
replace_in_file	Modifies file content by substituting patterns identified via regex
list_directory	Enumerates the contents of a directory, providing comprehensive metadata

Figma Interaction Suite

Utility Name	Functionality Description
figma_get_file	Retrieves the entire structure of a Figma document via its identifier
figma_get_file_nodes	Fetches specific elements (nodes) within a Figma document
figma_get_image	Obtains rasterized representations (images) for specified nodes
figma_get_image_fills	Extracts URLs for image assets utilized within a file's fills
figma_get_comments	Fetches all discussion threads associated with a Figma file
figma_post_comment	Submits a new comment to a specified Figma resource
figma_delete_comment	Removes an existing comment from the file record
figma_get_team_projects	Lists projects belonging to a specified team workspace
figma_get_project_files	Retrieves all documents contained within a project
figma_get_team_components	Indexes all master components defined at the team level
figma_get_file_components	Extracts component definitions present in a single document
figma_get_component	Retrieves the definition of a component using its unique ID
figma_get_team_component_sets	Indexes all defined component sets for a team
figma_get_team_styles	Retrieves global text and color styles for a team
figma_get_file_styles	Extracts style definitions local to a specific file
figma_get_style	Retrieves the definition of a style by its key

XiaoyuZhouFM Utilities

Utility Name	Functionality Description
xiaoyuzhoufm_download	Facilitates downloading of episodes from XiaoyuZhouFM, optionally applying conversion from M4A to MP3

Audio Processing Tools

Utility Name	Functionality Description
get_audio_length	Determines the total duration of an audio file, reported in seconds
get_audio_text	Extracts transcribed speech from an audio file within a user-defined temporal window

Persistent Knowledge Module (Memory Tools)

Utility Name	Functionality Description
think	Allows the tool to internally deliberate and log the reasoning process sequentially
get_session_id	Retrieves the unique identifier for the current operational session
remember	Persists a short summary and detailed context into the non-volatile knowledge store
recall	Performs a semantic search against stored knowledge to retrieve relevant past entries
forget	Initiates a complete erasure of all persisted knowledge entries

Document Transformation (Markitdown Tools)

Utility Name	Functionality Description
convert_file_to_markdown	Transforms the content of any supported file type into Markdown format
convert_url_to_markdown	Renders content fetched from a Uniform Resource Locator as Markdown

Information Retrieval (Web Tools)

Utility Name	Functionality Description
get_html	Fetches the raw HTML source code from a specified URL
save_html	Retrieves HTML from a URL and saves it persistently to a local file
search_with_tavily	Executes a web search query via the Tavily search engine (API required)
search_with_duckduckgo	Executes a web search query via the DuckDuckGo engine (API required)

Image Synthesis (Flux Tools)

Utility Name	Functionality Description
flux_generate_image	Employs the Flux API to synthesize a novel image and stores it locally

Operational Guidance

Launching the MCP Server Process

bash

Standard launch using standard I/O streams (default)

mcp-toolbox stdio

Launch utilizing Server-Sent Events (SSE) transport

mcp-toolbox sse --host localhost --port 9871

Interfacing with Claude Desktop

1. Configure the tool's parameters in your client application as detailed in the Configuration section.
2. Initiate the Claude Desktop application.
3. Direct Claude to utilize the toolbox for Figma interactions:
4. "Query operational data for Figma document ID: 12345abcde."
5. "Display all component definitions within Figma file 12345abcde."
6. "Retrieve discussion threads for Figma file 12345abcde."
7. Instruct Claude to execute system commands:
8. "List the contents of the current working directory."
9. "Report the current system timestamp."
10. "Display the contents of /etc/hosts."
11. Request podcast downloads from XiaoyuZhouFM:
12. "Fetch this episode: https://www.xiaoyuzhoufm.com/episode/67c3d80fb0167b8db9e3ec0f"
13. "Download and convert the audio for episode at https://www.xiaoyuzhoufm.com/episode/67c3d80fb0167b8db9e3ec0f to MP3 format"
14. Interact with audio files:
15. "Ascertain the duration in seconds of the file 'audio.m4a'."
16. "Generate a text transcript for the segment spanning 60 to 90 seconds in 'audio.m4a'."
17. "Extract spoken content from file 'audio.m4a' between timestamps 2:30 and 3:00."
18. Convert documents or web content to Markdown:
19. "Transform 'document.docx' into Markdown format."
20. "Render the webpage located at https://example.com as Markdown."
21. Utilize web-based utilities:
22. "Retrieve the underlying HTML structure from https://example.com."
23. "Persist the HTML source from https://example.com into a local file."
24. "Execute a web search for 'advancements in machine learning'."
25. Invoke Flux for image creation:
26. "Synthesize a high-quality visualization of a mountain vista at sunset."
27. "Generate a visual depiction of a feline wearing astronaut gear and save the output locally."
28. "Create an artistic rendering of a futuristic metropolis scene."
29. Engage the memory functions:
    • "Store this essential piece of information: The primary city of France is Paris."
    • "What is the current session identifier?"
    • "Query the knowledge base for any stored context related to 'France'."
    • "Engage internal reflection on the long-term impact of global climate shifts."
    • "Purge all retained historical data from the system."

Developer Information

Local Environment Setup

Begin by forking the repository and cloning it locally.

bash

Install dependencies in development mode

make install

Activate the isolated Python environment

source .venv/bin/activate # For Unix-like systems

or

.venv\Scripts\activate # For Windows

Executing Tests

bash make test

Running Linting and Static Checks

bash make check

Building Project Documentation

bash make docs

Integrating New Functionality

To introduce a new external service connector:

1. Update config.py to accommodate any necessary credentials.
2. Define the new logic within a dedicated module inside mcp_toolbox/.
3. Implement the API client wrapper and the corresponding tool definitions.
4. Ensure comprehensive test coverage for the new features.
5. Update this README.md to document any new required environment variables and the finalized tool interface.

Please consult the developer documentation for granular procedural guidance.

Collaboration Guidelines

We encourage community contributions! Feel free to submit a standard Pull Request.

1. Fork the repository.
2. Create a dedicated feature branch (e.g., git checkout -b feature/new-utility).
3. Commit changes with descriptive messages (git commit -m 'Implement feature XYZ').
4. Push the branch to your remote (git push origin feature/new-utility).
5. Submit a formal Pull Request.

Licensing

This software package is distributed under the terms specified in the accompanying license file within this repository structure.

WIKIPEDIA ENTRY CONTEXT: XMLHttpRequest (XHR) is an Application Programming Interface, structured as a JavaScript object, whose methods are used to dispatch HTTP requests from a web client to a backend server. These methods empower client-side applications to initiate server communications following page rendering, and subsequently receive responses. XHR is a cornerstone technology for Ajax methodology. Prior to its widespread adoption, server interaction relied predominantly on traditional link navigation and form submissions, which typically necessitated a full page reload.

== Historical Background == The fundamental concept underpinning XMLHttpRequest was initially conceptualized in the year 2000 by engineers working on Microsoft Outlook. This concept was subsequently materialized in Internet Explorer version 5 (released in 1999). Critically, the initial implementation did not use the XMLHttpRequest string identifier. Instead, proprietary identifiers such as ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP") were employed. As of Internet Explorer version 7 (released in 2006), universal support for the standardized XMLHttpRequest identifier was established across the browser family. Today, the XMLHttpRequest identifier functions as the established convention across all major web browsing platforms, including Mozilla's Gecko rendering engine (since 2002), Apple Safari 1.2 (since 2004), and Opera 8.0 (since 2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) formally published an initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Working Draft for Level 2 was published by the W3C on February 25, 2008. The Level 2 revision introduced enhancements for monitoring request progress, enabling cross-origin data exchange, and facilitating the handling of raw byte streams. By the close of 2011, the Level 2 features were formally merged back into the primary specification document. Development responsibilities were transitioned to the WHATWG consortium at the close of 2012, which now maintains a continuously updated specification defined using Web IDL syntax.

== Operational Steps == Generally, implementing a network request using XMLHttpRequest requires adherence to a sequence of programming actions.

1. Instantiation: A new XMLHttpRequest object is created by invoking its constructor function:
2. Configuration: The "open" method is called to define the request method (e.g., GET, POST), specify the target resource URI, and elect for synchronous or asynchronous processing:
3. Listener Setup: For asynchronous operations, an event listener must be established to intercept and process state transitions:
4. Transmission: The request is actively dispatched to the server by invoking the "send" method:
5. Response Handling: State changes are monitored within the designated event handler. Upon successful server return, the payload is typically accessible via the "responseText" attribute. Once processing concludes, the object transitions to state 4, signifying completion ("done"). Beyond these fundamental steps, XMLHttpRequest provides extensive mechanisms for granular control over request transmission parameters and response parsing. Custom HTTP headers can be appended to guide server behavior, and data payloads can be uploaded via arguments supplied to the "send" invocation. Responses formatted as JSON can be automatically deserialized into native JavaScript objects, or processed incrementally as data chunks arrive rather than awaiting the full transmission. Furthermore, requests can be terminated prematurely or assigned a strict timeout limit.

== Cross-Origin Transactions == In the nascent stages of the World Wide Web's evolution, the inherent security restrictions prevented direct communication bet