Blocksnet

blocksnet-mcp - локальный MCP-сервер городской аналитики поверх BlocksNetAgent. Сервер предоставляет один основной инструмент analyze_urban_question(...): принимает вопрос на естественном языке, запускает полный рассуждающий агент BlocksNet на локальной модели города и возвращает строгий машиночитаемый JSON.

Проект следует подходу WIKI-LLM: документация и директории индексируются так, чтобы LLM могла быстро понять назначение репозитория, выбрать нужные файлы и не загружать весь проект в контекст. Главный навигационный индекс: docs/WIKI-LLM.md.

Концепция

Выбран Вариант 2: не выносить 33 внутренних инструмента blocksnet как отдельные MCP-tools, а обернуть агента целиком.

Причина: ценность системы не только в расчетах, а в рассуждающем слое агента:

1. PTR-цикл predict -> test -> revise: фальсифицируемые гипотезы до расчетов и классификация исхода.
2. RAG по инструментам: короткие описания плюс полные карточки через find_tools / get_tool_help.
3. Инварианты качества M1-M3, C1/C2/C3, C-Hyp: проверка заземленности, измеренности и самосогласованности.
4. Измеренные предложения развития: TPE-оптимизация зон и сценарная проверка before -> after.

MCP-слой остается тонким: читает настройки, вызывает BlocksNetAgent.run(...), сериализует результат.

Текущий объем

Текущий MVP рассчитан на локальную работу:

Область	Решение
Транспорт	stdio, сервер запускается MCP-клиентом как подпроцесс
Данные	локальная папка data/ через DATA_DIR
LLM	внешний OpenAI-совместимый API (CHAT_URL, API_KEY, MODEL)
Инструмент	analyze_urban_question(question, max_iterations?)
Выход	JSON с планом, результатом, гипотезами, измеренными эффектами, ограничениями и артефактами

Вне текущего объема: UrbanDB-контекст (scenario_id / project_id), HTTP-транспорт, Bearer-авторизация, Docker-деплой и регистрация в MAS. В этом репозитории реализован только локальный stdio MCP.

Архитектура MVP

Локальный MCP-клиент
  -> stdio
  -> blocksnet_mcp.server
  -> tools_mcp.analyze_urban_question
  -> BlocksNetAgent.run(question)
  -> serialize.to_json(result)
  -> JSON-ответ MCP-клиенту

Структура репозитория:

blocksnet-mcp/
├── README.md
├── .env.example
├── .gitignore
├── requirements.txt
├── .python310/          # локальный Python 3.10.11, gitignored
├── .venv/               # локальное окружение Python 3.10.11, gitignored
├── docs/
│   ├── README.md
│   ├── WIKI-LLM.md
│   ├── overview_and_concept.md
│   ├── architecture.md
│   ├── tool_contract.md
│   ├── deployment.md
│   ├── mcp_repository_plan.md
│   ├── mas_integration_reference.md    # 🕘 Future-справка, gitignored
│   └── mas_registration.md             # 🕘 Future-справка, gitignored
├── blocksnet_mcp/
│   ├── README.md
│   ├── server.py
│   ├── tools_mcp.py
│   ├── serialize.py
│   ├── settings.py
│   └── __init__.py
├── blocksnet_agent/
│   ├── README.md
│   └── ... ядро агента из blocksnet-agent (agent.py / hypotheses.py / metrics.py / tools/...)
├── data/
│   ├── README.md                 # опц., локальный индекс
│   ├── service_type.json
│   ├── archetypes.csv
│   ├── service_aliases.json
│   ├── blocks_with_services.gpkg         # gitignored
│   ├── acc_mx.pickle                     # gitignored
│   └── <local-city-sandbox>/             # gitignored (например, saint_petersburg/)
├── tests/
│   ├── README.md
│   ├── test_serialize.py
│   ├── test_tool_contract.py
│   ├── test_async_mcp_contract.py
│   ├── test_confidence_signals.py
│   ├── test_overlay_candidates.py
│   ├── test_ptr_classifier.py
│   ├── test_runtime.py
│   ├── test_provision_cache.py
│   ├── test_numeric_metric_resolution.py
│   ├── test_provision_summaries.py
│   ├── test_target_block_selection.py
│   ├── test_tool_failure_dedup.py
│   ├── test_no_data_grounding.py
│   └── test_experiment_harness.py
├── scripts/
│   ├── README.md
│   └── smoke_client.py
├── examples/
│   ├── README.md
│   ├── test_visualization.ipynb
│   ├── saint_petersburg/main.py
│   ├── saint_petersburg/data/            # gitignored
│   └── yuzhno-sakhalinsk/                # gitignored
├── docs/
│   ├── reports/
│   │   ├── test_report_20260618.md
│   │   └── run_quality_report_20260706_spb.md
│   ├── mcp_repository_plan.md    # 🕘 локальный план, gitignored
│   ├── mas_integration_reference.md    # 🕘 Future-справка, gitignored
│   └── mas_registration.md             # 🕘 Future-справка, gitignored
└── outputs/             # runtime-артефакты, gitignored

Контракт инструмента

analyze_urban_question(question: str, max_iterations: int | None = None) возвращает структурный JSON (P1.1 — payload терминального submit_answer агента, P1.2 — авторитетная confidence + самооценка

• basis, P1.6 — overlay_candidates как fallback для recommendation_blocks):

{
  "question": "...",
  "analysis_plan": "...",
  "result": "...",
  "reflection": "...",
  "recommendations": [
    { "block_id": 4940, "service_type": "school", "added_capacity": null, "rationale": "..." }
  ],
  "measured_effects": [
    { "service_type": "pitch", "strong_before": 0.732, "strong_after": 0.781,
      "missing_before": 785, "missing_after": 769, "source": "compute_scenario_provision" }
  ],
  "recommendation_blocks": [4940],
  "confidence": 0.55,
  "confidence_self": 0.78,
  "confidence_basis": ["hypotheses=2/2_supported*0.25=+0.25", "data_basis=1.0*0.30=+0.30"],
  "overlay_candidates": [...],
  "overlay_meta": { "hard_passed": 5, "hard_total": 5, "diagnostic_layers": 1, "nondiagnostic_layers": 0 },
  "limitations": ["..."],
  "artifacts": ["maps/provision.png", "scenario.csv"],
  "run_id": "run_20260706_...",
  "run_dir": "outputs/run_20260706_...",
  "status": "ok",            // "ok" | "partial" | "failed"
  "salvaged": false
}

Полная спецификация: docs/tool_contract.md. Regex-fallback-поля (measured / hypotheses как строковый массив) описаны там же — в fallback-пути с salvaged: true и limitations += ["SALVAGED_ANSWER"].

Локальный запуск

Рабочее локальное окружение уже создано в репозитории:

Путь	Назначение	Git
.python310/	portable Python 3.10.11 для проекта	ignored
.venv/	виртуальное окружение на Python 3.10.11	ignored
requirements.txt	зависимости локального MCP и BlocksNetAgent	yes

.\.venv\Scripts\python.exe -m pytest tests
.\.venv\Scripts\python.exe scripts\smoke_client.py
.\.venv\Scripts\python.exe -m blocksnet_mcp.server

Минимальный .env (текущий шаблон — Ollama Cloud; для OpenAI-совместимых endpoint'ов можно подставить CHAT_URL и MODEL оттуда):

CHAT_URL=https://ollama.com/v1
API_KEY=your_ollama_cloud_api_key_here
MODEL=minimax-m3:cloud
DATA_DIR=./data
OUTPUT_DIR=./outputs
MAX_ITERATIONS=10

Опционально (имеют дефолты в settings.py): DEADLINE_SEC=480 — серверный дедлайн прогона, PROGRESS_INTERVAL_SEC=10.0 — интервал notifications/progress.

Пример конфигурации MCP-клиента:

{
  "mcpServers": {
    "blocksnet": {
      "command": "P:/AI_asistent/ITMO/blocksnet-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "blocksnet_mcp.server"],
      "cwd": "P:/AI_asistent/ITMO/blocksnet-mcp",
      "env": {
        "CHAT_URL": "https://ollama.com/v1",
        "API_KEY": "your_ollama_cloud_api_key_here",
        "MODEL": "minimax-m3:cloud",
        "DATA_DIR": "./data",
        "OUTPUT_DIR": "./outputs",
        "MAX_ITERATIONS": "10"
      }
    }
  }
}

Подробнее: docs/deployment.md.

Индексация WIKI-LLM

Индекс	Назначение
docs/WIKI-LLM.md	Главная карта проекта для LLM-навигации
docs/README.md	Человекочитаемый индекс документации
blocksnet_mcp/README.md	Индекс реализованного MCP-слоя
blocksnet_agent/README.md	Индекс переносимого ядра агента
data/README.md (опц.)	Локальный индекс данных
tests/README.md	Индекс контрактных тестов
scripts/README.md	Индекс локальных smoke-проверок MCP
examples/README.md	Индекс интерактивных блокнотов и локальных примеров

Документация

Документ	О чем
docs/overview_and_concept.md	что строится, зачем MCP-обертка целиком, границы локального режима
docs/architecture.md	структура, модули, поток запроса, транспорт
docs/tool_contract.md	вход и выход analyze_urban_question
docs/deployment.md	локальная установка и подключение MCP-клиента
docs/mcp_repository_plan.md (опц.)	план переноса ядра агента и реализации MVP (локальный, gitignored)
examples/test_visualization.ipynb	интерактивная визуализация тестов, run logs, артефактов и карт
examples/<local-city-example>/	локальные городские примеры/датасеты (например, Санкт-Петербург, Южно-Сахалинск); данные и артефакты держать вне Git
docs/mas_integration_reference.md 🕘	future-справка по MAS/UrbanDB, локальная и gitignored
docs/mas_registration.md 🕘	future-строки реестра Urban services, локальная и gitignored

Статус

Локальный MVP реализован: ядро BlocksNetAgent перенесено, stdio MCP-сервер добавлен, JSON-сериализация и контрактные тесты находятся в tests/. Окружение собрано на Python 3.10.11; pip check чистый, pytest проходит (контрактные + сериализация + P1.1/P1.2/P1.6 unit-тесты), MCP stdio smoke проходит через scripts/smoke_client.py. Текущий LLM-провайдер — Ollama Cloud (minimax-m3:cloud); контракт ответа использует P1.1 submit_answer, P1.2 авторитетную confidence + confidence_self

• confidence_basis, P1.6 overlay_candidates как fallback для recommendation_blocks. Сводный отчёт по результатам качества прогонов от 06.07.2026: docs/reports/run_quality_report_20260706_spb.md.

Источник истины по текущему объему - этот README, docs/WIKI-LLM.md, код blocksnet_mcp/, контракт docs/tool_contract.md и архитектура docs/architecture.md.