Quads MCP

quads mcp

一种用于QUADS的模型上下文协议

概述

这是一个模型上下文协议（MCP）服务器，它公开了工具、资源和提示，供Claude等LLM应用程序使用。MCP服务器允许您使用自定义功能、数据源和模板化交互来扩展AI应用程序。

安装

选项1：从PyPI安装（推荐）

# Install the latest version from PyPI
pip install quads-mcp

# Or using uvx for isolated installation
uvx install quads-mcp

# Run the server
quads-mcp

选项2：直接通过uvx运行

# Run the server
uvx quads-mcp

#### Claude Desktop Configuration (PyPI Installation)

{ "mcpServers": { "quads-mcp": { "command": "quads-mcp", "env": { "MCP_QUADS__BASE_URL": "https://your-quads-server.com/api/v3", "MCP_QUADS__USERNAME": "your-username", "MCP_QUADS__PASSWORD": "your-password", "MCP_QUADS__VERIFY_SSL": "false" } } } }

Claude Desktop Configuration (via uvx)

{
  "mcpServers": {
    "quads-mcp": {
      "command": "uvx",
      "args": [
        "--from", "quads-mcp", "quads-mcp"
      ],
      "env": {
        "MCP_QUADS__BASE_URL": "https://your-quads-server.com/api/v3",
        "MCP_QUADS__USERNAME": "your-username",
        "MCP_QUADS__PASSWORD": "your-password",
        "MCP_QUADS__VERIFY_SSL": "false"
      }
    }
  }
}

选项2：从源代码安装

快速开始

选项1：使用uvx运行（最简单）

无需任何设置即可运行服务器的最快方法：

# 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

选项2：使用紫外线设置（推荐）

# 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

备注：使用时不需要手动激活虚拟环境 make 命令-它们会自动使用 .venv 环境！

如果遇到导入错误，请运行 make reinstall 以刷新软件包安装。

选项3：手动设置

# 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配置

使用uvx运行时，您可以使用环境变量或.env文件配置服务器：

# 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

作为全局工具安装

# Install globally with uvx
uvx install .

# Now run from anywhere
quads-mcp

# Uninstall when done
uvx uninstall quads-mcp

容器

该项目使用Podman进行容器化。Podman是一个无守护进程的容器引擎，与OCI容器兼容，提供了比传统容器引擎更好的安全性。

Podman快速入门

# 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：

# 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

与Podman共同发展

对于实时代码重新加载的开发：

# 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

使用Podman进行配置

选项1：环境变量

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

选项2:.env文件

# 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

选项3：波德曼用.env作曲

# Edit podman-compose.yml to uncomment the .env volume mount
# Then run:
podman-compose up -d

生产建筑

多阶段构建（推荐）

对于更小、优化的生产图像：

# 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

超安全构建（分布式）

为了以最小的攻击面实现最大的安全性：

# 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

安全功能

• Alpine Linux基础版：以安全为重点的最小分发
• 非root用户：无特权运行 mcp 用户（UID/GID 1001）
• 分散选项：超小基础，无外壳或包管理器
• 安全更新：自动包含最新的安全补丁
• 最小攻击面：仅包括必要的依赖项

服务器架构

服务器由几个组件组成：

• server.py：主MCP服务器设置和配置
• config.py：配置管理
• tools/：工具实现（LLM可以执行的功能）
• resources/：资源实现（LLM可以访问的数据）
• prompts/：提示模板实现（可重用的对话模板）

MCP功能

此服务器实现了所有三个MCP原语：

1. 工具：LLM可以调用以执行操作的函数

- 例子： calculate, fetch_data, long_task

1. 资源：为LLM提供背景的数据源

- 例子： static://example, dynamic://{parameter}, config://{section}

1. 鼓励：LLM交互的可重用模板

- 例子： simple_prompt, structured_prompt, data_analysis_prompt

添加自己的组件

添加新工具

在中创建或修改文件 tools/ 目录：

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

添加新资源

在中创建或修改文件 resources/ 目录：

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

添加新提示

在中创建或修改文件 prompts/ 目录：

@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.
    """

配置

服务器支持通过以下方式进行配置：

1. 环境变量：前缀为 MCP_ （例如。， MCP_QUADS__BASE_URL=https://quads.example.com)

- 嵌套配置：使用双下划线(MCP_QUADS__USERNAME=myuser)

1. 配置文件：指定通过 MCP_CONFIG_FILE 环境变量

1. .env文件：放置a .env 项目目录中的文件

QUADS配置

# 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证书

对于具有自签名证书的QUADS服务器，请设置：

MCP_QUADS__VERIFY_SSL=false

⚠️ 安全说明：仅禁用受信任的内部服务器的SSL验证。看 SSL_配置.md 了解详情。

JSON配置示例

{
  "quads": {
    "base_url": "https://quads.example.com/api/v3",
    "username": "your-username",
    "password": "your-password",
    "timeout": 30,
    "verify_ssl": false
  }
}

发展

# Run tests
make test

# Format code
make format

# Type checking
make type-check

# Clean up build artifacts
make clean

许可证

\[在此处包含您的许可证信息\]