contract-risk-analyzer

Contract Risk Analyzer — это сервер FastMCP + рабочий процесс LangGraph, который считывает PDF-файлы финансовых контрактов, извлекает ключевые положения и обязательства, помечает известные рискованные условия с указанием степени серьезности, сравнивает версии контрактов и синтезирует всё это в структурированную сводку рисков для юристов, команд по управлению рисками и операторов, которым требуется быстрая и понятная сортировка контрактов.

Инструменты MCP принимают либо локальный file_path, либо удаленный pdf_url. Для размещенных развертываний, таких как Railway, используйте pdf_url, чтобы сервер мог загрузить PDF во временное хранилище перед анализом.

Архитектура (высокий уровень)

PDF
  |
  v
FastMCP_Server
  |
  +--> extract_clauses
  +--> flag_risk_terms
  +--> summarize_obligations
  +--> compare_contracts
  |
  v
LangGraph_Agent (orchestrates tools)
  |
  v
RiskBrief (Pydantic structured output)

Настройка (локально)

cd contract-risk-analyzer
cp .env.example .env
source .venv/bin/activate  # if you already created the project virtualenv
pip install -e ".[dev]"
python -m contract_risk_analyzer.server

• MCP эндпоинт: http://localhost:8000/mcp

• Проверка работоспособности: http://localhost:8000/health

• Файл .env должен содержать OPENAI_API_KEY.

Подключение из Claude Desktop (MCP-клиент)

Вариант A: Запуск в качестве локального STDIO-сервера (Claude Desktop запускает его сам)

В Claude Desktop добавьте запись MCP-сервера, аналогичную этой:

{
  "mcpServers": {
    "contract-risk-analyzer": {
      "command": "python",
      "args": ["-m", "contract_risk_analyzer.server"],
      "env": {
        "OPENAI_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

Вариант B: Подключение к локальному HTTP-серверу

Если вы запускаете сервер самостоятельно (python -m contract_risk_analyzer.server), свяжите Claude Desktop с локальным MCP HTTP-эндпоинтом с помощью mcp-remote:

{
  "mcpServers": {
    "contract-risk-analyzer": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:8000/mcp",
        "--allow-http"
      ]
    }
  }
}

Вариант C: Подключение к развернутому серверу Railway

Развернутый сервер доступен по адресу:

• Проверка работоспособности: https://contract-risk-analyzer-production-410a.up.railway.app/health

• MCP эндпоинт: https://contract-risk-analyzer-production-410a.up.railway.app/mcp

Конфигурация Claude Desktop:

{
  "mcpServers": {
    "contract-risk-analyzer": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://contract-risk-analyzer-production-410a.up.railway.app/mcp"
      ]
    }
  }
}

Примеры вызова инструментов

Правила для входных данных

Для инструментов, работающих с одним контрактом, укажите ровно один из следующих параметров:

{
  "file_path": "/app/samples/contract.pdf"
}

или:

{
  "pdf_url": "https://example.com/contracts/contract.pdf"
}

Для compare_contracts укажите ровно один источник для каждой стороны:

{
  "pdf_url_a": "https://example.com/contracts/v1.pdf",
  "pdf_url_b": "https://example.com/contracts/v2.pdf"
}

Удаленные PDF-файлы загружаются во временное хранилище (ограничение 50 МБ на PDF) и удаляются после каждого вызова инструмента.

extract_clauses

Входные данные:

{
  "pdf_url": "https://example.com/contracts/isda.pdf",
  "clause_type": "termination events"
}

Пример вывода:

[
  {
    "section_name": "ARTICLE_VII TERMINATION",
    "clause_type": "termination events",
    "raw_text": "…",
    "plain_english": "…",
    "page_references": [12, 13]
  }
]

flag_risk_terms

Входные данные:

{ "pdf_url": "https://example.com/contracts/isda.pdf" }

Пример вывода:

[
  {
    "term": "cross-default",
    "context": "…",
    "risk_explanation": "…",
    "severity": "high",
    "page_reference": 9
  }
]

summarize_obligations

Входные данные:

{ "pdf_url": "https://example.com/contracts/isda.pdf" }

Пример вывода:

[
  {
    "party": "Borrower",
    "obligations": ["Deliver monthly financial statements…"],
    "key_deadlines": ["Within 30 days after month-end…"],
    "conditions": ["So long as no Event of Default has occurred…"]
  }
]

compare_contracts

Входные данные:

{
  "pdf_url_a": "https://example.com/contracts/v1.pdf",
  "pdf_url_b": "https://example.com/contracts/v2.pdf"
}

Пример вывода:

{
  "added_clauses": ["New collateral top-up requirement…"],
  "removed_clauses": ["Removed cure period for payment default…"],
  "materially_changed_clauses": [
    {
      "section_name": "ARTICLE_IV EVENTS_OF_DEFAULT",
      "change_summary": "Acceleration now triggers immediately…",
      "risk_note": "Increases lender leverage; reduces borrower flexibility."
    }
  ],
  "risk_delta": "Overall risk increased for Borrower due to tighter default/acceleration terms."
}

Развертывание (Railway)

• Сборка: Railway соберет контейнер из Dockerfile.

• Запуск: Контейнер выполняет python -m contract_risk_analyzer.server и привязывается к $PORT (по умолчанию 8000).

• Проверка работоспособности: GET /health возвращает {"status":"ok"}.

• Окружение: Установите OPENAI_API_KEY в переменных службы Railway.

• Текущее развертывание: https://contract-risk-analyzer-production-410a.up.railway.app.

Технологический стек

• FastMCP

• OpenAI GPT-4o (через SDK openai)

• PyMuPDF (pymupdf)

• Pydantic

• LangGraph

• Docker

• Railway