Content
# Tool List
A LLM-native quantitative research platform that provides factor management, strategy backtesting, research report analysis and more, and allows AI assistants to directly access the quantitative knowledge base through the MCP protocol.
## Features
- **Factor Knowledge Base** - Factor management, scoring, analysis
- **Strategy Backtesting** - Strategy management, parameter search
- **Research Report Knowledge Base** - PDF upload, RAG conversation
- **Experience Knowledge Base** - Structured research experience, semantic search, knowledge distillation
- **Data Service** - K-line data, factor calculation
- **MCP Protocol** - LLM direct access to quantitative knowledge base
## Quick Start
### 1. Install Dependencies
Install the following dependencies in order:
| No. | Dependency | macOS / Linux | Windows |
|:----:|------|---------------|---------|
| 1 | Docker | [Download Docker Desktop](https://www.docker.com/products/docker-desktop/) | [Download Docker Desktop](https://www.docker.com/products/docker-desktop/) |
| 2 | Node.js 20+ | [Download](https://nodejs.org/) or `brew install node` | [Download installation package](https://nodejs.org/) |
| 3 | pnpm | `npm install -g pnpm` | `npm install -g pnpm` |
| 4 | uv | `curl -LsSf https://astral.sh/uv/install.sh \| sh` | `irm https://astral.sh/uv/install.ps1 \| iex` |
> **Windows Tip**: After installation, restart the terminal to make environment variables take effect.
### 2. Configure Environment Variables
```bash
# Copy environment variable template
cp .env.example .env
```
Edit the `.env` file and fill in the following necessary configurations:
| Configuration Item | Description | Example |
|--------|------|------|
| `PRE_DATA_PATH` | Preprocessed K-line data path | `/Users/xxx/Downloads/coin-binance-spot-swap-preprocess-pkl-1h` |
| `COIN_CAP_PATH` | Market capitalization data path (optional) | `/Users/xxx/Downloads/coin-cap` |
| `LLM_API_URL` | LLM API address | `https://api.openai.com/v1` |
| `LLM_API_KEY` | LLM API key | `sk-xxx` |
### 3. Start the Project
**macOS / Linux:**
```bash
# Clone the project
git clone https://github.com/your-username/quant-research-platform.git
cd quant-research-platform
# Start (automatically install dependencies, start database, start service)
make start local
# View service status
make status
# View logs
make logs local
# Stop service
make stop local
```
**Windows (PowerShell):**
```powershell
# One-click start (automatically install dependencies, start all services, open browser)
uv run python scripts/dev.py start
# Stop all services
uv run python scripts/dev.py stop
# View service status
uv run python scripts/dev.py status
# View logs
uv run python scripts/dev.py logs # All services
uv run python scripts/dev.py logs api # API only
uv run python scripts/dev.py logs -n 100 mcp-factor # Last 100 lines
```
> `scripts/dev.py` is a cross-platform task runner that can also be used on macOS/Linux, equivalent to `make start local`.
> This script will automatically start PostgreSQL, Redis, API, 7 MCP services, and frontend, without the need for manual opening of multiple terminals.
### 4. Access Services
After startup, access:
- Frontend interface: http://127.0.0.1:5173
- API documentation: http://127.0.0.1:8000/docs
## MCP Integration
Through the MCP protocol, LLM can directly access all functions of the platform.
### Claude Configuration
Add the following to `.mcp.json`:
```json
{
"mcpServers": {
"factor-hub": {
"url": "http://localhost:6789/mcp"
},
"data-hub": {
"url": "http://localhost:6790/mcp"
},
"strategy-hub": {
"url": "http://localhost:6791/mcp"
},
"note-hub": {
"url": "http://localhost:6792/mcp"
},
"research-hub": {
"url": "http://localhost:6793/mcp"
},
"experience-hub": {
"url": "http://localhost:6794/mcp"
}
}
}
```
## Development
### Directory Structure
```
quant-research-platform/
├── backend/
│ ├── app/routes/ # HTTP routing layer
│ ├── app/schemas/ # Pydantic models
│ └── domains/ # Business domains
│ ├── mcp_core/ # MCP infrastructure
│ ├── factor_hub/ # Factor knowledge base
│ ├── strategy_hub/ # Strategy backtesting
│ ├── research_hub/ # Research report RAG
│ ├── experience_hub/ # Experience knowledge base
│ ├── data_hub/ # Data service
│ └── note_hub/ # Note management
├── frontend/
│ └── src/
│ ├── features/ # Functional modules
│ ├── components/ # General components
│ └── lib/ # Utility library
├── docker/ # Container configuration
├── docs/ # Documentation
└── factors/ # Factor definition library
```
### Common Commands
```
# Development
make start local # Local development mode
make start dev # Docker development mode
make logs-api # API real-time logs
make logs-frontend # Frontend real-time logs
# Production
make start # Production mode
make healthcheck prod # Health check
```
### Running Modes
| Mode | Command | Description |
|------|------|------|
| local | `make start local` | Run Python/Node locally, only run database in Docker |
| dev | `make start dev` | Full containerization, support hot reload |
| prod | `make start` | Full containerization, optimized build |
## Tech Stack
**Backend**
- FastAPI, SQLAlchemy 2.0, PostgreSQL 16 + pgvector
- LangChain, Redis, aiohttp
- structlog, ruff, pytest
**Frontend**
- React 18, TypeScript, Vite 6
- TanStack Query, Zustand, shadcn/ui
- AG Grid, ECharts, Tailwind CSS
**Infrastructure**
- Docker, Docker Compose, Caddy, Supervisor
## License
MIT
---
## Important Updates
**Factor and section factor files have been migrated to `private/` directory.**
```
# Old location (deprecated)
factors/
sections/
# New location
private/
factors/ # Factor code (.py)
sections/ # Section factors (.py)
metadata/ # Factor metadata (YAML)
```
The `private/` directory has been gitignored and needs to be managed through a separate private repository. See `private/.gitkeep` for details.
