MCP-Contracts Tools

Erstellt: 2025-12-20 | Aktualisiert: 2025-12-20

Alle 9 verfügbaren MCP-Tools für Contract-Management.

Übersicht

contracts_list

Listet Contracts mit optionalen Filtern auf.

# Alle aktiven Contracts (kompakt)
contracts_list(status="active")

# Suche mit vollständigen Daten
contracts_list(search="architecture", compact=False)

contracts_get

Holt einen Contract nach ID oder Name.

# Nach ID
contracts_get(id=1)

# Nach Name mit Historie
contracts_get(name="CSS Contract", include_history=True)

contracts_create

Erstellt einen neuen Contract.

contracts_update

Aktualisiert einen Contract (erstellt neue Version mit Historie).

contracts_deprecate

Markiert einen Contract als deprecated.

contracts_validate

Führt eine Validierung gegen den Contract-Scope aus.

# Validierung nach Name
contracts_validate(name="layered-architecture-pruefung_v1.0")

contracts_history

Holt die Änderungshistorie eines Contracts.

contracts_violations

Holt die letzten Validierungen/Violations.

contracts_statistics

Holt Statistiken über alle Contracts.

contracts_statistics()

MCP-Contracts Architektur

Erstellt: 2025-12-20 | Aktualisiert: 2025-12-31

Verzeichnisstruktur und Komponenten des MCP-Contracts Servers.

Verzeichnisstruktur

/var/www/mcp-servers/mcp_contracts/
├── server.py              # Entry Point (FastMCP)
├── config.py              # Konfiguration
├── requirements.txt       # Dependencies
├── venv/                  # Python Virtual Environment
│
├── domain/
│   ├── __init__.py
│   └── contracts.py       # Entities (Contract, ContractHistory, Validation)
│
├── infrastructure/
│   ├── __init__.py
│   └── contract_repository.py # CRUD-Operationen
│
├── validators/
│   ├── __init__.py
│   ├── contract_validator.py  # Contract-Validierung
│   ├── rule_evaluator.py      # Regel-Auswertung
│   └── scope_resolver.py      # Scope-Auflösung
│
└── tools/
    ├── __init__.py
    └── contract_tools.py  # 9 MCP-Tools

Layer-Architektur

Komponenten

server.py

Entry Point mit FastMCP-Initialisierung:

from mcp.server.fastmcp import FastMCP
from tools.contract_tools import register_contract_tools

mcp = FastMCP("mcp-contracts", instructions="...")
register_contract_tools(mcp)

if __name__ == "__main__":
    mcp.run(transport="stdio")

domain/contracts.py

Dataclasses für Contract-Entities:

• Contract - id, uuid, name, yaml_content, version, status, scope_description
• ContractHistory - contract_id, previous_yaml, previous_version, change_description
• ContractValidation - contract_id, result, violations, triggered_by
• ContractStatus - Enum (draft, active, deprecated)

infrastructure/contract_repository.py

CRUD-Operationen auf ki_dev.contracts:

• find_by_id(), find_by_name()
• find_all() mit Filtern
• create(), update(), deprecate()
• get_history(), get_validations()
• save_validation()
• get_statistics()

Hinweis: Datenbankverbindung inline via shared config. Logging direkt in mcp_log.

validators/

Validierungslogik aufgeteilt in drei Module:

Datenbank-Schema (ki_dev)

-- ki_dev.contracts
CREATE TABLE contracts (
    id INT AUTO_INCREMENT PRIMARY KEY,
    uuid CHAR(36) NOT NULL,
    name VARCHAR(100) NOT NULL,
    version VARCHAR(20) NOT NULL,
    status ENUM('draft','active','deprecated') DEFAULT 'active',
    yaml_content TEXT NOT NULL,
    scope_description VARCHAR(500) DEFAULT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    created_by VARCHAR(100) DEFAULT 'system',
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uuid (uuid),
    UNIQUE KEY unique_name_version (name, version),
    INDEX idx_status (status),
    INDEX idx_name (name)
);

-- ki_dev.contract_history
CREATE TABLE contract_history (
    id INT AUTO_INCREMENT PRIMARY KEY,
    contract_id INT NOT NULL,
    previous_yaml TEXT DEFAULT NULL,
    previous_version VARCHAR(20) DEFAULT NULL,
    change_description TEXT DEFAULT NULL,
    changed_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    changed_by VARCHAR(100) DEFAULT 'system',
    INDEX idx_contract_id (contract_id),
    FOREIGN KEY (contract_id) REFERENCES contracts(id) ON DELETE CASCADE
);

-- ki_dev.contract_validations
CREATE TABLE contract_validations (
    id INT AUTO_INCREMENT PRIMARY KEY,
    contract_id INT NOT NULL,
    validated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    result ENUM('passed','failed') NOT NULL,
    critical_count INT DEFAULT 0,
    major_count INT DEFAULT 0,
    minor_count INT DEFAULT 0,
    violations LONGTEXT CHECK (JSON_VALID(violations)),
    triggered_by ENUM('sync','manual','hook','mcp') DEFAULT 'mcp',
    target_path VARCHAR(255) DEFAULT NULL,
    duration_ms INT DEFAULT 0,
    INDEX idx_contract_id (contract_id),
    INDEX idx_validated_at (validated_at),
    INDEX idx_result (result),
    FOREIGN KEY (contract_id) REFERENCES contracts(id) ON DELETE CASCADE
);

Datenfluss

Claude Code
    ↓ MCP Tool Call
FastMCP (server.py)
    ↓ contracts_validate()
contract_tools.py
    ↓ Repository + Validators
contract_repository.py + validators/*.py
    ↓ SQL + Logging
ki_dev.contracts + mcp_log

Verwandte Themen

• MCP-Contracts Übersicht
• Installation
• Tools im Detail

MCP-Contracts Installation

Aktualisiert: 2025-12-31

Setup, Konfiguration und Registrierung des MCP-Contracts Servers.

Voraussetzungen

• Python 3.10+
• MariaDB/MySQL mit ki_dev Datenbank
• Claude Code CLI

Installation

1. Verzeichnis erstellen

mkdir -p /var/www/mcp-servers/mcp_contracts
cd /var/www/mcp-servers/mcp_contracts

2. Virtual Environment

python3 -m venv venv
source venv/bin/activate
pip install mcp pymysql python-dotenv pyyaml

3. Struktur

/var/www/mcp-servers/mcp_contracts/
├── server.py
├── config.py
├── requirements.txt
├── venv/
├── domain/
│   ├── __init__.py
│   └── contracts.py
├── infrastructure/
│   ├── __init__.py
│   └── contract_repository.py
├── validators/
│   ├── __init__.py
│   ├── contract_validator.py
│   ├── rule_evaluator.py
│   └── scope_resolver.py
└── tools/
    ├── __init__.py
    └── contract_tools.py

4. Datenbank-Tabellen (ki_dev)

-- Contracts
CREATE TABLE IF NOT EXISTS contracts (
    id INT AUTO_INCREMENT PRIMARY KEY,
    uuid CHAR(36) NOT NULL,
    name VARCHAR(100) NOT NULL,
    version VARCHAR(20) NOT NULL,
    status ENUM('draft','active','deprecated') DEFAULT 'active',
    yaml_content TEXT NOT NULL,
    scope_description VARCHAR(500) DEFAULT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    created_by VARCHAR(100) DEFAULT 'system',
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uuid (uuid),
    UNIQUE KEY unique_name_version (name, version),
    INDEX idx_status (status),
    INDEX idx_name (name)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- History
CREATE TABLE IF NOT EXISTS contract_history (
    id INT AUTO_INCREMENT PRIMARY KEY,
    contract_id INT NOT NULL,
    previous_yaml TEXT DEFAULT NULL,
    previous_version VARCHAR(20) DEFAULT NULL,
    change_description TEXT DEFAULT NULL,
    changed_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    changed_by VARCHAR(100) DEFAULT 'system',
    INDEX idx_contract_id (contract_id),
    FOREIGN KEY (contract_id) REFERENCES contracts(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- Validations
CREATE TABLE IF NOT EXISTS contract_validations (
    id INT AUTO_INCREMENT PRIMARY KEY,
    contract_id INT NOT NULL,
    validated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    result ENUM('passed','failed') NOT NULL,
    critical_count INT DEFAULT 0,
    major_count INT DEFAULT 0,
    minor_count INT DEFAULT 0,
    violations LONGTEXT CHECK (JSON_VALID(violations)),
    triggered_by ENUM('sync','manual','hook','mcp') DEFAULT 'mcp',
    target_path VARCHAR(255) DEFAULT NULL,
    duration_ms INT DEFAULT 0,
    INDEX idx_contract_id (contract_id),
    INDEX idx_validated_at (validated_at),
    INDEX idx_result (result),
    FOREIGN KEY (contract_id) REFERENCES contracts(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Registrierung in Claude Code

# MCP-Server registrieren
claude mcp add mcp-contracts \
  --transport stdio \
  -- /var/www/mcp-servers/mcp_contracts/venv/bin/python \
     /var/www/mcp-servers/mcp_contracts/server.py

# Registrierung prüfen
claude mcp list

Test

# In Claude Code Session
contracts_list(compact=True)
contracts_statistics()

Fehlerbehebung

Server startet nicht

# Manuell testen
/var/www/mcp-servers/mcp_contracts/venv/bin/python \
  /var/www/mcp-servers/mcp_contracts/server.py

# Logs prüfen
tail -f ~/.claude/logs/mcp-*.log

Datenbankverbindung fehlgeschlagen

• DB-User Berechtigungen prüfen
• MariaDB-Service Status: systemctl status mariadb

Tool nicht gefunden

# MCP-Server neu registrieren
claude mcp remove mcp-contracts
claude mcp add mcp-contracts ...

Berechtigungen

Logging erfolgt in ki_dev.mcp_log.

Verwandte Themen

• MCP-Contracts Übersicht
• Architektur
• Tools im Detail