MCP数据库分析代理
最低限度 MCP风格 具有两个独立组件的自然语言数据库查询系统：
- 只读SQLite服务器 （FastAPI）--公开用于模式发现和查询执行的安全工具
- AI 代理 （Groq LLM）——理解英语或希伯来语的问题，生成SQL，安全执行，自我纠正错误，并返回清晰的答案
亮点:
- 基于工具的架构（MCP风格）
- 严格的只读强制（服务器端+提示符）
- 自动架构发现
- 自校正循环（最多3次重试）
- 双语支持（希伯来语+英语）
- 干净的模块化代码（src/layout，主逻辑中没有黑客）
- 综合测试套件（23/23通过）
- 额外的Streamlit网络用户界面
项目结构（src布局）
mcp_d_banalyst_赋值/
├── src/
│ ├── 代理商/
│ │ ├── init.py
│ │ ├── agent_main.py#CLI入口点
│ │ ├── llm_client.py
│ │ ├── mcp_client.py
│ │ ├── agent_loop.py
│ │ ├── ui.py#流式网络界面
│ │ └── 需求.txt
│ ├── 普通/
│ │ ├── init.py
│ │ └── prompts.py
│ ├── 服务器/
│ │ ├── 服务器.py
│ │ ├── init_db.py
│ │ └── 需求.txt
│ └── 测试/
│ ├── test_agent_end_to_end.py
│ ├── test_llm.py
│ ├── test_readonly.py
│ ├── test_valid_queries.py
│ ├── test_init_db.py
│ └── test_server.py
├── pyproject.toml
├── README.md
Mabalin遇到了i-print学生。
├── .env
└── docs/
└── ui-example.png#用户界面截图
text##安装
先决条件
- Python 3.9+
- Groq API密钥（免费https://console.groq.com/keys)
设置
# Clone & enter project
git clone https://github.com/Alexey-Butov/mcp-db-analyst-assignment.git
cd mcp-db-analyst-assignment
# Create & activate venv (recommended)
python -m venv venv
venv\Scripts\activate
# Install project + dependencies
pip install -e .
pip install -r src/agent/requirements.txt
pip install -r src/server/requirements.txt
pip install -r src/tests/requirements.txt # optional – for running tests
pip install streamlit # for UI
Create .env in root:
envGROQ_API_KEY=your_groq_api_key_here
GROQ_MODEL=llama-3.3-70b-versatile
MCP_SERVER_URL=http://127.0.0.1:8000
Initialize Database
Bashpython src/server/init_db.py
Creates src/server/db.sqlite3 with sample products & orders tables.
Running the Components
1. Start the Read-Only Server
Bashcd src/server
uvicorn server:app --reload
Endpoints:
GET /list_tables
POST /run_sql_query
GET /health
Keep this terminal open.
2. Run the Agent CLI
From project root:
Bashpython -m agent.agent_main "מה המוצר הכי זול?"
or
Bashpython src/agent/agent_main.py "כמה הכנסות היו בחודש מאי?"
3. Run the Web UI (Bonus)
Bashstreamlit run src/agent/ui.py
Opens in browser at http://localhost:8501
Ask natural-language questions (supports Hebrew & English).
UI Screenshot
MCP Database Analyst UI
Example: Asking "כמה הכנסות היו בחודש מאי?"
Running Tests
23 tests covering:
End-to-end agent flow (including refusal on impossible questions)
LLM connectivity & instruction following
Read-only enforcement
Valid SQL execution
DB initialization
Server health check
Run from root (venv activated):
Bashpytest -v
Coverage report (current ~46%):
Bashpytest --cov=agent --cov=common --cov=server --cov-report=term-missing tests/
All tests pass (23/23). Focus on core logic; UI & setup scripts untested.
Summary
Fully implements the assignment requirements:
MCP-style separation (server ↔ agent via HTTP tools)
Read-only enforcement (server-side + prompt)
Schema discovery & SQL generation
Self-correction loop
Bilingual support
Clean code, src layout, no hacks
Comprehensive tests & basic coverage
Ready for review.
Made with ❤️ by Alexey Butov```