Skip to main content
Glama

Зээлийн чатбот (backend)

Банкны зээлийн мэдээлэл лавлах чатботын backend систем. Хэрэглэгч (харилцагч) зээлийн төлөв, хугацаа хэтэрсэн төлбөр, өр-орлогын харьцаа (DTI) зэрэг асуултыг байгалийн хэлээр асуухад, LangGraph агент нь MCP (Model Context Protocol) серверээр дамжуулан бодит (mock) өгөгдлөөс хариулт бүрдүүлдэг.

Анхаарах зүйл: Энэ бол демо/тестийн систем. Жинхэнэ өгөгдлийн сан, гадаад банкны API, нэвтрэлт (authentication) байхгүй. customer_id нь хүсэлтийн биед шууд дамждаг (аль хэдийн нэвтэрсэн session-г төлөөлнө).

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

  • Python 3.11+, dependency management: uv (pyproject.toml + uv.lock)

  • FastAPI - HTTP API

  • PostgreSQL + SQLAlchemy (async) + Alembic - өгөгдлийн сан, migration

  • LangGraph - агентын orchestration (state graph)

  • LangChain + langchain-google-genai - prompt, LLM холболт (Gemini)

  • MCP Python SDK - зээл/аналитик/харилцагчийн мэдээллийг ил гаргах read-only tool сервер (stdio transport)

  • Pydantic v2 - өгөгдлийн баталгаажуулалт

  • Gradio - гар аргаар туршиж үзэх UI (/ui), үндсэн FastAPI дээр mount хийгдсэн

  • pytest + pytest-asyncio - тест

  • Docker + docker-compose - контейнержүүлэлт

Related MCP server: lending-data-mcp-server

Төслийн бүтэц

app/
├── agent/          # LangGraph: state, prompts, nodes, graph
├── api/            # FastAPI route-ууд, dependency-ууд
├── services/       # loan_service, analytics_service (детерминист!), mcp_client
├── mcp_servers/    # 1 read-only MCP сервер (server.py)
├── config/         # Тохиргоо (Pydantic Settings)
├── database/       # SQLAlchemy models, async session, seed.py
├── schemas/        # Pydantic v2 schema-ууд
├── ui.py           # Gradio UI, /ui дээр FastAPI-д mount хийгдсэн
└── main.py         # FastAPI entrypoint
alembic/             # Migration-ууд
tests/               # pytest тестүүд (бүгд offline ажилладаг)

Өгөгдлийн сан ба сервер архитектур

Энэ төсөл хостын машин дээрх бодит PostgreSQL-ийг ашигладаг (тусдаа docker-с удирдагдах db сервис биш). docker-compose.yml нь зөвхөн app (FastAPI) сервисийг агуулж, host.docker.internal-ээр дамжуулан хостын Postgres-т холбогддог (extra_hosts: host.docker.internal:host-gateway).

Migration нь Alembic скрипт хэлбэрээр хийгддэг (alembic/versions/), харин mock өгөгдлийг python -m app.database.seed скрипт үүсгэдэг (Alembic data migration биш) - учир нь энэ нь дахин ажиллуулахад аюулгүй (idempotent) бөгөөд --reset флагаар дахин үүсгэх боломжтой.

Суулгах, тохируулах

1. Хостын Postgres дээр role/database үүсгэх (нэг удаа)

sudo -u postgres psql -c "CREATE ROLE buren LOGIN PASSWORD 'buren';" 
                       -c "CREATE DATABASE buren_chatbot OWNER buren;"

2. .env файл үүсгэх

cp .env.example .env

Дараа нь .env-д өөрийн MODEL_API_KEY-г (Gemini API key, Google AI Studio-с авна) бичнэ үү. Жинхэнэ LLM дуудлага хийхэд шаардлагатай (үгүй бол /chat нь "API key required for Gemini Developer API" гэсэн 500 алдаа буцаана - энэ бол зөв ажиллаж байгааг илэрхийлнэ, гэхдээ LLM хариу өгөхгүй).

.env.example-ийн агуулга:

DATABASE_URL=postgresql+psycopg://buren:buren@host.docker.internal:5432/buren_chatbot
MODEL=gemini-2.0-flash
MODEL_API_KEY=
MCP_SERVER_PATH=

# Заавал биш: LangSmith трэйсинг
LANGSMITH_TRACING=
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_API_KEY=
LANGSMITH_PROJECT=

Локал (Docker-гүй) хөгжүүлэлт хийх үед DATABASE_URL-д host.docker.internal оронд localhost-г ашиглана:

export DATABASE_URL="postgresql+psycopg://buren:buren@localhost:5432/buren_chatbot"

MCP_SERVER_PATH-г хоосон орхивол програм өөрөө python -m app.mcp_servers.server-ээр серверийг ажиллуулна (custom скрипт зам зааж өгвөл түүнийг ашиглана).

3. Хамааралтай сангуудыг суулгах

uv sync

Migration ажиллуулах

uv run alembic upgrade head

Mock өгөгдөл үүсгэх (seed)

uv run python -m app.database.seed          # аль хэдийн байгаа бол алгасна
uv run python -m app.database.seed --reset  # устгаад дахин үүсгэнэ

Энэ нь 5 харилцагч (сар бүрийн орлого 800,000-5,000,000₮), тус бүрд нь 5-10 зээл (идэвхтэй/хугацаа хэтэрсэн/хаагдсан холимог), сүүлийн 12 сарын төлбөрийн түүхийн хамт үүсгэдэг. Дор хаяж 2 харилцагчид хугацаа хэтэрсэн зээл байгаа. Харилцагчийн ID-ууд тогтмол (uuid5 ашигласан тул дахин seed хийхэд ижил хэвээр байна) - гараар тестлэхэд хэрэг болно.

Тест ажиллуулах

uv run pytest tests/ -v

Бүх тест offline ажилладаг - жинхэнэ Postgres, жинхэнэ Gemini key, жинхэнэ MCP дэд процесс хэрэггүй (in-memory SQLite болон fake LLM/mocked MCP client ашигладаг):

  • test_loan_service.py, test_analytics_service.py - services давхарга (DTI тооцоолол нь LLM-гүйгээр, детерминист код гэдгийг батална)

  • test_agent_graph.py - LangGraph граф, fake LLM-тэй тусгаарлагдсан

  • test_chat_api.py - /chat endpoint, HTTP-ээр бодит хүсэлт илгээж, зөв intent → зөв MCP tool дуудагдсаныг шалгана

  • test_agent_nodes_helpers.py, test_mcp_client.py - жижиг дотоод функцүүдийн regression тест (LLM-ийн хариу боловсруулалт, MCP дэд процессын орчны хувьсагч дамжуулалт)

Локал сервер ажиллуулах (Docker-гүйгээр)

export DATABASE_URL="postgresql+psycopg://buren:buren@localhost:5432/buren_chatbot"
export MODEL_API_KEY="AIza..."
./run.sh   # эсвэл: uv run uvicorn app.main:app --host 0.0.0.0 --port 8000

run.sh нь FastAPI серверийг 8000 порт дээр ажиллуулна (migration/seed хийдэггүй - тэдгээрийг дээрх алхмуудад тусад нь хийсэн байх ёстой).

Gradio UI

Сервер ажиллаж байхад http://127.0.0.1:8000/ui хаягаар нэвтэрч, curl бичихгүйгээр браузер дээрээс шууд туршиж болно:

  • Харилцагч сонгох dropdown - сонгосон харилцагчийн бүх зээлийн мэдээлэл (төрөл, төлөв, үлдэгдэл, сар бүрийн төлбөр), DTI харьцаа хажуу талд шууд харагдана.

  • Чат цонх - чөлөөт бичвэрээр асуулт бичих, эсвэл хажуугийн санал болгож буй асуултууд дээр дарж шууд илгээх боломжтой.

Энэ нь тусдаа процесс биш - /chat endpoint-той адил FastAPI апп дотор ажилладаг тул run.sh, docker compose up ямар ч тохиргоо нэмэлтгүйгээр /ui-г мөн ажиллуулна.

LangSmith трэйсинг (заавал биш)

Агентын граф (intent ангилал, tool дуудлага, LLM хариу) бүрийг LangSmith-т трэйс хэлбэрээр илгээж болно - код өөрчлөх шаардлагагүй, зөвхөн .env-д доорх орчны хувьсагчдыг тохируулна:

LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_API_KEY=lsv2_...
LANGSMITH_PROJECT=<төслийн нэр>

LANGSMITH_TRACING-г хоосон орхивол (эсвэл огт бичихгүй бол) трэйсинг идэвхгүй байна - LangChain/LangGraph эдгээр хувьсагчийг байхгүй бол ямар ч нэмэлт зан үйлгүй хэвээрээ ажиллана.

Анхаарах зүйл: Settings (Pydantic Settings) нь .env-ээс зөвхөн өөрийн зарласан талбаруудыг (жишээ нь database_url, model) уншдаг бөгөөд бусад орчны хувьсагчийг жинхэнэ процессын environment рүү экспортлодоггүй. LangSmith SDK нь os.environ-оос шууд уншдаг тул app/config/settings.py-д load_dotenv()-г эхэнд нь дуудсан - ингэснээр .env доторх бүх түлхүүр (LangSmith-ийнх байх, эсвэл ирээдүйд нэмэгдэх бусад) жинхэнэ орчны хувьсагч болж, Docker дотор env_file-ээр аль хэдийн дамжуулагдсан утгыг дарж бичихгүй.

Docker Compose-оор ажиллуулах

cp .env.example .env   # .env дотор MODEL_API_KEY-г бөглөнө
docker compose up --build

Контейнер эхлэхэд автоматаар: хостын Postgres-г хүлээх → alembic upgrade head → seed скрипт (хоосон бол л ажиллана) → FastAPI сервер асна.

Гадаад MCP клиентүүдэд зориулсан HTTP endpoint

Дотоод (stdio) MCP серверээс гадна, яг ижил bodит tool-уудыг Railway дээр тусдаа сервис хэлбэрээр HTTP-ээр ил гаргасан байгаа - гадаад MCP клиент (жишээ нь Claude, ChatGPT connector) шууд дуудах боломжтой:

  • URL: https://mcp-min-test-production.up.railway.app/mcp (streamable HTTP transport)

  • Health check (нэвтрэлт шаардахгүй): https://mcp-min-test-production.up.railway.app/health

  • Нэвтрэлт: Authorization: Bearer <MCP_HTTP_TOKEN> толгой заавал шаардлагатай (/health-с бусад бүх хүсэлтэд) - токенгүй эсвэл буруу бол 401 буцаана.

  • Tool/resource/prompt-ууд: дотоод серверийн (app/mcp_servers/server.py) яг адилхан бүрэн жагсаалт - get_active_loans, get_loan_by_id, get_overdue_payments, calculate_dti, get_customer_income, get_customer_profile tool-ууд; resource://loan-types, resource://loan-statuses эх сурвалж; summarize_overdue, explain_dti prompt-ууд. Жинхэнэ (Neon) Postgres-тэй холбогддог тул хариу нь бодит өгөгдөл.

Нэрийн тухай: Railway дээрх сервисийн нэр нь mcp-min-test (анх Railway deploy/healthcheck-ийг оношлох зорилготой хамгийн бага хамааралтай туршилтын сервер байсан түүхийн улбаатай, mcp_min/ фолдер), гэхдээ одоо mcp_min/Dockerfile нь бусад бодит tool-уудтай ижил mcp_service/server.py-г ашигладаг тул бүрэн бодит сервис.

Жишээ (Python, mcp SDK-ийн streamable HTTP клиент ашиглан):

import asyncio
import httpx
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

URL = "https://mcp-min-test-production.up.railway.app/mcp"
TOKEN = "<MCP_HTTP_TOKEN-ийн утга>"

async def main() -> None:
    headers = {"Authorization": f"Bearer {TOKEN}"}
    async with httpx.AsyncClient(headers=headers, timeout=30) as http_client:
        async with streamable_http_client(URL, http_client=http_client) as (read, write):
            async with ClientSession(read, write) as session:
                await session.initialize()
                result = await session.call_tool(
                    "calculate_dti", {"customer_id": "f430bc26-9001-5579-bc8e-7051ff612b88"}
                )
                print(result.content)

asyncio.run(main())

API жишээ

GET /health

curl http://127.0.0.1:8000/health

POST /chat

curl -X POST http://127.0.0.1:8000/chat 
  -H "Content-Type: application/json" 
  -d '{
    "customer_id": "f430bc26-9001-5579-bc8e-7051ff612b88",
    "message": "Миний DTI хэд вэ?"
  }'

Жишээ хариу:

{
  "response": "Таны өр-орлогын харьцаа (DTI) 31.72% байна. Энэ мэдээлэл нь зөвхөн лавлагааны зорилготой бөгөөд зээлийн шийдвэр гаргах үндэслэл болохгүй.",
  "intent": "DTI_RATIO",
  "data": {
    "dti": {
      "customer_id": "f430bc26-9001-5579-bc8e-7051ff612b88",
      "monthly_income": 950000.0,
      "total_monthly_debt_payments": 301339.04,
      "dti_ratio": 31.72
    }
  }
}

Дэмжигдсэн асуултын төрлүүд (intent):

Intent

Жишээ асуулт

ACTIVE_LOANS

"Миний идэвхтэй зээлүүд юу вэ?"

OVERDUE_STATUS

"Надад хугацаа хэтэрсэн төлбөр байна уу?"

DTI_RATIO

"Миний өр-орлогын харьцаа хэд вэ?"

LOAN_DETAIL

"Миний машины зээлийн талаар хэлж өгөөч"

GENERAL_SUMMARY

"Миний зээлийн ерөнхий байдлыг хэлж өгөөч"

OUT_OF_SCOPE

Зээлтэй холбоогүй асуулт (шинэ зээл авах, цаг агаар г.м)

Хариу нь хэрэглэгчийн бичсэн хэлийг (монгол/англи) тольдоно.

Чухал зарчмууд

  • DTI тооцоолол нь бодит код (services/analytics_service.py) хийдэг - LLM тоо тооцдоггүй, зөвхөн бэлэн үр дүнг байгалийн хэлээр илэрхийлдэг.

  • Санхүүгийн бүх хариу нь сануулга өгүүлбэртэй дуусна ("Энэ мэдээлэл нь зөвхөн лавлагааны зорилготой...") - энэ нь prompt-д бичигдсэн, кодоор залгаагүй тул хожим засварлахад хялбар.

  • MCP сервер зөвхөн унших (read-only) - write/update/delete tool байхгүй.

  • Бүх мөнгөн дүн MNT (төгрөг)-өөр илэрхийлэгдэнэ, валют хөрвүүлэлт хийгддэггүй.

Хөгжүүлэлтийн талаар нэмэлт мэдээлэл

AGENTS.md файлд төслийн дизайны шийдвэрүүд, нарийн ширийн зүйлс (жишээ нь: "идэвхтэй зээл" гэдэг нь яг status == 'active' гэсэн үг, overdue-с ялгаатай; MCP хариуны JSON бүтцийн конвенц г.м) илүү дэлгэрэнгүй бичигдсэн.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Exposes a governed lending portfolio (loans, customers, risk-tier history) to any MCP-compatible AI client via read-only tools, schema resources, and analysis prompts, wrapping an existing API gateway instead of connecting directly to the database.
      -
    • A
      license
      A
      quality
      D
      maintenance
      A production-grade MCP server for a Loan Management System backed by Microsoft Dataverse, exposing read and analytics tools for loan applications.
      12
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server that lets any LLM client query the Home Credit Default Risk SQLite database (307,511 loan applications) through 7 read-only tools, 4 resources, and 1 prompt over stdio, with natural language, SQL, and tool-calling interfaces.
      -