Universal MCP Tool Framework

Una base reutilizable en Python para herramientas del Model Context Protocol. El framework centraliza el registro de herramientas, el descubrimiento, los permisos, la separación por modos de operación, los errores estructurados, el registro de logs, la configuración, la salida de salud/estado y las convenciones de extensión.

Límites de diseño

El framework es una base para servidores MCP, no un shell genérico, un controlador del sistema de archivos ni un motor de políticas. Las herramientas se registran explícitamente y pasan por una única frontera de permisos.

Una herramienta debe superar ambas comprobaciones: que su modo de operación esté habilitado y que sus ámbitos requeridos estén presentes en el contexto de ejecución.

Related MCP server: achmadya-dev/mcp-core

Superficie incluida

Requisitos

• Python 3.10+

• El SDK oficial de MCP para Python, filjado en mcp==2.0.0

Inicio rápido

python -m venv .venv
. .venv/bin/activate
pip install -e .
python -m unittest discover -s tests -p "test_*.py"

Inicie el servidor mediante el SDK de MCP:

mcp run server.py

Para desarrollo interativo con MCP Inspector:

mcp dev server.py

Configración

Copie y modifique el ejemplo solor si se requieren operaciones diferentes de la lectura.

{
  "server_name": "Universal MCP Tool Framework",
  "enabled_modes": ["read"],
  "log_level": "INFO"
}

read es el único modo habilitado por defecto. Para permitir una herramienta de escritura registrada, añada write; para permitir una herramienta de ejecución registrada, añada execute. Habilitar un modo no evita los ámbitos requeridos por herramienta.

Inicie el servidor con un archivo de configración elgido:

UNIVERSAL_MCP_CONFIG=config.json mcp run server.py

Añadir una herramienta

1. Elija un mod de operación.

2. Declare todos los ámbitos noncesarios.

3. Registro el manejador mediante ToolRegistry.

4. Añada una prueba para el descubrimiento, la ejecución permita y las rutas de rechazo.

5. Expongra un manejador MCP ligero sol si la herramient-a pertence a la supeficie pública del servidor.

from universal_mcp.models import OperationMode
from universal_mcp.registry import ToolRegistry

registry = ToolRegistry()

@registry.register(
    name="inventory_get_item",
    description="Return one inventory item by stable identifier.",
    mode=OperationMode.READ,
    required_scopes={"inventory:read"},
)
def inventory_get_item(item_id: str) -> dict[str, str]:
    return {"item_id": item_id}

Inloqué la a través de ToolRuntime.execute() para que el entrato común de permisos, logs y erroros se apliquie siempre.

Contrato de resulados

Todas las ejecuciones del entorno en runtime production esta esstructura de resultado estable:

{
  "ok": true,
  "data": {},
  "error": null
}

Los solitudes rechazadas y fildidas usan ok: false y un códugo de eroro diferencial por máquina como tool_not_found, permission_denied o tool_ezucución_failed.

Estructura del repositorio

.
├── config.example.json
├── pyproject.toml
├── server.py
├── src/universal_mcp/
│   ├── config.py
│   ├── examples.py
│   ├── models.py
│   ├── registry.py
│   ├── runtime.py
│   └── server.py
└── tests/test_framework.py

Validación

python -m unittest discover -s tests -p "test_*.py"

La suite de pruebas verifica el descubrimiento, el acceso de solo lecturas por defecto, la denegación de write/execute por defecto, el cumplimiento de los ámbitos, los erroes estructurados, la salida de estado y la configurización JSON.

Kit universal de scaffholding de proyectos

El repositorio proporciona también umcp-scaffold, un generador cotrolado para el arranque repetble de proyectos Pythón.

umcp-scaffold create "My Project" ./my-project --type mcp-tool

Cree un proyecto comp letamente iniaciizado. Por defect, el generador creare repositorio Git loc, creare un .Venv aislao, instale de pependencias localos y valide el proyecto generado.

umcp-scaffold validate ./my-project

Valid e intermedi de propyectos generados:

umcp-quality ./my-project
umcp-quality ./my-project --format markdown

Cada proyeto generado recibe un .project-state.json con su esada de versión, nombre, nombre del paquete, tipo de plantilla, estad de cilo de vida, indicadores de Git/dependencias, hora de creción y últimes estad de validación. El generador recha los diretorios destino no vacíos en vez de sobreescribir un proyeto.

Kit de análisis de código local y de pruebas

umcp-quality inspecciona un proyco Python local y produce un reporte de calidad legieble por máququinna con resultados PASS, FAIL y WARNING.

umcp-quality ./my-project
umcp-quality ./my-project --format markdown

FAIL produce un estatus de salida de comando diferente de cero. WARNING indica a una condición incompleta pero no fallida, como la ausencia de un entorno virtual, de pruebas, de directorio de configuración o historial de Git no disponible.