Universal MCP Tool Framework

A reusable Python foundation for Model Context Protocol tools. The framework centralises registration, discovery, permissions, operation-mode separation, structured errors, logging, configuration, health/status output, and extension conventions.

Design Boundary

The framework is an MCP server foundation, not a generic shell, filesystem controller, or policy engine. Tools are registered explicitly and run through one permission boundary.

A tool must pass both checks: its operation mode is enabled and its required scopes are present in the execution context.

Related MCP server: achmadya-dev/mcp-core

Included Surface

Requirements

• Python 3.10+

• The official MCP Python SDK, pinned to mcp==2.0.0

Quick Start

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

Start the server through the MCP SDK:

mcp run server.py

For interactive development with MCP Inspector:

mcp dev server.py

Configuration

Copy and modify the example only when non-read operations are required.

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

read is the only default mode. To permit a registered write tool, add write; to permit a registered execution tool, add execute. Enabling a mode does not bypass required per-tool scopes.

Start the server with a selected configuration file:

UNIVERSAL_MCP_CONFIG=config.json mcp run server.py

Add a Tool

1. Choose one operation mode.

2. Declare every required scope.

3. Register the handler through ToolRegistry.

4. Add a test for discovery, allowed execution, and rejection paths.

5. Expose a thin MCP handler only if the tool belongs in the public server surface.

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}

Call it through ToolRuntime.execute() so the common permission, logging, and error contract always applies.

Result Contract

All runtime executions produce this stable envelope:

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

Rejected and failed requests use ok: false and a machine-readable error code such as tool_not_found, permission_denied, or tool_execution_failed.

Repository Structure

.
├── 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

Validation

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

The test suite verifies discovery, default read access, write/execute denial by default, scope enforcement, structured errors, status output, and JSON configuration.

Universal Project Scaffolding Toolkit

The repository also provides umcp-scaffold, a controlled generator for repeatable Python project starts.

Create a fully initialized project. By default, the generator creates a local Git repository, creates an isolated .venv, installs local dependencies, and validates the generated project.

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

Validate a generated project later:

umcp-scaffold validate ./my-project

Every generated project receives .project-state.json with its schema version, name, package name, template type, lifecycle state, Git/dependency flags, creation time, and last validation state. The generator rejects non-empty target directories rather than overwriting a project.

Local Code Analysis and Testing Toolkit

umcp-quality inspects a local Python project and returns a machine-readable quality report with PASS, FAIL, and WARNING results.

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

FAIL produces a non-zero command exit status. WARNING indicates an incomplete but non-failing condition, such as no virtual environment, no tests, no configuration directory, or unavailable Git history.