Universal MCP Tool Framework

面向 Model Context Protocol 工具的可复用 Python 基础框架。该框架集中处理注册、发现、权限、操作模式分离、结构化错误、日志记录、配置、健康/状态输出以及扩展约定。

设计边界

该框架是 MCP 服务器基础，而非通用 shell、文件系统控制器或策略引擎。每个工具通过显式注册，执行时仅穿过一个统一权限边界。

工具必须同时通过两项检查：该工具的操作模式已启用，且执行上下文中存在该工具的所需作用域。

Related MCP server: achmadya-dev/mcp-core

包含的功能面

环境要求

• Python 3.10 及以上

• 官方 MCP Python SDK，版本固定为 mcp==2.0.0。

快速开始

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

用 MCP SDK 启动服务器：

mcp run server.py

如果希望使用 MCP Inspector 交互式开发：

mcp dev server.py

配置

仅当有非只读需求时，才复制并改改预设配置示例：

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

read 是唯一默认模式。要允许已注册的写入工具，添加 write；要允许某个执行工具，添加 execute。开启某个模式不能绕过工具所声明的必需作用域。

使用选择的配置文件启动服务器：

UNIVERSAL_MCP_CONFIG=config.json mcp run server.py

添加一个工具

1. 选择一种操作模式。

2. 为工具声明全部所需作用域。

3. 通过 ToolRegistry 注册。

4. 为 discovery（发现）、允许执行和拒绝路径各加测试。

5. 仅当工具属于公开服务时，才加一层轻量的 MCP handler，否则不暴露。

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}

通过 ToolRuntime.execute() 调用执行，以自动获得公共权限、日志记录和错误返回约定的保证。

结果契约

所有 runtime 执行都返回如下稳定结构：

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

被拒绝或失败的请求置 ok: flase，并携带机器可读的错误码，如 tool_not_found、permission_denied 或 tool_execution_failed。

仓库结构

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

验证

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

测试套件覆盖的检查项包括：discovery、默认只读、默认拒绝写/执行、作用域强制、结构化错误、状态输出以及 json 配置正确性。

Universal MCP Tool Framework

该仓库还提供 umcp-scaffold，一个用于可重复 Python 工程初始化的受控制生成器。

生成一个完全初始化的项目：默认地生成器会创建本地 Git 仓库，隔离的 .venv，安装本地依赖，并对生成结果做校验。

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

持续验证已生成的项目：

umcp-scaffold validate ./my-project

每个生成项目都会写 .project-state.json 文件，其中包含 schema 版本、项目名称、包名、模板类型、生命周期状态、Git/依赖标志位、创建时间以及最近校验状态。生成器拒绝覆盖非空目录。

本地代码分析与测试工具集

umcp-quatrik 可扫描本地 Python 项目，并生成带 PASS、FAIL、WARNING 三种状态的机器可读质量报告。

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

报告状态与退出码：FAIL 令命令返回非零退出码；WARNING 表示条件不完整但并不失败，比如缺少虚拟环境、测试、配置目录，或 Git 历史不可用。