Metadata-Version: 2.4
Name: code-reviewer-mcp
Version: 0.1.0
Summary: Robot Framework MCP Server
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: beautifulsoup4==4.13.3
Requires-Dist: chardet==5.2.0
Requires-Dist: cerberus==1.3.5
Requires-Dist: et-xmlfile==2.0.0
Requires-Dist: jmespath==1.0.1
Requires-Dist: lxml==5.3.1
Requires-Dist: numpy
Requires-Dist: openpyxl==3.1.5
Requires-Dist: pandas
Requires-Dist: python-dateutil==2.9.0.post0
Requires-Dist: pytz==2025.2
Requires-Dist: PyYAML==6.0.2
Requires-Dist: robotframework==7.2.2
Requires-Dist: six==1.17.0
Requires-Dist: soupsieve==2.6
Requires-Dist: typing-extensions==4.12.2
Requires-Dist: tzdata==2025.2
Requires-Dist: XlsxWriter==3.2.3
Requires-Dist: mcp>=1.0.0

## Pre-requisite
1. Install Python v3.8+
2. Install Pycharm IDE or any Git-enabled editor
3. Install Git if you plan to push to Bitbucket

## Robot Automated Code review repo
1. Clone or download the utility code from the JEIQ repository.

## Quick Setup (recommended)

Use the provided bootstrap script from the repo root:

```powershell
.\scripts\bootstrap.ps1
```

This will:
- create `.venv` if needed
- upgrade `pip`
- install everything from `requirements.txt`

> The bootstrap step requires access to your Python package index (public PyPI or your internal mirror / Artifactory).

### Manual setup (optional)

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

## To Execute Automated Code review utility (CLI)
	1. Run `python Main.py` — you will be prompted interactively for the project directory.
	   Alternatively pass it as an argument:
	   ```powershell
	   .\.venv\Scripts\python.exe .\Main.py C:\path\to\your\rf_project
	   .\.venv\Scripts\python.exe .\Main.py C:\path\to\your\rf_project C:\Reports
	   .\.venv\Scripts\python.exe .\Main.py C:\path\to\your\rf_project output_report.xlsx
	   ```
	2. Wait until execution is complete.
	3. Verify that the Excel file is created under the project repository.

	> **No config.ini required** — the directory is supplied at runtime.
	> The second argument can be either a target **directory** (timestamped Excel file will be created there)
	> or an explicit `.xlsx` file path.

---

## MCP Server (Model Context Protocol)

The project also exposes an MCP server (`mcp_server.py`) that can be used by AI assistants (Claude Desktop, GitHub Copilot, etc.) to invoke code review and script generation tools programmatically.

### Setup
```bash
pip install -r requirements.txt   # includes mcp>=1.0.0
```

### Running the MCP Server

**Stdio transport (default – for Claude Desktop / MCP clients):**
```powershell
.\scripts\start-mcp.ps1
```

**SSE transport (for HTTP-based clients):**
```powershell
.\scripts\start-mcp.ps1 -Sse -Port 8000
```

Custom path example:

```powershell
.\scripts\start-mcp.ps1 -Sse -BindHost 0.0.0.0 -Port 8000 -SsePath /sse
```

Optional bind-host example:

```powershell
.\scripts\start-mcp.ps1 -Sse -BindHost 0.0.0.0 -Port 8000
```

### Run as a Windows Service (recommended for deployment)

Use the service manager script to install and operate the MCP server as a background service.

> Run these commands in an **elevated PowerShell** (Run as Administrator).

Install or update the service:

```powershell
.\scripts\manage-mcp-service.ps1 -Action install -ServiceName RobotFrameworkMcp -BindHost 0.0.0.0 -Port 8000
```

Install or update the service with explicit SSE path:

```powershell
.\scripts\manage-mcp-service.ps1 -Action install -ServiceName RobotFrameworkMcp -BindHost 0.0.0.0 -Port 8000 -SsePath /sse
```

Start/stop/restart/status:

```powershell
.\scripts\manage-mcp-service.ps1 -Action start   -ServiceName RobotFrameworkMcp
.\scripts\manage-mcp-service.ps1 -Action stop    -ServiceName RobotFrameworkMcp
.\scripts\manage-mcp-service.ps1 -Action restart -ServiceName RobotFrameworkMcp
.\scripts\manage-mcp-service.ps1 -Action status  -ServiceName RobotFrameworkMcp
```

Uninstall the service:

```powershell
.\scripts\manage-mcp-service.ps1 -Action uninstall -ServiceName RobotFrameworkMcp
```

Notes:
- The service runs `mcp_server.py` in SSE mode.
- Default endpoint after start is `http://<server-host>:8000/sse`.
- The script configures auto-restart on service failure.
- If your repo is in a custom location, pass `-RepoRoot "D:\path\to\repo"`.
- If deployed behind an ingress/proxy, client URL must still use `/sse` unless you configured a custom `-SsePath`.

### Connecting from VS Code (`.vscode/mcp.json`)

This repo now includes a VS Code MCP template at:
```json
{
  "mcpServers": {
	"robot-framework-review": {
	  "command": "D:\\Tools\\code_review_checklist\\.venv\\Scripts\\python.exe",
	  "args": [
		"D:\\Tools\\code_review_checklist\\mcp_server.py"
	  ],
	  "env": {}
	}
  }
}
```
```text
.vscode/mcp.json.example
```

To enable the server in VS Code:

1. Copy `.vscode/mcp.json.example` to `.vscode/mcp.json`
2. Replace `<REPO_PATH>` with the absolute path to your cloned repository
3. Choose **one** connection mode:
   - `robot-framework-review-stdio` → VS Code launches `mcp_server.py` directly
   - `robot-framework-review-sse` → VS Code connects to an already-running SSE server

#### Option A — VS Code launches the server directly (recommended)

Create or edit `.vscode/mcp.json` like this:

```json
{
  "$schema": "vscode://schemas/mcp",
  "servers": {
	"robot-framework-review": {
	  "type": "stdio",
	  "command": "D:\\Tools\\code_review_checklist\\.venv\\Scripts\\python.exe",
	  "args": [
		"D:\\Tools\\code_review_checklist\\mcp_server.py"
	  ]
	}
  }
}
```

Use this mode when:
- you want the simplest setup
- VS Code should start/stop the MCP server for you
- you are running locally on your own machine

#### Option B — VS Code connects to an already-running SSE server

First start the server yourself:

```powershell
.\scripts\start-mcp.ps1 -Sse -Port 8000
```

Then configure `.vscode/mcp.json` like this:

```json
{
  "$schema": "vscode://schemas/mcp",
  "servers": {
	"robot-framework-review": {
	  "type": "sse",
	  "url": "http://127.0.0.1:8000/sse"
	}
  }
}
```

Use this mode when:
- the server is hosted on another machine / VM
- you want to run the MCP server independently of VS Code
- you want multiple tools or users to connect to the same running server

Deployed server example:

```json
{
	"$schema": "vscode://schemas/mcp",
	"servers": {
		"robot-framework-review": {
			"type": "sse",
			"url": "https://dev.testautomation.jnj.com/sse"
		}
	}
}
```

#### Notes for VS Code setup

- Keep `.vscode/mcp.json` **local** to your machine; it is ignored by `.gitignore`.
- Commit only `.vscode/mcp.json.example`.
- If you change the port in `start-mcp.ps1`, update the `url` in the SSE config to match.
- If you move the repo folder, update the `command` and `args` paths in the stdio config.
- `/ss` or `/ssee` are not valid default endpoints for this server. Use `/sse`.

### Available MCP Tools

| # | Tool | Purpose |
|---|---|---|
| 1 | `review_robot_project` | Full project review — runs all analyses, generates Excel, returns checklist + comments |
| 2 | `analyze_data_files` | Data folder only — naming, duplicates, cross-env consistency |
| 3 | `analyze_test_cases` | Test case files — settings, Gherkin format, Jira tags, docs |
| 4 | `analyze_keywords` | Keywords — docs, duplicates, XPaths, screenshots, sleep count |
| 5 | `analyze_other` | Jira/qTest, JPM pipeline config, credentials, Sample folder |
| 6 | `get_review_summary` | Pass/fail checklist with percentages, no Excel output |
| 7 | **`get_checklist_guidelines`** | Returns all checklist rules + actionable how-to guidance for **other AI/MCP tools** to follow when writing Robot scripts |
| 8 | **`generate_and_review_robot_script`** | Generates a `.robot` script AND immediately runs the full project review — all in one call |
| 9 | `generate_robot_test_script` | Generate a `.robot` test file from structured JSON input |
| 10 | `generate_robot_support_file` | Generate a support/resource `.robot` file with keywords |
| 11 | `generate_robot_data_file` | Generate a Python data file for test data variables |

> **All tools accept `directory_path` as a parameter — no `config.ini` needed.**
>
> **Response size note:** review/analysis MCP tools now return compact summaries by default.
> Use flags like `include_rows=true`, `include_comments=true`, or `include_checklist=true`
> when you explicitly want detailed row payloads.
>
> **Excel output note:** `review_robot_project` now expects a user-provided `report_output_directory`
> when `generate_excel=true`, and it writes the report file into that directory.

### Example: Generate a Robot Script via MCP

The `generate_robot_test_script` tool accepts:
- `script_type`: `web`, `api`, `database`, or `mobile`
- `test_name`: Name of the test case
- `jira_id`: Jira ticket ID (e.g. `PROJ-1234`)
- `description`: High-level test description
- `test_steps`: JSON string with Gherkin steps
- `keywords`: JSON string with keyword definitions
- `variables`: JSON string with variables
- `include_keywords_section`: defaults to `false` so generated test files stay aligned with the review checklist
- `output_path`: File path to write the .robot file

## Guided Prompt Templates for Users

If you want users to get cleaner, more appealing, and less noisy AI output, use the guided prompt templates in:

```text
prompts/USER_GUIDED_PROMPTS.md
```

This prompt guide includes ready-to-copy prompts for:
- generating new Robot Framework scripts
- improving an existing script
- removing unnecessary content
- making test steps more appealing and reviewer-friendly
- asking users for missing inputs like project path and report output directory
- reviewing generated scripts against the checklist

Recommended usage order:

1. Ask for missing inputs using the prompt in `USER_GUIDED_PROMPTS.md`
2. Generate the script
3. Remove unnecessary content
4. Review the script against the checklist
5. Run the MCP review tool to generate the Excel report

### Example: Run full review and store Excel in a chosen directory

When calling `review_robot_project` from an MCP client, provide:

- `directory_path` → Robot project root
- `report_output_directory` → folder where the Excel report should be created
- optional `output_excel_filename` → specific `.xlsx` name

Example JSON parameters:

```json
{
  "directory_path": "D:\\Projects\\my_robot_project",
  "report_output_directory": "D:\\Reports\\RobotReview",
  "output_excel_filename": "review_output.xlsx",
  "generate_excel": true,
  "include_comments": false,
  "include_checklist": false
}
```

## Smoke Test

To validate that the repo is ready after cloning:

```powershell
.\.venv\Scripts\python.exe .\scripts\smoke_test.py
```

## Bitbucket Branch and Push Workflow

Create a new branch locally:

```powershell
git checkout -b feature/bitbucket-ready-mcp
```

Commit your changes:

```powershell
git add .
git commit -m "Finalize MCP server repo for Bitbucket deployment"
```

Push the new branch to Bitbucket:

```powershell
git push -u origin feature/bitbucket-ready-mcp
```

## Bitbucket Pipeline

This repo now includes `bitbucket-pipelines.yml`. On push, Bitbucket Pipelines can:
- install dependencies
- run `scripts/smoke_test.py`
- validate that the MCP server repo is healthy

## Notes

- Generated Excel reports and local virtual environments should not be committed.

# Guided Prompt Templates for Users

These prompts are designed for users working with the MCP server, AI assistants, or Robot Framework script generation/review workflows.

Use them as copy-paste templates and replace the placeholders.

---

## 1. Prompt: Generate a New Robot Script

Use this when you want an AI assistant to generate a clean Robot Framework test script that follows the project checklist.

```text
Create a Robot Framework test script for the following scenario.

Project type: <web/api/database/mobile>
Test case name: <test case name>
Jira ID: <JIRA-ID>
Feature / story summary: <short business description>
Prerequisites: <preconditions>
Acceptance criteria:
- <criterion 1>
- <criterion 2>
- <criterion 3>

Strict requirements:
- Follow Robot Framework best practices.
- Use clear Given / When / Then / And steps.
- Add [Documentation] for the suite and test case.
- Add [Tags] including the Jira ID and one test type tag like Smoke/Regression/Sanity.
- Do NOT include unnecessary comments or placeholder text.
- Avoid hardcoded XPath or credentials.
- Keep the content concise, readable, and review-checklist compliant.
- Only include *** Keywords *** in the same file if explicitly needed; otherwise keep the test file clean.

Output:
- Return the final Robot Framework file content only.
```

---

## 2. Prompt: Improve an Existing Robot Script

Use this when you already have a `.robot` file and want an AI assistant to clean it up.

```text
Review and improve the following Robot Framework script.

Goals:
- Remove unnecessary or duplicated content.
- Make the script more appealing, readable, and maintainable.
- Preserve the functional meaning.
- Keep it aligned with Robot Framework code review checklist expectations.

Specific improvements required:
- Remove redundant comments, unused keywords, repeated steps, and unnecessary blank sections.
- Improve naming of test cases, keywords, and variables if they are unclear.
- Ensure Given / When / Then format is used where appropriate.
- Ensure [Documentation] and [Tags] are meaningful and concise.
- Avoid inline keyword duplication.
- Keep the final output clean and professional.
- Do not add decorative text, unnecessary explanation, or filler wording.

Here is the script:

<PASTE_EXISTING_ROBOT_SCRIPT_HERE>/<Directory _path_ to the .robot file>

Output:
- Return the improved Robot Framework file content.
- After the code, briefly list the unnecessary content you removed.
```

---

## 3. Prompt: Make Test Steps More Appealing

Use this when the logic is correct, but the wording is weak, repetitive, or hard to follow.

```text
Refine the following Robot Framework test steps to make them clearer, more professional, and easier to review.

Requirements:
- Keep the same test intent.
- Make step wording concise and business-readable.
- Prefer consistent Given / When / Then / And phrasing.
- Remove repetitive wording.
- Do not add extra steps that are not required.
- Do not add unnecessary comments.
- Keep the final wording suitable for code review and traceability.

Existing steps:
<PASTE_STEPS_HERE>

Output:
- Return only the improved steps.
```

---

## 4. Prompt: Remove Unnecessary Content

Use this prompt to explicitly trim noise from a generated script.

```text
Analyze the following Robot Framework content and remove anything unnecessary.

Remove or reduce:
- placeholder comments
- repeated setup/teardown content
- duplicate keywords
- unused variables
- overly verbose documentation
- extra blank lines
- unnecessary inline explanations
- repeated logging that does not help traceability

Keep:
- required documentation
- required tags
- essential Gherkin test steps
- important logs/screenshots needed for traceability
- only the keywords and variables that are truly used

Make the final output:
- shorter
- cleaner
- easier to maintain
- more appealing to reviewers
- aligned with a Robot Framework code review checklist

Input content:
<PASTE_CONTENT_HERE>

Output:
1. Cleaned content
2. Short bullet list of what was removed
```

---

## 5. Prompt: Ask the User for Missing Inputs Before Review

Use this when an assistant should not assume values like project path or report output folder.

```text
Before running the Robot Framework review, ask the user for the following required inputs:

1. Project directory path
   - The root folder containing the Data and Tests subfolders
2. Report output directory
   - The folder where the Excel review report should be generated
3. Optional output file name
   - If the user wants a specific .xlsx name instead of a timestamped file

When asking:
- Be concise and clear.
- Explain why each input is needed.
- Do not assume defaults unless the user explicitly agrees.
- Validate that the project path is correct and that the report directory exists.

After collecting the inputs:
- Confirm the resolved output path
- Then proceed with the review
```

---

## 6. Prompt: Review a Generated Script Against the Checklist

Use this after generation to get a structured review.

```text
Review the following Robot Framework script against a code review checklist.

Check specifically for:
- clear test case name
- meaningful documentation
- Jira ID and test type in tags
- Given / When / Then usage
- no unnecessary content
- no duplicate or irrelevant keywords
- no hardcoded XPath or credentials
- enough screenshots/logs for traceability
- concise and appealing structure

Script:
<PASTE_SCRIPT_HERE>

Output format:
1. PASS/FAIL summary
2. Issues found
3. Suggested improvements
4. Cleaned-up version if major cleanup is needed
```

---

## 7. Prompt: Best Final Prompt for MCP-Assisted Workflow

This is the most complete prompt for users who want generation + cleanup + review.

```text
I want you to help me prepare a Robot Framework script that is ready for code review.

Please follow this workflow:
1. Ask me for any missing required inputs:
   - project type
   - test name
   - Jira ID
   - acceptance criteria
   - project directory
   - report output directory
2. Generate a Robot Framework script using clear Given / When / Then steps.
3. Remove unnecessary content and make the script concise and appealing.
4. Keep the script aligned with Robot Framework code review checklist expectations.
5. If needed, separate keywords into support/resource files instead of bloating the test file.
6. Prepare the final version for MCP review.
7. Tell me what was removed or simplified.

Important expectations:
- No unnecessary placeholder text
- No noisy comments
- No redundant keywords
- No hardcoded credentials or XPath values
- Keep documentation useful but concise
- Keep the final output clean and reviewer-friendly
```

---

## Recommended Usage Pattern

For best results, follow this order:

1. Use **Prompt 5** to collect missing inputs
2. Use **Prompt 1** to generate a first draft
3. Use **Prompt 4** to remove unnecessary content
4. Use **Prompt 6** to review the result
5. Use the MCP `review_robot_project` tool to generate the final Excel report

---

## Notes

- These prompts are intentionally structured so users can get cleaner output with fewer unnecessary tokens.
- They help reduce repeated back-and-forth and improve the quality of generated Robot Framework content.
- They are especially useful when working with MCP clients such as VS Code, Claude Desktop, or similar AI-assisted tooling.

