Готовая к производству система корпоративной финансовой аналитики, интегрирующая Anthropic Model Context Protocol (MCP) с автономным агентом рассуждений. Система безопасно предоставляет многоттабличное реляционное хранилище финансовых данных большим языковым моделям (LLM) через стандартный транспорт JSON-RPC 2.0 stdio.
Она включает интеллектуальную 5-уровневую архитектуру эшелонированной защиты (Defense-in-Depth), чистый Python SQL AST-лексер и рекурсивный нисходящий парсер, анализатор производительности планов EXPLAIN, потокобезопасный пул соединений с тайм-аутами выполнения опкодов и цикл самовосстановления автономного агента, способный автоматически восстанавливаться после ошибок синтаксиса SQL, нарушений безопасности AST и предупреждений о декартовых соединениях.
┌─────────────────────────────────────────────────────────────────────────────┐
│ Stakeholder / User Prompt │
│ ("Identify branches with elevated 60+ delinquency") │
└──────────────────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Autonomous Agent Runner (agent/client_runner.py) │
│ - Multi-Turn Tool-Calling Loop (Anthropic Claude API / MockClaudeClient) │
│ - Schema-First Reflection & Planning │
│ - Closed-Loop Self-Correction & Query Repair Engine (Max Turns: 5) │
└──────────────────────────────────────┬──────────────────────────────────────┘
│ JSON-RPC 2.0 (stdio)
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ MCP Server Engine (agent/server.py) │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Methods: initialize, ping, tools/list, tools/call, resources, prompts │ │
│ └───────────────────────────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────────┼───────────────────────────────┐ │
│ ▼ ▼ ▼ │
│ query_database explain_query get_database_ │
│ (query_financial_lakehouse) schema │
└──────┬───────────────────────────────┬───────────────────────────────┬──────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────┐ ┌─────────────────────────┐ ┌─────────────────────┐
│ Layer 1: AST Gate │ │ Layer 2: Plan Analyzer │ │ Layer 3: Connection │
│ (agent/ast_validator.py)│ │(agent/explain_analyzer) │ │ Pool & Sandboxing │
│ - Pure Python Lexer │ │ - Cost Scoring (0-100) │ │ (agent/db_engine.py)│
│ - Recursive AST Parser │ │ - Full Scan Detection │ │ - URI mode=ro │
│ - 100% Non-DQL Block │ │ - Cartesian Join Flag │ │ - sqlite authorizer │
│ - Injection Defense │ │ - Index Tuning Advice │ │ - Opcode Timeouts │
└────────────┬────────────┘ └────────────┬────────────┘ └──────────┬──────────┘
│ │ │
└───────────────────────────┼─────────────────────────┘
▼
┌───────────────────────────────────────────────┐
│ Financial Data Warehouse (data/warehouse.db) │
│ - 6 Relational Tables & Composite Indexes │
│ - branches, customers, credit_ratings, │
│ loans, repayments, audit_log │
└───────────────────────────────────────────────┘Related MCP server: SQL Server MCP
Система обеспечивает строгие границы безопасности между LLM и механизмом базы данных на 5 независимых уровнях:
Уровень | Компонент | Механизм безопасности | Устраняемая угроза |
Уровень 1: AST-шлюз перед выполнением |
| Чистый Python-лексер и рекурсивный нисходящий парсер, проверяющие одно единственное выражение DQL ( | Составной запрос с несколькими операторами ( |
Уровень 2: Шлюз стоимости перед выполнением |
| Оценивает | Декартовы произведения (соединения $O(N \times M)$), неограниченные сканирования, истощение памяти из-за временных B-деревьев. |
Уровень 3: Режим “только чтение” ОС и механизма |
| Подключение SQLite с URI | Отказ в несанкционированных записях на диск, вмешательство в схему. |
Уровень 4: Авторизатор времени выполнения |
|
| Обходы, пытающиеся выполнить |
Уровень 5: Защитные ограничения ресурсов и памяти |
| Обработчик прогресса опкодов ( | Вышедшие из-под контроля рекурсивные CTE, отказ в обслуживании ЦП, разрушение памяти из-за безграничных результирующих наборов. |
agent/ast_validator.py)AST-шлюз безопасности реализует двухрежимный механизм:
Лексический анализатор и рекурсивный нисходящий парсер на чистых Python без зависимостей: построен с помощью стандартной библиотеки Python с полным отслеживанием координат (строка/колонка).
Опциональный движок sqlglot: парсер с учётом диалектов автоматически активируется, если установлен sqlglot.
Одно единственное выражение DQL: SELECT и WITH [RECURSIVE] ... SELECT.
Общие табличные выражения (CTE): отдельные и множественные связанные CTE. Парсер рекурсивно проходит определения CTE, гарантируя отсутствие встроенных DML-операций.
Оконные функции: OVER (PARTITION BY ... ORDER BY ... [ROWS/RANGE ...]), ROW_NUMBER(), RANK(), SUM() OVER ().
Соединения нескольких таблиц: INNER JOIN, LEFT OUTER JOIN, CROSS JOIN, NATURAL JOIN с ON и USING (...).
Подзапросы: подзапросы в FROM, скалярные подзапросы в SELECT, IN (SELECT ...), EXISTS (SELECT ...).
Составные операции над множествами: UNION [ALL], INTERSECT, EXCEPT.
Скалярные выражения: CASE WHEN ... THEN ... ELSE ... END, CAST(... AS ...), конкатенация строк (||), арифметика.
DDL: DROP, CREATE, ALTER, TRUNCATE.
DML: INSERT, UPDATE, DELETE, REPLACE, UPSERT, MERGE.
Административные команды: PRAGMA, ATTACH, DETACH, VACUUM, REINDEX, ANALYZE, BEGIN, COMMIT.
Опасные функции: load_extension, readfile, writefile, edit, fts3_tokenizer, eval, randomblob.
Системные таблицы: sqlite_master, sqlite_schema, sqlite_temp_master, sqlite_temp_schema, sqlite_sequence, sqlite_stat*.
Виды инъекций: операторы с несколькими выражениями через точку с запятой (;), незакрытые блочные комментарии (/* ...), незакрытые строковые литералы.
agent/explain_analyzer.py)Разбирает дерево EXPLAIN QUERY PLAN в формате из 4 столбцов начиная с SQLite 3.24+ (id, parent, notused, detail), а также в устаревших форматах.
$$\text{CostScore} = \min\left(100, ; \sum \text{Penalties}\right)$$
Операция | Классификация | Серьёзность | Штраф |
| Неиндексированное полное сканирование | Высокая | +25.0 каждая |
| Эфемерное построение индекса | Высокая | +20.0 |
| Неиндексированная сортировка | Средняя | +15.0 |
| Временное агрегирующее B-дерево | Средняя | +10.0 |
| Материализованный подзапрос | Средняя | +10.0 каждый |
Многотабличное неиндексированное сканирование | Декартово соединение | Критическая | +30.0 |
$0.0 - 25.0$ (OPTIMAL): Полностью индексированные поиски по условиям и диапазонам. Мгновенное выполнение.
$26.0 - 50.0$ (ACCEPTABLE): Незначительная временная сортировка или сканирование одной маленькой таблицы.
$51.0 - 74.0$ (WARNING): Субоптимальный план; множественные сканирования.
$75.0 - 100.0$ (CRITICAL): Декартово произведение или тяжёлое неиндексированное соединение. Блокируется шлюзом выполнения MCP.
data/schema.sql)Модель предметной области финансирования автомобильных активов с 6 реляционными таблицами:
┌──────────────┐ 1:N ┌──────────────┐ 1:N ┌──────────────┐
│ branches ├────────────────►│ customers ├────────────────►│credit_ratings│
└──────┬───────┘ └──────┬───────┘ └──────────────┘
│ 1:N │ 1:N
│ ┌──────────────┐ │
└────────►│ loans │◄──────┘
└──────┬───────┘
│ 1:N
┌──────▼───────┐
│ repayments │
└──────────────┘
┌──────────────┐
│ audit_log │ (Immutable lifecycle state transition log)
└──────────────┘branches: 12 региональных центров и розничных отделений с рекурсивной иерархией «родитель-потомок» (parent_branch_id).
customers: 300 профилей заёмщиков с логнормальным распределением доходов, коэффициентами долговой нагрузки и SHA-256 хэшами PII.
credit_ratings: более 600 продольных снимков кредитных скоринговых бюро от 5 уровням риска (от PRIME_PLUS до DEEP_SUBPRIME).
loans: 500 договоров автомобильного финансирования и МСП с скорректированными на риск процентными ставками и ежемесячными амортизационными платежами.
repayments: более 17 000 записей транзакционного журнала с разбивкой на основной долг, проценты, комиссии и отслеживанием просрочки.
audit_log: неизменяемые записи аудита, отслеживающие переходы состояния займа в DELINQUENT_90, DEFAULTED и WRITE_OFF.
Сервер (agent/server.py) предлагает 4 базовых инструмента:
query_database (Alaias: query_financial_lakehouse)Выполняет безопасные read-only SQL-запросы с автоматической предварительной AST-валидацией, тайм-аутами выполнения опкодов и ограничением количества строк.
Входные данные: query (str, обязательный), max_rows (int, по умолчанию: 100), timeout_seconds (float, по умолчанию: 5.0).
Выходные данные: JSON-объект с columns, rows, row_count, is_truncated, execution_time_ms.
explain_queryИзучает узлы плана выполнения, вычисляет оценку стоимости ($0-100$), обнаруживает сканирования и даёт рекомендации по индексам без выполнения мутаций.
Входные данные: query (str, обязательный).
Выходные данные: cost_score, complexity_rating, scanned_tables, indexed_tables, warnings, recommendations.
get_database_schemaОтражает метаданные каталога базы данных, типы столбцов, первичные ключи, внешние ключи и индексы.
Входные данные: table_name (str, опциональный).
Выходные данные: полные или отфильтрованные определения схемы таблиц.
validate_sql_safetyВыполняет статический анализ безопасности AST без доступа к базе данных.
Входные данные: query (str, обязательный).
Выходные данные: is_safe (bool), statement_type, referenced_tables, detected_risks.
agent/client_runner.py)AutonomousDataAgent реализует итерационный цикл вызова инструментов с текстовым замкнутым контуром исправления ошибок:
┌─────────────────────────────────────┐
│ User: "Top 5 default risk branches" │
└──────────────────┬──────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Turn 1: Introspect Database Schema │
└──────────────────┬──────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Turn 2: Synthesize & Explain Plan │
└──────────┬──────────────────────┬───┘
│ │
Plan Warning / ▼ ▼ Pass
Cartesian Join ┌──────────────────┐ ┌──────────────────┐
│ 🔄 Repair Query │ │ Turn 3: Execute │
│ (Add JOIN ... ON)│ │ query_database │
└────────┬─────────┘ └────────┬─────────┘
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Turn 4: Re-check │ │ Synthesize Final │
│ & Run Query │ │ Executive Report │
└──────────────────┘ └──────────────────┘Ошибка синтаксиса / схемы SQLite (например, ошибочно названный столбец): вставка SYNTAX_ERROR_TEMPLATE с каталогом схемы; агент исправляет имена столбцов.
Отказ безопасности AST (например, не-DQL запрос): вставка AST_VIOLATION_TEMPLATE; агент переформулирует запрос в один соответствующий оператор SELECT.
Высокая стоимость запроса / декартово соединение: вставка PLAN_WARNING_TEMPLATE; агент добавляет индексированные предикаты соединения.
Детерминимованное офлайн-выполнение: MockClaudeClient позволяет 100% -ое тестирование без использования API-ключа Anthropic.
# Clone and navigate to repository
cd MCP_Autonomous_Agent
# Install dependencies
pip install -r requirements.txtЗаполните data/warehouse.db детерминистическими синтетическими финансовыми данными (фиксированное seed 42):
python data/seed_warehouse.pyВывод:
[SeedWarehouse] branches : 12 rows
[SeedWarehouse] customers : 300 rows
[SeedWarehouse] credit_ratings : 627 rows
[SeedWarehouse] loans : 500 rows
[SeedWarehouse] repayments : 17120 rows
[SeedWarehouse] audit_log : 44 rows
[SeedWarehouse] Database seeding successfully completed.Выполните все 66 модульных и интеграционных тестов по AST-валидации, анализу EXPLAIN, потокобезопасности ядра БД, инструментам MCP и циклом самовосстановления агента:
python -m unittest discover -s tests -vПроведите многоходовую сессию аналитических запросов к финансовому хранилищу:
from agent.client_runner import AutonomousDataAgent
agent = AutonomousDataAgent()
response = agent.run("Identify the top default risk branches with delinquency counts and total exposure")
print(f"Success: {response.success}")
print(f"Turns Taken: {response.turns_taken}")
print(f"SQL Executed: {response.sql_executed}")
print(f"\n{response.final_answer}")Для подключения к приложению Anthropic Claude Desktop или к MCP Inspector:
python agent/server.pyНастройте в Claude Desktop claude_desktop_config.json:
{
"mcpServers": {
"financial-data-agent": {
"command": "python",
"args": ["-m", "agent.server"],
"cwd": "/path/to/MCP_Autonomous_Agent"
}
}
}MCP_Autonomous_Agent/
├── data/
│ ├── __init__.py
│ ├── schema.sql # 6-table relational financial warehouse DDL
│ ├── seed_warehouse.py # Deterministic synthetic data generator (seed 42)
│ └── warehouse.db # Generated SQLite database file
├── agent/
│ ├── __init__.py
│ ├── ast_validator.py # Pure-Python SQL Lexer & Recursive Descent AST Parser
│ ├── explain_analyzer.py # SQLite EXPLAIN QUERY PLAN analyzer & cost scorer
│ ├── db_engine.py # Thread-safe read-only connection pool & opcode timeout
│ ├── prompts.py # System prompts, tool schemas & remediation templates
│ ├── client_runner.py # Autonomous agent loop with closed-loop self-correction
│ └── server.py # MCP JSON-RPC 2.0 stdio server implementation
├── tests/
│ ├── __init__.py
│ ├── test_ast_validator.py # Unit tests for AST security and analytical DQL (29 tests)
│ ├── test_explain_analyzer.py# Unit tests for plan parsing, scans, cartesian (7 tests)
│ ├── test_db_engine.py # Unit tests for read-only pool, timeouts, threads (8 tests)
│ ├── test_mcp_tools.py # Unit tests for MCP protocol, tool calls, errors (15 tests)
│ └── test_client_runner.py # Unit tests for agent loop and self-healing (5 tests)
├── requirements.txt # Dependency specification (mcp, anthropic, sqlglot, pytest)
└── README.md # Complete architectural & technical documentationЛицензия MIT. Проект создан для корпоративной финансовой аналитики и демонстрации портфеля AI-агентов.
This server cannot be deployed
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Ask questions in plain language, get answers from your business database. No SQL required.
Ask business questions in plain English. Get instant answers from your database, no SQL needed.
Query OneLens cloud-cost data in natural language: breakdowns, trends, cost centers. Read-only.
