Metadata-Version: 2.4
Name: rvce-report-mcp
Version: 0.1.1
Summary: MCP server for generating RVCE Experiential Learning and Project reports as formatted .docx files
Project-URL: Homepage, https://github.com/sumedhudupa/RVCE-report-mcp-generator
Project-URL: Repository, https://github.com/sumedhudupa/RVCE-report-mcp-generator
Project-URL: Issues, https://github.com/sumedhudupa/RVCE-report-mcp-generator/issues
Author-email: Your Name <you@email.com>
License: MIT License
        
        Copyright (c) 2025 GongRzhe
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: document-generation,docx,experiential-learning,fastmcp,mcp,report,rvce,word
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Office Suites
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.8.1
Requires-Dist: lxml>=4.9.0
Requires-Dist: python-docx>=1.1.2
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# rvce-report-mcp

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that generates **RVCE Experiential Learning (EL)** and **VTU Project Reports** as properly formatted `.docx` files — directly from your AI assistant.

Attach your project folder to GitHub Copilot (or any MCP-compatible client), paste your TOC, and the LLM extracts content from your project files and builds the full report automatically.

---

## Features

- **Two-file output** — `report_pretoc.docx` (cover, certificate, declaration) + `report_main.docx` (abstract through references)
- **Format extraction** — reads a sample RVCE `.docx` template and replicates its exact heading styles, fonts, margins, header/footer rules
- **Auto Table of Contents** — inserts a real Word `{ TOC }` field; press `Ctrl+A → F9` to populate page numbers
- **Figure & table cross-references** — auto-generates `Figure X.Y` / `Table X.Y` labels and appends `(see Figure X.Y)` to the preceding paragraph
- **List of Figures / List of Tables** — built automatically from registered figures and tables
- **Bold keyword highlighting** — terms from `bold_keywords` (or the EL topic name) are auto-bolded throughout body text
- **Filename italicisation** — file/path tokens in body text are auto-italicised
- **Strict validation** — catches missing fields, short paragraphs, emoji in text, malformed references, and table column mismatches _before_ building
- **Personal reflection entries** — structured per-student reflection blocks with bold name + italic text
- **Supports `el_report` and `project_report`** format profiles (VTU CHAPTER-prefix style)
- **Three transports** — `stdio` (default), `streamable-http`, `sse`

---

## Requirements

- Python ≥ 3.11
- A pre-TOC Word template (`pre_toc_template.docx`) with the token placeholders listed below — place it at `rvce_report_mcp/assets/pre_toc_template.docx`

---

## Install

```bash
pip install rvce-report-mcp
```

Or for local development:

```bash
git clone https://github.com/sumedhudupa/RVCE-report-mcp-generator.git
cd rvce-report-mcp
pip install -e ".[dev]"
```

---

## MCP Client Configuration

### VS Code (GitHub Copilot Agent mode)

Add to your `.vscode/mcp.json` or user `settings.json`:

```json
{
  "mcp": {
    "servers": {
      "rvce-report-generator": {
        "type": "stdio",
        "command": "rvce-report-mcp",
        "env": {
          "RVCE_MCP_TRANSPORT": "stdio"
        }
      }
    }
  }
}
```

### Claude Desktop

```json
{
  "mcpServers": {
    "rvce-report-generator": {
      "command": "rvce-report-mcp",
      "env": {
        "RVCE_MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

### HTTP / SSE transport

```bash
RVCE_MCP_TRANSPORT=streamable-http RVCE_MCP_PORT=8001 rvce-report-mcp
```

---

## Usage

### Prerequisites

Before generating a report:

1. Place your `pre_toc_template.docx` at `rvce_report_mcp/assets/pre_toc_template.docx` with all the placeholder tokens (see [Pre-TOC Template Tokens](#pre-toc-template-tokens))
2. Configure the MCP server in your client (see [MCP Client Configuration](#mcp-client-configuration))
3. Have your project files ready in a folder you can attach to the chat

### Quick start

In Copilot Agent mode (or any MCP-compatible client):

1. **Attach your project folder** to the chat context
2. **Paste your desired TOC structure** (chapter and section titles)
3. **Provide your team, mentor, and academic details** (see required inputs below)
4. **Send the prompt** — the LLM reads your project files, builds the `project_context` JSON, and calls the tools in the correct order

After generation, open `report_main.docx` in Word and press **`Ctrl+A` → `F9`** to populate Table of Contents page numbers.

### Example prompt

Copy and adapt this prompt to use with any MCP-compatible AI client:

```
Generate an experiential learning report for the given project
using the provided MCP tools.

Constraints:
- Do not use markdown
- Do not create files manually

Execution order:
1. Verify the report template using inspect_pretoc_template
2. Read project files to extract section content
3. Generate pre-TOC pages using generate_pretoc_pages
4. Assemble the final report using create_rvce_report

Sections:
1. Introduction
2. Problem Definition
   2.1 Problem Statement
3. Objectives
   3.1 Primary Objectives
   3.2 Secondary Objectives
4. Methodology
5. Tools and Techniques Used
6. Prototype
7. Results
8. Conclusion and Insights
9. References

Inputs:
- Team details: <name, USN, department, email for each member>
- Mentor details: <name, designation, department>
- Academic year: <e.g. 2025-26>
- Semester: <e.g. V>
- SDG theme: <e.g. SDG 9 - Industry, Innovation and Infrastructure>
```

### Required inputs

Provide these details in your prompt or as a follow-up when the LLM asks:

| Input | Description |
|---|---|
| Team members | Name, USN, department, and email for each student (max 5) |
| Faculty mentor | Name, designation, and department |
| Academic year | Short form e.g. `2025-26` |
| Semester | Roman numeral e.g. `V` |
| SDG theme | Sustainable Development Goal aligned with the project |
| Project title | Full title of the EL project |

### Tool execution order

```
inspect_pretoc_template → generate_pretoc_pages → create_rvce_report
```

**Output files:**

| File | Contents |
|---|---|
| `output/report_pretoc.docx` | Cover page, certificate, and declaration |
| `output/report_main.docx` | Abstract, TOC, all chapters, and references |

Merge both files in Word (or any tool) to produce the final submission-ready document.

---

## Available Tools

| Tool | Description |
|---|---|
| `read_template` | Extract a `FormatProfile` (heading styles, margins, header/footer) from a sample RVCE `.docx` |
| `inspect_template` | Paragraph-by-paragraph dump of any `.docx` — use to verify what `read_template` will detect |
| `inspect_pretoc_template` | List all `[token]` placeholders in the pre-TOC template. Call this **first** |
| `generate_pretoc_pages` | Fill the pre-TOC template with project details → `report_pretoc.docx` |
| `get_rvce_format_profile` | Return the built-in formatting defaults as JSON (no template required) |
| `create_rvce_report` | Build the full report (abstract → TOC → chapters → references) → `report_main.docx` |
| `inspect_report` | Paragraph-by-paragraph dump of a generated report — use to verify output |
| `add_report_section` | Replace or append a named section (`abstract`, `acknowledgement`, `chapter_N`, `references`, `appendix`) in an existing `.docx` |

---

## `project_context` Schema

```json
{
  "report_type": "el_report",
  "project_title": "string — required",
  "sdg_theme": "SDG 9 - Industry, Innovation and Infrastructure",
  "college_name": "RV College of Engineering",
  "academic_year": "2025-26",
  "semester": "V",
  "faculty_mentor": {
    "name": "string — required",
    "designation": "string",
    "department": "string"
  },
  "abstract": "string — 150-250 words",
  "el_topic": "string — EL topic name (used in header and as bold keyword)",
  "bold_keywords": ["keyword1", "keyword2"],
  "team": [
    {"name": "string", "usn": "string", "dept": "string", "email": "string"}
  ],
  "chapters": [
    {
      "number": 1,
      "title": "string",
      "sections": [
        {
          "heading": "1.1 Section Title",
          "paragraphs": [
            {"type": "body", "text": "string — min 40 words"},
            {"type": "bullet_list", "items": ["item 1", "item 2"]},
            {"type": "numbered_list", "items": ["step 1", "step 2"]},
            {"type": "figure", "id": "fig_unique_id", "caption": "string", "source": "screenshot"},
            {"type": "table", "id": "tbl_unique_id", "caption": "string",
             "headers": ["Col 1", "Col 2"], "rows": [["val", "val"]]},
            {"type": "personal_reflection", "entries": [
              {"name": "Student Name", "text": "reflection text"}
            ]}
          ],
          "subsections": []
        }
      ]
    }
  ],
  "appendix": {
    "title": "Visuals",
    "paragraphs": [
      {"type": "figure", "id": "fig_appendix", "caption": "string", "source": "screenshot"}
    ]
  },
  "references": [
    "1. A. Author, \"Title,\" Journal, vol. 1, pp. 1-10, 2024."
  ]
}
```

### Paragraph rules

- Every section requires **minimum 3 paragraph objects** (body, list, figure, and table all count)
- Body paragraphs require **minimum 40 words**
- First and last paragraph of each section must be `type: body`
- Figure and table `id` values must be **unique across the entire document**
- Table `headers` column count must match every row in `rows`
- `col_widths` (optional) must sum to exactly `100`
- Maximum **5 team members** in the pre-TOC template
- Minimum **5 references**
- No emoji in any text field

### Figure `source` values

| Value | Behaviour |
|---|---|
| `napkin` | Grey placeholder with Napkin export instructions |
| `draw.io` | Grey placeholder with draw.io export instructions |
| `screenshot` | Grey placeholder for screenshot |
| `image_file` | Grey placeholder for generic image |
| `embed` | Embeds the actual image from `file_path` |

---

## Pre-TOC Template Tokens

Place `pre_toc_template.docx` in `rvce_report_mcp/assets/`. The following tokens are replaced at build time:

| Token | Replaced with |
|---|---|
| `[project_title]` | `project_context.project_title` |
| `[theme]` | `project_context.sdg_theme` |
| `[team_member_name_1]` … `[team_member_name_5]` | Team member names |
| `[usn_1]` … `[usn_5]` | Team member USNs |
| `[mentor_name]` | `faculty_mentor.name` |
| `[mentor_designation]` | `faculty_mentor.designation` |
| `[mentor_dept]` | `faculty_mentor.department` |
| `[today's date]` | Current date (`dd Month YYYY`) |
| `2025-26` | `academic_year` short form |
| `2025-2026` | `academic_year` long form |

---

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `RVCE_MCP_TRANSPORT` | `stdio` | Transport type: `stdio`, `streamable-http`, `sse` |
| `RVCE_MCP_HOST` | `0.0.0.0` | Host for HTTP/SSE transport |
| `RVCE_MCP_PORT` | `8001` | Port for HTTP/SSE transport |
| `RVCE_MCP_PATH` | `/mcp` | Path for streamable-http transport |
| `RVCE_MCP_SSE_PATH` | `/sse` | Path for SSE transport |
| `RVCE_MCP_DEBUG` | `false` | Enable debug logging |

---

## Project Structure

```
rvce_report_mcp/
├── main.py                  # FastMCP server entry point, tool registration
├── assets/
│   └── pre_toc_template.docx  # Place your RVCE template here
├── core/
│   ├── __init__.py          # FormatProfile, HeaderProfile, FooterProfile dataclasses
│   ├── cross_reference.py   # FigureRegistry, TableRegistry
│   ├── format_extractor.py  # Extracts FormatProfile from a sample DOCX
│   ├── page_setup.py        # Page margins, header/footer builder
│   ├── placeholder.py       # Grey figure placeholder boxes
│   ├── report_builder.py    # Full document orchestrator
│   └── token_extractor.py   # Extracts [tokens] from template XML
├── tools/
│   ├── report_tools.py      # generate_pretoc_pages, create_rvce_report, inspect_report
│   ├── section_tools.py     # add_report_section
│   └── template_tools.py    # read_template, inspect_template
└── utils/
    ├── style_utils.py       # apply_paragraph_format, column width helpers
    ├── toc_utils.py         # TOC, LoF, LoT builders
    └── validator.py         # project_context validation
```

---

## License

MIT — see [LICENSE](LICENSE).