Content
# bidding-automation
> Automated workflow system for law firm's bidding and award applications
[](https://www.apache.org/licenses/LICENSE-2.0)
[](https://www.python.org/)
[](CHANGELOG.md)
Automatically discovers law firm's material files (DOCX/PPTX/PDF), identifies candidate cases, extracts fields, and generates four types of outputs: team introduction, bidding performance, award application, and award report. Provides three entry points: local web website, CLI, and MCP Server.
## Table of Contents
- [Features](#features)
- [Quick Start](#quick-start)
- [Usage](#usage)
- [MCP Configuration](#mcp-configuration)
- [API Reference](#api-reference)
- [Project Structure](#project-structure)
- [Configuration](#configuration)
- [Contributing](#contributing)
- [License](#license)
## Features
- **Automatic Case Material Discovery**: Scans folders, removes duplicates using SHA256, and groups files into candidate cases using rules
- **Field Extraction**: Uses pandoc for text extraction, with optional LLM field extraction (OpenAI compatible API)
- **Review Workflow**: Five modes (auto-approve/manual/filtered/batch/skip)
- **4 Types of Outputs**:
| Output | Format | Purpose |
|------|------|------|
| Team Introduction | DOCX | Law firm/team introduction |
| Bidding Performance | DOCX | Bidding performance list |
| Award Application | DOCX | Excellent case application material |
| Award Report | PPTX | Case report presentation |
- **3 Entry Points**:
- Local web website (bottle.py, 127.0.0.1:8765, 6 Tab single-page application)
- CLI (8 subcommands)
- MCP Server (9 tools, stdio + SSE dual-mode, supports Claude Code/Cursor/Trae)
- **Portable**: Supports mobile hard drive workspaces, can be used on any team computer
## Quick Start
### Developer Installation
```bash
# Clone repository
git clone https://github.com/66666-design/bidding-automation.git
cd bidding-automation
# Create virtual environment (Python 3.13+)
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate
# Install dependencies
pip install -e .
# Optional: install Web + MCP dependencies
pip install -e ".[web,mcp]"
# Initialize workspace
bidding-cli init --workspace ./my-workspace
# End-to-end pipeline (scan → detect → extract → review → build)
bidding-cli pipeline --folder ./cases --target all
```
### Start Web Website
```bash
python app/app.py
# Automatically open browser to http://127.0.0.1:8765/
```
### Start MCP Server
```bash
# SSE mode (any agent can connect)
python app/mcp_server_http.py --port 8766
# stdio mode (Claude Code/Cursor direct start)
python app/mcp_server.py
```
## Usage
### CLI
```bash
# Environment self-test
bidding-cli env-probe
# Scan folder
bidding-cli scan --folder D:\案件材料
# Case grouping
bidding-cli detect
# Field extraction (skip LLM)
bidding-cli extract --skip-llm
# View pending cases
bidding-cli review --list --status pending
# Auto-approve all pending cases
bidding-cli review --auto-approve --docs team_intro,tender,award
# Build outputs
bidding-cli assemble --target all
# End-to-end pipeline
bidding-cli pipeline --folder D:\案件材料 --target all --auto-approve
```
### Web Website
Visit `http://127.0.0.1:8765/`, 6 Tabs:
1. **Status** — System information + case statistics
2. **Material Library** — Reference material list
3. **Cases** — Case list (filtered by status)
4. **Review** — Review pending cases
5. **Build** — Build DOCX/PPTX outputs
6. **Outputs** — Download generated outputs
### MCP Server
See [MCP Configuration](#mcp-configuration) section.
## MCP Configuration
### Claude Desktop / Cursor (stdio mode)
Add to MCP configuration file:
```json
{
"mcpServers": {
"bidding": {
"command": "python",
"args": ["D:\\path\\to\\bidding-automation\\app\\mcp_server.py"]
}
}
}
```
### Trae / Any Agent (SSE mode)
Start SSE Server:
```bash
python app/mcp_server_http.py --port 8766
```
Client configuration:
```json
{
"mcpServers": {
"bidding-http": {
"url": "http://127.0.0.1:8766/sse"
}
}
}
```
### 9 MCP Tools
| Tool | Purpose |
|------|------|
| `bidding_status` | System status + case statistics |
| `bidding_scan` | Scan folder |
| `bidding_detect` | Case grouping |
| `bidding_extract` | Field extraction (optional LLM) |
| `bidding_list_cases` | List cases (with title fallback) |
| `bidding_review_case` | Review case |
| `bidding_build` | Build DOCX/PPTX outputs |
| `bidding_pipeline` | End-to-end pipeline (agent one-click call) |
| `bidding_list_outputs` | List generated outputs |
## API Reference
| Method | Path | Description |
|------|------|------|
| GET | `/api/status` | System status + case statistics |
| GET | `/api/reference` | Reference material list |
| GET | `/api/output` | Generated outputs |
| GET | `/api/download/<filename>` | Download output |
| POST | `/api/scan` | Scan folder |
| POST | `/api/detect` | Case grouping |
| POST | `/api/extract` | Field extraction |
| GET | `/api/cases?status=pending` | Case list |
| POST | `/api/cases/<id>/decision` | Update case decision |
| POST | `/api/build` | Build outputs |
| POST | `/api/pipeline` | End-to-end pipeline |
## Project Structure
```
bidding-automation/
├── src/bidding_automation/
│ └── case_sync/ # Case synchronization core subpackage
│ ├── scanner.py # File scanning + SHA256 deduplication
│ ├── case_detector.py # Case grouping
│ ├── extractor.py # Text extraction + LLM field extraction
│ ├── reviewer.py # Review workflow
│ ├── assembler.py # Output assembler coordinator
│ ├── assemblers/ # 4 output assemblers
│ ├── config.py # Workspace configuration + tool lookup
│ ├── db.py # SQLite schema
│ ├── models.py # Data models
│ ├── env_probe.py # Environment self-test
│ └── cli.py # CLI entry point
├── app/ # Web + MCP applications
│ ├── app.py # bottle.py Web entry point
│ ├── bidding_client.py # Core encapsulation (Web + MCP shared)
│ ├── bidding_mcp_tools.py # MCP tool definitions
│ ├── mcp_server.py # stdio MCP Server
│ ├── mcp_server_http.py # SSE MCP Server
│ └── static/ # Web frontend
├── scripts/ # Test and tool scripts
├── pyproject.toml
├── CHANGELOG.md
├── LICENSE
└── README.md
```
## Configuration
### Workspace Directory Structure
```
my-workspace/
├── cases/ # Pending case materials
├── reference/ # Reference materials (team introduction templates, bidding templates, etc.)
├── output/ # Generated outputs
├── state/ # Runtime state (SQLite db, PID files)
└── config.yaml # Optional: tool configuration (LLM API Key, pandoc path, etc.)
```
### config.yaml Example
```yaml
llm:
api_key: sk-xxx
base_url: https://api.openai.com/v1
model: gpt-4o-mini
tools:
pandoc: D:\tools\pandoc\pandoc.exe
libreoffice: C:\Program Files\LibreOffice\program\soffice.exe
ocr:
provider: paddleocr # or siliconflow
siliconflow_api_key: sk-xxx
```
## Contributing
Welcome to submit issues and pull requests.
1. Fork this repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m 'Add amazing feature'`)
4. Push branch (`git push origin feature/amazing-feature`)
5. Submit pull request
## License
[Apache-2.0](LICENSE)
