Universal MCP Tool Framework

Model Context Protocol 도구를 위한 재사용 가능한 Python 기반입니다. 이 프레임워크는 등록, 발견, 권한, 운영 모드 분리, 구조화된 오류, 로깅, 구성, 상태/헬스 출력, 확장 규칙을 중앙화합니다.

설계 경계

이 프레임워크는 MCP 서버 기반이지, 일반적인 셸, 파이일시스템 컨트롤러, 정책 엔진이 아닙니다. 도구는 명시적으로 등록되며 단일 권한 경계를 통해 실행됩니다.

도구는 두 가지 검사를 모두 통과해야 합니다. 즉, 운영 모드가 활성화되어 있고 필요한 스코프가 실행 컨스트에 존재해야 합니다.

Related MCP server: achmadya-dev/mcp-core

제 공 범위

요조건

• Python 3.10+

• mcp==2.0.0로 고정된 공식 MCP Python SDK

빠른 기작

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. 발견, 허용실행, 거부 경로에 대하 테스트를 추가하세요.

5. 도구가 public 서버 표면에 속한 경우에만 제한된 MCP 핸들러를 노출하세요.

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()을 통해서학세요.

결과 규약

모든 러타임 작업은 다음의 안정된 결과 envelope를 생합니다:

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

거부되거나 실패한 요청은 ok: false와 함께 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"

테스트 스위트는 도구 방전, 기본 읽기 공, 기본으로 쓰기/실행 거부 권한, 스코프 시행, 구저 오류, 상테 출력, JSON 구성을 검증합니다.

유니버셜 프로젝트 스폴딩 트

이 리포지터에도 umcp-scaffold를 제 공합니다. 반적인 Python 프로젝트의 시작을 위한 생성을 정형화하는 생성기입니다.

전체 초기화된 프로젝트를 만들으세요. 기본적으로 생성기는 로컬 Git 리포지터리를 만들고, 격리된 .venv를 만들고, 로컬 의존를 된 설치하고, 생성된 프로젝트를 검증합니다.

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

생성된 프로젝트를 만족하십시오:

umcp-scaffold validate ./my-project

Generat 생성된 모든 프로젝트는 .project-state.json에 스키마 버전, 이체, 패에게지, 템플레이트 유형, 프로젝트 상태, Git/의존성 플래그, 생성 시각, 마지막 상태를 담습니다. 생성되는 기존 비아 있지 않은 대상 폴더는 덮어쓰지 않고 거부됩니다.

로컬 코드 분석 및 테스트 툴킷

umcp-quality는 로컬 Python 프로젝트를 분석하고 PASS, FAIL, WARNING 결과로 이루어진 기계가 읽을 수 있는 품질 보고서를 반환합니다.

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

FAIL은 명령의 종바 코드가 0이 아닙니다. WARNING은 비완전하지만 실패 조건이 아닙 것(예: 아래 가환경, 테스트가 없, config/가 없음, Git 역이 롣존)을 나타냄니다.