Metadata-Version: 2.4
Name: survey-collector-mcp
Version: 0.1.2
Summary: MCP server for survey collection with LLM-powered intelligent follow-up questions
Author-email: Your Name <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/survey-collector-mcp
Project-URL: Documentation, https://github.com/yourusername/survey-collector-mcp#readme
Project-URL: Repository, https://github.com/yourusername/survey-collector-mcp
Project-URL: Issues, https://github.com/yourusername/survey-collector-mcp/issues
Keywords: mcp,survey,llm,fastmcp,ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=0.1.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# Survey Collector MCP Server

[![PyPI version](https://badge.fury.io/py/survey-collector-mcp.svg)](https://pypi.org/project/survey-collector-mcp/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

MCP server for survey collection with LLM-powered intelligent follow-up questions.

## Features

- 📋 **Survey Collection**: Send questions to groups and collect replies
- 🤖 **LLM-powered Follow-up**: Automatically generate follow-up questions based on replies
- 📊 **Criteria Evaluation**: Multiple evaluation criteria (all replied, majority agree, etc.)
- 📝 **Summary Reports**: Auto-generate Markdown summary reports

## Installation

### Via pip
```bash
pip install survey-collector-mcp
```

### Via uvx (recommended)
```bash
uvx survey-collector-mcp
```

### Upgrade to latest version
```bash
pip install --upgrade survey-collector-mcp
# or
uvx --upgrade survey-collector-mcp
```

## Usage

### Local Mode (stdio)
Add to your `mcp.json`:
```json
{
  "mcpServers": {
    "survey-collector": {
      "command": "uvx",
      "args": ["survey-collector-mcp"]
    }
  }
}
```

### Remote Mode (SSE)
Start the server:
```bash
survey-collector --transport sse --host 0.0.0.0 --port 8001
```

Client configuration:
```json
{
  "mcpServers": {
    "survey-collector": {
      "url": "http://localhost:8001/sse"
    }
  }
}
```

## Tools

### collect_survey_info
Execute a complete survey workflow with intelligent follow-up.

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| chat_id | string | Yes | Group chat ID |
| members | string | Yes | Member names, comma-separated |
| question | string | Yes | Survey question |
| criteria | string | No | Evaluation criteria (default: all_replied) |
| follow_up_rule | string | No | Follow-up rule in natural language |
| max_rounds | int | No | Max follow-up rounds (default: 5) |
| timeout_per_round | int | No | Timeout per round in seconds (default: 600) |

**Example:**
```
Question: "周一上午有没有时间打球？"
Follow-up rule: "如果对方说没时间，每次追问日期往后推一天"

Result:
- Round 1: "周一上午有没有时间打球？"
- Round 2: "周二上午有没有时间打球？" (LLM generated)
- Round 3: "周三上午有没有时间打球？"
```

## Configuration

Set environment variables or create `.env` file:

```bash
# HITL Platform
HITL_SERVICE_URL=https://hitl.woa.com/api

# LLM API (for intelligent follow-up)
LLM_API_BASE=https://api.deepseek.com/v1
LLM_API_KEY=your-api-key
LLM_MODEL=deepseek-chat

# Debug mode
DEBUG=false
```

## 📚 Documentation

- **Quick Start**: [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) - 3-step guide
- **Interaction Guide**: [INTERACTION_GUIDE.md](./INTERACTION_GUIDE.md) - Standard inquiry process
- **Remote Deployment**: [README_REMOTE.md](./README_REMOTE.md) - Team deployment
- **Troubleshooting**: [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) - Problem diagnosis
- **Config Examples**: [config/mcp-examples/](./config/mcp-examples/) - Different scenarios
- **Survey Template**: [config/survey-template.json](./config/survey-template.json) - Configuration template

## License

MIT License
