| Name | mcp-stdio-toolbox JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | A universal MCP server for wrapping CLI tools as MCP tools - stable alternative to experimental MCP implementations |
| upload_time | 2025-08-09 15:23:40 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | MIT License
Copyright (c) 2025 Richard Chen
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
ai-integration
automation
claude
cli-tools
codex
gpt
mcp
model-context-protocol
openai
toolbox
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# MCP Stdio Toolbox
A universal MCP (Model Context Protocol) server that wraps CLI tools as MCP tools through simple YAML configuration.
## Features
- 🔧 **Universal CLI Wrapper**: Convert any CLI tool to an MCP tool via configuration
- ⚡ **Async Execution**: Non-blocking command execution with timeout support
- 📝 **YAML Configuration**: Simple, declarative tool definitions
- 🛡️ **Input Validation**: JSON Schema validation for tool inputs
- 📊 **Output Management**: Automatic truncation and error handling
- 🧪 **Well Tested**: Comprehensive test coverage with pytest
## Quick Start
### Installation
```bash
# Using uv (recommended)
uv pip install mcp-stdio-toolbox
# Using pip
pip install mcp-stdio-toolbox
```
### Configuration
Create a `tools.yaml` configuration file:
```yaml
server:
name: "my-toolbox"
version: "1.0.0"
default_timeout_sec: 30
max_output_bytes: 1048576
tools:
- name: "echo"
description: "Echo text to stdout"
command: "echo"
args: []
input_schema:
type: object
properties:
text:
type: string
description: "Text to echo"
required: ["text"]
arg_mapping:
- ["text"]
- name: "grep_file"
description: "Search patterns in files"
command: "grep"
args: ["-n"]
timeout_sec: 60
input_schema:
type: object
properties:
pattern:
type: string
description: "Pattern to search for"
file:
type: string
description: "File to search in"
required: ["pattern", "file"]
arg_mapping:
- ["pattern"]
- ["file"]
```
### Usage
#### Standalone Server
```bash
mcp-stdio-toolbox --config tools.yaml
```
#### With Claude Desktop
Add to your Claude Desktop configuration:
```json
{
"mcpServers": {
"stdio-toolbox": {
"command": "mcp-stdio-toolbox",
"args": ["--config", "/path/to/tools.yaml"]
}
}
}
```
#### With Claude Code
```bash
claude mcp add stdio-toolbox "mcp-stdio-toolbox --config tools.yaml"
```
## Configuration Reference
### Server Configuration
```yaml
server:
name: string # Server name (default: "mcp-stdio-toolbox")
version: string # Server version (default: "0.1.0")
default_timeout_sec: int # Default timeout in seconds (default: 30)
max_output_bytes: int # Max output size in bytes (default: 1048576)
```
### Tool Configuration
```yaml
tools:
- name: string # Tool name (required)
description: string # Tool description (required)
command: string # Command to execute (required)
args: list # Default command arguments (default: [])
timeout_sec: int # Tool-specific timeout (default: server default)
input_schema: # JSON Schema for input validation (required)
type: object
properties:
param_name:
type: string
description: "Parameter description"
required: ["param_name"]
arg_mapping: # Maps input parameters to command arguments
- ["param_name"] # Each list item becomes a command argument
```
## Examples
### File Operations
```yaml
tools:
- name: "cat_file"
description: "Display file contents"
command: "cat"
input_schema:
type: object
properties:
file:
type: string
description: "File to display"
required: ["file"]
arg_mapping:
- ["file"]
- name: "find_files"
description: "Find files by name pattern"
command: "find"
args: ["."]
input_schema:
type: object
properties:
name:
type: string
description: "Name pattern to search for"
type:
type: string
enum: ["f", "d"]
description: "File type (f=file, d=directory)"
default: "f"
required: ["name"]
arg_mapping:
- ["-name"]
- ["name"]
- ["-type"]
- ["type"]
```
### HTTP Requests
```yaml
tools:
- name: "curl_get"
description: "Make HTTP GET request"
command: "curl"
args: ["-s", "-L"]
timeout_sec: 120
input_schema:
type: object
properties:
url:
type: string
description: "URL to fetch"
headers:
type: array
items:
type: string
description: "HTTP headers (format: 'Header: Value')"
required: ["url"]
arg_mapping:
- ["url"]
- ["headers"]
```
### Git Operations
```yaml
tools:
- name: "git_log"
description: "Show git commit history"
command: "git"
args: ["log", "--oneline"]
input_schema:
type: object
properties:
max_count:
type: integer
description: "Maximum number of commits"
default: 10
directory:
type: string
description: "Repository directory"
default: "."
arg_mapping:
- ["-C"]
- ["directory"]
- ["-n"]
- ["max_count"]
```
## Development
### Setup
```bash
git clone <repository>
cd mcp-stdio-toolbox
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"
```
### Testing
```bash
# Run tests
pytest
# Run with coverage
pytest --cov=src --cov-report=html
# Lint and format
ruff check src tests
ruff format src tests
```
### Project Structure
```
mcp-stdio-toolbox/
├── src/mcp_stdio_toolbox/
│ ├── __init__.py
│ ├── server.py # Main MCP server
│ ├── config_loader.py # YAML configuration loading
│ ├── tool_registry.py # Dynamic tool registration
│ └── subprocess_runner.py # Async command execution
├── tests/ # Test suite
├── config/
│ └── tools.example.yaml # Example configuration
├── pyproject.toml # Project configuration
└── README.md
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-stdio-toolbox",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "ai-integration, automation, claude, cli-tools, codex, gpt, mcp, model-context-protocol, openai, toolbox",
"author": null,
"author_email": "Richard Chen <yingchuan.chen.2007@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f9/05/13170263f7194b8d30647b0251fbc9542822740274df6b8406d341753c18/mcp_stdio_toolbox-0.1.0.tar.gz",
"platform": null,
"description": "# MCP Stdio Toolbox\n\nA universal MCP (Model Context Protocol) server that wraps CLI tools as MCP tools through simple YAML configuration.\n\n## Features\n\n- \ud83d\udd27 **Universal CLI Wrapper**: Convert any CLI tool to an MCP tool via configuration\n- \u26a1 **Async Execution**: Non-blocking command execution with timeout support\n- \ud83d\udcdd **YAML Configuration**: Simple, declarative tool definitions\n- \ud83d\udee1\ufe0f **Input Validation**: JSON Schema validation for tool inputs\n- \ud83d\udcca **Output Management**: Automatic truncation and error handling\n- \ud83e\uddea **Well Tested**: Comprehensive test coverage with pytest\n\n## Quick Start\n\n### Installation\n\n```bash\n# Using uv (recommended)\nuv pip install mcp-stdio-toolbox\n\n# Using pip\npip install mcp-stdio-toolbox\n```\n\n### Configuration\n\nCreate a `tools.yaml` configuration file:\n\n```yaml\nserver:\n name: \"my-toolbox\"\n version: \"1.0.0\"\n default_timeout_sec: 30\n max_output_bytes: 1048576\n\ntools:\n - name: \"echo\"\n description: \"Echo text to stdout\"\n command: \"echo\"\n args: []\n input_schema:\n type: object\n properties:\n text:\n type: string\n description: \"Text to echo\"\n required: [\"text\"]\n arg_mapping:\n - [\"text\"]\n\n - name: \"grep_file\"\n description: \"Search patterns in files\"\n command: \"grep\"\n args: [\"-n\"]\n timeout_sec: 60\n input_schema:\n type: object\n properties:\n pattern:\n type: string\n description: \"Pattern to search for\"\n file:\n type: string\n description: \"File to search in\"\n required: [\"pattern\", \"file\"]\n arg_mapping:\n - [\"pattern\"]\n - [\"file\"]\n```\n\n### Usage\n\n#### Standalone Server\n\n```bash\nmcp-stdio-toolbox --config tools.yaml\n```\n\n#### With Claude Desktop\n\nAdd to your Claude Desktop configuration:\n\n```json\n{\n \"mcpServers\": {\n \"stdio-toolbox\": {\n \"command\": \"mcp-stdio-toolbox\",\n \"args\": [\"--config\", \"/path/to/tools.yaml\"]\n }\n }\n}\n```\n\n#### With Claude Code\n\n```bash\nclaude mcp add stdio-toolbox \"mcp-stdio-toolbox --config tools.yaml\"\n```\n\n## Configuration Reference\n\n### Server Configuration\n\n```yaml\nserver:\n name: string # Server name (default: \"mcp-stdio-toolbox\")\n version: string # Server version (default: \"0.1.0\")\n default_timeout_sec: int # Default timeout in seconds (default: 30)\n max_output_bytes: int # Max output size in bytes (default: 1048576)\n```\n\n### Tool Configuration\n\n```yaml\ntools:\n - name: string # Tool name (required)\n description: string # Tool description (required)\n command: string # Command to execute (required)\n args: list # Default command arguments (default: [])\n timeout_sec: int # Tool-specific timeout (default: server default)\n input_schema: # JSON Schema for input validation (required)\n type: object\n properties:\n param_name:\n type: string\n description: \"Parameter description\"\n required: [\"param_name\"]\n arg_mapping: # Maps input parameters to command arguments\n - [\"param_name\"] # Each list item becomes a command argument\n```\n\n## Examples\n\n### File Operations\n\n```yaml\ntools:\n - name: \"cat_file\"\n description: \"Display file contents\"\n command: \"cat\"\n input_schema:\n type: object\n properties:\n file:\n type: string\n description: \"File to display\"\n required: [\"file\"]\n arg_mapping:\n - [\"file\"]\n\n - name: \"find_files\"\n description: \"Find files by name pattern\"\n command: \"find\"\n args: [\".\"]\n input_schema:\n type: object\n properties:\n name:\n type: string\n description: \"Name pattern to search for\"\n type:\n type: string\n enum: [\"f\", \"d\"]\n description: \"File type (f=file, d=directory)\"\n default: \"f\"\n required: [\"name\"]\n arg_mapping:\n - [\"-name\"]\n - [\"name\"]\n - [\"-type\"]\n - [\"type\"]\n```\n\n### HTTP Requests\n\n```yaml\ntools:\n - name: \"curl_get\"\n description: \"Make HTTP GET request\"\n command: \"curl\"\n args: [\"-s\", \"-L\"]\n timeout_sec: 120\n input_schema:\n type: object\n properties:\n url:\n type: string\n description: \"URL to fetch\"\n headers:\n type: array\n items:\n type: string\n description: \"HTTP headers (format: 'Header: Value')\"\n required: [\"url\"]\n arg_mapping:\n - [\"url\"]\n - [\"headers\"]\n```\n\n### Git Operations\n\n```yaml\ntools:\n - name: \"git_log\"\n description: \"Show git commit history\"\n command: \"git\"\n args: [\"log\", \"--oneline\"]\n input_schema:\n type: object\n properties:\n max_count:\n type: integer\n description: \"Maximum number of commits\"\n default: 10\n directory:\n type: string\n description: \"Repository directory\"\n default: \".\"\n arg_mapping:\n - [\"-C\"]\n - [\"directory\"]\n - [\"-n\"]\n - [\"max_count\"]\n```\n\n## Development\n\n### Setup\n\n```bash\ngit clone <repository>\ncd mcp-stdio-toolbox\nuv venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\nuv pip install -e \".[dev]\"\n```\n\n### Testing\n\n```bash\n# Run tests\npytest\n\n# Run with coverage\npytest --cov=src --cov-report=html\n\n# Lint and format\nruff check src tests\nruff format src tests\n```\n\n### Project Structure\n\n```\nmcp-stdio-toolbox/\n\u251c\u2500\u2500 src/mcp_stdio_toolbox/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 server.py # Main MCP server\n\u2502 \u251c\u2500\u2500 config_loader.py # YAML configuration loading\n\u2502 \u251c\u2500\u2500 tool_registry.py # Dynamic tool registration\n\u2502 \u2514\u2500\u2500 subprocess_runner.py # Async command execution\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 config/\n\u2502 \u2514\u2500\u2500 tools.example.yaml # Example configuration\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u2514\u2500\u2500 README.md\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Run the test suite\n6. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details.",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Richard Chen\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "A universal MCP server for wrapping CLI tools as MCP tools - stable alternative to experimental MCP implementations",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/yingchuan/mcp-stdio-toolbox#readme",
"Homepage": "https://github.com/yingchuan/mcp-stdio-toolbox",
"Issues": "https://github.com/yingchuan/mcp-stdio-toolbox/issues",
"Repository": "https://github.com/yingchuan/mcp-stdio-toolbox"
},
"split_keywords": [
"ai-integration",
" automation",
" claude",
" cli-tools",
" codex",
" gpt",
" mcp",
" model-context-protocol",
" openai",
" toolbox"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "420b729e87c0b9bc7dbf7f93701cfc98f74b56ca36d6f83aa57c663dbbb70fea",
"md5": "edec67e45c8e8d5f6fad4d569cf2f71e",
"sha256": "457a9f5528c18e4208f84d60ff53c8c1bfbf72d2d0bd91a89f770889223e023d"
},
"downloads": -1,
"filename": "mcp_stdio_toolbox-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "edec67e45c8e8d5f6fad4d569cf2f71e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 9753,
"upload_time": "2025-08-09T15:23:38",
"upload_time_iso_8601": "2025-08-09T15:23:38.888908Z",
"url": "https://files.pythonhosted.org/packages/42/0b/729e87c0b9bc7dbf7f93701cfc98f74b56ca36d6f83aa57c663dbbb70fea/mcp_stdio_toolbox-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f90513170263f7194b8d30647b0251fbc9542822740274df6b8406d341753c18",
"md5": "5671c5af7785b3b7abb192578c5ab67e",
"sha256": "75c9235850b9840477a1adda8c6977d4cfb7aec813522895bb482a3724e8238a"
},
"downloads": -1,
"filename": "mcp_stdio_toolbox-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "5671c5af7785b3b7abb192578c5ab67e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 13113,
"upload_time": "2025-08-09T15:23:40",
"upload_time_iso_8601": "2025-08-09T15:23:40.346271Z",
"url": "https://files.pythonhosted.org/packages/f9/05/13170263f7194b8d30647b0251fbc9542822740274df6b8406d341753c18/mcp_stdio_toolbox-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-09 15:23:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yingchuan",
"github_project": "mcp-stdio-toolbox#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mcp-stdio-toolbox"
}
