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:

.\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)

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

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

Running the MCP Server

Stdio transport (default – for Claude Desktop / MCP clients):

.\scripts\start-mcp.ps1

SSE transport (for HTTP-based clients):

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

Custom path example:

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

Optional bind-host example:

.\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:

.\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:

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

Start/stop/restart/status:

.\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:

.\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:

{
  "mcpServers": {
	"robot-framework-review": {
	  "command": "D:\\Tools\\code_review_checklist\\.venv\\Scripts\\python.exe",
	  "args": [
		"D:\\Tools\\code_review_checklist\\mcp_server.py"
	  ],
	  "env": {}
	}
  }
}

.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:

{
  "$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:

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

Then configure .vscode/mcp.json like this:

{
  "$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:

{
	"$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:

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:

{
  "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:

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

Bitbucket Branch and Push Workflow

Create a new branch locally:

git checkout -b feature/bitbucket-ready-mcp

Commit your changes:

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

Push the new branch to Bitbucket:

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.

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.

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.

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.

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.

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.

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.

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.