# MCP Server: Generate Manual Test Cases
This MCP server provides the **generate_testcases** tool to generate manual test cases from **documentation** and **rules** you supply.
## Installation
```bash
npm install
npm run build
```
## Running the server
- **Production:** `npm start` (runs `node dist/index.js`)
- **Development:** `npm run dev` (runs with ts-node)
The server communicates over **stdio** (stdin/stdout) and is intended to be started by Cursor or another MCP client.
## Configuring in Cursor
Add to your MCP config (e.g. Cursor: **Settings → MCP** or `~/.cursor/mcp.json`):
```json
{
"mcpServers": {
"manual-testcases": {
"command": "node",
"args": ["/PATH/TO/PROJECT/dist/index.js"]
}
}
}
```
Example with a real path:
```json
{
"mcpServers": {
"manual-testcases": {
"command": "node",
"args": ["/Users/huenguyen/Desktop/hue-data/hue-data/workspace/mcp-manual-testcases/dist/index.js"]
}
}
}
```
After adding this, Cursor will expose the **generate_testcases** tool from this server.
## Tool: `generate_testcases`
Generates test cases from documentation and rules.
### Parameters
| Parameter | Required | Description |
|---------------------|----------|-------------|
| `document_content` | No | Document content (text). Omit if using `document_path`. |
| `document_path` | No | Path to the document file (txt, md, or **PDF**). Prefer when available. |
| `output_format` | No | `"markdown"` (default) or `"csv"`. CSV uses columns: 模块,标题,前置条件,步骤描述,预期结果,test1测试人员,test1测试结果,buglink,PRE测试人员,PRE测试结果,buglink. |
| `rules` | Yes | Rules for generating test cases (format, priority, scope, language, etc.). |
| `use_llm` | No | Default `true`. If `true` and client supports sampling, the LLM is used to generate test cases; if `false`, only the formatted prompt is returned. |
| `max_tokens` | No | Max tokens for the LLM response (default 4096). |
**Note:** At least one of `document_content` or `document_path` is required.
### How it works
1. **Read document:** From `document_content` or by reading the file at `document_path`. **PDF** files are supported (text is extracted automatically).
2. **Combine with rules:** Build a prompt from document + rules.
3. **Generate test cases:**
- If `use_llm === true` and the client (e.g. Cursor) supports **sampling** (LLM): the server sends a request to the client so the LLM generates test cases and returns the result.
- Otherwise (client does not support sampling or `use_llm === false`): the server returns the **formatted prompt** for you to copy and use with an external LLM.
### Example rules
- "Output test cases as a table: ID, Description, Preconditions, Steps, Expected result, Priority."
- "Priority P1 for login/payment flows; P2 for secondary screens."
- "Output language: English."
- "Each scenario has at most 10 steps; split into multiple scenarios if more complex."
### Example usage in Cursor
You can ask the AI in Cursor, for example:
- "Use the generate_testcases tool: document_path is `docs/feature-login.md`, rules are 'Table format, English, P1 for happy path'."
- Or paste document content and use `document_content` with `rules`.
## Generate test cases locally (script)
The script reads **doc** (txt, md, or **PDF**) and **rules**, then either calls OpenAI to generate test cases or prints the formatted prompt.
**Environment variables:**
| Variable | Description |
|-------------------|-------------|
| `DOC_PATH` | Path to requirement document (default: `samples/doc-example.md`). **PDF is supported.** |
| `RULES_PATH` | Path to rules file (default: `samples/rules-example.txt`). |
| `OUTPUT_FORMAT` | `prompt` (default) or `csv`. |
| `OUTPUT_FILE` | Output file path. For CSV, default is `samples/generated-testcases.csv`. |
| `OPENAI_API_KEY` | If set, the script calls OpenAI to generate test cases. |
**Examples:**
```bash
# Print formatted prompt (no API key needed)
npm run generate-testcases
# Read requirement from PDF and output CSV (requires OPENAI_API_KEY)
export OPENAI_API_KEY=sk-your-key
export DOC_PATH=path/to/requirements.pdf
export RULES_PATH=samples/rules-example.txt
export OUTPUT_FORMAT=csv
export OUTPUT_FILE=samples/generated-testcases.csv
npm run generate-testcases
```
CSV columns match the rules format: 模块, 标题, 前置条件, 步骤描述, 预期结果, test1测试人员, test1测试结果, buglink, PRE测试人员, PRE测试结果, buglink.
## Quick try with samples
The `samples/` folder contains:
- `doc-example.md` — sample requirement doc (中控后台PC, 6.1–6.4). It references prototype images in `Images/` (image1.png–image4.png).
- `images/` (or `Images/`) — prototype screenshots; when present next to the doc, the script and MCP prompt include the image list so generated test cases can reference them (e.g. “参照原型 Images/image1.png”).
- `rules-example.txt` — sample rules (table columns, 模块 format 代理后台-AGBE/…, language, strict/quality rules).
Generate test cases from doc + images + rules (MCP or script):
- **MCP:** Call tool `generate_testcases` with `document_path`: `samples/doc-example.md`, `rules`: content from `samples/rules-example.txt`, and optionally `output_format`: `"csv"` or `"markdown"`.
- **Script:** `DOC_PATH=samples/doc-example.md RULES_PATH=samples/rules-example.txt OUTPUT_FORMAT=both npm run generate-testcases` (set `OPENAI_API_KEY` for LLM generation).
## Project structure
```
mcp-manual-testcases/
├── src/
│ └── index.ts # MCP server + generate_testcases tool
├── samples/
│ ├── doc-example.md # Sample requirement (references Images/)
│ ├── images/ # Prototype images (image1.png …)
│ ├── rules-example.txt # Sample rules
│ ├── generated-testcases.md
│ └── generated-testcases.csv
├── dist/ # Build output (after npm run build)
├── package.json
├── tsconfig.json
└── README.md
```
## License
ISC
depend on doc-example.md and images folder generate tescase for the feature depend on mcp and rules
