| Name | quads-mcp JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | A Model Context Protocol server for QUADS bare-metal server management |
| upload_time | 2025-07-10 10:25:12 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | MIT |
| keywords |
mcp
quads
server
management
bare-metal
claude
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# quads-mcp
A Model Context Protocol for QUADS
## Overview
This is a Model Context Protocol (MCP) server that exposes tools, resources, and prompts for use with LLM applications like Claude. MCP servers let you extend AI applications with custom functionality, data sources, and templated interactions.
## Quick Start
### Option 1: Run with uvx (Easiest)
The fastest way to run the server without any setup:
```bash
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh
# Run the server directly (from project directory)
uvx --from . quads-mcp
# Or run the module
uvx --from . python -m quads_mcp.server
```
### Option 2: Setup with uv (Recommended)
```bash
# Set up the environment
make setup
# Check virtual environment status
make status
# Run the server (automatically uses virtual environment)
make run
# Run in development mode with MCP Inspector
make dev
# Install the server in Claude Desktop
make install
```
**Note**: You don't need to manually activate the virtual environment when using `make` commands - they automatically use the `.venv` environment!
If you encounter import errors, run `make reinstall` to refresh the package installation.
### Option 3: Manual Setup
```bash
# Install uv if you don't have it
pip install uv
# Create a virtual environment
uv venv
# Activate the virtual environment
source .venv/bin/activate # On Unix/MacOS
# or
.venv\Scripts\activate # On Windows
# Install the package in development mode
uv pip install -e .
# Run in development mode
mcp dev quads_mcp.server
# Install in Claude Desktop
mcp install quads_mcp.server
```
### uvx Configuration
When running with uvx, you can configure the server using environment variables or .env files:
```bash
# Option 1: Environment variables
MCP_QUADS__BASE_URL="https://your-quads-api.com/api/v3" \
MCP_QUADS__AUTH_TOKEN="your-token" \
uvx --from . quads-mcp
# Option 2: .env file (recommended)
cp .env.example .env
# Edit .env with your configuration
uvx --from . quads-mcp
# Option 3: Development mode
MCP_DEBUG=true uvx --from . quads-mcp
```
#### Installing as Global Tool
```bash
# Install globally with uvx
uvx install .
# Now run from anywhere
quads-mcp
# Uninstall when done
uvx uninstall quads-mcp
```
## Containers
This project uses Podman for containerization. Podman is a daemonless container engine that's compatible with OCI containers and provides better security than traditional container engines.
### Quick Start with Podman
```bash
# Build the container image
make container-build
# or
podman build -t quads-mcp .
# Run the container
make container-run
# or
podman run -p 8000:8000 quads-mcp
```
### Podman Compose (Recommended)
For easier development and deployment, use Podman Compose:
```bash
# Run with Podman Compose
make compose-up
# or
podman-compose up -d
# View logs
make compose-logs
# or
podman-compose logs -f
# Stop the service
make compose-down
# or
podman-compose down
```
### Development with Podman
For development with live code reloading:
```bash
# Run development profile
make compose-dev
# or
podman-compose --profile dev up -d quads-mcp-dev
# The development container mounts your code for live updates
```
### Configuration with Podman
#### Option 1: Environment Variables
```bash
podman run -p 8000:8000 \
-e MCP_QUADS__BASE_URL=https://your-quads-api.com/api/v3 \
-e MCP_QUADS__AUTH_TOKEN=your-token \
quads-mcp
```
#### Option 2: .env File
```bash
# Create .env file with your configuration
cp .env.example .env
# Edit .env with your values
# Run with .env file
podman run -p 8000:8000 \
-v $(pwd)/.env:/app/.env:ro \
quads-mcp
```
#### Option 3: Podman Compose with .env
```bash
# Edit podman-compose.yml to uncomment the .env volume mount
# Then run:
podman-compose up -d
```
### Production Builds
#### Multi-stage Build (Recommended)
For smaller, optimized production images:
```bash
# Build with multi-stage Containerfile
make container-build-prod
# or
podman build -f Containerfile.multistage -t quads-mcp:production .
# Run production image
make container-run-prod
# or
podman run -p 8000:8000 quads-mcp:production
```
#### Ultra-Secure Build (Distroless)
For maximum security with minimal attack surface:
```bash
# Build with distroless base image
make container-build-distroless
# or
podman build -f Containerfile.distroless -t quads-mcp:distroless .
# Run distroless image
make container-run-distroless
# or
podman run -p 8000:8000 quads-mcp:distroless
```
### Security Features
- **Alpine Linux Base**: Minimal, security-focused distribution
- **Non-root User**: Runs as unprivileged `mcp` user (UID/GID 1001)
- **Distroless Option**: Ultra-minimal base with no shell or package manager
- **Security Updates**: Automatically includes latest security patches
- **Minimal Attack Surface**: Only includes necessary dependencies
## Server Architecture
The server is organized into several components:
- `server.py`: Main MCP server setup and configuration
- `config.py`: Configuration management
- `tools/`: Tool implementations (functions that LLMs can execute)
- `resources/`: Resource implementations (data that LLMs can access)
- `prompts/`: Prompt template implementations (reusable conversation templates)
## MCP Features
This server implements all three MCP primitives:
1. **Tools**: Functions that the LLM can call to perform actions
- Example: `calculate`, `fetch_data`, `long_task`
2. **Resources**: Data sources that provide context to the LLM
- Example: `static://example`, `dynamic://{parameter}`, `config://{section}`
3. **Prompts**: Reusable templates for LLM interactions
- Example: `simple_prompt`, `structured_prompt`, `data_analysis_prompt`
## Adding Your Own Components
### Adding a New Tool
Create or modify files in the `tools/` directory:
```python
@mcp.tool()
def my_custom_tool(param1: str, param2: int = 42) -> str:
"""
A custom tool that does something useful.
Args:
param1: Description of first parameter
param2: Description of second parameter with default value
Returns:
Description of the return value
"""
# Your implementation here
return f"Result: {param1}, {param2}"
```
### Adding a New Resource
Create or modify files in the `resources/` directory:
```python
@mcp.resource("my-custom-resource://{param}")
def my_custom_resource(param: str) -> str:
"""
A custom resource that provides useful data.
Args:
param: Description of the parameter
Returns:
The resource content
"""
# Your implementation here
return f"Resource content for: {param}"
```
### Adding a New Prompt
Create or modify files in the `prompts/` directory:
```python
@mcp.prompt()
def my_custom_prompt(param: str) -> str:
"""
A custom prompt template.
Args:
param: Description of the parameter
Returns:
The formatted prompt
"""
return f"""
# Custom Prompt Template
Context: {param}
Please respond with your analysis of the above context.
"""
```
## Configuration
The server supports configuration via:
1. **Environment Variables**: Prefix with `MCP_` (e.g., `MCP_QUADS__BASE_URL=https://quads.example.com`)
- Nested config: Use double underscores (`MCP_QUADS__USERNAME=myuser`)
2. **Config File**: Specify via `MCP_CONFIG_FILE` environment variable
3. **.env File**: Place a `.env` file in the project directory
### QUADS Configuration
```bash
# Required: QUADS API URL
MCP_QUADS__BASE_URL=https://your-quads-server.com/api/v3
# Authentication (use either username/password OR token)
MCP_QUADS__USERNAME=your-username
MCP_QUADS__PASSWORD=your-password
# OR
MCP_QUADS__AUTH_TOKEN=your-auth-token
# Optional settings
MCP_QUADS__TIMEOUT=30
MCP_QUADS__VERIFY_SSL=true # Set to false for self-signed certificates
```
### SSL Certificates
For QUADS servers with self-signed certificates, set:
```bash
MCP_QUADS__VERIFY_SSL=false
```
⚠️ **Security Note**: Only disable SSL verification for trusted internal servers. See [SSL_CONFIGURATION.md](SSL_CONFIGURATION.md) for details.
### JSON Configuration Example
```json
{
"quads": {
"base_url": "https://quads.example.com/api/v3",
"username": "your-username",
"password": "your-password",
"timeout": 30,
"verify_ssl": false
}
}
```
## Development
```bash
# Run tests
make test
# Format code
make format
# Type checking
make type-check
# Clean up build artifacts
make clean
```
## License
[Include your license information here]
Raw data
{
"_id": null,
"home_page": null,
"name": "quads-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "mcp, quads, server, management, bare-metal, claude",
"author": null,
"author_email": "Gonzalo Rafuls <grafuls@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d5/db/3f09773ed937f26cce6933fc30cb04b5ffec186b10fb65a024c112a7680c/quads_mcp-0.1.0.tar.gz",
"platform": null,
"description": "# quads-mcp\n\nA Model Context Protocol for QUADS\n\n## Overview\n\nThis is a Model Context Protocol (MCP) server that exposes tools, resources, and prompts for use with LLM applications like Claude. MCP servers let you extend AI applications with custom functionality, data sources, and templated interactions.\n\n## Quick Start\n\n### Option 1: Run with uvx (Easiest)\n\nThe fastest way to run the server without any setup:\n\n```bash\n# Install uv if you don't have it\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Run the server directly (from project directory)\nuvx --from . quads-mcp\n\n# Or run the module\nuvx --from . python -m quads_mcp.server\n```\n\n### Option 2: Setup with uv (Recommended)\n\n```bash\n# Set up the environment\nmake setup\n\n# Check virtual environment status\nmake status\n\n# Run the server (automatically uses virtual environment)\nmake run\n\n# Run in development mode with MCP Inspector\nmake dev\n\n# Install the server in Claude Desktop\nmake install\n```\n\n**Note**: You don't need to manually activate the virtual environment when using `make` commands - they automatically use the `.venv` environment!\n\nIf you encounter import errors, run `make reinstall` to refresh the package installation.\n\n### Option 3: Manual Setup\n\n```bash\n# Install uv if you don't have it\npip install uv\n\n# Create a virtual environment\nuv venv\n\n# Activate the virtual environment\nsource .venv/bin/activate # On Unix/MacOS\n# or\n.venv\\Scripts\\activate # On Windows\n\n# Install the package in development mode\nuv pip install -e .\n\n# Run in development mode\nmcp dev quads_mcp.server\n\n# Install in Claude Desktop\nmcp install quads_mcp.server\n```\n\n### uvx Configuration\n\nWhen running with uvx, you can configure the server using environment variables or .env files:\n\n```bash\n# Option 1: Environment variables\nMCP_QUADS__BASE_URL=\"https://your-quads-api.com/api/v3\" \\\nMCP_QUADS__AUTH_TOKEN=\"your-token\" \\\nuvx --from . quads-mcp\n\n# Option 2: .env file (recommended)\ncp .env.example .env\n# Edit .env with your configuration\nuvx --from . quads-mcp\n\n# Option 3: Development mode\nMCP_DEBUG=true uvx --from . quads-mcp\n```\n\n#### Installing as Global Tool\n\n```bash\n# Install globally with uvx\nuvx install .\n\n# Now run from anywhere\nquads-mcp\n\n# Uninstall when done\nuvx uninstall quads-mcp\n```\n\n## Containers\n\nThis project uses Podman for containerization. Podman is a daemonless container engine that's compatible with OCI containers and provides better security than traditional container engines.\n\n### Quick Start with Podman\n\n```bash\n# Build the container image\nmake container-build\n# or\npodman build -t quads-mcp .\n\n# Run the container\nmake container-run\n# or\npodman run -p 8000:8000 quads-mcp\n```\n\n### Podman Compose (Recommended)\n\nFor easier development and deployment, use Podman Compose:\n\n```bash\n# Run with Podman Compose\nmake compose-up\n# or\npodman-compose up -d\n\n# View logs\nmake compose-logs\n# or\npodman-compose logs -f\n\n# Stop the service\nmake compose-down\n# or\npodman-compose down\n```\n\n### Development with Podman\n\nFor development with live code reloading:\n\n```bash\n# Run development profile\nmake compose-dev\n# or\npodman-compose --profile dev up -d quads-mcp-dev\n\n# The development container mounts your code for live updates\n```\n\n### Configuration with Podman\n\n#### Option 1: Environment Variables\n```bash\npodman run -p 8000:8000 \\\n -e MCP_QUADS__BASE_URL=https://your-quads-api.com/api/v3 \\\n -e MCP_QUADS__AUTH_TOKEN=your-token \\\n quads-mcp\n```\n\n#### Option 2: .env File\n```bash\n# Create .env file with your configuration\ncp .env.example .env\n# Edit .env with your values\n\n# Run with .env file\npodman run -p 8000:8000 \\\n -v $(pwd)/.env:/app/.env:ro \\\n quads-mcp\n```\n\n#### Option 3: Podman Compose with .env\n```bash\n# Edit podman-compose.yml to uncomment the .env volume mount\n# Then run:\npodman-compose up -d\n```\n\n### Production Builds\n\n#### Multi-stage Build (Recommended)\n\nFor smaller, optimized production images:\n\n```bash\n# Build with multi-stage Containerfile\nmake container-build-prod\n# or\npodman build -f Containerfile.multistage -t quads-mcp:production .\n\n# Run production image\nmake container-run-prod\n# or\npodman run -p 8000:8000 quads-mcp:production\n```\n\n#### Ultra-Secure Build (Distroless)\n\nFor maximum security with minimal attack surface:\n\n```bash\n# Build with distroless base image\nmake container-build-distroless\n# or\npodman build -f Containerfile.distroless -t quads-mcp:distroless .\n\n# Run distroless image\nmake container-run-distroless\n# or\npodman run -p 8000:8000 quads-mcp:distroless\n```\n\n### Security Features\n\n- **Alpine Linux Base**: Minimal, security-focused distribution\n- **Non-root User**: Runs as unprivileged `mcp` user (UID/GID 1001)\n- **Distroless Option**: Ultra-minimal base with no shell or package manager\n- **Security Updates**: Automatically includes latest security patches\n- **Minimal Attack Surface**: Only includes necessary dependencies\n\n## Server Architecture\n\nThe server is organized into several components:\n\n- `server.py`: Main MCP server setup and configuration\n- `config.py`: Configuration management\n- `tools/`: Tool implementations (functions that LLMs can execute)\n- `resources/`: Resource implementations (data that LLMs can access)\n- `prompts/`: Prompt template implementations (reusable conversation templates)\n\n## MCP Features\n\nThis server implements all three MCP primitives:\n\n1. **Tools**: Functions that the LLM can call to perform actions\n - Example: `calculate`, `fetch_data`, `long_task`\n\n2. **Resources**: Data sources that provide context to the LLM\n - Example: `static://example`, `dynamic://{parameter}`, `config://{section}`\n\n3. **Prompts**: Reusable templates for LLM interactions\n - Example: `simple_prompt`, `structured_prompt`, `data_analysis_prompt`\n\n## Adding Your Own Components\n\n### Adding a New Tool\n\nCreate or modify files in the `tools/` directory:\n\n```python\n@mcp.tool()\ndef my_custom_tool(param1: str, param2: int = 42) -> str:\n \"\"\"\n A custom tool that does something useful.\n \n Args:\n param1: Description of first parameter\n param2: Description of second parameter with default value\n \n Returns:\n Description of the return value\n \"\"\"\n # Your implementation here\n return f\"Result: {param1}, {param2}\"\n```\n\n### Adding a New Resource\n\nCreate or modify files in the `resources/` directory:\n\n```python\n@mcp.resource(\"my-custom-resource://{param}\")\ndef my_custom_resource(param: str) -> str:\n \"\"\"\n A custom resource that provides useful data.\n \n Args:\n param: Description of the parameter\n \n Returns:\n The resource content\n \"\"\"\n # Your implementation here\n return f\"Resource content for: {param}\"\n```\n\n### Adding a New Prompt\n\nCreate or modify files in the `prompts/` directory:\n\n```python\n@mcp.prompt()\ndef my_custom_prompt(param: str) -> str:\n \"\"\"\n A custom prompt template.\n \n Args:\n param: Description of the parameter\n \n Returns:\n The formatted prompt\n \"\"\"\n return f\"\"\"\n # Custom Prompt Template\n \n Context: {param}\n \n Please respond with your analysis of the above context.\n \"\"\"\n```\n\n## Configuration\n\nThe server supports configuration via:\n\n1. **Environment Variables**: Prefix with `MCP_` (e.g., `MCP_QUADS__BASE_URL=https://quads.example.com`)\n - Nested config: Use double underscores (`MCP_QUADS__USERNAME=myuser`)\n\n2. **Config File**: Specify via `MCP_CONFIG_FILE` environment variable\n\n3. **.env File**: Place a `.env` file in the project directory\n\n### QUADS Configuration\n\n```bash\n# Required: QUADS API URL\nMCP_QUADS__BASE_URL=https://your-quads-server.com/api/v3\n\n# Authentication (use either username/password OR token)\nMCP_QUADS__USERNAME=your-username\nMCP_QUADS__PASSWORD=your-password\n# OR\nMCP_QUADS__AUTH_TOKEN=your-auth-token\n\n# Optional settings\nMCP_QUADS__TIMEOUT=30\nMCP_QUADS__VERIFY_SSL=true # Set to false for self-signed certificates\n```\n\n### SSL Certificates\n\nFor QUADS servers with self-signed certificates, set:\n\n```bash\nMCP_QUADS__VERIFY_SSL=false\n```\n\n\u26a0\ufe0f **Security Note**: Only disable SSL verification for trusted internal servers. See [SSL_CONFIGURATION.md](SSL_CONFIGURATION.md) for details.\n\n### JSON Configuration Example\n\n```json\n{\n \"quads\": {\n \"base_url\": \"https://quads.example.com/api/v3\",\n \"username\": \"your-username\",\n \"password\": \"your-password\",\n \"timeout\": 30,\n \"verify_ssl\": false\n }\n}\n```\n\n## Development\n\n```bash\n# Run tests\nmake test\n\n# Format code\nmake format\n\n# Type checking\nmake type-check\n\n# Clean up build artifacts\nmake clean\n```\n\n## License\n\n[Include your license information here]\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Model Context Protocol server for QUADS bare-metal server management",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/grafuls/quads-mcp/issues",
"Documentation": "https://github.com/grafuls/quads-mcp/blob/main/README.md",
"Homepage": "https://github.com/grafuls/quads-mcp",
"Repository": "https://github.com/grafuls/quads-mcp"
},
"split_keywords": [
"mcp",
" quads",
" server",
" management",
" bare-metal",
" claude"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "79590fb398a3e1dd90dcb51c96de2bb051a61ef026b328dcc6b073571df4a827",
"md5": "58a436897b6c201ed3a2911ca2a441ca",
"sha256": "96bbccf49ed3a47469d5b647b5bcd1adccf6ed59e5682cd9983a6a025a41219a"
},
"downloads": -1,
"filename": "quads_mcp-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "58a436897b6c201ed3a2911ca2a441ca",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 20894,
"upload_time": "2025-07-10T10:25:10",
"upload_time_iso_8601": "2025-07-10T10:25:10.754035Z",
"url": "https://files.pythonhosted.org/packages/79/59/0fb398a3e1dd90dcb51c96de2bb051a61ef026b328dcc6b073571df4a827/quads_mcp-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d5db3f09773ed937f26cce6933fc30cb04b5ffec186b10fb65a024c112a7680c",
"md5": "e5dc97ae2bda6eb255e50d1a7c59790c",
"sha256": "aa3d8badb8e3a926411fb1e07598b5c77bca4491d6fa92a8d68d528866edb7f8"
},
"downloads": -1,
"filename": "quads_mcp-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "e5dc97ae2bda6eb255e50d1a7c59790c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 26359,
"upload_time": "2025-07-10T10:25:12",
"upload_time_iso_8601": "2025-07-10T10:25:12.328135Z",
"url": "https://files.pythonhosted.org/packages/d5/db/3f09773ed937f26cce6933fc30cb04b5ffec186b10fb65a024c112a7680c/quads_mcp-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 10:25:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "grafuls",
"github_project": "quads-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "quads-mcp"
}
